net.sf.mmm.client.ui.base.widget.custom.field

Class UiWidgetCustomField<VALUE,DELEGATE extends UiWidgetComposite<?>>

java.lang.Object

net.sf.mmm.client.ui.base.feature.AbstractUiFeatureValueAndValidation<VALUE>

net.sf.mmm.client.ui.base.widget.AbstractUiWidget<VALUE>

net.sf.mmm.client.ui.base.widget.custom.UiWidgetCustom<VALUE,DELEGATE>

net.sf.mmm.client.ui.base.widget.custom.field.UiWidgetCustomField<VALUE,DELEGATE>

Type Parameters:

VALUE - is the generic type of the value. Typically a custom Datatype.

DELEGATE - is the generic type of the delegate.

All Implemented Interfaces:

AttributeReadAccessKey, AttributeReadAriaRole, AttributeReadEnabled, AttributeReadFocused, AttributeReadHtmlId, AttributeReadLabel, AttributeReadMode, AttributeReadModeFixed, AttributeReadModified, AttributeReadPrimaryStyle, AttributeReadStyles, AttributeReadStylesAdvanced, AttributeReadTooltip, AttributeReadTrimValue, AttributeReadValidationFailure, AttributeReadValueAdvanced<VALUE>, AttributeReadValueAsString, AttributeReadVisible, AttributeReadVisibleRecursive, AttributeWriteAccessKey, AttributeWriteEnabled, AttributeWriteFocused, AttributeWriteHtmlId, AttributeWriteLabel, AttributeWriteMode, AttributeWriteModeFixed, AttributeWriteModified, AttributeWriteOnlyFocused, AttributeWritePrimaryStyle, AttributeWriteStyles, AttributeWriteStylesAdvanced, AttributeWriteTooltip, AttributeWriteTrimValue, AttributeWriteValidationFailure, AttributeWriteValueAdvanced<VALUE>, AttributeWriteValueAsString, AttributeWriteVisible, AttributeWriteVisibleAdvanced, UiFeature, UiFeatureEvent, UiFeatureFocus, UiFeatureMessages, UiFeatureMode, UiFeatureValidation<VALUE>, UiFeatureValue<VALUE>, UiFeatureValueAndValidation<VALUE>, UiWidgetField<VALUE>, UiWidget, UiWidgetAbstractComposite, UiWidgetAbstractWithValue<VALUE>, UiWidgetActive, UiWidgetComposite<UiWidget>, UiWidgetRegular, UiWidgetRegularComposite<UiWidget>, UiWidgetWithValue<VALUE>, AttributeReadDisposed, AttributeReadId<String>, AttributeReadValue<VALUE>, AttributeWriteDisposed, AttributeWriteId<String>, AttributeWriteValue<VALUE>, Accessibility, AbstractValidatableObject, HasValueValidators<VALUE>, ValidatableObject<VALUE>

Direct Known Subclasses:

UiWidgetCustomFieldAtomic, UiWidgetCustomFieldComposite

public abstract class UiWidgetCustomField<VALUE,DELEGATE extends UiWidgetComposite<?>>
extends UiWidgetCustom<VALUE,DELEGATE>
implements UiWidgetField<VALUE>

This is the abstract base class for a custom widget that is a field widget. The major usecase is to create field widgets for custom Datatype based on existing field widgets.
Instead of extending this class directly you should rather extend one of its sub-classes.

Since:

1.0.0

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

See Also:

UiWidgetFactoryDatatype.createForDatatype(Class)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	UiWidgetCustomField.EventHandlerAdapter This inner class is an event handler that adapts from the internal fields to this composite custom widget.

Nested classes/interfaces inherited from class net.sf.mmm.client.ui.base.widget.AbstractUiWidget

AbstractUiWidget.AccessHelper, AbstractUiWidget.EventSender, AbstractUiWidget.HandlerContainer

Field Summary

Fields

Modifier and Type	Field and Description
private UiWidgetCustomField.EventHandlerAdapter	eventHandlerAdapter
private UiFeature	focusField The sub-field that currently has the focus or null.

Fields inherited from interface net.sf.mmm.client.ui.api.widget.field.UiWidgetField

