CircleProgressBar

2026-09-20Loading rating…

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)

MethodParamsDescription
setWidthIntWidth (dp); special values RemoteView.MATCH_PARENT(-1) / WRAP_CONTENT(-2)
setHeightIntHeight (dp); same special values
setMinSizeminWidth: Int, minHeight: IntMinimum size (dp)
setPaddingleft, top, right, bottom: IntPadding (dp)
setVisibilityVisibilityTypeVisibility: VISIBLE / INVISIBLE / GONE
setAlphaFloatOpacity, 0.0 – 1.0
setEnabledBooleanWhether enabled

Background & Shape (inherited from RemoteViewProvider)

MethodParamsDescription
setBackgroundIntSolid background color (ARGB Int)
setBackgroundShapeShapeDescriptorBackground shape: fill / stroke / corner radius

Circle Progress Bar Properties

MethodParamsDescription
setProgressIntCurrent progress, range 0-100 (internally coerceIn(0, 100))
setMaxIntMaximum progress value, defaults to 100, must be greater than 0
setProgressColorIntProgress-arc color (ARGB Int)
setTextStringCenter text, only effective in NORMAL state
setTextColorIntCenter text color (ARGB Int)
setTextSizeFloatCenter text size (sp, rounded internally)
setStatusProgressStatusTypeState: NORMAL (shows text) / SUCCESS (shows success icon, hides text) / FAIL (shows fail icon, hides text)

3. Tips

  1. Colors must be ARGB Int. setProgressColor / setTextColor / setBackground accept an Int color value (e.g. 0xFF1A8BFF.toInt() or Color.RED). Do not pass "#RRGGBB", "0xAARRGGBB", or R.color.xxx.
  2. The SUCCESS / FAIL states hide the center text. In these two states the center shows a success / fail icon instead, and the text set via setText is not displayed; only the NORMAL state shows center text. Switching back to NORMAL shows the text again.
  3. Progress range is fixed at 0-100. setProgress internally applies coerceIn(0, 100) to the argument, so out-of-range values are clamped. For a custom maximum, use setMax and ensure progress ≤ max yourself.
  4. Call syncToRemote() after changing a mounted component's properties. setXxx only updates the local cache; syncToRemote() batch-syncs to Pilot. If you configure properties before mounting, no extra call is needed.
  5. Center text size is in sp; setTextSize rounds 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.ktopen in new window in the official Sample open-pilot-plugin-sample.

Last Updated: