Class 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") 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 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 NameAbbreviationsOrientationDescription
    label-component-gaplcg, lcgapbothgap between a label and the labeled component
    related-gaprg, rgapbothgap between two related components
    unrelated-gapug, ugapbothgap between two unrelated components
    buttonbhorizontalbutton column with minimum width
    line-gaplg, lgapverticalgap between two lines
    narrow-line-gapnlg, nlgapverticalnarrow gap between two lines
    paragraphpg, pgapverticalgap 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.
    • Constructor Summary

      Constructors 
      Constructor Description
      LayoutMap()
      Constructs a LayoutMap that has the root LayoutMap as parent.
      LayoutMap​(LayoutMap parent)
      Constructs a LayoutMap with the given optional parent.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      boolean columnContainsKey​(java.lang.String key)
      Returns true 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)
      Returns true 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.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
    • 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 be null
    • 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)
        Returns 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:
        true if this map contains a column mapping for the specified key.
        Throws:
        java.lang.NullPointerException - if the key is null.
        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, or null if no LayoutMap in the parent chain contains an association.
        Throws:
        java.lang.NullPointerException - if key is null
        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 be null. To remove an association from this map use columnRemove(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 the key or value is null.
        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 - if key is null.
        See Also:
        Map.remove(Object)
      • rowContainsKey

        public boolean rowContainsKey​(java.lang.String key)
        Returns 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:
        true if this map contains a row mapping for the specified key.
        Throws:
        java.lang.NullPointerException - if the key is null.
        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, or null if no LayoutMap in the parent chain contains an association.
        Throws:
        java.lang.NullPointerException - if key is null
        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 use rowRemove(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 the key or value is null.
        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 - if key is null.
        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 class java.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)