Skip to content

ui_authoring.md

Latest commit

 

History

History
1659 lines (1147 loc) · 29.8 KB

ui_authoring.md

File metadata and controls

1659 lines (1147 loc) · 29.8 KB
Raw

UI Application Authoring Guide

eepp provides a declarative UI system built around XML widget hierarchies, CSS styling, native layout containers, and C++ behavior.

The framework borrows ideas from several UI systems, most notably Android-style layout concepts and CSS, while also having its own widget, sizing, scene, and layout semantics. This gives eepp a flexible UI model, but it can also be misleading if concepts from Android or the web are assumed to behave identically.

This guide documents the recommended way to build normal eepp application interfaces. It is intended both for developers and for AI coding agents working on eepp applications.

The focus is practical application UI such as:

  • application shells;
  • toolbars and status bars;
  • settings panels;
  • dialogs and forms;
  • editor and workspace layouts;
  • lists, trees, and tables;
  • sidebars and split views;
  • application-specific tools and panels.

The goal is not to duplicate the API reference or CSS property reference. Instead, this guide establishes the mental model, conventions, and preferred patterns that should be used when authoring eepp UI.

When examples or analogies from Android, HTML, CSS, Qt, or other frameworks conflict with eepp behavior, eepp's own layout rules and implementation take precedence.

1. The most important distinction

eepp exposes two different layout worlds.

They coexist in the same UI framework, but they are intended for different jobs.

Normal eepp application UI

For application UI such as ecode, eterm, eproc, dialogs, settings panels, toolbars, sidebars, forms, editors, tables, and controls, use eepp's native layout system:

  • UILinearLayout
    • <vbox>
    • <hbox>
  • UIRelativeLayout
  • UIGridLayout
  • UIFlowLayout
  • UISplitter
  • UITabWidget
  • other specialized eepp containers

Use native eepp layout properties such as:

layout_width
layout_height
layout_weight
layout_gravity
margin
padding
layout-to-left-of
layout-to-right-of
layout-to-top-of
layout-to-bottom-of

CSS is still used extensively for styling these widgets and may also set these eepp-native layout properties.

This is the normal and preferred way to build an eepp application UI.

HTML compatibility layout

eepp also implements a large portion of web layout for:

  • UIWebView
  • UIMarkdownView
  • HTML rendering
  • HTML-compatible rich document layout

That includes concepts such as:

display: block
display: inline
display: inline-block
display: flex
display: grid
table layout
float
absolute/fixed/sticky positioning
web min/max sizing behavior

These capabilities are primarily part of the HTML compatibility layer.

They can technically be used outside HTML content, but ordinary eepp application UI generally does not need them.

Do not default to web layout just because eepp supports CSS.

For a normal eepp settings window, toolbar, sidebar, dialog, form, or editor shell, prefer the native eepp layout containers.

2. Mental model

Think of ordinary eepp UI as:

XML
    defines widget/layout hierarchy

native eepp layouts
    decide where children go and how available space is distributed

CSS
    styles widgets
    and can set eepp-native layout properties

C++
    provides behavior, data, commands, models, bindings, and dynamic changes

The hierarchy is DOM-like, but ordinary application layout is not browser layout.

Example:

<vbox layout_width="match_parent"
      layout_height="match_parent"
      padding="12dp">

    <TextView
        text="Project"
        layout_width="match_parent"
        layout_height="wrap_content" />

    <TextInput
        id="project"
        layout_width="match_parent"
        layout_height="wrap_content" />

    <hbox
        layout_width="match_parent"
        layout_height="wrap_content">

        <Widget layout_width="0dp"
                layout_height="1dp"
                layout_weight="1" />

        <PushButton text="Cancel" />
        <PushButton text="Save"
                    margin-left="8dp" />
    </hbox>
</vbox>

The layout model here is eepp-native:

vbox
    vertical packing

hbox
    horizontal packing

layout-width / layout-height
    child's sizing contract with the parent layout

layout-weight
    distribution of remaining space

layout-gravity
    child's placement within layout-controlled space

3. XML and CSS are not separate layout systems

A common mistake is assuming:

XML attributes = Android layout
CSS properties = browser layout

That is wrong.

eepp's CSS engine can set eepp-native properties too.

These are equivalent in purpose:

<TextInput
    layout_width="0dp"
    layout_weight="1"
    layout_height="wrap_content" />

and a stylesheet rule such as:

.form-input {
    layout-width: 0dp;
    layout-weight: 1;
    layout-height: wrap_content;
}

The choice between XML and CSS is about where the property should live, not about selecting a different layout engine.

A useful rule:

  • put one-off structural layout values directly in XML;
  • put repeated/shared values in CSS;
  • use CSS for visual styling;
  • use classes instead of repeating styling attributes;
  • do not move structural values into CSS merely because browsers do.

4. Native size policies

Ordinary eepp layouts use three core size policies:

enum class SizePolicy {
    Fixed,
    MatchParent,
    WrapContent
};

In XML/CSS these are normally represented through layout_width and layout_height in XML (or layout-width and layout-height in CSS).

wrap_content

layout_width="wrap_content"
layout_height="wrap_content"

Meaning:

Size the widget from its content/intrinsic size, including the relevant padding.

Typical uses:

  • labels;
  • buttons;
  • toolbars;
  • compact rows;
  • dialog action buttons;
  • intrinsic controls.

Example:

<PushButton
    text="Save"
    layout_width="wrap_content"
    layout_height="wrap_content" />

wrap_content is also the default value of native layout width/height where applicable.

match_parent

layout_width="match_parent"
layout_height="match_parent"

Meaning:

Consume the available size provided by the parent layout on that axis, accounting for the layout's margins/padding rules.

Typical uses:

  • top-level content;
  • editors;
  • lists;
  • tables;
  • child rows that should span the container;
  • main panes.

Example:

<ListView
    layout_width="match_parent"
    layout_height="match_parent" />

Do not interpret match_parent as CSS width: 100%.

They may often produce similar geometry, but they belong to different layout models and have different surrounding rules.

Fixed size

A concrete dimension implies fixed sizing on that axis:

layout_width="240dp"
layout_height="32dp"

Use fixed sizes when the size itself is meaningful.

Avoid hard-coding dimensions simply to force a layout to look correct.

5. layout-weight: distributing remaining space

layout_weight in XML (layout-weight in CSS) is a UILinearLayout concept derived from Android's linear layout model.

It distributes remaining space along the layout orientation.

The essential pattern is:

Horizontal flexible child

<hbox layout_width="match_parent"
      layout_height="wrap_content">

    <TextView
        text="Project"
        min-width="90dp"
        layout_gravity="center_vertical" />

    <TextInput
        layout_width="0dp"
        layout_height="wrap_content"
        layout_weight="1" />
</hbox>

For a horizontal linear layout:

layout-width = 0
layout-weight > 0

means:

Allocate this child a weighted share of the remaining horizontal space.

Vertical flexible child

<vbox layout_width="match_parent"
      layout_height="match_parent">

    <TextView text="Build queue" />

    <ListView
        layout_width="match_parent"
        layout_height="0dp"
        layout_weight="1" />

    <hbox layout_width="match_parent"
          layout_height="wrap_content">
        ...
    </hbox>
</vbox>

For a vertical linear layout:

layout-height = 0
layout-weight > 0

means:

Allocate this child a weighted share of the remaining vertical space.

This is a canonical eepp pattern.

Real examples exist in:

src/examples/ui_data_handling/ui_data_handling.cpp
src/examples/ui_data_collections/ui_data_collections.cpp
src/tools/ecode/plugins/pluginmanager.cpp
src/eepp/ui/tools/uiaudioplayer.cpp

6. gravity vs layout-gravity

This distinction is extremely important.

gravity

gravity controls content inside the widget.

Example:

<TextView
    text="Hello"
    gravity="center" />

This centers the text/content inside the TextView.

Typical values include:

left
right
top
bottom
center_horizontal
center_vertical
center

layout-gravity

layout-gravity controls the widget's placement relative to its parent layout, when that parent/layout supports the operation.

Example:

<PushButton
    text="Close"
    layout_gravity="right|center_vertical" />

Common agent mistake

Wrong reasoning:

"The button itself is not centered, so set gravity=center."

That centers the button's content, not necessarily the button.

If the widget itself must move within layout-controlled space, inspect:

layout-gravity
parent layout type
margins
size policies
layout weight

7. UILinearLayout: the default application layout

UILinearLayout is the workhorse layout for ordinary application UI.

Aliases:

<vbox> ... </vbox>
<hbox> ... </hbox>

Use it for most application structures.

Vertical box

<vbox
    layout_width="match_parent"
    layout_height="match_parent">

    <WidgetA />
    <WidgetB />
    <WidgetC />
</vbox>

Children are packed vertically.

Use for:

  • settings pages;
  • sidebar sections;
  • forms;
  • panels;
  • dialogs;
  • stacked tool areas.

Horizontal box

<hbox
    layout_width="match_parent"
    layout_height="wrap_content">

    <WidgetA />
    <WidgetB />
    <WidgetC />
</hbox>

Children are packed horizontally.

Use for:

  • form rows;
  • button rows;
  • toolbars;
  • status rows;
  • label + field pairs.

Canonical growing-content pattern

A very common application shell is:

<vbox lw="mp" lh="mp">

    <hbox lw="mp" lh="wc">
        <!-- toolbar -->
    </hbox>

    <SomeMainWidget
        lw="mp"
        lh="0dp"
        lw8="1" />

    <hbox lw="mp" lh="wc">
        <!-- status / actions -->
    </hbox>
</vbox>

Note: use the weight on the axis controlled by the linear layout.

For a vertical layout, the flexible child uses height 0dp plus weight.

8. Property naming convention and aliases

eepp accepts property-name aliases, including both underscore and hyphenated forms, but normal eepp code follows a useful convention:

XML attributes  -> underscore-separated
CSS properties  -> hyphen-separated

Preferred examples:

<TextInput
    layout_width="0dp"
    layout_height="wrap_content"
    layout_weight="1"
    layout_gravity="center_vertical" />
.form-input {
    layout-width: 0dp;
    layout-height: wrap_content;
    layout-weight: 1;
    layout-gravity: center_vertical;
}

This distinction is intentional even though eepp can resolve aliases. It makes XML feel like widget configuration while CSS retains normal CSS spelling, and it makes mixed XML/CSS code easier to read.

Compact aliases are also used heavily in production code:

layout_width    -> lw
layout_height   -> lh
layout_weight   -> lw8
layout_gravity  -> lg

Special size abbreviations commonly used in eepp layouts:

mp = match_parent
wc = wrap_content

So:

<vbox lw="mp" lh="mp">

is an idiomatic compact form of:

<vbox
    layout_width="match_parent"
    layout_height="match_parent">

Agents should be able to read both styles.

When writing new documentation-oriented examples, prefer the full names first.

When editing an existing codebase, follow the local style.

9. UIRelativeLayout

Use UIRelativeLayout when children need relationships to each other or the parent that are awkward in a simple linear hierarchy.

It supports relationships such as:

layout-to-left-of
layout-to-right-of
layout-to-top-of
layout-to-bottom-of

Conceptually:

<RelativeLayout
    layout_width="match_parent"
    layout_height="match_parent">

    <Widget id="sidebar" ... />

    <Widget
        id="content"
        layout_to_right_of="sidebar"
        ... />
</RelativeLayout>

Do not use a relative layout just because it allows arbitrary placement.

If a hierarchy can be naturally represented as nested vbox/hbox, that is usually easier to maintain.

ecode uses UIRelativeLayout for several larger composite areas where the relative relationships are genuinely useful.

Examples:

