Skip to content

Latest commit

 

History

History
160 lines (126 loc) · 5.66 KB

ProgressIndicator.md

File metadata and controls

160 lines (126 loc) · 5.66 KB

Progress Indicator

com.google.android.material provides an implementation of linear and circular progress indicator, compatible back to API 15 (Ice Cream Sandwich MR1). The easiest way to make use of these indicators is through ProgressIndicator.

ProgressIndicator

ProgressIndicator is API-compatible with Android's ProgressBar class and can therefore be used as a drop-in replacement. It can be included in XML layouts, or constructed programmatically:

XML

<?xml version="1.0" encoding="utf-8"?>
<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
  xmlns:app="http://schemas.android.com/apk/res-auto"
  android:layout_width="match_parent"
  android:layout_height="match_parent">
  <!-- ... -->

  <com.google.android.material.progressindicator.ProgressIndicator
    style="@style/Widget.MaterialComponents.ProgressIndicator.Circular.Indeterminate"
    android:id="@+id/Progress"/>

  <!-- ... -->
</FrameLayout>

Java

// An example to create circular indeterminate progress indicator.
import static com.google.android.material.progressindicator.R.style.
    Widget_MaterialComponents_ProgressIndicator_Circular_Indeterminate;

import com.google.android.material.progressindicator.ProgressIndicator;

ProgressIndicator progressIndicator =
    new ProgressIndicator(getContext(), null, 0,
        Widget_MaterialComponents_ProgressIndicator_Circular_Indeterminate);

Showing and hiding with animations

The progress indicator can be animated in and out by calling #show() or #hide() actively on ProgressIndicator:

// ...
ProgressIndicator progress = (ProgressIndicator) findViewById(R.id.Progress);
progress.show();
// ... wait until finished
progress.hide();

The component can also be animated in when it's attached to the current window:

// ...
LinearLayout layout = (LinearLayout) findViewById(R.id.layout);
ProgressIndicator progress = new ProgressIndicator(activity, null, 0,
    Widget_MaterialComponents_ProgressIndicator_Circular_Indeterminate);
// ... configures the components.
layout.addView(progress, new LayoutParams(MATCH_PARENT, WRAP_CONTENT));

Same GrowMode will have different visual effects to the linear and circular progress indicators.

GrowModeLinearCircular
GROW_MODE_INCOMING Indicator expending vertically from top Indicator expending inward from outter side
GROW_MODE_OUTCOMING Indicator expending vertically from bottom Indicator expending outward from inner side
GROW_MODE_BIDIRECTIONAL Indicator expending in both ways from the central line
GROW_MODE_NONE Show or hide immediately

Preset styles

There are a number of preset styles available that match the types of indicators shown in the spec. To use them, simply set your style attribute in XML to the desired name.

Preset style nameStyle
Widget.MaterialComponents.ProgressIndicator.
 Linear.Determinate		 4 dp high linear determinate with default max (100)
Widget.MaterialComponents.ProgressIndicator.
 Linear.Indeterminate		 4 dp high linear indeterminate
Widget.MaterialComponents.ProgressIndicator.
 Circular.Determinate		 48x48 dp circular determinate with default max (100)
Widget.MaterialComponents.ProgressIndicator.
 Circular.Indeterminate		 48x48 dp circular indeterminate

Custom styling

ProgressIndicator can be styled further by customizing colors, size, grow mode, etc. These are done through XML attributes, or their corresponding setter methods.

Colors

For single color mode styles (i.e., all determinate types, and some indeterminate types), the color of indicator (or stroke) can be set in attribute indicatorColor in XML or setIndicatorColors(int[]) programmatically; the color of track (the parts of track other than stroke) can be set in attribute trackColor in XML or setTrackColor(int) programmatically.

Note: Multiple colors can only take effect in indeterminate mode. If multiple indicator colors are set in determinate mode, only the first color will be used.

Note: In XML, only one of the attributes indicatorColor and indicatorColors can be set. If both are defined, IllegalArgumentException will be thrown while initialization. If neither is defined, the primary color of the current theme will be used as the indicator color.

Size

Use indicatorWidth to customize the size of linear types. It can adjust the height of the progress bar (as the width of the indicator/track). To add inset for linear types, please use padding of the layout.

Note: For both linear and circular types, indicator and track always have the same width.

The size of circular types can be set with a combination of indicatorWidth, circularRadius, and circularInset. indicatorWidth defines the width of the ring (circular spinner). circularRadius defines the radius of the central line of the ring. circularInset gives extra space between the outer boundary to the bounds of the component.

Note: If half of the indicatorWidth is greater than the circularRadius, IllegalArgumentException will be thrown during initialization.

Caveats

Subclassing ProgressIndicator is not recommended. If additional features are needed, please file an issue througth Github with feature request tag. Pull requests directly to ProgressIndicator are also welcome.