net.sf.mmm.client.ui.base.widget.adapter

Class AbstractUiWidgetAdapter<WIDGET>

java.lang.Object

net.sf.mmm.client.ui.base.widget.adapter.AbstractUiWidgetAdapter<WIDGET>

Type Parameters:

WIDGET - is the generic type of getToplevelWidget().

All Implemented Interfaces:

AttributeReadAccessKey, AttributeReadAltText, AttributeReadAttribute, AttributeReadColumnSpan, AttributeReadEnabled, AttributeReadFocused, AttributeReadHeightInRows, AttributeReadHtmlId, AttributeReadImage<UiWidgetImage>, AttributeReadLabel, AttributeReadLengthProperty, AttributeReadMaximumTextLength, AttributeReadPrimaryStyle, AttributeReadResizable, AttributeReadSelectionMode, AttributeReadSizeInPixel, AttributeReadStyles, AttributeReadStylesAdvanced, AttributeReadTooltip, AttributeReadUrl, AttributeReadValidationFailure, AttributeWriteAttribute, AttributeWriteEnabled, AttributeWriteHtmlId, AttributeWriteLengthProperty, AttributeWriteOnlyAttribute, AttributeWritePrimaryStyle, AttributeWriteStyles, AttributeWriteStylesAdvanced, AttributeWriteTooltip, UiWidgetAdapter, AttributeReadDisposed, AttributeReadId<String>, AttributeReadTitle<String>, AttributeWriteDisposed, AttributeWriteId<String>, Accessibility

Direct Known Subclasses:

AbstractUiWidgetAdapterWithEvents, UiWidgetAdapterTest

public abstract class AbstractUiWidgetAdapter<WIDGET>
extends Object
implements UiWidgetAdapter, AttributeReadAltText, AttributeReadUrl, AttributeReadLabel, AttributeReadTitle<String>, AttributeReadImage<UiWidgetImage>, AttributeReadValidationFailure, AttributeReadAccessKey, AttributeReadFocused, AttributeReadMaximumTextLength, AttributeReadHeightInRows, AttributeReadColumnSpan, AttributeReadResizable, AttributeReadSelectionMode

This is the abstract base implementation of UiWidgetAdapter.

Since:

1.0.0

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

Field Summary

Fields

Modifier and Type	Field and Description
private WIDGET	toplevelWidget
private AbstractUiWidgetNative<?,?>	uiWidget

Fields inherited from interface net.sf.mmm.client.ui.api.attribute.AttributeReadHtmlId

HTML_ATTRIBUTE_ID, ID_SEPARATOR, PROPERTY_ID

Fields inherited from interface net.sf.mmm.client.ui.api.attribute.AttributeReadStyles

PROPERTY_STYLES, STYLE_PATTERN_MULTIPLE, STYLE_PATTERN_SINGLE

Fields inherited from interface net.sf.mmm.util.lang.api.concern.Accessibility

WAI_ARIA

Fields inherited from interface net.sf.mmm.client.ui.api.attribute.AttributeReadLabel

PROPERTY_LABEL

Fields inherited from interface net.sf.mmm.client.ui.api.attribute.AttributeReadAccessKey

ACCESS_KEY_NONE, HTML_ATTRIBUTE_ACCESS_KEY

Fields inherited from interface net.sf.mmm.client.ui.api.attribute.AttributeReadColumnSpan

ATTRIBUTE_COLSPAN

Constructor Summary

Constructors

Constructor and Description
AbstractUiWidgetAdapter() The constructor.
AbstractUiWidgetAdapter(WIDGET toplevelWidget) The constructor.

Method Summary

