types
Class GUIAttributes

java.lang.Object
  java.util.AbstractMap<K,V>
      java.util.TreeMap<String,List<String>>
          types.GUIAttributes

All Implemented Interfaces:

Serializable, Cloneable, Map<String,List<String>>, SortedMap<String,List<String>>

public final class GUIAttributes
extends TreeMap<String,List<String>>

A specialized extension of TreeMap which helps in handling widget attributes. Specifically, a GUIAttributes object holds a map with default values for all attributes; has methods to assist in attribute retrieval and parsing; remembers what widget it is associated with; and automates error handling by generating exceptions that, 90% of the time, should be sufficient such that a widget definition doesn't need any explicit error checking.

See Also:

Serialized Form

Field Summary

static Map<String,Boolean>	boolStrings A mapping of acceptible string values for Boolean attributes to their Boolean values.
static Map<String,String>	colorEquivs A mapping of color synonyms to their canonical color names.
static SortedSet<String>	colors The set of acceptable color names (except that colors in colorEquivs are accepted as well).
Map<String,List<String>>	defaults A map of the names of the recognized attributes to their default values.
static Pattern	htmlColorPat The regular expression matching HTML-style color values.
Map<String,List<String>>	multisynonyms A map on multisynonymous attribute names to the names of their component attributes.
Map<String,String>	synonyms A map of synonymous attribute names to their canonical equivalents.
Widget	widget The Widget to which this object belongs.

Constructor Summary

GUIAttributes(Map<String,List<String>> defaults, Map<String,String> synonyms, Map<String,List<String>> multisynonyms, Widget widget)
Construct a GUIAttributes map, given a map of the defaults, a map describing synonymies of the attributes, and the Widget which is to own the map.

GUIAttributes(Map<String,List<String>> defaults, Map<String,String> synonyms, Widget widget)
Construct a GUIAttributes map, given a map of the defaults, a map describing synonymies of the attributes, and the Widget which is to own the map.

GUIAttributes(Map<String,List<String>> defaults, Widget widget)
Construct a GUIAttributes map, given a map of the defaults and the Widget which is to own it.

Method Summary

