SwatObject
└─SwatUIObject
└─SwatWidget
public abstract class SwatWidget
extends SwatUIObject
| Field Summary | |
|---|---|
| protected boolean | Whether or not this widget has been displayed. |
| string | A non-visible unique id for this widget, or null. |
| protected boolean | Whether or not this widget has been initialized. |
| protected array | Messages affixed to this widget. |
| protected boolean | Whether or not this widget has been processed. |
| protected boolean | Specifies that this widget requires an id. |
| boolean | Sensitive. |
| string | Stylesheet. |
| Fields inherited from Swat.SwatUIObject | |
|---|---|
| classes, html_head_entry_set, parent, visible | |
| Constructor Summary | |
|---|---|
SwatWidget(string id) Creates a new widget. |
|
| Method Summary | |
|---|---|
| protected final void | addCompositeWidget(SwatWidget widget, string key) Adds a composite a widget to this widget. |
| void | addMessage(SwatMessage message) Adds a message to this widget. |
| protected final void | Confirms composite widgets have been created. |
| SwatUIObject | copy(string id_suffix) Performs a deep copy of the UI tree starting with this UI object. |
| protected void | Creates and adds composite widgets of this widget. |
| void | display() Displays this widget. |
| void | Displays the HTML head entries for this widget. |
| protected array | Gets the array of CSS classes that are applied to this widget. |
| protected final SwatWidget | getCompositeWidget(string key) Gets a composite widget of this widget by the composite widget's key. |
| protected final array | getCompositeWidgets(string class_name) Gets all composite widgets added to this widget. |
| string | Gets the id attribute of the XHTML element displayed by this widget that should receive focus. |
| SwatHtmlHeadEntrySet | Gets the SwatHtmlHeadEntry objects needed by this widget. |
| array | Gets all messages. |
| boolean | Checks for the presence of messages. |
| void | init() Initializes this widget. |
| boolean | Whether or not this widget is displayed. |
| boolean | Whether or not this widget is initialized. |
| boolean | Whether or not this widget is processed. |
| boolean | Determines the sensitivity of this widget. |
| abstract void | |
| void | process() Processes this widget. |
| SwatContainer | Replace this widget with a new container. |
| Methods inherited from Swat.SwatUIObject | |
|---|---|
| addComment, addJavaScript, addStyleSheet, addTangoAttribution, copy, getCSSClassNames, getCSSClassString, getFirstAncestor, getHtmlHeadEntrySet, getInlineJavaScript, getUniqueId, isVisible | |
protected boolean $displayed = false
Whether or not this widget has been displayed
public string $id = null
A non-visible unique id for this widget, or null
protected boolean $initialized = false
Whether or not this widget has been initialized
protected array $messages = array()
Messages affixed to this widget
protected boolean $processed = false
Whether or not this widget has been processed
protected boolean $requires_id = false
Specifies that this widget requires an id
If an id is required then the init() method sets a unique id if an id is not already set manually.
public boolean $sensitive = true
Sensitive
Whether the widget is sensitive. If a widget is sensitive it reacts to user input. Insensitive widgets should display "grayed-out" to inform the user they are not sensitive. All widgets that the user can interact with should respect this property.
public string $stylesheet = null
Stylesheet
The URI of a stylesheet for use with this widget. If this property is
set before SwatWidget::init() then the
SwatUIObject::addStyleSheet() method will be called to add this
stylesheet to the header entries. Primarily this should be used by
SwatUI to set a stylesheet in SwatML. To set a stylesheet in PHP code,
it is recommended to call addStyleSheet() directly.
public SwatWidget(string id)
Creates a new widget
id - a non-visible unique id for this widget.protected final void addCompositeWidget(SwatWidget widget, string key)
Adds a composite a widget to this widget
widget - the composite widget to add.key - a key identifying the widget so it may be retrieved later. The key does not have to be the widget's id but the key does have to be unique within this widget relative to the keys of other composite widgets.public void addMessage(SwatMessage message)
Adds a message to this widget
The message may be shown by the SwatWidget::display() method and
will as cause SwatWidget::hasMessage() to return as true.
message - the message to add.protected final void confirmCompositeWidgets()
Confirms composite widgets have been created
Widgets are only created once. This method may be called multiple times in different places to ensure composite widgets are available. In general, it is best to call this method before attempting to use composite widgets.
This method is called by the default implementations of init(),
process() and is called any time SwatWidget::getCompositeWidget()
is called so it rarely needs to be called manually.
public SwatUIObject copy(string id_suffix)
Performs a deep copy of the UI tree starting with this UI object
id_suffix - optional. A suffix to append to copied UI objects in the UI tree.protected void createCompositeWidgets()
Creates and adds composite widgets of this widget
Created composite widgets should be added in this method using
SwatWidget::addCompositeWidget().
public void display()
Displays this widget
Displays this widget displays as well as recursively displays any child widgets of this widget.
If this widget has not been initialized, it is automatically initialized before displaying.
public void displayHtmlHeadEntries()
Displays the HTML head entries for this widget
Each entry is displayed on its own line. This method should be called inside the
protected array getCSSClassNames()
Gets the array of CSS classes that are applied to this widget
protected final SwatWidget getCompositeWidget(string key)
Gets a composite widget of this widget by the composite widget's key
This is used by other methods to retrieve a specific composite widget. This method ensures composite widgets are created before trying to retrieve the specified widget.
key - the key of the composite widget to get.protected final array getCompositeWidgets(string class_name)
Gets all composite widgets added to this widget
This method ensures composite widgets are created before retrieving the widgets.
class_name - optional class name. If set, only widgets that are instances of $class_name are returned.public string getFocusableHtmlId()
Gets the id attribute of the XHTML element displayed by this widget that should receive focus
Elements receive focus either through JavaScript methods or by clicking on label elements with their for attribute set. If there is no such element (for example, there are several elements and none is more important than the others) then null is returned.
By default, widgets return null and are un-focusable. Sub-classes that are focusable should override this method to return the appripriate XHTML id.
public SwatHtmlHeadEntrySet getHtmlHeadEntrySet()
Gets the SwatHtmlHeadEntry objects needed by this widget
If this widget has not been displayed, an empty set is returned to reduce the number of required HTTP requests.
public array getMessages()
Gets all messages
Gathers all messages from children of this widget and this widget itself.
Messages from composite widgets of this widget are included by default.
public boolean hasMessage()
Checks for the presence of messages
public void init()
Initializes this widget
Initialization is done post-construction. Initilization may be done
manually by calling init() on the UI tree at any time. If a
call to SwatWidget::process() or SwatWidget::display()
is made before the tree is initialized, this method is called
automatically. As a result, you often do not need to worry about calling
init().
Having an initialization method separate from the constructor allows properties to be manually set on widgets after construction but before initilization.
Composite widgets of this widget are automatically initialized as well.
public boolean isDisplayed()
Whether or not this widget is displayed
public boolean isInitialized()
Whether or not this widget is initialized
public boolean isProcessed()
Whether or not this widget is processed
public boolean isSensitive()
Determines the sensitivity of this widget.
Looks at the sensitive property of the ancestors of this widget to determine if this widget is sensitive.
public abstract void printWidgetTree()
public void process()
Processes this widget
After a form submit, this widget processes itself and its dependencies and then recursively processes any of its child widgets.
Composite widgets of this widget are automatically processed as well.
If this widget has not been initialized, it is automatically initialized before processing.
public SwatContainer replaceWithContainer()
Replace this widget with a new container
Replaces this widget in the widget tree with a new SwatContainer,
then adds this widget to the new container.
Base class for all widgets
Widget composition:
Complicated widgets composed of multiple individual widgets can be easily built using
SwatWidget's composite features. The main methods used for widget composition are:SwatWidget::createCompositeWidgets(),SwatWidget::addCompositeWidget()andSwatWidget::getCompositeWidget().Developers should implement the
createCompositeWidgets()method by creating composite widgets and adding them to this widget by callingaddCompositeWidget(). As long as the parent implemtations ofSwatWidget::init()andSwatWidget::process()are called, nothing further needs to be done forinit()andprocess(). For theSwatWidget::display()method, developers can use thegetCompositeWidget()method to retrieve a specific composite widget for display. Composite widgets are not displayed by the default implementation ofdisplay().In keeping with object-oriented composition theory, none of the composite widgets are publicly accessible. Methods could be added to make composite widgets available publicly, but in that case it would be better to just extend
SwatContainer.