CheckBox

2026-09-20Loading rating…

1. Feature Description

RemoteCheckBox is a checkbox component with a text label, corresponding to ViewType.CHECK_BOX. It supports default checked state, checkbox tint, text, font size, font style, alignment, and a checked-change listener. It fits multi-select lists, agreement checks, toggle-style options, and similar scenarios.

Create it via RemoteViewHelper.createCheckBox():

val check = helper.createCheckBox()

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

CheckBox Properties

MethodParamsDescription
setCheckedBooleanWhether checked
setCheckBoxTintIntCheckbox tint (ARGB Int)
setTextStringText label content
setTextSizeFloatFont size (rounded to sp internally)
setTextColorIntText color (ARGB Int)
setGravityGravityTypeAlignment: CENTER / START / END / LEFT / RIGHT / TOP / BOTTOM, etc.
setFontStyleFontStyleTypeFont style: NORMAL / BOLD / ITALIC / BOLD_ITALIC

Events

MethodParamsDescription
setOnCheckChangeListenerIRemoteViewOnCheckedChangeListenerChecked-change listener: onCheckedChanged(view, isChecked). Callbacks run on the Binder thread pool

3. Tips

  1. Colors must be ARGB Int. setCheckBoxTint / setTextColor accept an Int color value (e.g. 0xFF1A8BFF.toInt() or Color.RED). Do not pass "#RRGGBB", "0xAARRGGBB", or R.color.xxx.
  2. setOnCheckChangeListener callbacks run on the Binder thread pool, not the main thread. To update UI inside the callback, switch back to the main thread first (e.g. Handler(Looper.getMainLooper()).post { ... }).
  3. Call syncToRemote() after changing a mounted component's properties. setXxx only updates the local cache; syncToRemote() batch-syncs to Pilot.
  4. The disabled state needs setEnabled(false) combined with setAlpha(...). setEnabled(false) alone only blocks interaction; combine it with reduced opacity for a visually greyed effect.
  5. setCheckBoxTint only affects the tint of the box; the label color is controlled separately by setTextColor.

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 CheckBox (unchecked / checked / blue / red / disabled)

// Unchecked
val unchecked = helper.createCheckBox().apply {
    setText("Unchecked"); setHeight(30); setChecked(false)
}

// Checked
val checked = helper.createCheckBox().apply {
    setText("Checked"); setHeight(30); setChecked(true)
}

// Blue tint
val blue = helper.createCheckBox().apply {
    setText("Blue"); setHeight(30); setChecked(true)
    setCheckBoxTint(0xFF1A8BFF.toInt())
}

// Red tint
val red = helper.createCheckBox().apply {
    setText("Red"); setHeight(30); setChecked(true)
    setCheckBoxTint(0xFFE41F29.toInt())
}

// Disabled: create first, then reduce opacity
val disabled = helper.createCheckBox().apply {
    setText("Disabled"); setHeight(30); setChecked(true)
    setEnabled(false)
    setAlpha(0.6f)
}

// Checked-change listener (callbacks run on the Binder thread pool; switch to main thread to update UI)
checked.setOnCheckChangeListener(object : IRemoteViewOnCheckedChangeListener {
    override fun onCheckedChanged(view: RemoteView, isChecked: Boolean) {
        Handler(Looper.getMainLooper()).post {
            // Safely update UI on the main thread
        }
    }
})

For a full runnable example, see drawing/CheckBoxDrawer.ktopen in new window in the official Sample open-pilot-plugin-sample.

Last Updated: