.. index:: pair: page; UI Application Authoring Guide
.. _doxid-ui_authoring:

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**.



.. _doxid-ui_authoring_1autotoc_md607:

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.





.. _doxid-ui_authoring_1autotoc_md608:

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:

.. ref-code-block:: cpp

	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.





.. _doxid-ui_authoring_1autotoc_md610:

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:

.. ref-code-block:: cpp

	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.





.. _doxid-ui_authoring_1autotoc_md612:

2. Mental model
~~~~~~~~~~~~~~~

Think of ordinary eepp UI as:

.. ref-code-block:: cpp

	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:

.. ref-code-block:: cpp

	<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:

.. ref-code-block:: cpp

	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





.. _doxid-ui_authoring_1autotoc_md614:

3. XML and CSS are not separate layout systems
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A common mistake is assuming:

.. ref-code-block:: cpp

	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:

.. ref-code-block:: cpp

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

and a stylesheet rule such as:

.. ref-code-block:: cpp

	.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.





.. _doxid-ui_authoring_1autotoc_md616:

4. Native size policies
~~~~~~~~~~~~~~~~~~~~~~~

Ordinary eepp layouts use three core size policies:

.. ref-code-block:: cpp

	enum class :ref:`SizePolicy <doxid-namespace_e_e_1_1_u_i_1a034aac001333b3fcb1af246289ba9031>` {
	    :ref:`Fixed <doxid-namespace_e_e_1_1_u_i_1aecdbebafda7616abe045a8b0c7901361a4457d440870ad6d42bab9082d9bf9b61>`,
	    :ref:`MatchParent <doxid-namespace_e_e_1_1_u_i_1a034aac001333b3fcb1af246289ba9031a809357452f170d2f30ff5b5e22261058>`,
	    :ref:`WrapContent <doxid-namespace_e_e_1_1_u_i_1a034aac001333b3fcb1af246289ba9031a06355dd2324d1273ff95fbe9c1008e10>`
	};

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



.. _doxid-ui_authoring_1autotoc_md618:

<tt>wrap_content</tt>
---------------------

.. ref-code-block:: cpp

	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:

.. ref-code-block:: cpp

	<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.





.. _doxid-ui_authoring_1autotoc_md620:

<tt>match_parent</tt>
---------------------

.. ref-code-block:: cpp

	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:

.. ref-code-block:: cpp

	<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.





.. _doxid-ui_authoring_1autotoc_md622:

Fixed size
----------

A concrete dimension implies fixed sizing on that axis:

.. ref-code-block:: cpp

	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.







.. _doxid-ui_authoring_1autotoc_md624:

5. <tt>layout-weight</tt>: 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:



.. _doxid-ui_authoring_1autotoc_md625:

Horizontal flexible child
-------------------------

.. ref-code-block:: cpp

	<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:

.. ref-code-block:: cpp

	layout-width = 0
	layout-weight > 0

means:

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





.. _doxid-ui_authoring_1autotoc_md627:

Vertical flexible child
-----------------------

.. ref-code-block:: cpp

	<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:

.. ref-code-block:: cpp

	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:

.. ref-code-block:: cpp

	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







.. _doxid-ui_authoring_1autotoc_md629:

6. <tt>gravity</tt> vs <tt>layout-gravity</tt>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This distinction is extremely important.



.. _doxid-ui_authoring_1autotoc_md630:

<tt>gravity</tt>
----------------

``gravity`` controls **content inside the widget**.

Example:

.. ref-code-block:: cpp

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

This centers the text/content inside the ``TextView``.

Typical values include:

.. ref-code-block:: cpp

	left
	right
	top
	bottom
	center_horizontal
	center_vertical
	center





.. _doxid-ui_authoring_1autotoc_md632:

<tt>layout-gravity</tt>
-----------------------

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

Example:

.. ref-code-block:: cpp

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





.. _doxid-ui_authoring_1autotoc_md634:

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:

.. ref-code-block:: cpp

	layout-gravity
	parent layout type
	margins
	size policies
	layout weight







.. _doxid-ui_authoring_1autotoc_md636:

7. <tt>UILinearLayout</tt>: the default application layout
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``UILinearLayout`` is the workhorse layout for ordinary application UI.

Aliases:

.. ref-code-block:: cpp

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

Use it for most application structures.



.. _doxid-ui_authoring_1autotoc_md638:

Vertical box
------------

.. ref-code-block:: cpp

	<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.





.. _doxid-ui_authoring_1autotoc_md640:

Horizontal box
--------------

.. ref-code-block:: cpp

	<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.





.. _doxid-ui_authoring_1autotoc_md642:

Canonical growing-content pattern
---------------------------------

A very common application shell is:

.. ref-code-block:: cpp

	<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.







.. _doxid-ui_authoring_1autotoc_md644:

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:

.. ref-code-block:: cpp

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

Preferred examples:

.. ref-code-block:: cpp

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

.. ref-code-block:: cpp

	.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:

.. ref-code-block:: cpp

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

Special size abbreviations commonly used in eepp layouts:

.. ref-code-block:: cpp

	mp = match_parent
	wc = wrap_content

So:

.. ref-code-block:: cpp

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

is an idiomatic compact form of:

.. ref-code-block:: cpp

	<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.





.. _doxid-ui_authoring_1autotoc_md646:

9. <tt>UIRelativeLayout</tt>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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:

.. ref-code-block:: cpp

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

Conceptually:

.. ref-code-block:: cpp

	<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:

.. ref-code-block:: cpp

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





.. _doxid-ui_authoring_1autotoc_md648:

10. Native <tt>UIGridLayout</tt> 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:

.. ref-code-block:: cpp

	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:

.. ref-code-block:: cpp

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

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





.. _doxid-ui_authoring_1autotoc_md650:

11. <tt>UIFlowLayout</tt>
~~~~~~~~~~~~~~~~~~~~~~~~~

``UIFlowLayout`` is eepp's native wrapping flow layout.

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

.. ref-code-block:: cpp

	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:

.. ref-code-block:: cpp

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





.. _doxid-ui_authoring_1autotoc_md651:

12. <tt>UISplitter</tt> and workspace layout
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

For resizable application panes, use ``UISplitter``.

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

Typical uses:

.. ref-code-block:: cpp

	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.





.. _doxid-ui_authoring_1autotoc_md653:

13. Margins and padding
~~~~~~~~~~~~~~~~~~~~~~~

The distinction follows the usual box-model intuition:

.. ref-code-block:: cpp

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

Typical native layout usage:

.. ref-code-block:: cpp

	<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:

.. ref-code-block:: cpp

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





.. _doxid-ui_authoring_1autotoc_md655:

14. Use <tt>dp</tt> for application UI dimensions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

eepp uses device-independent pixels:

.. ref-code-block:: cpp

	dp

for scalable application UI metrics.

Examples:

.. ref-code-block:: cpp

	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.





.. _doxid-ui_authoring_1autotoc_md657:

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:

.. ref-code-block:: cpp

	.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.





.. _doxid-ui_authoring_1autotoc_md659:

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

For ordinary application UI, avoid defaulting to:

.. ref-code-block:: cpp

	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:

.. ref-code-block:: cpp

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

Bad default reasoning:

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

Preferred eepp reasoning:

.. ref-code-block:: cpp

	UISplitter
	or
	nested native layouts

depending on whether the divider must be user-resizable.





.. _doxid-ui_authoring_1autotoc_md661:

17. HTML layout is appropriate when rendering HTML
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

When working inside:

.. ref-code-block:: cpp

	UIWebView
	UIMarkdownView
	HTML document content
	HTML-compatible rich content

use normal web-layout reasoning where supported.

There:

.. ref-code-block:: cpp

	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.





.. _doxid-ui_authoring_1autotoc_md663:

18. Choose layouts by behavior
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Use this decision guide.



.. _doxid-ui_authoring_1autotoc_md664:

Need a vertical sequence?
-------------------------

Use:

.. ref-code-block:: cpp

	<vbox>





.. _doxid-ui_authoring_1autotoc_md666:

Need a horizontal sequence?
---------------------------

Use:

.. ref-code-block:: cpp

	<hbox>





.. _doxid-ui_authoring_1autotoc_md668:

Need one child to consume leftover space?
-----------------------------------------

Use ``layout-weight`` on the linear-layout axis.

Horizontal:

.. ref-code-block:: cpp

	layout_width="0dp"
	layout_weight="1"

Vertical:

.. ref-code-block:: cpp

	layout_height="0dp"
	layout_weight="1"





.. _doxid-ui_authoring_1autotoc_md670:

Need resizable panes?
---------------------

Use:

.. ref-code-block:: cpp

	UISplitter





.. _doxid-ui_authoring_1autotoc_md672:

Need tabs/workspace splitting?
------------------------------

Use:

.. ref-code-block:: cpp

	UITabWidget
	UITabWidgetSplitter





.. _doxid-ui_authoring_1autotoc_md674:

Need children positioned relative to siblings?
----------------------------------------------

Use:

.. ref-code-block:: cpp

	UIRelativeLayout





.. _doxid-ui_authoring_1autotoc_md676:

Need repeated same-sized/weighted grid cells?
---------------------------------------------

Use:

.. ref-code-block:: cpp

	UIGridLayout

not CSS Grid.





.. _doxid-ui_authoring_1autotoc_md678:

Need items to flow horizontally and wrap?
-----------------------------------------

Use:

.. ref-code-block:: cpp

	UIFlowLayout

This is the canonical native eepp flow/wrap layout.





.. _doxid-ui_authoring_1autotoc_md680:

Need document/web flow?
-----------------------

Use the HTML compatibility system through:

.. ref-code-block:: cpp

	UIWebView
	UIMarkdownView







.. _doxid-ui_authoring_1autotoc_md682:

19. Canonical application patterns
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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



.. _doxid-ui_authoring_1autotoc_md684:

Pattern: form row
-----------------

.. ref-code-block:: cpp

	<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:

.. ref-code-block:: cpp

	src/examples/ui_data_handling/ui_data_handling.cpp





.. _doxid-ui_authoring_1autotoc_md686:

Pattern: header + flexible content + footer
-------------------------------------------

.. ref-code-block:: cpp

	<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.





.. _doxid-ui_authoring_1autotoc_md688:

Pattern: actions aligned to the right
-------------------------------------

.. ref-code-block:: cpp

	<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:

.. ref-code-block:: cpp

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

Follow the existing component's style.





.. _doxid-ui_authoring_1autotoc_md690:

Pattern: settings UI
--------------------

Prefer reusable framework facilities where available.

eepp now provides:

.. ref-code-block:: cpp

	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.





.. _doxid-ui_authoring_1autotoc_md692:

Pattern: application charts
---------------------------

eepp provides:

.. ref-code-block:: cpp

	UIChart

with framework-level charting behavior.

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

See:

.. ref-code-block:: cpp

	docs/articles/ui_charts.md

and eproc for a production consumer.







.. _doxid-ui_authoring_1autotoc_md694:

20. Common agent mistakes
~~~~~~~~~~~~~~~~~~~~~~~~~



.. _doxid-ui_authoring_1autotoc_md695:

Mistake: using browser Flexbox for an application toolbar
---------------------------------------------------------

Avoid:

.. ref-code-block:: cpp

	.toolbar {
	    display: flex;
	}

for ordinary application UI.

Prefer:

.. ref-code-block:: cpp

	<hbox class="toolbar">





.. _doxid-ui_authoring_1autotoc_md697:

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.





.. _doxid-ui_authoring_1autotoc_md699:

Mistake: setting <tt>gravity</tt> 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.





.. _doxid-ui_authoring_1autotoc_md701:

Mistake: weight without zero size on the weighted axis
------------------------------------------------------

Avoid:

.. ref-code-block:: cpp

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

Preferred:

.. ref-code-block:: cpp

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

For a vertical layout, use height ``0dp``.





.. _doxid-ui_authoring_1autotoc_md703:

Mistake: fixed sizing to solve parent-layout problems
-----------------------------------------------------

Before forcing:

.. ref-code-block:: cpp

	layout_width="417dp"

inspect:

.. ref-code-block:: cpp

	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.





.. _doxid-ui_authoring_1autotoc_md705:

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.





.. _doxid-ui_authoring_1autotoc_md707:

Mistake: treating <tt>UIFlowLayout</tt> 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.







.. _doxid-ui_authoring_1autotoc_md709:

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:

.. ref-code-block:: cpp

	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:

.. ref-code-block:: cpp

	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.





.. _doxid-ui_authoring_1autotoc_md711:

22. Debugging a wrong size
~~~~~~~~~~~~~~~~~~~~~~~~~~

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

.. ref-code-block:: cpp

	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.





.. _doxid-ui_authoring_1autotoc_md713:

23. Debugging wrong alignment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Inspect:

.. ref-code-block:: cpp

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

Remember:

.. ref-code-block:: cpp

	gravity
	    content inside widget
	
	layout-gravity
	    widget placement in parent layout





.. _doxid-ui_authoring_1autotoc_md715:

24. Debugging weighted layouts
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

For a horizontal ``hbox`` :

.. ref-code-block:: cpp

	weighted dimension = width

Expected flexible-child pattern:

.. ref-code-block:: cpp

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

For a vertical ``vbox`` :

.. ref-code-block:: cpp

	weighted dimension = height

Expected pattern:

.. ref-code-block:: cpp

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

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





.. _doxid-ui_authoring_1autotoc_md717:

25. Debugging <tt>UIWebView</tt>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A ``UIWebView`` document is a separate nested scene.

An application-scene query does not cross into it.

Workflow:

.. ref-code-block:: cpp

	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.





.. _doxid-ui_authoring_1autotoc_md719:

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:

.. ref-code-block:: cpp

	src/tools/ecode/

Useful starting points include:

.. ref-code-block:: cpp

	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:

.. ref-code-block:: cpp

	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:

.. ref-code-block:: cpp

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





.. _doxid-ui_authoring_1autotoc_md721:

27. Source priority for agents
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

.. ref-code-block:: cpp

	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.





.. _doxid-ui_authoring_1autotoc_md723:

28. When modifying existing UI
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

Before editing:

.. ref-code-block:: cpp

	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:

.. ref-code-block:: cpp

	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.





.. _doxid-ui_authoring_1autotoc_md725:

29. Runtime verification is expected
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

Preferred closed-loop workflow:

.. ref-code-block:: cpp

	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.





.. _doxid-ui_authoring_1autotoc_md727:

30. Do not create a second mental model unnecessarily
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

For ordinary eepp application UI, think:

.. ref-code-block:: cpp

	native widgets
	+
	native layouts
	+
	CSS styling

Do not think:

.. ref-code-block:: cpp

	HTML page rendered as desktop UI

unless you are actually working in the HTML compatibility layer.

This single distinction prevents many layout mistakes.





.. _doxid-ui_authoring_1autotoc_md729:

31. Quick reference
~~~~~~~~~~~~~~~~~~~



.. _doxid-ui_authoring_1autotoc_md730:

Preferred ordinary UI containers
--------------------------------

.. ref-code-block:: cpp

	<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





.. _doxid-ui_authoring_1autotoc_md731:

Core sizing
-----------

.. ref-code-block:: cpp

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





.. _doxid-ui_authoring_1autotoc_md732:

Alignment
---------

.. ref-code-block:: cpp

	gravity            content inside widget
	layout-gravity     widget against parent layout





.. _doxid-ui_authoring_1autotoc_md733:

Styling
-------

.. ref-code-block:: cpp

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





.. _doxid-ui_authoring_1autotoc_md734:

HTML
----

.. ref-code-block:: cpp

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





.. _doxid-ui_authoring_1autotoc_md735:

Debugging
---------

.. ref-code-block:: cpp

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