JGoodies Forms :: Reference :: Layout Variables
Author: Karsten Lentzsch
Description: The JGoodies Forms helps you layout and implement elegant Panel quickly and consistently.
Keywords: JGoodies Forms Java Layout Swing UI Design Usability Lentzsch Kiel
Date: 2003-07-31

# :: 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 ::=    ${label-component-gap}  | $lcgap    | $lcg
                       ${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");
(c) 2012 JGoodies |  |