Android -purpose of useLevel in shape tag

Question

What is the purpose of android shape xml tag useLevel attribute ? This is in respect to a layer-list but should not matter. From the docs i found the meanging of the useLevel tag:

Indicates whether the drawable's level affects the way the gradient is drawn.

So if i have the following xml snippet:

    <?xml version="1.0" encoding="utf-8"?>
<shape
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:shape="ring"
    android:innerRadius="15dp"
    android:thickness="10dp"
    android:useLevel="false">

    <solid android:color="#ababf2" />

    <size
        android:height="50dp"
        android:width="50dp" />
</shape>

then with the useLevel=true, the ring is disabled. It must be false for the ring to appear. But what is the purpose of this attribute ? The docs are not clear.

Favourite

The docs are not clear - like this never happened before on Android, right? :) – Sides

This portion of the docs has android:useLevel on the <gradient> element, with a description of "true if this is used as a LevelListDrawable." LevelListDrawable definitely has the notion of a level. That being said, I don't understand the relationship here. – Heavy

Answer 1

It is for ProgressBars. For example this gist uses a ring shape as a progress drawable.

res/drawable/github_232_circular.xml:

<shape xmlns:android="http://schemas.android.com/apk/res/android"
       android:innerRadiusRatio="2.3"
       android:shape="ring"
       android:thickness="3.8sp"
       android:useLevel="true">
    <solid android:color="#ff0000" />
</shape>

In your layout:

<ProgressBar
    android:id="@+id/progress"
    style="?android:attr/progressBarStyleHorizontal"
    android:layout_width="64dp"
    android:layout_height="64dp"
    android:layout_gravity="top|end"
    android:max="100"
    android:progress="0"
    android:progressDrawable="@drawable/github_232_circular"
/>

Basically, useLevel makes it so the drawable can be drawn partially. For example there is a method ImageView.setImageLevel() that lets you set a "level," e.g. 25% progress, so the ring drawable would be drawn as a quarter-circle. And ProgressBar.setProgress() does the same thing, updating the "level" of the drawable you've set on the ProgressBar.

Apostolate

so your saying that the useLevel makes the progressbar circular ? im still not following you as the shape you provided is alraedy a ring. – Favourite

useLevel makes it so the drawable can be drawn partially. For example there is a method ImageView.setImageLevel() that lets you set a "level," e.g. 25% progress, so the ring drawable would be drawn as a quarter-circle. And ProgressBar sets the drawable "level" whenever you use ProgressBar.setProgress(). I'll update my answer with this extra detail. – Apostolate