SGWTProperties
APIs such as
ListGrid.setHeaderButtonproperties() or
FormItem.setDefaultProperties() are
properties APIs - they can be passed a Canvas
or FormItem instance as a "properties object": a means of configuring an
AutoChild or establishing new defaults for the class.
When calling a properties API:
- all settings applied to the properties object are copied when the properties API
is called. Subsequent changes to the properties object are ignored.
- the properties object is not a real widget; it's essentially just a type-safe API for
establishing default properties. Only calls to simple Java Bean-style setters are generally
supported, and in the case of AutoChildren, event registrations
(
addSomethingHandler()). It's invalid to
BaseWidget.draw() a properties object, ask it to fetch data,
or in any other way treat it like a real widget.
- similarly you cannot take a live widget and pass it to a properties API. For example,
you cannot take a Button that has already been drawn and pass it a properties API
- the properties object is not a live link to whatever AutoChild or other component is
configured by those properties. For example, if you use
Window.changeAutoChildDefaults("header", headerProperties) to affect the window
"header" AutoChild, you cannot later call
Canvas.setBorder() on the
headerProperties object to affect the header border. You would call
Window.getHeader() to get the live
header object instead.
- it is valid for a Canvas-based properties object to be further modified and
passed to a second properties API on some other object, however it is not valid to do
this with a FormItem-based properties object or DataClass-based properties object (such as
ListGridField).