:: Reference :: Layout Variables ::

Layout variables are used to use improve the design consistency.

Predefined and custom variables start with a dollar sign ($) and can be surrounded by braces ({ … }). For example $lcgap, ${label-component-gap}, $myvariable1, ${myvariable1}, ${my variable with white space}. If surrounded by braces the variable name can contain hyphens and white-space.

variable ::= $<alphanumeric> | ${<string>}

Predefined Variables

Predefined variables provide access to logical sizes in the Forms' string language. Their values are requested from the current Layout Style.

columnVariable ::= ${label-component-gap}  | $lcgap    | $lcg
                   ${related-gap}          | $rgap     | $rg
                   ${unrelated-gap}        | $ugap     | $ug
                   $button                 | $b
                   ${growing-button}       | $gb
                   ${dialog-margin}        | $dmargin  | $dm
                   ${tabbed-dialog-margin} | $tdmargin | $tdm
                   $glue

rowVariable ::=    ${related-gap}          | $rgap     | $rg
                   ${unrelated-gap}        | $ugap     | $ug
                   ${narrow-line-gap}      | $nlgap    | $nlg
                   ${line-gap}             | $lgap     | $lg
                   ${paragaph-gap}         | $pgap     | $pg
                   ${dialog-margin}        | $dmargin  | $dm
                   ${tabbed-dialog-margin} | $tdmargin | $tdm
                   $button                 | $b
                   $glue

Custom Variables

Custom variables further reduce the costs to achieve consistent design in teams and when implementing many screens. Let's say you want right-aligned labels in all your screens. You would repeat "right:pref" in every individual FormLayout construction. If you introduce a custom variable $label by setting it in the shared root LayoutMap you could later refer to it in the FormLayout constructor

LayoutMap.getRoot().columnPut("label", "right:pref");

new FormLayout("$label, $lcgap, pref", …);

If you setup custom variables, you can honor the platform, locale, and other context information. Let's say you want to ensure a consistent width of all label columns using "right:[85dlu,pref]". The 85dlu will likely waste space in Chinese.

String width = <compute width per Locale>; // e.g. "85dlu" vs. "25dlu"
LayoutMap.getRoot().columnPut("label", "right:[" + width + ", pref]");

Overriding and Changing Variable Values

You can change a predefined variable value globally or locally. Layout variable values are requested from LayoutMaps. There's a shared root LayoutMap available via LayoutMap.getRoot() that is used by default by the FormLayout constructor and other methods that use encoded column and row specifications.

If you re-define a variable value in the root LayoutMap, the change will affect all layouts that use the default LayoutMap. For example: LayoutMap.getRoot().columnPut("lcgap", "1dlu");.

As an alternative you can create a child LayoutMap and use this change locally.

LayoutMap childMap = new LayoutMap();   // has the root map as parent
childMap.columnPut("lcgap", "1dlu");
new FormLayout("&hellip", "&hellip", childMap);     // uses the child map

Examples

LayoutMap map = LayoutMap.getRoot();
map.columnPut("label", "right:[85dlu,pref]");
map.rowPut   ("table", "fill:100dlu:grow");

new FormLayout("right:[85dlu,pref], 3dlu, pref, 3dlu, 50dlu",      // no var
               "p, 3dlu, p, 3dlu, fill:100dlu:grow");
               
new FormLayout("right:[85dlu,pref], $lcgap, pref, $rgap, $button", // vars
               "p, $lgap, p, $lgap, fill:100dlu:grow");
               
new FormLayout("right:[85dlu,pref], $lcg, pref, $rg, $b",          // short
               "p, $lg, p, $lg, fill:100dlu:grow");
               
new FormLayout("$label, $lcgap, pref, $rgap, $button",             // custom vars
               "p, $lgap, p, $lgap, $table");