Base class for all DirectGui items. Handles composite widgets and
command line argument parsing.
Code overview:
1) Each widget defines a set of options (optiondefs) as a list of tuples
of the form ``('name', defaultValue, handler)``.
'name' is the name of the option (used during construction of configure)
handler can be: None, method, or INITOPT. If a method is specified, it
will be called during widget construction (via initialiseoptions), if the
Handler is specified as an INITOPT, this is an option that can only be set
during widget construction.
2) :func:`~DirectGuiBase.defineoptions` is called. defineoption creates:
self._constructorKeywords = { keyword: [value, useFlag] }
A dictionary of the keyword options specified as part of the
constructor keywords can be of the form 'component_option', where
component is the name of a widget's component, a component group or a
component alias.
self._dynamicGroups
A list of group names for which it is permissible to specify options
before components of that group are created.
If a widget is a derived class the order of execution would be::
foo.optiondefs = {}
foo.defineoptions()
fooParent()
fooParent.optiondefs = {}
fooParent.defineoptions()
3) :func:`~DirectGuiBase.addoptions` is called. This combines options
specified as keywords to the widget constructor (stored in
self._constructorKeywords) with the default options (stored in optiondefs).
Results are stored in
``self._optionInfo = { keyword: [default, current, handler] }``.
If a keyword is of the form 'component_option' it is left in the
self._constructorKeywords dictionary (for use by component constructors),
otherwise it is 'used', and deleted from self._constructorKeywords.
Notes:
- constructor keywords override the defaults.
- derived class default values override parent class defaults
- derived class handler functions override parent class functions
4) Superclass initialization methods are called (resulting in nested calls
to define options (see 2 above)
5) Widget components are created via calls to
:func:`~DirectGuiBase.createcomponent`. User can specify aliases and groups
for each component created.
Aliases are alternate names for components, e.g. a widget may have a
component with a name 'entryField', which itself may have a component
named 'entry', you could add an alias 'entry' for the 'entryField_entry'
These are stored in self.__componentAliases. If an alias is found,
all keyword entries which use that alias are expanded to their full
form (to avoid conversion later)
Groups allow option specifications that apply to all members of the group.
If a widget has components: 'text1', 'text2', and 'text3' which all belong
to the 'text' group, they can be all configured with keywords of the form:
'text_keyword' (e.g. ``text_font='comic.rgb'``). A component's group
is stored as the fourth element of its entry in self.__componentInfo.
Note: the widget constructors have access to all remaining keywords in
_constructorKeywords (those not transferred to _optionInfo by
define/addoptions). If a component defines an alias that applies to
one of the keywords, that keyword is replaced with a new keyword with
the alias expanded.
If a keyword (or substituted alias keyword) is used during creation of the
component, it is deleted from self._constructorKeywords. If a group
keyword applies to the component, that keyword is marked as used, but is
not deleted from self._constructorKeywords, in case it applies to another
component. If any constructor keywords remain at the end of component
construction (and initialisation), an error is raised.
5) :func:`~DirectGuiBase.initialiseoptions` is called. This method calls any
option handlers to respond to any keyword/default values, then checks to
see if any keywords are left unused. If so, an error is raised.