CircleProgressBar
1. Feature Description
RemoteCircleProgressBar is a component that shows progress as a ring, corresponding to ViewType.CIRCULAR_PROGRESS_BAR. It supports setting the progress, maximum value, and progress-arc color, and can display text at the center (content / color / size), as well as switch among Normal / Success / Fail states. It fits circular progress with result feedback (such as task execution, download verification, etc.).
Create it via RemoteViewHelper.createCircleProgressBar():
val circleBar = helper.createCircleProgressBar()
2. Common Properties
The following properties are set via the corresponding setXxx() methods. Unless noted otherwise, if the component is already mounted, call syncToRemote() after changing a property to make it take effect on Pilot.
Size & Layout (inherited from RemoteViewProvider)
| Method | Params | Description |
|---|---|---|
setWidth | Int | Width (dp); special values RemoteView.MATCH_PARENT(-1) / WRAP_CONTENT(-2) |
setHeight | Int | Height (dp); same special values |
setMinSize | minWidth: Int, minHeight: Int | Minimum size (dp) |
setPadding | left, top, right, bottom: Int | Padding (dp) |
setVisibility | VisibilityType | Visibility: VISIBLE / INVISIBLE / GONE |
setAlpha | Float | Opacity, 0.0 – 1.0 |
setEnabled | Boolean | Whether enabled |
Background & Shape (inherited from RemoteViewProvider)
| Method | Params | Description |
|---|---|---|
setBackground | Int | Solid background color (ARGB Int) |
setBackgroundShape | ShapeDescriptor | Background shape: fill / stroke / corner radius |
Circle Progress Bar Properties
| Method | Params | Description |
|---|---|---|
setProgress | Int | Current progress, range 0-100 (internally coerceIn(0, 100)) |
setMax | Int | Maximum progress value, defaults to 100, must be greater than 0 |
setProgressColor | Int | Progress-arc color (ARGB Int) |
setText | String | Center text, only effective in NORMAL state |
setTextColor | Int | Center text color (ARGB Int) |
setTextSize | Float | Center text size (sp, rounded internally) |
setStatus | ProgressStatusType | State: NORMAL (shows text) / SUCCESS (shows success icon, hides text) / FAIL (shows fail icon, hides text) |
3. Tips
- Colors must be ARGB Int.
setProgressColor/setTextColor/setBackgroundaccept an Int color value (e.g.0xFF1A8BFF.toInt()orColor.RED). Do not pass"#RRGGBB","0xAARRGGBB", orR.color.xxx. - The
SUCCESS/FAILstates hide the center text. In these two states the center shows a success / fail icon instead, and the text set viasetTextis not displayed; only theNORMALstate shows center text. Switching back toNORMALshows the text again. - Progress range is fixed at 0-100.
setProgressinternally appliescoerceIn(0, 100)to the argument, so out-of-range values are clamped. For a custom maximum, usesetMaxand ensureprogress ≤ maxyourself. - Call
syncToRemote()after changing a mounted component's properties.setXxxonly updates the local cache;syncToRemote()batch-syncs to Pilot. If you configure properties before mounting, no extra call is needed. - Center text size is in sp;
setTextSizerounds the value internally.
4. Sample Code
In each group below, the code sample is on the left and the corresponding Pilot-side rendered preview is on the right.
01 Progress & Text (arc / center text / size & color)
// Different progress values, center shows percentage text
val p33 = helper.createCircleProgressBar().apply {
setWidth(30); setHeight(30)
setMax(100); setProgress(33); setProgressColor(0xFF1A8BFF.toInt())
setStatus(ProgressStatusType.NORMAL)
setText("33%"); setTextColor(0xFFFFFFFF.toInt()); setTextSize(11f)
}
val p66 = helper.createCircleProgressBar().apply {
setWidth(30); setHeight(30)
setMax(100); setProgress(66); setProgressColor(0xFF1A8BFF.toInt())
setStatus(ProgressStatusType.NORMAL)
setText("66%"); setTextColor(0xFFFFFFFF.toInt()); setTextSize(11f)
}
val p100 = helper.createCircleProgressBar().apply {
setWidth(30); setHeight(30)
setMax(100); setProgress(100); setProgressColor(0xFF1A8BFF.toInt())
setStatus(ProgressStatusType.NORMAL)
setText("100%"); setTextColor(0xFFFFFFFF.toInt()); setTextSize(11f)
}
// Different arc colors: blue / orange / red
val blue = helper.createCircleProgressBar().apply {
setWidth(30); setHeight(30); setProgress(33)
setProgressColor(0xFF1A8BFF.toInt()); setText("33%"); setTextColor(0xFFFFFFFF.toInt())
}
val orange = helper.createCircleProgressBar().apply {
setWidth(30); setHeight(30); setProgress(66)
setProgressColor(0xFFFF8100.toInt()); setText("66%"); setTextColor(0xFFFFFFFF.toInt())
}
val red = helper.createCircleProgressBar().apply {
setWidth(30); setHeight(30); setProgress(88)
setProgressColor(0xFFE41F29.toInt()); setText("88%"); setTextColor(0xFFFFFFFF.toInt())
}
02 Component States (NORMAL / SUCCESS / FAIL)
// FAIL: center shows fail icon, text hidden
val fail = helper.createCircleProgressBar().apply {
setWidth(30); setHeight(30)
setProgress(25); setProgressColor(0xFFE41F29.toInt())
setText("25%") // text is hidden in FAIL state
setStatus(ProgressStatusType.FAIL)
}
// NORMAL: normal state, center shows progress text
val normal = helper.createCircleProgressBar().apply {
setWidth(30); setHeight(30)
setProgress(45); setProgressColor(0xFF1A8BFF.toInt())
setText("45%"); setTextColor(0xFFFFFFFF.toInt()); setTextSize(11f)
setStatus(ProgressStatusType.NORMAL)
}
// SUCCESS: center shows success icon, text hidden
val success = helper.createCircleProgressBar().apply {
setWidth(30); setHeight(30)
setProgress(100); setProgressColor(0xFF00C774.toInt())
setText("100%") // text is hidden in SUCCESS state
setStatus(ProgressStatusType.SUCCESS)
}
For a full runnable example, see drawing/ProgressBarDrawer.kt in the official Sample
open-pilot-plugin-sample.