Modifier and Type	Method and Description
boolean	addStyle(String style) This method adds the given style to the styles.
AbstractUiWidgetLabel<?>	createLabel(UiContext context) This method creates the label for this widget.
protected abstract WIDGET	createToplevelWidget() This method creates the underlying widget.
char	getAccessKey() This method gets the access key of this object.
Object	getActiveWidget() This method gets the active widget.
String	getAltText() This method gets the alternative text of this object.
String	getAttribute(String name) This method gets the attribute with the given name of this object.
protected NlsBundleClientUiRoot	getBundle()
int	getColumnSpan() This method gets the number of columns spanned by this object (cell).
UiContext	getContext()
int	getHeightInRows() This method gets the height in rows of this object.
String	getId() This method gets the unique identifier of this object.
UiWidgetImage	getImage() This method gets the image of this object.
String	getLabel() This method gets the label of this object.
int	getMaximumTextLength() This method gets the maximum text length of this object.
String	getPrimaryStyle() This method gets the primary style of this object.
SelectionMode	getSelectionMode() This method gets the SelectionMode.
String	getStyles() This method gets the style(s) (also called style-name(s)) of this object.
String	getTitle() This method gets the title of this object.
String	getTooltip() This method gets the tooltip of this object.
WIDGET	getToplevelWidget()
AbstractUiWidgetNative<?,?>	getUiWidget() This method gives access to the native UI widget wrapping this widget adapter.
protected AbstractUiWidgetNative<?,?>	getUiWidgetTyped() This method is a design suggestion for implementations of widget adapters that need typed access to getUiWidget() and want to perform the cast only in a single place.
String	getUrl() This method gets the URL of this object.
String	getValidationFailure() This method gets the validation failure of this object.
boolean	hasStyle(String style) This method checks if the given style is contained in the set of styles of this object.
boolean	isDisposed() This method tests if this object has been disposed.
boolean	isEnabled() This method determines if this object is enabled.
boolean	isFocused() This method determines if this object currently has the focus.
boolean	isResizable() This method determines if this object is resizable.
boolean	isStyleDeltaSupported() This method determines if the style delta operations AttributeWriteStylesAdvanced.addStyle(String), AttributeWriteStylesAdvanced.removeStyle(String) and AttributeWritePrimaryStyle.setPrimaryStyle(String) are supported by this widget adapter.
boolean	removeStyle(String style) This method removes the given style from the styles.
void	setMode(boolean editMode) This method is called from UiModeChanger for AttributeWriteMode.setMode(net.sf.mmm.client.ui.api.common.UiMode).
void	setParent(UiWidgetComposite<?> parent) This method gets called whenever the parent of the according UiWidget is changed.
void	setPrimaryStyle(String primaryStyle) This method sets the primary style.
void	setUiWidget(AbstractUiWidgetNative<?,?> uiWidget)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface net.sf.mmm.client.ui.base.widget.adapter.UiWidgetAdapter

createAbsoluteImageUrl, removeFromParent, setEventSender, setVisible

Methods inherited from interface net.sf.mmm.client.ui.api.attribute.AttributeWriteHtmlId

setId

Methods inherited from interface net.sf.mmm.client.ui.api.attribute.AttributeWriteTooltip

setTooltip

Methods inherited from interface net.sf.mmm.client.ui.api.attribute.AttributeWriteEnabled

setEnabled

Methods inherited from interface net.sf.mmm.client.ui.api.attribute.AttributeWriteStyles

setStyles

Methods inherited from interface net.sf.mmm.util.lang.api.attribute.AttributeWriteDisposed

dispose

Methods inherited from interface net.sf.mmm.client.ui.api.attribute.AttributeWriteLengthProperty

setLength

Methods inherited from interface net.sf.mmm.client.ui.api.attribute.AttributeReadLengthProperty

getLength

Methods inherited from interface net.sf.mmm.client.ui.api.attribute.AttributeReadSizeInPixel

getHeightInPixel, getWidthInPixel

Methods inherited from interface net.sf.mmm.client.ui.api.attribute.AttributeWriteOnlyAttribute

setAttribute

Field Detail

toplevelWidget

private WIDGET toplevelWidget

See Also:

getToplevelWidget()

uiWidget

private AbstractUiWidgetNative<?,?> uiWidget

See Also:

getUiWidget()

Constructor Detail

AbstractUiWidgetAdapter

public AbstractUiWidgetAdapter()

The constructor.

AbstractUiWidgetAdapter