STYLE_FIELD, STYLE_LABEL, STYLE_MANDATORY, STYLE_VIEW

Fields inherited from interface net.sf.mmm.client.ui.api.widget.UiWidget

STYLE_HEADER

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

Constructor Summary

Constructors

Constructor and Description
UiWidgetCustomField(UiContext context, DELEGATE delegate, Class<VALUE> valueClass) The constructor.

Method Summary

Modifier and Type	Method and Description
void	addFocusHandler(UiHandlerEventFocus handler) This method adds the given UiHandlerEventFocus to this object.
char	getAccessKey() This method gets the access key of this object.
UiWidget	getChild(int index) This method gets the child at the given index.
UiWidget	getChild(String id) This method gets the child with the given id.
int	getChildCount() This method gets the number of children in this composite.
int	getChildIndex(UiWidget child) This method determines the index of the given child in the list of children of this composite.
(package private) UiWidgetCustomField.EventHandlerAdapter	getEventHandlerAdapter()
(package private) abstract UiWidgetField<?>	getFirstField() This method gets the first active field contained in this custom field.
String	getLabel() This method gets the label of this object.
UiWidgetLabel	getLabelWidget() This method gets the label widget associated with this field.
protected VALUE	getNullValue() This method gets the value in case the delegate widget returns null as value.
String	getValidationFailure() This method gets the validation failure of this object.
String	getValueAsString() This method gets the value as String.
boolean	isFocused() This method determines if this object currently has the focus.
boolean	removeFocusHandler(UiHandlerEventFocus handler) This method removes the given UiHandlerEventFocus from this object.
void	setAccessKey(char accessKey) This method sets the accessKey attribute of this object.
boolean	setFocused() This method sets the focus to this object.
void	setLabel(String label) This method sets the label of this object.
void	setValidationFailure(String validationFailure) This method sets the validation failure.
void	setValueAsString(String value) This method sets the valueAsString of this object.
String	toString()

Methods inherited from class net.sf.mmm.client.ui.base.widget.custom.UiWidgetCustom

addStyle, clearMessages, clearValidity, dispose, doInitialize, doSetMode, doValidate, getAriaRole, getDelegate, getDelegate, getId, getMode, getModeFixed, getParent, getPrimaryStyle, getSize, getSource, getStyles, getTooltip, getValueClass, getVisibleFlag, getWidgetAdapter, hasStyle, hasWidgetAdapter, initialize, isDisposed, isEnabled, isModifiedRecursive, isVisible, isVisibleRecursive, removeFromParent, removeStyle, setEnabled, setId, setMode, setMode, setModeFixed, setParent, setPrimaryStyle, setStyles, setTooltip, setVisible, setVisible

Methods inherited from class net.sf.mmm.client.ui.base.widget.AbstractUiWidget

addChangeHandler, addEventHandler, addValidator, clearMessagesLocal, clearValidationFailure, convertValueToString, doGetValue, doSetValue, fireEvent, fireValueChange, getBasicUtil, getContext, getDataBinding, getDataBinding, getDataBindingForWidget, getEventSender, getFactory, getLogger, getObserverSource, getOriginalValue, getRecentValue, getValueDirect, getValueOrException, getWidgetAdapter, hasEventSender, isMandatory, isModified, removeChangeHandler, removeEventHandler, removeFromParent, removeValidator, setMandatory, setModified, setParent, setValue

Methods inherited from class net.sf.mmm.client.ui.base.feature.AbstractUiFeatureValueAndValidation

addValidatorMandatory, createValidationFailure, getValue, getValueAndValidate, handleGetValueError, resetValue, setValue, setValueForUser, validate

Methods inherited from class java.lang.Object

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

Methods inherited from interface net.sf.mmm.client.ui.api.widget.UiWidget

getContext, getParent, getSize

Methods inherited from interface net.sf.mmm.client.ui.api.feature.UiFeatureMessages

clearMessages

Methods inherited from interface net.sf.mmm.client.ui.api.feature.UiFeatureEvent

addEventHandler, removeEventHandler

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

setMode

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

getMode

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

setModeFixed

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

getModeFixed

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

setId

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

