WidgetDef

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

types
Class WidgetDef

java.lang.Object
  types.WidgetDef

Direct Known Subclasses:: BorderLayout, Button, CheckButton, Clickable, Clock, ColumnLayout, ComboBox, Container, DialogBox, FileChooser, Frame, GridLayout, Label, Layout, Menu, MenuBar, MenuItem, MenuSeparator, RadioButton, RadioButtonGroup, RowLayout, ScrollingFrame, Spacer, TextArea, TextField, Tree, TreeNode, Widget, Window

public abstract class WidgetDef
extends Object
extends Object

WidgetDef is the abstract class that all definitions in the library implement. Standardized Formats for our Libraries: String Concatenation: Use the StringBuilder class and the StringBuilder.append() method to concatenate strings. String Formatting: use the String.format(String, args) to format strings. Use Window.java class as an example.

Nested Class Summary
`static interface`	`WidgetDef.Abstract` Annotation forbidding a widget type from being instantiated.
`static interface`	`WidgetDef.Contained` Declare that a widget type cannot appear at the top level.
`static interface`	`WidgetDef.Derived` Annotation specifying the base widget types of a widget.

Field Summary
`String`	`id` id of Widget object
`protected WidgetDef`	`parent` Parent widget def
`protected Widget`	`widget` Widget object that is passed as a parameter in the constructor.

Constructor Summary
`protected`	`WidgetDef(Widget widget, WidgetDef parent)`
`protected`	`WidgetDef(Widget widget, WidgetDef parent, LangDef langDef)`

Method Summary
`abstract String`	`addAttributes(GUIAttributes attrs)` The addAttributes code does two things; it creates the lib.java code necessary for the attributes and it type checks for all attributes.
`String`	`addChild(String childType, String childId, GUIAttributes attrs)` Check to make sure the childType is legal for the widget, then add it.
`protected static String`	`commentForm(String id, String type)` Format a widget identifier for use in comments.
`static WidgetDef`	`defineWidget(LangDef lang, Widget widget)` Create a WidgetDef object for a given Widget and language.
`static WidgetDef`	`defineWidget(LangDef lang, Widget widget, WidgetDef parent)` Create a WidgetDef object for a given Widget and language, with the given WidgetDef as the parent of the widget.
`boolean`	`equals(Object other)` Compare this WidgetDef to another.
`List<WidgetDef>`	`getAncestry()` Get all widget types from which this one derives, in method resolution order, including this type itself.
`List<Class<? extends WidgetDef>>`	`getBaseWidgetDefClasses()` Retrieve the base widget types.
`List<Class<? extends WidgetDef>>`	`getBaseWidgetDefClasses(Class<? extends WidgetDef> cls)` Retrieve the base widget types for a given WidgetDef class.
`static List<Class<? extends WidgetDef>>`	`getBaseWidgetDefClasses(Class<? extends WidgetDef> cls, LangDef langDef)` Retrieve the base widget types for a given WidgetDef class.
`List<WidgetDef>`	`getBaseWidgetDefs()` Retrieve the base widget types.
`Map<String,List<String>>`	`getChildDefaults()` Specifies the child attributes for the widget.
`List<String>`	`getChildModifiers()` Analog of `getModifiers()` for child attributes.
`protected String`	`getCommentName()` Format the widget identifier for use in comments.
`abstract Map<String,List<String>>`	`getDefaults()` Every attribute in our language has to have a default setting.
`abstract Set<String>`	`getImports()` getImports keeps a Set of import lines that are pertinent to the code generated in the other methods.
`Set<String>`	`getInnerClasses()` getInnerClasses returns a set of strings corresponding to any inner classes utilized by the widget at runtime.
`abstract String`	`getLanguage()` Accessor method for the Widget language.
`abstract List<String>`	`getModifiers()` getModifiers returns a list of methods designed to modify various attributes of the widget type in question.
`Map<String,List<String>>`	`getMultisynonymousAttributes()` Specifies multisynonymous attributes.
`Map<String,String>`	`getSynonymousAttributes()` Specifies synonymous attributes.
`abstract List<String>`	`getVariables()` Returns a chunk of code intended to declare variables which the backend code may need access to and therefore should be declared outside of the constructor code.
`int`	`hashCode()`
`boolean`	`isAbstract()` Test whether this widget definition is for an abstract widget type.
`static boolean`	`isAbstract(Class<? extends WidgetDef> cls)` Test whether a class defines an abstract widget type.
`boolean`	`isContained()` Test whether the represented widget is contained, and so cannot appear at the top level of a .gui file.
`boolean`	`isContained(Class<? extends WidgetDef> cls)` Test whether a class defines the type of a widget that is contained, and so cannot appear at the top level of a .gui file.
`static boolean`	`isContained(Class<? extends WidgetDef> cls, LangDef langDef)` Test whether a class defines the type of a widget that is contained, and so cannot appear at the top level of a .gui file.
`boolean`	`isDerivedFrom(Class<? extends WidgetDef> cls)` Test whether this widget definition derives from that specified by the given WidgetDef class.
`protected boolean`	`isDerivedFrom(Class<? extends WidgetDef> deriv, Class<? extends WidgetDef> maybeBase)` Determines whether one widget type is derived from or the same as another, directly or otherwise.
`protected static boolean`	`isDerivedFrom(Class<? extends WidgetDef> deriv, Class<? extends WidgetDef> maybeBase, LangDef langDef)` Determines whether one widget type is derived from or the same as another, directly or otherwise.
`protected boolean`	`isDerivedFrom(String derivName, Class<? extends WidgetDef> maybeBase)` Determines whether one widget type is derived from or the same as another, directly or otherwise.
`protected static boolean`	`isDerivedFrom(String derivName, Class<? extends WidgetDef> maybeBase, LangDef langDef)` Determines whether one widget type is derived from or the same as another, directly or otherwise.
`protected boolean`	`isDerivedFrom(String derivName, String maybeBaseName)` Determines whether one widget type is derived from or the same as another, directly or otherwise.
`protected static boolean`	`isDerivedFrom(String derivName, String maybeBaseName, LangDef langDef)` Determines whether one widget type is derived from or the same as another, directly or otherwise.
`boolean`	`isDerivedFrom(WidgetDef widgetDef)` Test whether this widget definition derives from the given one.
`String`	`postamble()` Get the chunk of initialization code to be run after everything else is done.
`abstract String`	`preamble()` Get the chunk of initialization code to be run first.
`GUIAttributes`	`processAttributes()` Create a GUIAttributes object for a widget.

Methods inherited from class java.lang.Object
`clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait`

Field Detail

widget

protected final Widget widget

Widget object that is passed as a parameter in the constructor.

id

public final String id

id of Widget object

parent

protected final WidgetDef parent

Parent widget def

Constructor Detail

WidgetDef

protected WidgetDef(Widget widget,
                    WidgetDef parent)

Parameters:: widget - The Widget object.; parent - The WidgetDef for the parent widget, or null for a top-level widget.

WidgetDef

protected WidgetDef(Widget widget,
                    WidgetDef parent,
                    LangDef langDef)

Parameters:: widget - The Widget object.; parent - The WidgetDef for the parent widget, or null for a top-level widget.; langDef - The language definition in use.

Method Detail

getCommentName

protected String getCommentName()

Format the widget identifier for use in comments. Replaces the id of an anonymous widget with something more readable.

Returns:: id, if the widget is not anonymous; a placeholder otherwise.

commentForm

protected static String commentForm(String id,
                                    String type)

Format a widget identifier for use in comments. Replaces the id of an anonymous widget with something more readable.

Parameters:: id - The identifier of the widget.; type - The type of the widget.
Returns:: id, if the widget is not anonymous; a placeholder otherwise.

getLanguage

public abstract String getLanguage()

Accessor method for the Widget language.

Returns:: language

preamble

public abstract String preamble()

Get the chunk of initialization code to be run first. Typically this code will declare a local variable for the widget.

Note that, by its nature, a preamble should only be called once; therefore the preamble is not inherited.

Returns:: Instatiation code.

postamble

public String postamble()

Get the chunk of initialization code to be run after everything else is done. This is an empty string by default.

Note that the preamble() and postamble are not inherited (much as Java constructors aren't).

Returns:: Final-phase initialization code.

getVariables

public abstract List<String> getVariables()

Returns a chunk of code intended to declare variables which the backend code may need access to and therefore should be declared outside of the constructor code.

Returns:: Variable Declaration for the widget.

processAttributes

public final GUIAttributes processAttributes()
                                      throws BadAttributeException

Create a GUIAttributes object for a widget.

Returns:: The GUIAttributes object.
Throws:: BadAttributeException - If an unrecognized attribute is listed for the widget.

getDefaults

public abstract Map<String,List<String>> getDefaults()

Every attribute in our language has to have a default setting. This returns all the defaults in a map of Strings to Lists of Strings.

Returns:: Map of attribute defaults

addAttributes

public abstract String addAttributes(GUIAttributes attrs)
                              throws BadAttributeException

The addAttributes code does two things; it creates the lib.java code necessary for the attributes and it type checks for all attributes. A BadAttributeException is thrown if the names or the values are erroneous. If an attribute is not found in the GUIAttributes, a BadAttributeNameException is thrown from GUIAttributes.

Parameters:: attrs - The attributes to set for the widget.
Returns:: The generated code to set the attributes.
Throws:: BadAttributeException

getSynonymousAttributes

public Map<String,String> getSynonymousAttributes()

Specifies synonymous attributes. For each entry in this map, the key is the name of an attribute (which does not appear in getDefaults()), and the value is the name of the real attribute with which that attribute is synonymous (i.e. equivalent).

By default, returns the empty map; WidgetDef subclasses may override to specify synonymous attributes.

Returns:: The map of synonymous attributes.

getMultisynonymousAttributes

public Map<String,List<String>> getMultisynonymousAttributes()

Specifies multisynonymous attributes. A multisynonymous attribute is one that is equivalent to giving a number of other attributes in one value list. For instance, a "size" attribute to be multisynonymous with "width" and "height", and then one could either give the values of width and height separately or give the size attribute both values.

Returns:: A mapping; each key is a multisynonymous attribute, and each value is a list of the attributes to receive its values, in the order in which they must appear in the attribute value list.

getChildDefaults

public Map<String,List<String>> getChildDefaults()

Specifies the child attributes for the widget. A container widget can have associated attributes that are attributes not of the container itself but of its children. For instance, any widget in a GridLayout has attributes for its position and span; it has these attributes not because of its widget type, but because of its parent's widget type. Such are called child attributes.

Returns:: A map of the default values for the child attributes
See Also:: getDefaults()

addChild

public String addChild(String childType,
                       String childId,
                       GUIAttributes attrs)
                throws BadChildWidgetException,
                       BadAttributeException

Check to make sure the childType is legal for the widget, then add it.

Parameters:: childType - The widget type of the child.; childId - The identifier of the child.; attrs - The child's GUIAttributes map. Child attributes will be read from this map.
Returns:: The generated code to add the child to this widget.
Throws:: BadChildWidgetException - If the child is of an inappropriate type. For instance, a menu can only have certain widgets (items, submenus, etc.) as children.; BadAttributeException - If one of the given attributes is erroneous.

getModifiers

public abstract List<String> getModifiers()

getModifiers returns a list of methods designed to modify various attributes of the widget type in question. When getModifiers is called, the accessors and mutators for all attributes are returned.

Returns:: List of mutators and accessors for the widget type.

getChildModifiers

public List<String> getChildModifiers()

Analog of getModifiers() for child attributes.

Returns:: List of mutators and accessors for attributes of children of widgets of this type.

getImports

public abstract Set<String> getImports()

getImports keeps a Set of import lines that are pertinent to the code generated in the other methods.

Returns:: Set of import strings.

getInnerClasses

public Set<String> getInnerClasses()

getInnerClasses returns a set of strings corresponding to any inner classes utilized by the widget at runtime. This is primarily intended to make defining and manipulating (at runtime) non swing elements more straightforward and flexible. Since the majority of definitions will most likely not be utilizing this functionality, the default action is to return an empty set. This can be overridden where appropriate.

Returns:: Set of Inner Classes.

defineWidget

public static WidgetDef defineWidget(LangDef lang,
                                     Widget widget,
                                     WidgetDef parent)
                              throws BadWidgetTypeException

Create a WidgetDef object for a given Widget and language, with the given WidgetDef as the parent of the widget. Calls are cached, so multiple calls with the same Widget and language will return the same WidgetDef.

Parameters:

lang - The LangDef for the language to output.

widget - The Widget, as given by the parser.

parent - The WidgetDef for the parent widget.

Returns:

A new WidgetDef.

Throws:

BadWidgetTypeException - If the Widget specifies a widget type in Widget.type that:

does not exist,
is abstract, or
is contained, when widget has no parent

defineWidget

public static WidgetDef defineWidget(LangDef lang,
                                     Widget widget)
                              throws BadWidgetTypeException

Create a WidgetDef object for a given Widget and language. The Widget is assumed to be at the top level (i.e. it has no parent). Calls are cached, so multiple calls with the same Widget and language will return the same WidgetDef.

Parameters:: lang - The LangDef for the language to output.; widget - The Widget, as given by the parser.
Returns:: A new WidgetDef.
Throws:: BadWidgetTypeException - If the Widget specifies a widget type in Widget.type that is either abstract or nonexistant.

getBaseWidgetDefs

public final List<WidgetDef> getBaseWidgetDefs()

Retrieve the base widget types.

Returns:: A list of the base widget types, as WidgetDefs.
See Also:: WidgetDef.Derived

getBaseWidgetDefClasses

public final List<Class<? extends WidgetDef>> getBaseWidgetDefClasses()

Retrieve the base widget types.

Returns:: A list of the base widget types' bare classes.
See Also:: WidgetDef.Derived

getBaseWidgetDefClasses

public final List<Class<? extends WidgetDef>> getBaseWidgetDefClasses(Class<? extends WidgetDef> cls)

Retrieve the base widget types for a given WidgetDef class.

Parameters:: cls - The class in question.
Returns:: A list of the base widget types' bare classes.
See Also:: WidgetDef.Derived

getBaseWidgetDefClasses

public static List<Class<? extends WidgetDef>> getBaseWidgetDefClasses(Class<? extends WidgetDef> cls,
                                                                       LangDef langDef)

Retrieve the base widget types for a given WidgetDef class.

Parameters:: cls - The class in question.; langDef - The language definition for the class.
Returns:: A list of the base widget types' bare classes.
See Also:: WidgetDef.Derived

getAncestry

public final List<WidgetDef> getAncestry()

Get all widget types from which this one derives, in method resolution order, including this type itself. This order determines which types' members override members of which base types; in particular, a member of a type earlier in the list overrides that later in the list. (In the case of a single-inheritance type hierarchy, like Java's (not counting interfaces), this list will simply include this type, followed by its base type, and then that widget type's base, and so forth.)

The method resolution order (MRO) used here is called C3; I'm borrowing the algorithm from Python 2.3 (which in turn borrowed it from a Lisp variant called Dylan). See this essay for a more thorough explanation and justification of the C3 algorithm.

Returns:: This type's ancestors, direct bases first, as WidgetDefs.
See Also:: The Python 2.3 Method Resolution Order

isDerivedFrom

public final boolean isDerivedFrom(WidgetDef widgetDef)

Test whether this widget definition derives from the given one.

Parameters:: widgetDef - The potential ancestor of this widget definition.
Returns:: true if this widget definition derives, directly or indirectly, from widgetDef.

isDerivedFrom

public final boolean isDerivedFrom(Class<? extends WidgetDef> cls)

Test whether this widget definition derives from that specified by the given WidgetDef class.

Parameters:: cls - The class of the potential ancestor of this widget definition.
Returns:: true if this widget definition derives, directly or indirectly, from that specified by cls.