public AbstractUiWidgetAdapter(WIDGET toplevelWidget)

The constructor.

Parameters:

toplevelWidget - is the toplevel widget.

Method Detail

createToplevelWidget

protected abstract WIDGET createToplevelWidget()

This method creates the underlying widget.
ATTENTION:
This method is called from the constructor but implemented in sub-classes. You should NOT access or even modify member variables as they are NOT set at this point (even final members). However, this design is done by intention instead of passing the widget as constructor argument to give more flexibility by overriding and also for potential lazy initialization of the widget.

Returns:

a new instance of the underlying widget.

getToplevelWidget

public WIDGET getToplevelWidget()

Specified by:

getToplevelWidget in interface UiWidgetAdapter

Returns:

the native widget.

See Also:

AbstractUiWidgetFactoryNative.getNativeWidget(net.sf.mmm.client.ui.api.widget.UiWidgetRegular)

getActiveWidget

public Object getActiveWidget()

This method gets the active widget. For simple cases this will be the same as getToplevelWidget(). In more complex scenarios the toplevel widget may only be a container widget and this method returns a child that represents the active part.

Returns:

the active widget.

getUiWidget

public final AbstractUiWidgetNative<?,?> getUiWidget()

This method gives access to the native UI widget wrapping this widget adapter.
ATTENTION:
For the most cases the call hierarchy should go from the widget to the widget adapter. Only access this method when required (to avoid redundant storage of attributes, etc.).

Returns:

the UI widget wrapping this widget adapter.

getUiWidgetTyped

protected AbstractUiWidgetNative<?,?> getUiWidgetTyped()

This method is a design suggestion for implementations of widget adapters that need typed access to getUiWidget() and want to perform the cast only in a single place. If you would override getUiWidget() to add the cast and do that multiple times across the inheritance hierarchy this would cause multiple/unnecessary casts. Casting is required as we already declare enough generics for widget adapters and also want to keep the code more flexible.

Returns:

the UiWidget potentially specifically typed.

getContext

public UiContext getContext()

Returns:

the UiContext.

setUiWidget

public void setUiWidget(AbstractUiWidgetNative<?,?> uiWidget)

Parameters:

uiWidget - is the uiWidget to set

setParent

public void setParent(UiWidgetComposite<?> parent)

This method gets called whenever the parent of the according UiWidget is changed. It does nothing by default but may be overridden to deal with special behavior of native UI toolkits.

Specified by:

setParent in interface UiWidgetAdapter

Parameters:

parent - is the new parent or null if removed from parent.

getId

public String getId()

This method gets the unique identifier of this object.
ATTENTION:
In order to be compliant with all possible UI toolkit implementations, a valid ID has to fulfill ECMA-262, Section 7.6. It is recommended to use IDs of the form [a-zA-Z][a-zA-Z0-9_$]*. Invalid IDs (e.g. containing colon, hash or period) are not accepted to prevent you from later having problems with CSS selectors.

Specified by:

getId in interface AttributeReadHtmlId

Specified by:

getId in interface AttributeReadId<String>

Returns:

the ID of this object.

See Also:

AttributeReadHtmlId.ID_SEPARATOR

getSelectionMode

public SelectionMode getSelectionMode()

This method gets the SelectionMode.

Specified by:

getSelectionMode in interface AttributeReadSelectionMode

Returns:

the SelectionMode. Must not be null.

setMode

public void setMode(boolean editMode)

This method is called from UiModeChanger for AttributeWriteMode.setMode(net.sf.mmm.client.ui.api.common.UiMode). It only handles the predefined UiModes.

Specified by:

setMode in interface UiWidgetAdapter

Parameters:

editMode - - true of UiMode.EDIT and false for UiMode.VIEW.

getBundle

protected NlsBundleClientUiRoot getBundle()

Returns:

the instance of NlsBundleClientUiRoot.

getTooltip

public String getTooltip()

This method gets the tooltip of this object. It is a brief description that explains this object. If the user remains on the object (e.g. with the mouse pointer) this tooltip is displayed as hover.

Specified by:

getTooltip in interface AttributeReadTooltip

Returns:

the text of this object.

isEnabled

public boolean isEnabled()

This method determines if this object is enabled. If it is NOT enabled, the user can NOT interact with the object.

Specified by:

isEnabled in interface AttributeReadEnabled

Returns:

true if this object is enabled, false if this object is disabled.

getStyles

public String getStyles()

This method gets the style(s) (also called style-name(s)) of this object. The style defines aspects for the appearance (look & feel) of a UI element when displayed to the user.
If you are familiar with web-technology just think of this as the class attribute of HTML elements that are then configured via some cascading style sheet (CSS).
The following situations can be distinguished:

• no style
  The empty string is returned.
• single style
  The name of that single style is returned. The result does NOT contain any whitespace.
• multiple styles
  The list of individual styles are separated by whitespaces in the result.

Each individual style has to match AttributeReadStyles.STYLE_PATTERN_SINGLE. Any number of styles or in other words the result of this has to match AttributeReadStyles.STYLE_PATTERN_MULTIPLE. The first style is called the primary style.

Specified by:

getStyles in interface AttributeReadStyles

Returns:

the style(s) of this object.

isDisposed

public boolean isDisposed()

This method tests if this object has been disposed. A disposed object can NOT be used anymore.

Specified by:

isDisposed in interface AttributeReadDisposed

Returns:

true if this object has been disposed.

See Also:

AttributeWriteDisposed.dispose()

getAltText

public String getAltText()

This method gets the alternative text of this object. This text is used to provide the essential information of an object in textual form. E.g. if an image can NOT be displayed because it is missing, the alternative text is displayed instead. Further, accessibility tools such as screen-readers can use this information to help the user in order to better understand the meaning of an object.

Specified by:

getAltText in interface AttributeReadAltText

Returns:

the alternative text or null if NOT set.

getUrl

public String getUrl()

This method gets the URL of this object. The URL can be absolute or relative (a path relative to the current base URL).

Specified by:

getUrl in interface AttributeReadUrl

Returns:

the URL or null if NOT set.

getLabel

public String getLabel()

This method gets the label of this object. A label is some text that is permanently shown to the user in the UI in order to describe the meaning of the object and in particular its value. For elements that allow to display or edit a value the label is typically shown beside the edit/display widget. For action elements such as buttons or links the label is the actual text (lettering).

Specified by:

getLabel in interface AttributeReadLabel

Returns:

the label text. Will be the empty string if no label has been set.

getTitle

public String getTitle()

This method gets the title of this object.
NOTE:
For generic usage you need to use Object.toString() of the result if NOT null

Specified by:

getTitle in interface AttributeReadTitle<String>

Returns:

the title or null if not set. The string-representation of the result (if NOT null) needs to be suitable for end-users.

getImage

public UiWidgetImage getImage()

This method gets the image of this object. If the image is attached to an object with arbitrary other features and has a smaller size, it is typically called icon.

Specified by:

getImage in interface AttributeReadImage<UiWidgetImage>

Returns:

the image or null if no image is defined.

getValidationFailure

public String getValidationFailure()

This method gets the validation failure of this object. This is a text that explains the user why the value he has entered is invalid (typically provided as tooltip of an error icon).

Specified by:

getValidationFailure in interface AttributeReadValidationFailure

Returns:

the validation error text or null for no error.

getAttribute

public String getAttribute(String name)

This method gets the attribute with the given name of this object. This is generic and not further specified. It can e.g. allow to get DOM attributes of an element.

Specified by:

getAttribute in interface AttributeReadAttribute

Parameters:

name - is the name of the requested attribute.

Returns:

the value of the attribute with the given name or null if NOT set.

getAccessKey

public char getAccessKey()

This method gets the access key of this object. If the access key is pressed together with the [shift] and [alt] keys this object will be invoked. Here invoked means the same as if the end-user would click on the object. In case of an action item (button, link, etc.) it is invoked, otherwise it will get the focus.

Specified by:

getAccessKey in interface AttributeReadAccessKey

Returns:

the access key. Will be AttributeReadAccessKey.ACCESS_KEY_NONE if no access key is defined.

getMaximumTextLength

public int getMaximumTextLength()

This method gets the maximum text length of this object. Will be Integer.MAX_VALUE if no maximum is defined.

Specified by:

getMaximumTextLength in interface AttributeReadMaximumTextLength

Returns:

the maximum number of characters a user is allowed to enter into this object (field).

getHeightInRows

public int getHeightInRows()

This method gets the height in rows of this object. This is the number of rows (e.g. textual lines) that are visible at a time. If the there are more rows than this height a scrollbar will automatically appear.

Specified by:

getHeightInRows in interface AttributeReadHeightInRows

Returns:

the height in rows.

isResizable

public boolean isResizable()

This method determines if this object is resizable.

Specified by:

isResizable in interface AttributeReadResizable

Returns:

true if the object can be resized (by the end-user), false otherwise.

getColumnSpan

public int getColumnSpan()

This method gets the number of columns spanned by this object (cell). This cell expands to that number of cells horizontally so a value greater than 1 indicates that the next cells to the right are connected.

Specified by:

getColumnSpan in interface AttributeReadColumnSpan

Returns:

the column span. By default 1.

getPrimaryStyle

public String getPrimaryStyle()

This method gets the primary style of this object.

Specified by:

getPrimaryStyle in interface AttributeReadPrimaryStyle

Returns:

the primary style of this object. Will be null if NOT defined.

hasStyle

public boolean hasStyle(String style)

This method checks if the given style is contained in the set of styles of this object.

Specified by:

hasStyle in interface AttributeReadStylesAdvanced

Parameters:

style - is the style to check.

Returns:

true if the given style is active.

addStyle

public boolean addStyle(String style)

This method adds the given style to the styles.

Specified by:

addStyle in interface AttributeWriteStylesAdvanced

Parameters:

style - is the style to add. If this style is already contained in the styles, this will have no effect.

Returns:

true if the styles has actually been added, false if it was already present before.

removeStyle

public boolean removeStyle(String style)

This method removes the given style from the styles.

Specified by:

removeStyle in interface AttributeWriteStylesAdvanced

Parameters:

style - is the style to remove. If this style is NOT contained in the styles, this will have no effect.

Returns:

true if the given style has actually been removed, false otherwise (if it was NOT present).

setPrimaryStyle

public void setPrimaryStyle(String primaryStyle)

This method sets the primary style.

Specified by:

setPrimaryStyle in interface AttributeWritePrimaryStyle

Parameters:

primaryStyle - is the new value for primary style.

See Also:

AttributeReadStyles.getStyles()

isStyleDeltaSupported

public boolean isStyleDeltaSupported()

This method determines if the style delta operations AttributeWriteStylesAdvanced.addStyle(String), AttributeWriteStylesAdvanced.removeStyle(String) and AttributeWritePrimaryStyle.setPrimaryStyle(String) are supported by this widget adapter. Otherwise such operations are always performed via the AttributeWriteStyles.setStyles(String) method. If supported the delta operations are preferred as they are assumed to be more efficient.

Specified by:

isStyleDeltaSupported in interface UiWidgetAdapter

Returns:

true if style delta operations are supported, false otherwise.

isFocused

public boolean isFocused()

This method determines if this object currently has the focus. In this case the cursor is placed in the object (e.g. a text input) and it will receive keyboard events.

Specified by:

isFocused in interface AttributeReadFocused

Returns:

true if this object is focused, false otherwise.

createLabel

public AbstractUiWidgetLabel<?> createLabel(UiContext context)

This method creates the label for this widget. Depending on the underlying toolkit implementation the native widget may already contain the label (applies e.g. for FormItem in SmartGWT). In such case this method will wrap it as UiWidgetLabel. Otherwise this method should create a new UiWidgetLabel and return it.

Specified by:

createLabel in interface UiWidgetAdapter

Parameters:

context - is the UiContext that may be used to create the label.

Returns:

the label.