getId

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

setTooltip

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

getTooltip

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

getVisibleFlag, isVisible, setVisible, setVisible

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

isVisibleRecursive

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

setEnabled

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

isEnabled

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

addStyle, removeStyle

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

hasStyle

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

setStyles

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

getStyles

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

setPrimaryStyle

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

getPrimaryStyle

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

dispose

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

isDisposed

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

isModified

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

getAriaRole

Methods inherited from interface net.sf.mmm.client.ui.api.widget.UiWidgetWithValue

getValue

Methods inherited from interface net.sf.mmm.client.ui.api.feature.UiFeatureValueAndValidation

getValueAndValidate, getValueDirect

Methods inherited from interface net.sf.mmm.client.ui.api.feature.UiFeatureValue

addChangeHandler, removeChangeHandler

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

resetValue, setValue, setValue, setValueForUser

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

getOriginalValue, getValueOrException

Methods inherited from interface net.sf.mmm.client.ui.api.feature.UiFeatureValidation

addValidatorMandatory, isMandatory

Methods inherited from interface net.sf.mmm.util.validation.api.HasValueValidators

addValidator, removeValidator

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

setTrimValue

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

isTrimValue

Field Detail

eventHandlerAdapter

private final UiWidgetCustomField.EventHandlerAdapter eventHandlerAdapter

See Also:

getEventHandlerAdapter()

focusField

private UiFeature focusField

The sub-field that currently has the focus or null.

Constructor Detail

UiWidgetCustomField

public UiWidgetCustomField(UiContext context,
                           DELEGATE delegate,
                           Class<VALUE> valueClass)

The constructor.

Parameters:

context - is the context.

delegate - is the delegate.

valueClass - is the value class.

Method Detail

getEventHandlerAdapter

UiWidgetCustomField.EventHandlerAdapter getEventHandlerAdapter()

Returns:

the UiWidgetCustomField.EventHandlerAdapter.

getNullValue

protected VALUE getNullValue()

This method gets the value in case the delegate widget returns null as value. The default implementation return null. Override to change.

Returns:

the null-value.

getValueAsString

public String getValueAsString()

This method gets the value as String. It returns the value as it is entered by the end-user that may be invalid.

Specified by:

getValueAsString in interface AttributeReadValueAsString

Returns:

the value as entered by the user. Will be the empty String if the field is blank.

setValueAsString

public void setValueAsString(String value)

This method sets the valueAsString of this object.
ATTENTION:
This method shall only be used in very specific situations. Use it e.g. if you explicitly want to enter invalid data.

Specified by:

setValueAsString in interface AttributeWriteValueAsString

Parameters:

value - is the new value as it would have been entered by the user.

toString

public String toString()

Overrides:

toString in class AbstractUiWidget<VALUE>

getFirstField

abstract UiWidgetField<?> getFirstField()

This method gets the first active field contained in this custom field. This can be the delegate itself but also a child of the delegate in case of a composite custom field.

Returns:

the UiWidgetCustom.getDelegate()

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).

NOTE:
Every field widget (UiWidgetField) has an associated label widget. This method gets its label text. Please note that the label widget is not contained in this field widget itself, so if you regularly add this field widget to some other widget you will not see the label. However, UiWidgetGridPanel also automatically adds the label widget. The recommended use-case is to create a form to view and edit your business object extending UiWidgetCustomGridPanel and use UiDataBinding.
Unlike UiWidgetField.getLabelWidget().getLabel() this method prevents actually creating the label widget if it does NOT yet exist. Further it will only return what has been set via UiWidgetField.setLabel(String) and NOT what has potentially been set via UiWidgetField.getLabelWidget() . setLabel (what should be avoided).

Specified by:

getLabel in interface AttributeReadLabel

Specified by:

getLabel in interface UiWidgetField<VALUE>

Returns:

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

setLabel

public void setLabel(String label)

This method sets the label of this object.

Specified by:

setLabel in interface AttributeWriteLabel

Specified by:

setLabel in interface UiWidgetField<VALUE>

Parameters:

label - is the new label to set.

See Also:

UiWidgetField.getLabel()

getLabelWidget

public UiWidgetLabel getLabelWidget()

