Layout

2026-09-20Loading rating…

1. Feature Description

RemoteLayout is the base class of all layout containers, used to organize and arrange child Views. It derives two common container types:

  • Linear layout RemoteLinearLayout: children are laid out sequentially in the horizontal or vertical direction, corresponding to ViewType.LINEAR_LAYOUT_HORIZONTAL / ViewType.LINEAR_LAYOUT_VERTICAL. Create via helper.createLinearLayoutHorizontal() / helper.createLinearLayoutVertical().
  • Constraint layout RemoteConstraintLayout: children are positioned via relative constraints, corresponding to ViewType.CONSTRAINT_LAYOUT. Create via helper.createConstraintLayout() and build constraints with helper.setConstraints(...).

Mount the container itself with addToRoot(), and add children with addToRemote(child, params?):

// Horizontal linear layout
val row = helper.createLinearLayoutHorizontal().apply {
    setWidth(RemoteView.MATCH_PARENT); setHeight(RemoteView.WRAP_CONTENT)
}
row.addToRoot()
row.addToRemote(helper.createButton().apply { setText("Button") })

Key Concepts

  • setGravity(GravityType): sets the overall alignment of children inside the container. Values include CENTER / CENTER_HORIZONTAL / CENTER_VERTICAL / TOP / BOTTOM / LEFT / RIGHT / START / END, etc.
  • WidgetLayoutParam: the layout params of a child within its parent. It carries weight (for linear layouts), margin, and layoutGravity (the child's own alignment in the parent).
  • weight + size set to 0: in a linear layout, set the child's size along the layout direction to 0 with a weight to distribute remaining space proportionally (width=0 horizontally, height=0 vertically).
  • ViewSide: the direction enum for constraint layouts, with values START / END / TOP / BOTTOM (plus UNKNOWN).

2. Common Properties

The following properties are set via the corresponding setXxx() methods. Unless noted otherwise, if the container 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

Container Properties

MethodParamsDescription
setGravityGravityTypeSets the overall alignment of children inside the container
addToRootparams: WidgetLayoutParam?Mount the container to the root layout (optional layout params)
addToRemotechild: RemoteViewProvider, params: WidgetLayoutParam?Add a child to the container (optional layout params) and auto-sync the child's initial properties

Common WidgetLayoutParam (child layout params) items:

Method / FieldParamsDescription
weightFloatWeight; used with linear layouts, the size along that direction must be 0
setMarginleft, top, right, bottom: IntMargins on all sides (dp)
marginLeft / marginTop / marginRight / marginBottomIntSingle-side margin (dp)
setLayoutGravityGravityTypeThe child's own alignment within its parent

Constraint Positioning (via RemoteViewHelper)

MethodParamsDescription
setConstraintslayoutId, viewId, targetId: String, viewDirection: ViewSide, targetDirection: ViewSide, margin: Int = 0Constrain the viewDirection edge of viewId to the targetDirection edge of targetId; targetId may be the parent layout's own id. Returns OperationResult

ViewSide values: START / END / TOP / BOTTOM (UNKNOWN is the invalid value).

3. Tips

  1. weight requires the corresponding size to be 0. To split children by weight in a horizontal linear layout, set setWidth(0); vertically, set setHeight(0). Otherwise a child first takes its content size and weight has no effect.
  2. Call addToRemote before setConstraints. If the constrained viewId or targetId has not been added to the layout yet, it returns OperationResult.NO_SUCH_VIEW_ID / NO_SUCH_PARENT_VIEW_ID. Add all children with addToRemote first, then build constraints.
  3. targetId may be the parent layout's own id. Constrain a child's edge to the container's id (the constraint layout's own id) to position it relative to the parent — corners, center, etc.
  4. Centering needs constraints on both axes. To center a child in a constraint layout, constrain both START↔parent START, END↔parent END (horizontal) and TOP↔parent TOP, BOTTOM↔parent BOTTOM (vertical).
  5. Colors must be ARGB Int. Container setBackground / setBackgroundShape colors are Int values (e.g. 0xFF1A8BFF.toInt()); do not pass "#RRGGBB" or R.color.xxx.
  6. Call syncToRemote() after changing a mounted container's properties. addToRemote / addToRoot already sync initial properties; only later standalone property changes need syncToRemote().

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 Linear Layout (weighted split / fixed width & spacing / vertical alignment)

// 1) Horizontal weighted split 1:1:1
val rowEqual = helper.createLinearLayoutHorizontal().apply {
    setWidth(RemoteView.MATCH_PARENT); setHeight(30)
}
rowEqual.addToRoot()
listOf("1", "2", "3").forEach { t ->
    val block = helper.createButton().apply {
        setText(t); setWidth(0); setHeight(30)   // width=0 with weight
        setBackgroundShape(ShapeDescriptor.Builder().fillColor(0xFF1A8BFF.toInt()).cornerRadius(2f).build())
    }
    rowEqual.addToRemote(block, WidgetLayoutParam().apply { weight = 1f; marginLeft = 2 })
}

