Class LayoutMap
- java.lang.Object
-
- com.jgoodies.forms.layout.LayoutMap
-
public final class LayoutMap extends java.lang.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")
ornew 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 usingnew 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 Name Abbreviations Orientation Description label-component-gap lcg, lcgap both gap between a label and the labeled component related-gap rg, rgap both gap between two related components unrelated-gap ug, ugap both gap between two unrelated components button b horizontal button column with minimum width line-gap lg, lgap vertical gap between two lines narrow-line-gap nlg, nlgap vertical narrow gap between two lines paragraph pg, pgap vertical gap 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:
- You should carefully override predefined variables, because variable users may expect that these don't change.
- Set custom variables in the root LayoutMap.
- Avoid aliases for custom variables.
- Since:
- 1.2
- Version:
- $Revision: 1.24 $
- See Also:
FormLayout
,ColumnSpec
,RowSpec
-
-
Field Summary
Fields Modifier and Type Field Description private static java.util.Map<java.lang.String,java.lang.String>
COLUMN_ALIASES
Maps column aliases to their default name, for example"rgap"
->"related-gap"
.private java.util.Map<java.lang.String,java.lang.String>
columnMap
Holds the raw associations from variable names to expressions.private java.util.Map<java.lang.String,java.lang.String>
columnMapCache
Holds the cached associations from variable names to expressions.private LayoutMap
parent
Refers to the parent map that is used to look up values if this map contains no association for a given key.private static LayoutMap
root
Holds the lazily initialized root map.private static java.util.Map<java.lang.String,java.lang.String>
ROW_ALIASES
Maps row aliases to their default name, for example"rgap"
->"related-gap"
.private java.util.Map<java.lang.String,java.lang.String>
rowMap
Holds the raw associations from variable names to expressions.private java.util.Map<java.lang.String,java.lang.String>
rowMapCache
Holds the cached associations from variable names to expressions.private static char
VARIABLE_PREFIX_CHAR
Marks a layout variable; used by the Forms parsers.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description boolean
columnContainsKey(java.lang.String key)
Returnstrue
if this map or a parent map - if any - contains a mapping for the specified key.java.lang.String
columnGet(java.lang.String key)
Looks up and returns the String associated with the given key.java.lang.String
columnPut(java.lang.String key, ColumnSpec value)
java.lang.String
columnPut(java.lang.String key, Size value)
java.lang.String
columnPut(java.lang.String key, java.lang.String value)
Associates the specified column String with the specified key in this map.private void
columnPut(java.lang.String key, java.lang.String[] aliases, ColumnSpec value)
java.lang.String
columnRemove(java.lang.String key)
Removes the column value mapping for this key from this map if it is present.private static LayoutMap
createRoot()
private static void
ensureLowerCase(java.lang.String str)
(package private) java.lang.String
expand(java.lang.String expression, boolean horizontal)
private java.lang.String
expansion(java.lang.String variableName, boolean horizontal)
static LayoutMap
getRoot()
Lazily initializes and returns the LayoutMap that is used for variable expansion, if no custom LayoutMap is provided.private static java.lang.String
nextVariableName(java.lang.String expression, int start)
private static java.lang.String
resolveColumnKey(java.lang.String key)
private static java.lang.String
resolveRowKey(java.lang.String key)
boolean
rowContainsKey(java.lang.String key)
Returnstrue
if this map or a parent map - if any - contains a RowSpec mapping for the specified key.java.lang.String
rowGet(java.lang.String key)
Looks up and returns the RowSpec associated with the given key.java.lang.String
rowPut(java.lang.String key, RowSpec value)
Associates the specified ColumnSpec with the specified key in this map.java.lang.String
rowPut(java.lang.String key, Size value)
java.lang.String
rowPut(java.lang.String key, java.lang.String value)
private void
rowPut(java.lang.String key, java.lang.String[] aliases, RowSpec value)
java.lang.String
rowRemove(java.lang.String key)
Removes the row value mapping for this key from this map if it is present.private static java.lang.String
stripBraces(java.lang.String variableName)
java.lang.String
toString()
Returns a string representation of this LayoutMap that lists the column and row associations.
-
-
-
Field Detail
-
VARIABLE_PREFIX_CHAR
private static final char VARIABLE_PREFIX_CHAR
Marks a layout variable; used by the Forms parsers.- See Also:
- Constant Field Values
-
COLUMN_ALIASES
private static final java.util.Map<java.lang.String,java.lang.String> COLUMN_ALIASES
Maps column aliases to their default name, for example"rgap"
->"related-gap"
.
-
ROW_ALIASES
private static final java.util.Map<java.lang.String,java.lang.String> ROW_ALIASES
Maps row aliases to their default name, for example"rgap"
->"related-gap"
.
-
root
private static LayoutMap root
Holds the lazily initialized root map.
-
parent
private final LayoutMap parent
Refers to the parent map that is used to look up values if this map contains no association for a given key. The parent maps can build chains.
-
columnMap
private final java.util.Map<java.lang.String,java.lang.String> columnMap
Holds the raw associations from variable names to expressions. The expression may contain variables that are not expanded.
-
columnMapCache
private final java.util.Map<java.lang.String,java.lang.String> columnMapCache
Holds the cached associations from variable names to expressions. The expression are fully expanded and contain no variables.
-
rowMap
private final java.util.Map<java.lang.String,java.lang.String> rowMap
Holds the raw associations from variable names to expressions. The expression may contain variables that are not expanded.
-
rowMapCache
private final java.util.Map<java.lang.String,java.lang.String> rowMapCache
Holds the cached associations from variable names to expressions. The expression are fully expanded and contain no variables.
-
-
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 benull
-
-
Method Detail
-
getRoot
public static LayoutMap getRoot()
Lazily initializes and returns the LayoutMap that is used for variable expansion, if no custom LayoutMap is provided.- Returns:
- the LayoutMap that is used, if no custom LayoutMap is provided
-
columnContainsKey
public boolean columnContainsKey(java.lang.String key)
Returnstrue
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:
true
if this map contains a column mapping for the specified key.- Throws:
java.lang.NullPointerException
- if the key isnull
.- See Also:
Map.containsKey(Object)
-
columnGet
public java.lang.String columnGet(java.lang.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
key
, ornull
if no LayoutMap in the parent chain contains an association. - Throws:
java.lang.NullPointerException
- ifkey
isnull
- See Also:
Map.get(Object)
-
columnPut
public java.lang.String columnPut(java.lang.String key, java.lang.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
value
must not benull
. To remove an association from this map usecolumnRemove(String)
.- 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
null
if there was no mapping for key. - Throws:
java.lang.NullPointerException
- if thekey
orvalue
isnull
.- See Also:
Map.put(Object, Object)
-
columnPut
public java.lang.String columnPut(java.lang.String key, ColumnSpec value)
-
columnPut
public java.lang.String columnPut(java.lang.String key, Size value)
-
columnRemove
public java.lang.String columnRemove(java.lang.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
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
null
if there was no mapping for key. - Throws:
java.lang.NullPointerException
- ifkey
isnull
.- See Also:
Map.remove(Object)
-
rowContainsKey
public boolean rowContainsKey(java.lang.String key)
Returnstrue
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:
true
if this map contains a row mapping for the specified key.- Throws:
java.lang.NullPointerException
- if the key isnull
.- See Also:
Map.containsKey(Object)
-
rowGet
public java.lang.String rowGet(java.lang.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
key
, ornull
if no LayoutMap in the parent chain contains an association. - Throws:
java.lang.NullPointerException
- ifkey
isnull
- See Also:
Map.get(Object)
-
rowPut
public java.lang.String rowPut(java.lang.String key, java.lang.String value)
-
rowPut
public java.lang.String rowPut(java.lang.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
null
. To remove an association from this map userowRemove(String)
.- 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
null
if there was no mapping for key. - Throws:
java.lang.NullPointerException
- if thekey
orvalue
isnull
.- See Also:
Map.put(Object, Object)
-
rowPut
public java.lang.String rowPut(java.lang.String key, Size value)
-
rowRemove
public java.lang.String rowRemove(java.lang.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
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
null
if there was no mapping for key. - Throws:
java.lang.NullPointerException
- ifkey
isnull
.- See Also:
Map.remove(Object)
-
toString
public java.lang.String toString()
Returns a string representation of this LayoutMap that lists the column and row associations.- Overrides:
toString
in classjava.lang.Object
- Returns:
- a string representation
-
expand
java.lang.String expand(java.lang.String expression, boolean horizontal)
-
nextVariableName
private static java.lang.String nextVariableName(java.lang.String expression, int start)
-
expansion
private java.lang.String expansion(java.lang.String variableName, boolean horizontal)
-
stripBraces
private static java.lang.String stripBraces(java.lang.String variableName)
-
resolveColumnKey
private static java.lang.String resolveColumnKey(java.lang.String key)
-
resolveRowKey
private static java.lang.String resolveRowKey(java.lang.String key)
-
createRoot
private static LayoutMap createRoot()
-
columnPut
private void columnPut(java.lang.String key, java.lang.String[] aliases, ColumnSpec value)
-
rowPut
private void rowPut(java.lang.String key, java.lang.String[] aliases, RowSpec value)
-
ensureLowerCase
private static void ensureLowerCase(java.lang.String str)
-
-