com.jgoodies.forms.layout

Class LayoutMap

public final class LayoutMap extends Object

Provides a hierarchical variable expansion useful to improve layout consistency, style guide compliance, and layout readability.

A LayoutMap maps variable names to layout expression Strings. The FormLayout, ColumnSpec, and RowSpec parsers expand variables before an encoded layout specification is parsed and converted into ColumnSpec and RowSpec values. Variables start with the '$' character. The variable name can be wrapped by braces ('{' and '}'). For example, you can write: new FormLayout("pref, $lcg, pref",) or new FormLayout("pref, ${lcg}, pref").

LayoutMaps build a chain; each LayoutMap has an optional parent map. The root is defined by getRoot. Application-wide variables should be defined in the root LayoutMap. If you want to override application-wide variables locally, obtain a LayoutMap using {@code new LayoutMap()}, configure it, and provide it as argument to the FormLayout, ColumnSpec, and RowSpec constructors/factory methods.

By default the root LayoutMap provides the following associations:

Variable NameAbbreviationsValue
label-component-gaplcg, lcgapgap between a label and its component
related-gaprg, rgapgap between two related components
unrelated-gapug, ugapgap between two unrelated components
line-gaplg, lgapgap between two lines
narrow-line-gapnlg, nlgapnarrow gap between two lines
paragraphpg, pgapgap between two paragraphs/sections

Examples:

 // Predefined variables
 new FormLayout(
     "pref, $lcgap, pref, $rgap, pref",
     "p, $lgap, p, $lgap, p");

 // Custom variables
 LayoutMap.getRoot().columnPut("half", "39dlu");
 LayoutMap.getRoot().columnPut("full", "80dlu");
 LayoutMap.getRoot().rowPut("table", "fill:0:grow");
 LayoutMap.getRoot().rowPut("table50", "fill:50dlu:grow");
 new FormLayout(
     "pref, $lcgap, $half, 2dlu, $half",
     "p, $lcgap, $table50");
 new FormLayout(
     "pref, $lcgap, $full",
     "p, $lcgap, $table50");

 // Nested variables
 LayoutMap.getRoot().columnPut("c-gap-c", "$half, 2dlu, $half");
 new FormLayout(
     "pref, $lcgap, ${c-gap-c}", // -> "pref, $lcgap, $half, 2dlu, $half",
     "p, $lcgap, $table");
 
LayoutMap holds two internal Maps that associate key Strings with expression Strings for the columns and rows respectively. Null values are not allowed.

Tips:

Since: 1.2

Version: $Revision: 1.14 $

Author: Karsten Lentzsch

See Also: FormLayout ColumnSpec

Constructor Summary
LayoutMap()
Constructs a LayoutMap that has the root LayoutMap as parent.
LayoutMap(LayoutMap parent)
Constructs a LayoutMap with the given optional parent.
Method Summary
booleancolumnContainsKey(String key)
Returns {@code true} if this map or a parent map - if any - contains a mapping for the specified key.
StringcolumnGet(String key)
Looks up and returns the String associated with the given key.
StringcolumnPut(String key, String value)
Associates the specified column String with the specified key in this map.
StringcolumnPut(String key, ColumnSpec value)
StringcolumnPut(String key, Size value)
StringcolumnRemove(String key)
Removes the column value mapping for this key from this map if it is present.

Returns the value to which the map previously associated the key, or {@code null} if the map contained no mapping for this key.

static LayoutMapgetRoot()
Lazily initializes and returns the LayoutMap that is used for variable expansion, if no custom LayoutMap is provided.

The root LayoutMap is stored in the UIManager that in turn uses an AppContext to store the values.

booleanrowContainsKey(String key)
Returns {@code true} if this map or a parent map - if any - contains a RowSpec mapping for the specified key.
StringrowGet(String key)
Looks up and returns the RowSpec associated with the given key.
StringrowPut(String key, String value)
StringrowPut(String key, RowSpec value)
Associates the specified ColumnSpec with the specified key in this map.
StringrowPut(String key, Size value)
StringrowRemove(String key)
Removes the row value mapping for this key from this map if it is present.

Returns the value to which the map previously associated the key, or {@code null} if the map contained no mapping for this key.

StringtoString()
Returns a string representation of this LayoutMap that lists the column and row associations.

Constructor Detail

LayoutMap

public LayoutMap()
Constructs a LayoutMap that has the root LayoutMap as parent.

LayoutMap

public LayoutMap(LayoutMap parent)
Constructs a LayoutMap with the given optional parent.

Parameters: parent the parent LayoutMap, may be {@code null}

Method Detail

columnContainsKey

public boolean columnContainsKey(String key)
Returns {@code true} if this map or a parent map - if any - contains a mapping for the specified key.

Parameters: key key whose presence in this LayoutMap chain is to be tested.

Returns: {@code true} if this map contains a column mapping for the specified key.

Throws: NullPointerException if the key is {@code null}.

See Also: Map#containsKey(Object)

columnGet

public String columnGet(String key)
Looks up and returns the String associated with the given key. First looks for an association in this LayoutMap. If there's no association, the lookup continues with the parent map - if any.

Parameters: key key whose associated value is to be returned.

Returns: the column String associated with the {@code key}, or {@code null} if no LayoutMap in the parent chain contains an association.

Throws: NullPointerException if {@code key} is {@code null}

See Also: Map#get(Object)

columnPut

public String columnPut(String key, String value)
Associates the specified column String with the specified key in this map. If the map previously contained a mapping for this key, the old value is replaced by the specified value. The value set in this map overrides an association - if any - in the chain of parent LayoutMaps.

The {@code value} must not be {@code null}. To remove an association from this map use columnRemove.

Parameters: key key with which the specified value is to be associated. value column expression value to be associated with the specified key.

Returns: previous String associated with specified key, or {@code null} if there was no mapping for key.

Throws: NullPointerException if the {@code key} or {@code value} is {@code null}.

See Also: Map#put(Object, Object)

columnPut

public String columnPut(String key, ColumnSpec value)

columnPut

public String columnPut(String key, Size value)

columnRemove

public String columnRemove(String key)
Removes the column value mapping for this key from this map if it is present.

Returns the value to which the map previously associated the key, or {@code null} if the map contained no mapping for this key. The map will not contain a String mapping for the specified key once the call returns.

Parameters: key key whose mapping is to be removed from the map.

Returns: previous value associated with specified key, or {@code null} if there was no mapping for key.

Throws: NullPointerException if {@code key} is {@code null}.

See Also: Map#remove(Object)

getRoot

public static LayoutMap getRoot()
Lazily initializes and returns the LayoutMap that is used for variable expansion, if no custom LayoutMap is provided.

The root LayoutMap is stored in the UIManager that in turn uses an AppContext to store the values. This way applets in different contexts uses different defaults.

Returns: the LayoutMap that is used, if no custom LayoutMap is provided

rowContainsKey

public boolean rowContainsKey(String key)
Returns {@code true} if this map or a parent map - if any - contains a RowSpec mapping for the specified key.

Parameters: key key whose presence in this LayoutMap chain is to be tested.

Returns: {@code true} if this map contains a row mapping for the specified key.

Throws: NullPointerException if the key is {@code null}.

See Also: Map#containsKey(Object)

rowGet

public String rowGet(String key)
Looks up and returns the RowSpec associated with the given key. First looks for an association in this LayoutMap. If there's no association, the lookup continues with the parent map - if any.

Parameters: key key whose associated value is to be returned.

Returns: the row specification associated with the {@code key}, or {@code null} if no LayoutMap in the parent chain contains an association.

Throws: NullPointerException if {@code key} is {@code null}

See Also: Map#get(Object)

rowPut

public String rowPut(String key, String value)

rowPut

public String rowPut(String key, RowSpec value)
Associates the specified ColumnSpec with the specified key in this map. If the map previously contained a mapping for this key, the old value is replaced by the specified value. The RowSpec set in this map override an association - if any - in the chain of parent LayoutMaps.

The RowSpec must not be {@code null}. To remove an association from this map use rowRemove.

Parameters: key key with which the specified value is to be associated. value ColumnSpec to be associated with the specified key.

Returns: previous ColumnSpec associated with specified key, or {@code null} if there was no mapping for key.

Throws: NullPointerException if the {@code key} or {@code value} is {@code null}.

See Also: Map#put(Object, Object)

rowPut

public String rowPut(String key, Size value)

rowRemove

public String rowRemove(String key)
Removes the row value mapping for this key from this map if it is present.

Returns the value to which the map previously associated the key, or {@code null} if the map contained no mapping for this key. The map will not contain a String mapping for the specified key once the call returns.

Parameters: key key whose mapping is to be removed from the map.

Returns: previous value associated with specified key, or {@code null} if there was no mapping for key.

Throws: NullPointerException if {@code key} is {@code null}.

See Also: Map#remove(Object)

toString

public String toString()
Returns a string representation of this LayoutMap that lists the column and row associations.

Returns: a string representation

Copyright © 2002-2008 JGoodies Karsten Lentzsch. All Rights Reserved.