Widget Insertion

Working with Widgets

Most widgets (button, checkbox, child...) can be placed onto the window in several ways:

• standard layout mode - widget will be placed either in the same row or create a new row
• column layout mode - widgets will be placed in columns that is the x-coordinate of leftmost widgets in the column are equal. Two widgets currently support column mode layout (Child, Table).
• free-positioning mode - widget will be aligned to the parent's window corner and it will float above other widgets

Size of the widgets in each dimension can be either:

• fixed
• anchored to the parent's right/bottom edge
• stretched in a box layout

Widget Placement

Standard Layout

This is the default layout supported by ImRAD.

New widget can be placed to the side of an existing widget (ImGui::SameLine) or as the first widget in the new row above or below. Window padding and spacing is respected. After selecting new widget from the Palette move cursor over the window and observe that horizontal / vertical / rectangular marker appears.

Rectangular marker is shown when the widget is going to be the first widget in its parent:

Vertical marker is shown when widget will be placed in the same row:

Horizontal marker is shown when the widget will be placed in a new row:

When widget is placed inside another widget (such as Child widget) markers change color to denote the parent is different:

Column Layout

Columns layout widgets in such a way that first widgets on each row in the column will be positioned on the same x-coordinate. Columns themselves contain widgets in a standard row layout.

Currently these two widgets allow to layout their children in columns:

• Child - uses original ImGui column functionality which ImGui probably deprecated by now but it can still be occasionally useful. You can specify column count and optional column border.

• Table - uses configurable columns which allow to specify stretch or fixed policy through the Table Columns dialog. When table borders and header is hidden Table can be used as a general layouting mechanism. In simple cases such Table can be created automatically by using the Table Layout Helper from the toolbar but usually box layouts as introduced in ImRAD 0.8 are a more natural option.

To use column layout first set the column properties in one of these two parent widgets. Then when you are inserting a child widget follow the markers as usual. To specify the widget belongs to the next column set its nextColumn property. This will also shift all subsequent widgets to their next columns:

Here the new widget will be inserted as last in the first column. If you set its nextColumn it will move the widget to the next column and other widgets will be shifted too (because currently the nextColumn property of the next widget is not reset). The checkbox from the last column will move into the first column but second row.

Free Positioning

When inserting a widget press and hold the Ctrl key. The mouse cursor will change into crosshair and rectangular marker will appear to denote the selected parent widget. When a widget is inserted it will take the closest parent's corner as a reference so even when parent's size changes the distance to the referenced corner will be kept constant. Which corner is referenced is denoted by the small triangle sitting at one of the widget's corners:

Alternatively you can switch a widget into free positioning by checking its overlayPos property. Positivity or negativity of pos_x/y values will determine the referenced parent corner.

Holding Ctrl will work even when copy pasting widget from clipboard.

.

Padding - Spacing - Indent

The benefit of standard and column layout is inserted widgets will always respect window padding (gap between the parent borders and widget) and spacing (inner gap between widgets). This way your dialogs stay consistent.

You can edit these values in parent widget style property or globally in the custom style INI file. You can also specify a gap in multiplies of these values by using the widget spacing/indent property.

.

Widget's Size

Some widgets don't allow to specify size at all f.e. Text, Checkbox or Radio Button widgets. It's because ImGui calculates size from their label dimensions (use Selectable as a Text widget replacement when setting size or alignment is required).

Some widgets like Input, Combo allow to specify horizontal size_x only.

Several other widgets allow to set both size_x and size_y. For example Multiline Input, Child, Table and Spacer

For size_x/y ImRAD follows ImGui convention which is:

• size_x > 0 specifies fixed width. For example ImRAD sets Input's size_x=200 by default.

• size_x < 0 specifies anchoring to the right border of the parent widget. You can use this to make the widget stretch but leave a gap which stays constant when window size changes. Setting size_x = -1 (e.g. the smallest negative value) can be interpreted as a full stretch as 1px gap is not noticeable by the user and it is often used for this purpose. Anchoring is the easiest way how to achieve widget stretch.

  

  Anchoring can also be activated by resizing the widget with mouse and bringing widget's edge to the parent's edge. Parent's edge is visualized with a red background.

  The disadvantage of anchoring is it only works well for the widget who comes last in its row/column. If the widget is not last in its row one has to know the size of following widgets to leave enough gap for them.

• size_x = 0 requests some sort of default width but the exact meaning can differ from widget to widget as implemented in ImGui. For example:

  • Button size_x=0 will cause the size to be calculated from its label dimension (you can add adjust frame padding to achieve margins).

  • Table size_x=0 means take all available width (anchoring).

  • Input size_x=0 means take all available width except a fixed gap for a potential label on the right side of the widget (anchoring).

  Because in ImGui the meaning of zero size value varies I don't recommend to use it for anchoring at all.

• size_x = stretch

  This is a part of a new box layout mechanism which was first introduced in ImRAD 0.8. Box layout is more flexible than anchoring and Table Layout because it

  • works both in horizontal and vertical direction
  • allows to stretch multiple widgets at once
  • stretched widgets don't need to come last in their rows/columns

  The downside is box layouts are implemented on top of ImGui functionality so slightly more code will be generated when used.

  

  To use box layouts simply set some of the widget sizes to stretch. Box layout will dynamically calculate position and size of widgets depending on available content width.

  To achieve widget alignment insert a Spacer widget. Spacer is a widget which only takes space and its dimensions can also be stretched.

.

Dialog Units

All the overlay positions and all size values are set in chosen dialog units. The default unit for a new winow is px (pixel) and the default unit for Android Activity is dp (device independent pixel) but you can change it from the toolbar.

dp is meant to be roughly equal to the px on a medium density screen. On devices with different screen density (such as phones) a custom scaling factor is applied. Switching dialog unit to dp causes the generated code to multiply dimension values by ImRad::IOUserData::dpiScale. If you let ImRAD to generate Android main.cpp you can see the dpiScale is calculated from device DPI.

DPI aware UI should:

• Use dp units in all windows
• Calculate IOUserData::dpiScale factor from your screen density (generated android main.cpp does this for you)
• Scale style dimension values such as padding, spacing by calling ImGuiStyle::ScaleAllSizes (generated android main.cpp does this for you).
• Scale fonts upon loading (generated android main.cpp does this for you).