This method gets the label widget associated with this field.
ATTENTION:
Depending on the underlying toolkit the label widget is lazily created on the first call of this method. Additionally users of this API (unlike implementors of the API) may only use this for very specific cases (e.g. setting the style of the label). Therefore you should avoid calling this method unless you are aware of what you are doing. To access the label-text simply use UiWidgetField.getLabel() and UiWidgetField.setLabel(String). Be aware that some native toolkits (e.g. SmartGWT) already implement field widgets including the label. In this case this method will return a different view on the same native widget.

Specified by:

getLabelWidget in interface UiWidgetField<VALUE>

Returns:

the associated label widget.

getChildIndex

public int getChildIndex(UiWidget child)

This method determines the index of the given child in the list of children of this composite.
The signature is by intention not using the generic to support delegation without suffering by the java compiler.

Specified by:

getChildIndex in interface UiWidgetAbstractComposite

Parameters:

child - is the potential child.

Returns:

the index of the given child or -1 if it is NOT a child of this composite.

See Also:

List.indexOf(Object)

getChild

public UiWidget getChild(int index)
                  throws IndexOutOfBoundsException

This method gets the child at the given index.

Specified by:

getChild in interface UiWidgetAbstractComposite

Specified by:

getChild in interface UiWidgetComposite<UiWidget>

Parameters:

index - is the index of the requested child. Has to be in the range from 0 to UiWidgetAbstractComposite.getChildCount() - 1.

Returns:

the requested child.

Throws:

IndexOutOfBoundsException - if the given index is out of bounds.

See Also:

List.get(int)

getChild

public UiWidget getChild(String id)

This method gets the child with the given id.

Specified by:

getChild in interface UiWidgetAbstractComposite

Specified by:

getChild in interface UiWidgetComposite<UiWidget>

Parameters:

id - is the ID of the requested child.

Returns:

the child with the given id or null if no such child exists.

getChildCount

public int getChildCount()

This method gets the number of children in this composite.

Specified by:

getChildCount in interface UiWidgetAbstractComposite

Returns:

the child count.

setFocused

public boolean setFocused()

This method sets the focus to this object.
NOTE:
You can only set the focus. To actually remove it, you need to set it in a different widget. Further, as an API user you can normally ignore the result. This is only relevant for composite widgets such as panels, that delegate the call recursively and may not contain any child that can take the focus.

Specified by:

setFocused in interface AttributeWriteOnlyFocused

Overrides:

setFocused in class UiWidgetCustom<VALUE,DELEGATE extends UiWidgetComposite<?>>

Returns:

true if the focus has been set successfully, 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.

addFocusHandler

public void addFocusHandler(UiHandlerEventFocus handler)

This method adds the given UiHandlerEventFocus to this object.

Specified by:

addFocusHandler in interface UiFeatureFocus

Parameters:

handler - is the UiHandlerEventFocus to add.

removeFocusHandler

public boolean removeFocusHandler(UiHandlerEventFocus handler)

This method removes the given UiHandlerEventFocus from this object.

Specified by:

removeFocusHandler in interface UiFeatureFocus

Parameters:

handler - is the UiHandlerEventFocus to remove.

Returns:

true if the handler has been removed successfully, false if it was NOT registered and nothing has changed.

setAccessKey

public void setAccessKey(char accessKey)

This method sets the accessKey attribute of this object.

Specified by:

setAccessKey in interface AttributeWriteAccessKey

Parameters:

accessKey - is the new value of AttributeReadAccessKey.getAccessKey(). Use AttributeReadAccessKey.ACCESS_KEY_NONE to unset.

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.

setValidationFailure

public void setValidationFailure(String validationFailure)

This method sets the validation failure.
ATTENTION:
For regular usage you should use UiFeatureValidation. This method is only intended as back-door for very special cases (e.g. you have to use your own validator infrastructure and perform validation outside this framework). It is not recommended to use this method as an API user.

Specified by:

setValidationFailure in interface AttributeWriteValidationFailure

Parameters:

validationFailure - is the validation failure text. The empty string or null will clear the error and mark the field as valid. Otherwise the field will be invalid.

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.