List<String>	get(Object attr) Deprecated. Use getAll(java.lang.String) instead; it typechecks its argument and throws suitable exceptions on invalid attribute values. Better yet, use one of getString(java.lang.String), getStrings(java.lang.String), getInteger(java.lang.String), etc., as needed. This method is only meant to allow GUIAttributes objects to be cast to Maps and still work (somewhat).
List<String>	getAll(String attr) Retrieve all values of an attribute by name, as strings.
boolean	getBoolean(String attr) Retrieve, as a boolean, the value of an attribute which only allows one value.
List<Boolean>	getBooleans(String attr) Retrieve all values of an attribute as booleans.
String	getColor(String attr) Retrieve, as a color identifier, the value of an attribute which only allows one value.
List<String>	getColors(String attr) Retrieve all values of a color attribute as identifier strings suitable for use in generated code.
double	getDouble(String attr) Retrieve, as a double, the value of an attribute which only allows one value.
List<Double>	getDoubles(String attr) Retrieve all values of an attribute as doubles.
<E extends Enum> E	getEnum(String attr, Class<E> cls) Retrieve, as an enumeration constant, the value of an attribute which only allows one value.
<E extends Enum> List<E>	getEnums(String attr, Class<E> cls) Retrieve all values of an attribute as enumeration constants.
float	getFloat(String attr) Retrieve, as a double, the value of an attribute which only allows one value.
List<Float>	getFloats(String attr) Retrieve all values of an attribute as doubles.
int	getInteger(String attr) Retrieve, as an integer, the value of an attribute which only allows one value.
Pair<Integer,Integer>	getIntegerPair(String attr) Retrieve, as a pair of integers, the value of an attribute which only allows exactly two values.
List<Integer>	getIntegers(String attr) Retrieve all values of an attribute as integers.
List<String>	getMany(String attr, int quantity) Retrieve all values of an attribute which allows exactly N values, for some N.
String	getOne(String attr) Retrieve the value of an attribute which only allows one value.
String	getString(String attr) Retrieve, as a string, the value of an attribute which only allows one value.
List<String>	getStrings(String attr) Retrieve all values of an attribute as strings.
boolean	hasValue(String attr) Test to see if an attribute has a value (i.e.
boolean	parseBoolean(String attr, String value) Parse a string as a boolean attribute value, as getBoolean(java.lang.String) would.
String	parseColor(String attr, String value) Parse a string as a color value, as getColor(java.lang.String) would.
double	parseDouble(String attr, String value) Parse a string as a double attribute value, as getDouble(java.lang.String) would.
<E extends Enum> E	parseEnum(String attr, String value, Class<E> cls) Parse a string as an enumeration constaint, as getEnum(java.lang.String, java.lang.Class) would.
float	parseFloat(String attr, String value) Parse a string as a float attribute value, as getFloat(java.lang.String) would.
int	parseInteger(String attr, String value) Parse a string as an integer attribute value, as getInteger(java.lang.String) would.
List<String>	put(String attr, List<String> values) Deprecated. Use putAttribute(String, String[]) when possible, as it throws the proper checked exception, BadAttributeNameException, on error. This method is only provided for compatibility with the base class.
void	putAllAttributes(Map<String,? extends List<String>> attrs)
List<String>	putAttribute(String attr, List<String> values) Add an attribute, with arbitrarily many values, to this map.
List<String>	putAttribute(String attr, String... values) Add an attribute, with arbitrarily many values, to this map.

Methods inherited from class java.util.TreeMap

clear, clone, comparator, containsKey, containsValue, entrySet, firstKey, headMap, keySet, lastKey, putAll, remove, size, subMap, tailMap, values

Methods inherited from class java.util.AbstractMap

equals, hashCode, isEmpty, toString

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Map

equals, hashCode, isEmpty

Field Detail

defaults

public final Map<String,List<String>> defaults

A map of the names of the recognized attributes to their default values.

synonyms

public final Map<String,String> synonyms

A map of synonymous attribute names to their canonical equivalents.

multisynonyms

public final Map<String,List<String>> multisynonyms

A map on multisynonymous attribute names to the names of their component attributes.

widget

public final Widget widget

The Widget to which this object belongs.

boolStrings

public static final Map<String,Boolean> boolStrings

A mapping of acceptible string values for Boolean attributes to their Boolean values.

colors

public static final SortedSet<String> colors

The set of acceptable color names (except that colors in colorEquivs are accepted as well). Case-insensitive.

colorEquivs

public static final Map<String,String> colorEquivs

A mapping of color synonyms to their canonical color names. Case-insensitive.

htmlColorPat

public static final Pattern htmlColorPat

The regular expression matching HTML-style color values.

Constructor Detail

GUIAttributes

public GUIAttributes(Map<String,List<String>> defaults,
                     Map<String,String> synonyms,
                     Map<String,List<String>> multisynonyms,
                     Widget widget)

Construct a GUIAttributes map, given a map of the defaults, a map describing synonymies of the attributes, and the Widget which is to own the map.

Parameters:

defaults - A map of the names of the recognized attributes to their default values.

synonyms - A map, each entry of which has an attribute name as the key and the real attribute with which it is synonymous as the value.

multisynonyms - A map, each entry of which has an attribute name as the key and the list of real attributes which it maps to as the value. For instance, if giving the "size" attribute a value of two integers is equivalent to giving the "width" and "height" attributes separately, the map would have an entry with key "size" and values "width" and "height".

widget - The Widget to which this object belongs.

GUIAttributes

public GUIAttributes(Map<String,List<String>> defaults,
                     Map<String,String> synonyms,
                     Widget widget)

Construct a GUIAttributes map, given a map of the defaults, a map describing synonymies of the attributes, and the Widget which is to own the map.

Parameters:

defaults - A map of the names of the recognized attributes to their default values.

synonyms - A map, each entry of which has an attribute name as the key and the real attribute with which it is synonymous as the value.

widget - The Widget to which this object belongs.

GUIAttributes

public GUIAttributes(Map<String,List<String>> defaults,
                     Widget widget)

Construct a GUIAttributes map, given a map of the defaults and the Widget which is to own it. The map will have no synonymous attributes (see GUIAttributes(Map, Map, Widget) for this).

Parameters:

defaults - A map of the names of the recognized attributes to their default values.

widget - The Widget to which this object belongs.

Method Detail

putAllAttributes

public void putAllAttributes(Map<String,? extends List<String>> attrs)
                      throws BadAttributeException

Parameters:

attrs - A map of attributes, each of which will be added.

Throws:

BadAttributeNameException - If any of the given attribute names are not valid for this widget.

BadAttributeValueException - If a multisynonymous attribute (see WidgetDef.getMultisynonymousAttributes() has the wrong number of values.

BadAttributeException

putAttribute

public List<String> putAttribute(String attr,
                                 String... values)
                          throws BadAttributeException

Add an attribute, with arbitrarily many values, to this map.

Parameters:

attr - The name of the attribute.

values - Zero or more values for the attribute.

Returns:

The previous values of the attribute, or null if it was at its default setting.

Throws:

BadAttributeNameException - If the attribute name is not recognized (see defaults).

BadAttributeValueException - If the attribute is a multisynonym (see WidgetDef.getMultisynonymousAttributes()) with the wrong number of values.

BadAttributeException

putAttribute

public List<String> putAttribute(String attr,
                                 List<String> values)
                          throws BadAttributeException

Add an attribute, with arbitrarily many values, to this map.

Parameters:

attr - The name of the attribute.

values - A list of values for the attribute.

Returns:

The previous values of the attribute, or null if it was at its default value.

Throws:

BadAttributeNameException - If the attribute name is not recognized (see defaults).

BadAttributeException

put

@Deprecated
public List<String> put(String attr,
                                   List<String> values)

Deprecated. Use putAttribute(String, String[]) when possible, as it throws the proper checked exception, BadAttributeNameException, on error. This method is only provided for compatibility with the base class.

Add an attribute to this map.

Specified by:

put in interface Map<String,List<String>>

Overrides:

put in class TreeMap<String,List<String>>

Parameters:

attr - The name of the attribute.

values - A list of its values.

Returns:

The previous values of the attribute, or null if it was at its default setting.

Throws:

IllegalArgumentException - If the attribute name is not recognized (see defaults).

get

@Deprecated
public List<String> get(Object attr)

Deprecated. Use getAll(java.lang.String) instead; it typechecks its argument and throws suitable exceptions on invalid attribute values. Better yet, use one of getString(java.lang.String), getStrings(java.lang.String), getInteger(java.lang.String), etc., as needed. This method is only meant to allow GUIAttributes objects to be cast to Maps and still work (somewhat).

Retrieve all values of an attribute by name, as strings.

Specified by:

get in interface Map<String,List<String>>

Overrides:

get in class TreeMap<String,List<String>>

Parameters:

attr - The name of the attribute.

Returns:

The values of the attribute, or null if there is no such attribute.

getAll

public List<String> getAll(String attr)
                    throws BadAttributeException

Retrieve all values of an attribute by name, as strings.

Parameters:

attr - The name of the attribute.

Returns:

The values of the attribute, as strings.

Throws:

BadAttributeNameException - If there is no such attribute.

BadAttributeException

getMany

public List<String> getMany(String attr,
                            int quantity)
                     throws BadAttributeException

Retrieve all values of an attribute which allows exactly N values, for some N. Checks to make sure that there are N items in the attribute list.

Parameters:

attr - The name of the atttribute.

quantity - The number of values to require.

Returns:

The values of the attribute.

Throws:

BadAttributeNameException - If there is no such attribute.

BadAttributeValueException - If the attribute has more or fewer values than quantity.

BadAttributeException

getOne

public String getOne(String attr)
              throws BadAttributeException

Retrieve the value of an attribute which only allows one value. Checks to make sure that there is only one item in the attribute list.

Parameters:

attr - The name of the atttribute.

Returns:

The value of the attribute.

Throws:

BadAttributeNameException - If there is no such attribute.

BadAttributeValueException - If the attribute has more than one value.

BadAttributeException

getStrings

public List<String> getStrings(String attr)
                        throws BadAttributeException

Retrieve all values of an attribute as strings. Equivalent to getAll().

Parameters:

attr - The name of the attribute.

Returns:

The values of the attribute, as strings.

Throws:

BadAttributeNameException - If there is no such attribute.

BadAttributeException

getString

public String getString(String attr)
                 throws BadAttributeException

Retrieve, as a string, the value of an attribute which only allows one value. Equivalent to getOne().

Parameters:

attr - The name of the attribute.

Returns:

The value of the attribute, as a string, if it has only one value.

Throws:

BadAttributeNameException - If there is no such attribute.

BadAttributeValueException - If the attribute has more than one value.

BadAttributeException

getIntegers

public List<Integer> getIntegers(String attr)
                          throws BadAttributeException

Retrieve all values of an attribute as integers.

Parameters:

attr - The name of the attribute.

Returns:

The values of the attribute, as integers.

Throws:

BadAttributeNameException - If there is no such attribute.

BadAttributeValueException - If any attribute value fails to parse as an integer.

BadAttributeException

getInteger

public int getInteger(String attr)
               throws BadAttributeException

Retrieve, as an integer, the value of an attribute which only allows one value.

Parameters:

attr - The name of the attribute.

Returns:

The value of the attribute, as an integer, if it has only one value.

Throws:

BadAttributeNameException - If there is no such attribute.

BadAttributeValueException - If the value fails to parse as an integer, or the attribute has more than one value.

BadAttributeException

getIntegerPair

public Pair<Integer,Integer> getIntegerPair(String attr)
                                     throws BadAttributeException

Retrieve, as a pair of integers, the value of an attribute which only allows exactly two values.

Parameters:

attr - The name of the attribute.

Returns:

The value of the attribute, as an integer, if it has only one value.

Throws:

BadAttributeNameException - If there is no such attribute.

BadAttributeValueException - If the value fails to parse as an integer, or the attribute has more than one value.

BadAttributeException

parseInteger

public int parseInteger(String attr,
                        String value)
                 throws BadAttributeValueException

Parse a string as an integer attribute value, as getInteger(java.lang.String) would.

Parameters:

attr - The name of the attribute, passed to the exception if one is thrown.

value - The value to parse.

Returns:

The attribute value, as an integer.

Throws:

BadAttributeValueException - If the value fails to parse as an integer.

getFloats

public List<Float> getFloats(String attr)
                      throws BadAttributeException

Retrieve all values of an attribute as doubles.

Parameters:

attr - The name of the attribute.

Returns:

The values of the attribute, as doubles.

Throws:

BadAttributeNameException - If there is no such attribute.

BadAttributeValueException - If any attribute value fails to parse as a double.

BadAttributeException

getFloat

public float getFloat(String attr)
               throws BadAttributeException

Retrieve, as a double, the value of an attribute which only allows one value.

Parameters:

attr - The name of the attribute.

Returns:

The value of the attribute, as a double, if it has only one value.

Throws:

BadAttributeNameException - If there is no such attribute.

BadAttributeValueException - If the value fails to parse as a double, or the attribute has more than one value.

BadAttributeException

parseFloat

public float parseFloat(String attr,
                        String value)
                 throws BadAttributeValueException

Parse a string as a float attribute value, as getFloat(java.lang.String) would.

Parameters:

attr - The name of the attribute, passed to the exception if one is thrown.

value - The value to parse.

Returns:

The attribute value, as a float.

Throws:

BadAttributeValueException - If the value fails to parse as a float.

getDoubles

public List<Double> getDoubles(String attr)
                        throws BadAttributeException

Retrieve all values of an attribute as doubles.

Parameters:

attr - The name of the attribute.

Returns:

The values of the attribute, as doubles.

Throws:

BadAttributeNameException - If there is no such attribute.

BadAttributeValueException - If any attribute value fails to parse as a double.

BadAttributeException

getDouble

public double getDouble(String attr)
                 throws BadAttributeException

Retrieve, as a double, the value of an attribute which only allows one value.

Parameters:

attr - The name of the attribute.

Returns:

The value of the attribute, as a double, if it has only one value.

Throws:

BadAttributeNameException - If there is no such attribute.

BadAttributeValueException - If the value fails to parse as a double, or the attribute has more than one value.

BadAttributeException

parseDouble

public double parseDouble(String attr,
                          String value)
                   throws BadAttributeValueException

Parse a string as a double attribute value, as getDouble(java.lang.String) would.

Parameters:

attr - The name of the attribute, passed to the exception if one is thrown.

value - The value to parse.

Returns:

The attribute value, as a double.

Throws:

BadAttributeValueException - If the value fails to parse as a double.

getEnums

public <E extends Enum> List<E> getEnums(String attr,
                                         Class<E> cls)
                              throws BadAttributeException

Retrieve all values of an attribute as enumeration constants.

Type Parameters:

E - The enumeration class.

Parameters:

attr - The name of the attribute.

cls - The enumeration class.

Returns:

The values of the attribute, as doubles.

Throws:

BadAttributeNameException - If there is no such attribute.

BadAttributeValueException - If any attribute value fails to parse as a double.

BadAttributeException

getEnum

public <E extends Enum> E getEnum(String attr,
                                  Class<E> cls)
                       throws BadAttributeException

Retrieve, as an enumeration constant, the value of an attribute which only allows one value.

Type Parameters:

E - The enumeration class.

Parameters:

attr - The name of the attribute.

cls - The enumeration class.

Returns:

The value of the attribute, as an integer, if it has only one value.

Throws:

BadAttributeNameException - If there is no such attribute.

BadAttributeValueException - If the value fails to parse as an integer, or the attribute has more than one value.

BadAttributeException

parseEnum

public <E extends Enum> E parseEnum(String attr,
                                    String value,
                                    Class<E> cls)
                         throws BadAttributeValueException

Parse a string as an enumeration constaint, as getEnum(java.lang.String, java.lang.Class) would.

Type Parameters:

E - The enumeration class.

Parameters:

attr - The name of the attribute, passed to the exception if one is thrown.

value - The value to parse.

cls - The enumeration class.

Returns:

The attribute value, as a value of <E>.

Throws:

BadAttributeValueException - If the value fails to parse as a constant of the given enumeration.

getBooleans

public List<Boolean> getBooleans(String attr)
                          throws BadAttributeException

Retrieve all values of an attribute as booleans.

Parameters:

attr - The name of the attribute.

Returns:

The values of the attribute, as booleans.

Throws:

BadAttributeNameException - If there is no such attribute.

BadAttributeException - If any attribute value fails to parse as a boolean (see getBoolean(java.lang.String)).

See Also:

getBoolean(java.lang.String)

getBoolean

public boolean getBoolean(String attr)
                   throws BadAttributeException

Retrieve, as a boolean, the value of an attribute which only allows one value.

Parameters:

attr - The name of the attribute.

Returns:

true for "true", "yes", "1", or "on"; false for "false", "no", "0", or "off". (Case insensitive.)

Throws:

BadAttributeNameException - If there is no such attribute.

BadAttributeValueException - If none of the above matches, or there is more than one value.

BadAttributeException

parseBoolean

public boolean parseBoolean(String attr,
                            String value)
                     throws BadAttributeValueException

Parse a string as a boolean attribute value, as getBoolean(java.lang.String) would.

Parameters:

attr - The name of the attribute, passed to the exception if one is thrown.

value - The value to parse.

Returns:

The attribute value, as a boolean.

Throws:

BadAttributeValueException - If the value fails to parse as a boolean.

See Also:

boolStrings

getColors

public List<String> getColors(String attr)
                       throws BadAttributeException

Retrieve all values of a color attribute as identifier strings suitable for use in generated code.

Parameters:

attr - The name of the attribute.

Returns:

Identifiers for the colors specified.

Throws:

BadAttributeNameException - If there is no such attribute.

BadAttributeValueException - If any attribute value is not recognized as a color.

BadAttributeException

getColor

public String getColor(String attr)
                throws BadAttributeException

Retrieve, as a color identifier, the value of an attribute which only allows one value. This identifier is suitable for use in generated code.

Parameters:

attr - The name of the attribute.

Returns:

The identifier for the color specified.

Throws:

BadAttributeNameException - If there is no such attribute.

BadAttributeValueException - If the value is not recognized as a color, or there is more than one value.

BadAttributeException

parseColor

public String parseColor(String attr,
                         String value)
                  throws BadAttributeValueException

Parse a string as a color value, as getColor(java.lang.String) would.

Parameters:

attr - The name of the attribute, passed to the exception if one is thrown.

value - The value to parse.

Returns:

The attribute value, as a color identifier.

Throws:

BadAttributeValueException - If the value fails to parse as a color.

hasValue

public boolean hasValue(String attr)
                 throws BadAttributeException

Test to see if an attribute has a value (i.e. is not null).

Parameters:

attr - The name of the attribute to test.

Returns:

true if the attribute is not equal to null.

Throws:

BadAttributeException - If there is no such attribute.