src/tools/ecode/uiwelcomescreen.cpp
src/tools/ecode/uirightpanel.cpp
src/tools/ecode/uibuildsettings.cpp

10. Native UIGridLayout is NOT CSS Grid

eepp has a native UIGridLayout.

This must not be confused with the HTML/CSS Grid implementation.

Native UIGridLayout lays children into repeated rows/columns using eepp-native sizing rules.

It supports properties such as:

column-mode
row-mode
column-weight
row-weight
column-width
row-height
column-margin
row-margin

Modes can use fixed sizes or weighted sizes.

Use native UIGridLayout when building a normal application UI that needs a repeated grid of similarly sized children.

Do not reach for CSS:

display: grid;
grid-template-columns: ...;

unless you are intentionally working in the HTML compatibility layout world.

11. UIFlowLayout

UIFlowLayout is eepp's native wrapping flow layout.

It places visible children horizontally and starts a new row when the available width is exhausted:

A B C D
E F G
H I

Its behavior is similar in spirit to layout types commonly called FlowLayout, Wrap, WrapPanel, or FlowRow in other UI frameworks.

It also supports per-row vertical alignment through row-valign.

Use it for things such as:

  • tag/chip collections;
  • language selectors;
  • wrapping tool controls;
  • compact option groups;
  • responsive rows of controls.

ecode uses it for dynamic language buttons, build/run options, search controls, and other wrapping control groups. eepp also uses it in merge-view tooling.

Example production locations:

src/tools/ecode/ecode.cpp
src/tools/ecode/uibuildsettings.cpp
src/eepp/ui/tools/uimergeview.cpp

12. UISplitter and workspace layout

For resizable application panes, use UISplitter.

Do not emulate resizable panes with manual dimensions or HTML flex resizing.

Typical uses:

sidebar | editor
editor | terminal
tree | details
multi-pane workspace

For tabbed/split editor workspaces, eepp also provides UITabWidget and UITabWidgetSplitter.

ecode is the primary production reference.

13. Margins and padding

The distinction follows the usual box-model intuition:

margin
    outside the widget

padding
    inside the widget, between its edge and its content/children

Typical native layout usage:

<vbox
    padding="12dp">

    <TextView
        margin-bottom="8dp"
        text="Settings" />
</vbox>

Margins participate in native layout calculations.

Do not add spacer widgets unless spacing represents actual flexible space.

Use margins/padding for ordinary spacing.

A zero-sized weighted widget can still be appropriate when the goal is intentionally consuming remaining space:

<Widget
    layout_width="0dp"
    layout_height="1dp"
    layout_weight="1" />

14. Use dp for application UI dimensions

eepp uses device-independent pixels:

dp

for scalable application UI metrics.

Examples:

padding="8dp"
margin-left="4dp"
layout_height="32dp"
font-size="14dp"

Do not use raw pixel dimensions for ordinary application UI unless physical/native pixels are specifically required.

Pixel-density behavior is part of the framework's UI environment.

15. CSS in ordinary eepp application UI

CSS is still a major part of normal eepp UI.

Use it for:

  • colors;
  • backgrounds;
  • borders;
  • fonts;
  • icons;
  • transitions;
  • animations;
  • pseudo-classes;
  • shared dimensions;
  • margins/padding;
  • native layout properties;
  • theme variables;
  • media queries;
  • reusable classes.

Example:

.settings-row {
    layout-width: match_parent;
    layout-height: wrap_content;
    margin-bottom: 8dp;
}

.settings-row > TextView {
    min-width: 120dp;
    layout-gravity: center_vertical;
}

.settings-row > TextInput {
    layout-width: 0dp;
    layout-weight: 1;
}

This is still the native eepp layout system, even though the rules are written in CSS.

16. Do not casually use HTML layout properties in application UI

For ordinary application UI, avoid defaulting to:

display: flex;
display: grid;
display: block;
float: left;
position: sticky;

Those are primarily part of the HTML compatibility system.

The fact that eepp can interpret them does not make them the preferred application-layout abstraction.

Bad default agent reasoning:

"I need two controls next to each other, so use display:flex."

Preferred eepp reasoning:

<hbox>
    <WidgetA />
    <WidgetB />
</hbox>

Bad default reasoning:

"I need a sidebar and content area, so use CSS Grid."

Preferred eepp reasoning:

UISplitter
or
nested native layouts

depending on whether the divider must be user-resizable.

17. HTML layout is appropriate when rendering HTML

When working inside:

UIWebView
UIMarkdownView
HTML document content
HTML-compatible rich content

use normal web-layout reasoning where supported.

There:

display: flex;
min-width: 0;
position: sticky;

may be exactly correct.

The Runtime UI Inspector treats a UIWebView document as its own scene. Do not assume application-scene selectors automatically enter the HTML document scene.

18. Choose layouts by behavior

Use this decision guide.

Need a vertical sequence?

Use:

<vbox>

Need a horizontal sequence?

Use:

<hbox>

Need one child to consume leftover space?

Use layout-weight on the linear-layout axis.

Horizontal:

layout_width="0dp"
layout_weight="1"

Vertical:

layout_height="0dp"
layout_weight="1"

Need resizable panes?

Use:

UISplitter

Need tabs/workspace splitting?

Use:

UITabWidget
UITabWidgetSplitter

Need children positioned relative to siblings?

Use:

UIRelativeLayout

Need repeated same-sized/weighted grid cells?

Use:

UIGridLayout

not CSS Grid.

Need items to flow horizontally and wrap?

Use:

UIFlowLayout

This is the canonical native eepp flow/wrap layout.

Need document/web flow?

Use the HTML compatibility system through:

UIWebView
UIMarkdownView

19. Canonical application patterns

Agents should prefer production-tested patterns instead of inventing layout strategies.

Pattern: form row

<hbox
    layout_width="match_parent"
    layout_height="wrap_content"
    margin-bottom="8dp">

    <TextView
        text="Project"
        min-width="90dp"
        layout_gravity="center_vertical" />

    <TextInput
        id="project"
        layout_width="0dp"
        layout_height="wrap_content"
        layout_weight="1" />
</hbox>

Reference:

src/examples/ui_data_handling/ui_data_handling.cpp

Pattern: header + flexible content + footer

<vbox
    layout_width="match_parent"
    layout_height="match_parent">

    <hbox
        layout_width="match_parent"
        layout_height="wrap_content">
        <!-- header -->
    </hbox>

    <SomeContent
        layout_width="match_parent"
        layout_height="0dp"
        layout_weight="1" />

    <hbox
        layout_width="match_parent"
        layout_height="wrap_content">
        <!-- footer -->
    </hbox>
</vbox>

This is one of the most important patterns to understand.

Pattern: actions aligned to the right

<hbox
    layout_width="match_parent"
    layout_height="wrap_content">

    <Widget
        layout_width="0dp"
        layout_height="1dp"
        layout_weight="1" />

    <PushButton text="Cancel" />
    <PushButton text="Save" margin-left="8dp" />
</hbox>

Alternatively, where parent gravity semantics make it appropriate:

<hbox layout_gravity="right">
    ...
</hbox>

Follow the existing component's style.

Pattern: settings UI

Prefer reusable framework facilities where available.

eepp now provides:

EE::UI::Tools::UISettingsPanel

which is used by real applications including ecode, eterm, and eproc.

Do not recreate a settings framework from primitive widgets without first checking whether UISettingsPanel covers the requirement.

Pattern: application charts

eepp provides:

UIChart

with framework-level charting behavior.

Do not implement charts manually with primitive drawing unless the requirement falls outside the chart system.

See:

docs/articles/ui_charts.md

and eproc for a production consumer.

20. Common agent mistakes

Mistake: using browser Flexbox for an application toolbar

Avoid:

.toolbar {
    display: flex;
}

for ordinary application UI.

Prefer:

<hbox class="toolbar">

Mistake: confusing native GridLayout and CSS Grid

These are separate systems.

Use native UIGridLayout for ordinary eepp application grids.

Use CSS Grid for HTML compatibility content.

Mistake: setting gravity to move a widget

gravity generally aligns the widget's content.

Use layout-gravity, layout hierarchy, margins, or the appropriate parent-layout mechanism to place the widget itself.

Mistake: weight without zero size on the weighted axis

Avoid:

<hbox>
    <TextInput
        layout_width="match_parent"
        layout_weight="1" />
</hbox>

Preferred:

<hbox>
    <TextInput
        layout_width="0dp"
        layout_weight="1" />
</hbox>

For a vertical layout, use height 0dp.

Mistake: fixed sizing to solve parent-layout problems

Before forcing:

layout_width="417dp"

inspect:

parent type
layout-width policy
layout-height policy
layout-weight
layout-gravity
margin
padding
min/max dimensions

A hard-coded size often hides the real layout mistake.

Mistake: assuming CSS means browser behavior everywhere

eepp's stylesheet engine applies to ordinary widgets too, but ordinary widgets often use eepp-native layout semantics.

Read the property definition and parent layout behavior instead of assuming browser behavior from the property syntax.

Mistake: treating UIFlowLayout as an overlay

UIFlowLayout is a wrapping flow layout: children advance horizontally and wrap into new rows.

It is not a z-stack or absolute overlay container.

21. Debug layout with the Runtime UI Inspector & Automation Protocol

Do not guess geometry when the application can tell you the answer.

Enable the inspector and inspect the real running UI. See ui_inspector.md for activation, client setup, and scene selection. The handles and scene IDs in the commands below are examples; get the actual values from contexts and query for the running application.

Basic workflow:

1. discover windows/scenes
2. query the target by selector
3. inspect geometry and relevant properties
4. inspect its parent
5. capture a screenshot if visual context matters
6. interact if necessary
7. wait for the next frame
8. inspect again

Example commands:

python3 projects/scripts/eepp-inspect.py contexts

python3 projects/scripts/eepp-inspect.py query '#project'

python3 projects/scripts/eepp-inspect.py inspect \
    w:42 \
    geometry.size \
    geometry.position \
    css.layout-width \
    css.layout-height

python3 projects/scripts/eepp-inspect.py tree --depth 4

python3 projects/scripts/eepp-inspect.py screenshot --scene scene:1

Use the inspector instead of inferring runtime layout solely from source code or screenshots.

22. Debugging a wrong size

When a widget is unexpectedly too large or too small, inspect in this order:

1. What parent layout owns it?
2. What are layout-width and layout-height?
3. Is the relevant axis Fixed, MatchParent, or WrapContent?
4. Does it have layout-weight?
5. If weighted, is the weighted axis set to 0?
6. What margins does the child have?
7. What padding does the parent have?
8. Are min-width/max-width/min-height/max-height constraining it?
9. Is the widget's intrinsic content changing wrap_content?
10. Is the parent itself constrained correctly?

Only after that consider a fixed size.

23. Debugging wrong alignment

Inspect:

gravity
layout-gravity
parent layout type
layout direction/orientation
margin
widget size
available parent space

Remember:

gravity
    content inside widget

layout-gravity
    widget placement in parent layout

24. Debugging weighted layouts

For a horizontal hbox:

weighted dimension = width

Expected flexible-child pattern:

layout_width="0dp"
layout_weight="..."

For a vertical vbox:

weighted dimension = height

Expected pattern:

layout_height="0dp"
layout_weight="..."

If the result is wrong, inspect sibling fixed sizes and margins because weights distribute remaining space.

25. Debugging UIWebView

A UIWebView document is a separate nested scene.

An application-scene query does not cross into it.

Workflow:

query the UIWebView in parent scene
    ↓
read its documentScene handle
    ↓
query that scene separately

At that point web-layout rules are appropriate because the target is actual HTML-compatible content.

26. Learn from production code

The best reference application is ecode.

It uses a very broad cross-section of eepp UI:

  • linear layouts;
  • relative layouts;
  • flow layouts;
  • splitters;
  • tabs;
  • menus;
  • settings;
  • status UI;
  • dialogs;
  • tables/trees/models;
  • code editors;
  • terminal integration;
  • plugins;
  • rich text;
  • Markdown/HTML;
  • notifications;
  • complex commands;
  • data binding;
  • nested scenes.

Most ecode source lives inside the eepp repository:

src/tools/ecode/

Useful starting points include:

src/tools/ecode/applayout.xml.hpp
src/tools/ecode/uiwelcomescreen.cpp
src/tools/ecode/uirightpanel.cpp
src/tools/ecode/uibuildsettings.cpp
src/tools/ecode/plugins/pluginmanager.cpp
src/tools/ecode/plugins/git/gitplugin.cpp
src/tools/ecode/plugins/debugger/debuggerplugin.cpp
src/tools/ecode/plugins/aiassistant/chatui.cpp

Framework-level reusable components are also excellent references:

src/eepp/ui/tools/uisettingspanel.cpp
src/eepp/ui/tools/uiaudioplayer.cpp
src/eepp/ui/tools/uidocfindreplace.cpp
src/eepp/ui/tools/uimergeview.cpp

Simple examples remain useful when learning one concept in isolation:

src/examples/ui_application_hello_world/
src/examples/ui_data_handling/
src/examples/ui_data_collections/
src/examples/ui_richtext/

27. Source priority for agents

When sources disagree or an assumption is uncertain, use this priority:

1. Current eepp implementation
2. Current eepp tests
3. Current production eepp/ecode usage
4. Current eepp documentation
5. Android/web analogy
6. Generic prior knowledge

Android and browser knowledge are useful for intuition only.

They are not authoritative for eepp behavior.

28. When modifying existing UI

Do not rewrite an existing screen into a different layout paradigm without a strong reason.

Before editing:

identify current parent layout
inspect nearby sibling patterns
find similar code in the same subsystem
preserve local XML/CSS naming style
preserve compact/full property naming style

For example, if nearby code uses:

lw="mp"
lh="wc"
lw8="1"
lg="center_vertical"

an agent can use the same aliases.

For new explanatory examples and documentation, prefer full names first.

29. Runtime verification is expected

For non-trivial visual changes, an agent should not stop after editing code.

Preferred closed-loop workflow:

read layout rules
    ↓
find canonical production pattern
    ↓
edit XML/CSS/C++
    ↓
build/run
    ↓
inspect runtime tree
    ↓
inspect geometry/properties
    ↓
capture screenshot when useful
    ↓
interact with UI
    ↓
wait next frame
    ↓
verify final state

The Runtime UI Inspector & Automation Protocol exists specifically to make this workflow reliable and automatable.

30. Do not create a second mental model unnecessarily

For ordinary eepp application UI, think:

native widgets
+
native layouts
+
CSS styling

Do not think:

HTML page rendered as desktop UI

unless you are actually working in the HTML compatibility layer.

This single distinction prevents many layout mistakes.

31. Quick reference

Preferred ordinary UI containers

<vbox> / <hbox>    sequential layout
RelativeLayout     sibling-relative placement
GridLayout         repeated native grid
FlowLayout        horizontal wrapping/flow
Splitter           resizable panes
TabWidget          tabs
TabWidgetSplitter  split/tab workspaces

Core sizing

wrap_content       intrinsic/content size
match_parent       consume parent allocation
fixed dimension    explicit size
layout-weight      share remaining LinearLayout space

Alignment

gravity            content inside widget
layout-gravity     widget against parent layout

Styling

CSS is normal and encouraged.
CSS does not imply browser layout.

HTML

Flexbox/Grid/block/inline/etc.
primarily belong to UIWebView/UIMarkdownView/HTML compatibility.

Debugging

Use the Runtime UI Inspector & Automation Protocol.
Inspect actual state instead of guessing.