// 2) Horizontal weighted ratio 1:2:3
val rowRatio = helper.createLinearLayoutHorizontal().apply {
    setWidth(RemoteView.MATCH_PARENT); setHeight(30)
}
rowRatio.addToRoot()
listOf(1f, 2f, 3f).forEach { w ->
    val block = helper.createButton().apply {
        setText("${w.toInt()}"); setWidth(0); setHeight(30)
        setBackgroundShape(ShapeDescriptor.Builder().fillColor(0xFF1A8BFF.toInt()).cornerRadius(2f).build())
    }
    rowRatio.addToRemote(block, WidgetLayoutParam().apply { weight = w; marginLeft = 2 })
}

// 3) Fixed width + spacing (no weight)
val rowFixed = helper.createLinearLayoutHorizontal().apply {
    setWidth(RemoteView.MATCH_PARENT); setHeight(30)
}
rowFixed.addToRoot()
listOf(30, 50, 40).forEach { wDp ->
    val block = helper.createButton().apply {
        setText("${wDp}dp"); setWidth(wDp); setHeight(30)
        setBackgroundShape(ShapeDescriptor.Builder().fillColor(0xFF1A8BFF.toInt()).cornerRadius(2f).build())
    }
    rowFixed.addToRemote(block, WidgetLayoutParam().apply { marginRight = 4 })
}

// 4) Vertical layout + gravity center alignment
val colCenter = helper.createLinearLayoutVertical().apply {
    setWidth(RemoteView.MATCH_PARENT); setHeight(120)
    setGravity(GravityType.CENTER_HORIZONTAL)   // children horizontally centered
}
colCenter.addToRoot()
colCenter.addToRemote(helper.createText().apply { setText("Title") })
colCenter.addToRemote(helper.createText().apply { setText("Subtitle") })

02 Constraint Layout (corners + center)

// Create and mount the constraint layout
val cl = helper.createConstraintLayout().apply {
    setWidth(RemoteView.MATCH_PARENT); setHeight(120)
    setBackgroundShape(ShapeDescriptor.Builder().fillColor(0xFF0659D9.toInt()).cornerRadius(4f).build())
}
cl.addToRoot()

// Add all children into the container first (must addToRemote before constraining)
val tl = helper.createButton().apply { setText("TL"); setWidth(50); setHeight(28) }
val tr = helper.createButton().apply { setText("TR"); setWidth(50); setHeight(28) }
val bl = helper.createButton().apply { setText("BL"); setWidth(50); setHeight(28) }
val br = helper.createButton().apply { setText("BR"); setWidth(50); setHeight(28) }
val center = helper.createButton().apply { setText("Center"); setWidth(50); setHeight(28) }
listOf(tl, tr, bl, br, center).forEach { cl.addToRemote(it) }

val parentId = cl.remoteView.id
val m = 8

// Top-left: START↔parent START, TOP↔parent TOP
helper.setConstraints(cl.remoteView.id, tl.remoteView.id, parentId, ViewSide.START, ViewSide.START, m)
helper.setConstraints(cl.remoteView.id, tl.remoteView.id, parentId, ViewSide.TOP, ViewSide.TOP, m)

// Top-right: END↔parent END, TOP↔parent TOP
helper.setConstraints(cl.remoteView.id, tr.remoteView.id, parentId, ViewSide.END, ViewSide.END, m)
helper.setConstraints(cl.remoteView.id, tr.remoteView.id, parentId, ViewSide.TOP, ViewSide.TOP, m)

// Bottom-left: START↔parent START, BOTTOM↔parent BOTTOM
helper.setConstraints(cl.remoteView.id, bl.remoteView.id, parentId, ViewSide.START, ViewSide.START, m)
helper.setConstraints(cl.remoteView.id, bl.remoteView.id, parentId, ViewSide.BOTTOM, ViewSide.BOTTOM, m)

// Bottom-right: END↔parent END, BOTTOM↔parent BOTTOM
helper.setConstraints(cl.remoteView.id, br.remoteView.id, parentId, ViewSide.END, ViewSide.END, m)
helper.setConstraints(cl.remoteView.id, br.remoteView.id, parentId, ViewSide.BOTTOM, ViewSide.BOTTOM, m)

// Center: constrain all four edges to the parent (both axes -> centered)
helper.setConstraints(cl.remoteView.id, center.remoteView.id, parentId, ViewSide.START, ViewSide.START)
helper.setConstraints(cl.remoteView.id, center.remoteView.id, parentId, ViewSide.END, ViewSide.END)
helper.setConstraints(cl.remoteView.id, center.remoteView.id, parentId, ViewSide.TOP, ViewSide.TOP)
helper.setConstraints(cl.remoteView.id, center.remoteView.id, parentId, ViewSide.BOTTOM, ViewSide.BOTTOM)

See the official Sample open-pilot-plugin-sample drawing/LayoutDrawer.ktopen in new window for a full runnable example.

Last Updated: