From 42f139c0696e2988adb24048fab998695e95fba3 Mon Sep 17 00:00:00 2001 From: Scott Main Date: Fri, 29 Apr 2011 10:31:10 -0700 Subject: docs: more documentation for ProgressBar Change-Id: Ief415c0b22da3e7d4ea318e321edc7d215603f0f --- core/java/android/widget/ProgressBar.java | 88 ++++++++++++++++++++++++++----- 1 file changed, 75 insertions(+), 13 deletions(-) diff --git a/core/java/android/widget/ProgressBar.java b/core/java/android/widget/ProgressBar.java index ef4e4e0..3f8ef29 100644 --- a/core/java/android/widget/ProgressBar.java +++ b/core/java/android/widget/ProgressBar.java @@ -64,15 +64,16 @@ import com.android.internal.R; * *

* A progress bar can also be made indeterminate. In indeterminate mode, the - * progress bar shows a cyclic animation. This mode is used by applications - * when the length of the task is unknown. + * progress bar shows a cyclic animation without an indication of progress. This mode is used by + * applications when the length of the task is unknown. The indeterminate progress bar can be either + * a spinning wheel or a horizontal bar. *

* *

The following code example shows how a progress bar can be used from * a worker thread to update the user interface to notify the user of progress: *

* - * 
+ * 
  * public class MyActivity extends Activity {
  *     private static final int PROGRESS = 0x1;
  *
@@ -91,7 +92,7 @@ import com.android.internal.R;
  *         // Start lengthy operation in a background thread
  *         new Thread(new Runnable() {
  *             public void run() {
- *                 while (mProgressStatus < 100) {
+ *                 while (mProgressStatus < 100) {
  *                     mProgressStatus = doWork();
  *
  *                     // Update the progress bar
@@ -104,8 +105,61 @@ import com.android.internal.R;
  *             }
  *         }).start();
  *     }
- * }
- * 

+ * }
+ * + *

To add a progress bar to a layout file, you can use the {@code <ProgressBar>} element. + * By default, the progress bar is a spinning wheel (an indeterminate indicator). To change to a + * horizontal progress bar, apply the {@link android.R.style#Widget_ProgressBar_Horizontal + * Widget.ProgressBar.Horizontal} style, like so:

+ * + * 
+ * <ProgressBar
+ *     style="@android:style/Widget.ProgressBar.Horizontal"
+ *     ... />
+ * + *

If you will use the progress bar to show real progress, you must use the horizontal bar. You + * can then increment the progress with {@link #incrementProgressBy incrementProgressBy()} or + * {@link #setProgress setProgress()}. By default, the progress bar is full when it reaches 100. If + * necessary, you can adjust the maximum value (the value for a full bar) using the {@link + * android.R.styleable#ProgressBar_max android:max} attribute. Other attributes available are listed + * below.

+ * + *

Another common style to apply to the progress bar is {@link + * android.R.style#Widget_ProgressBar_Small Widget.ProgressBar.Small}, which shows a smaller + * version of the spinning wheel—useful when waiting for content to load. + * For example, you can insert this kind of progress bar into your default layout for + * a view that will be populated by some content fetched from the Internet—the spinning wheel + * appears immediately and when your application receives the content, it replaces the progress bar + * with the loaded content. For example:

+ * + * 
+ * <LinearLayout
+ *     android:orientation="horizontal"
+ *     ... >
+ *     <ProgressBar
+ *         android:layout_width="wrap_content"
+ *         android:layout_height="wrap_content"
+ *         style="@android:style/Widget.ProgressBar.Small"
+ *         android:layout_marginRight="5dp" />
+ *     <TextView
+ *         android:layout_width="wrap_content"
+ *         android:layout_height="wrap_content"
+ *         android:text="@string/loading" />
+ * </LinearLayout>
+ * + *

Other progress bar styles provided by the system include:

+ * + *

The "inverse" styles provide an inverse color scheme for the spinner, which may be necessary + * if your application uses a light colored theme (a white background).

* *

XML attributes *

@@ -113,13 +167,21 @@ import com.android.internal.R; * {@link android.R.styleable#View View Attributes} *

* - *

Styles - *

- * @attr ref android.R.styleable#Theme_progressBarStyle - * @attr ref android.R.styleable#Theme_progressBarStyleSmall - * @attr ref android.R.styleable#Theme_progressBarStyleLarge - * @attr ref android.R.styleable#Theme_progressBarStyleHorizontal - *

+ * @attr ref android.R.styleable#ProgressBar_animationResolution + * @attr ref android.R.styleable#ProgressBar_indeterminate + * @attr ref android.R.styleable#ProgressBar_indeterminateBehavior + * @attr ref android.R.styleable#ProgressBar_indeterminateDrawable + * @attr ref android.R.styleable#ProgressBar_indeterminateDuration + * @attr ref android.R.styleable#ProgressBar_indeterminateOnly + * @attr ref android.R.styleable#ProgressBar_interpolator + * @attr ref android.R.styleable#ProgressBar_max + * @attr ref android.R.styleable#ProgressBar_maxHeight + * @attr ref android.R.styleable#ProgressBar_maxWidth + * @attr ref android.R.styleable#ProgressBar_minHeight + * @attr ref android.R.styleable#ProgressBar_minWidth + * @attr ref android.R.styleable#ProgressBar_progress + * @attr ref android.R.styleable#ProgressBar_progressDrawable + * @attr ref android.R.styleable#ProgressBar_secondaryProgress */ @RemoteView public class ProgressBar extends View { -- cgit v1.1