Switch

2026-09-20Loading rating…

1. Feature Description

RemoteSwitch is a toggle component for switching between "on" and "off" states, corresponding to ViewType.SWITCH. It supports default checked state, thumb color, track color, text, font size, font style, alignment, and a checked-change listener. It fits settings toggles, feature enable/disable, and similar scenarios.

Create it via RemoteViewHelper.createSwitch():

val toggle = helper.createSwitch()

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

Switch Properties

MethodParamsDescription
setCheckedBooleanWhether checked (on / off)
setThumbColorIntThumb color (ARGB Int)
setTrackColorIntTrack color (ARGB Int)
setTextStringText 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. setThumbColor / setTrackColor / 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. setThumbColor controls the thumb color and setTrackColor controls the track color; they are set independently and can be freely combined.

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 Switch (default off / default on / green thumb / red track / custom colors / disabled)

// Default off
val off = helper.createSwitch().apply {
    setWidth(40); setHeight(20); setChecked(false)
}

// Default on
val on = helper.createSwitch().apply {
    setWidth(40); setHeight(20); setChecked(true)
}

// Green thumb
val greenThumb = helper.createSwitch().apply {
    setWidth(55); setHeight(25); setChecked(true)
    setThumbColor(0xFF00C774.toInt())
}

// Red track
val redTrack = helper.createSwitch().apply {
    setWidth(55); setHeight(25); setChecked(true)
    setTrackColor(0xFFE41F29.toInt())
}

// Custom colors: blue track + white thumb
val custom = helper.createSwitch().apply {
    setWidth(55); setHeight(25); setChecked(true)
    setTrackColor(0xFF1A8BFF.toInt())
    setThumbColor(0xFFFFFFFF.toInt())
}

// Disabled: create first, then reduce opacity
val disabled = helper.createSwitch().apply {
    setWidth(40); setHeight(20); setChecked(true)
    setEnabled(false)
    setAlpha(0.6f)
}

// Checked-change listener (callbacks run on the Binder thread pool; switch to main thread to update UI)
on.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/SwitchDrawer.ktopen in new window in the official Sample open-pilot-plugin-sample.

Last Updated: