Layout
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 toViewType.LINEAR_LAYOUT_HORIZONTAL/ViewType.LINEAR_LAYOUT_VERTICAL. Create viahelper.createLinearLayoutHorizontal()/helper.createLinearLayoutVertical(). - Constraint layout
RemoteConstraintLayout: children are positioned via relative constraints, corresponding toViewType.CONSTRAINT_LAYOUT. Create viahelper.createConstraintLayout()and build constraints withhelper.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 includeCENTER/CENTER_HORIZONTAL/CENTER_VERTICAL/TOP/BOTTOM/LEFT/RIGHT/START/END, etc.WidgetLayoutParam: the layout params of a child within its parent. It carriesweight(for linear layouts),margin, andlayoutGravity(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 to0with aweightto distribute remaining space proportionally (width=0horizontally,height=0vertically).ViewSide: the direction enum for constraint layouts, with valuesSTART/END/TOP/BOTTOM(plusUNKNOWN).
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)
| 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 |
Container Properties
| Method | Params | Description |
|---|---|---|
setGravity | GravityType | Sets the overall alignment of children inside the container |
addToRoot | params: WidgetLayoutParam? | Mount the container to the root layout (optional layout params) |
addToRemote | child: 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 / Field | Params | Description |
|---|---|---|
weight | Float | Weight; used with linear layouts, the size along that direction must be 0 |
setMargin | left, top, right, bottom: Int | Margins on all sides (dp) |
marginLeft / marginTop / marginRight / marginBottom | Int | Single-side margin (dp) |
setLayoutGravity | GravityType | The child's own alignment within its parent |
Constraint Positioning (via RemoteViewHelper)
| Method | Params | Description |
|---|---|---|
setConstraints | layoutId, viewId, targetId: String, viewDirection: ViewSide, targetDirection: ViewSide, margin: Int = 0 | Constrain 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
weightrequires the corresponding size to be 0. To split children byweightin a horizontal linear layout, setsetWidth(0); vertically, setsetHeight(0). Otherwise a child first takes its content size andweighthas no effect.- Call
addToRemotebeforesetConstraints. If the constrainedviewIdortargetIdhas not been added to the layout yet, it returnsOperationResult.NO_SUCH_VIEW_ID/NO_SUCH_PARENT_VIEW_ID. Add all children withaddToRemotefirst, then build constraints. targetIdmay be the parent layout's own id. Constrain a child's edge to the container'sid(the constraint layout's own id) to position it relative to the parent — corners, center, etc.- Centering needs constraints on both axes. To center a child in a constraint layout, constrain both
START↔parent START,END↔parent END(horizontal) andTOP↔parent TOP,BOTTOM↔parent BOTTOM(vertical). - Colors must be ARGB Int. Container
setBackground/setBackgroundShapecolors are Int values (e.g.0xFF1A8BFF.toInt()); do not pass"#RRGGBB"orR.color.xxx. - Call
syncToRemote()after changing a mounted container's properties.addToRemote/addToRootalready sync initial properties; only later standalone property changes needsyncToRemote().
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-sampledrawing/LayoutDrawer.kt for a full runnable example.