com.smartgwt.client.widgets.form.fields
Class DateItem

java.lang.Object
  extended by com.smartgwt.client.core.JsObject
      extended by com.smartgwt.client.core.DataClass
          extended by com.smartgwt.client.core.RefDataClass
              extended by com.smartgwt.client.widgets.form.fields.FormItem
                  extended by com.smartgwt.client.widgets.form.fields.DateItem
All Implemented Interfaces:
HasHandlers, HasBlurHandlers, HasChangedHandlers, HasChangeHandlers, HasClickHandlers, HasDoubleClickHandlers, HasFocusHandlers, HasIconClickHandlers, HasIconKeyPressHandlers, HasItemHoverHandlers, HasKeyDownHandlers, HasKeyPressHandlers, HasKeyUpHandlers, HasTitleHoverHandlers
Direct Known Subclasses:
DateTimeItem

public class DateItem
extends FormItem

Item for manipulating Dates.

Can be rendered as a text field, or as 3 selects for day, month, year. Includes optional pop-up picker.


Field Summary
 
Fields inherited from class com.smartgwt.client.core.JsObject
jsObj
 
Constructor Summary
DateItem()
           
DateItem(JavaScriptObject jsObj)
           
DateItem(String name)
           
DateItem(String name, String title)
           
 
Method Summary
 void deselectValue()
          If useTextField is true, falls through to standard com.smartgwt.client.widgets.form.fields.FormItem#deselectValue implementation on this items freeform text entry field.
 void deselectValue(boolean start)
          If useTextField is true, falls through to standard com.smartgwt.client.widgets.form.fields.FormItem#deselectValue implementation on this items freeform text entry field.
 int getCenturyThreshold()
          Only used if we're showing the date in a text field.
 DateDisplayFormat getDisplayFormat()
          If useTextField is true this property can be used to customize the format in which dates are displayed.
Should be set to a standard DateDisplayFormat or a function which will return a formatted date string.
 Date getEndDate()
          Maximum date the selectors will allow the user to pick.
 Boolean getEnforceDate()
          Can this field be set to a non-date value [other than null]?
 String getInputFormat()
          If useTextField is true this property can be used to specify the input format for date strings.
 String getInvalidDateStringMessage()
          Validation error message to display if the user enters an invalid date
static DateItem getOrCreateRef(JavaScriptObject jsObj)
           
 String getPickerIconPrompt()
          Prompt to show when the user hovers the mouse over the picker icon for this DateItem.
 int[] getSelectionRange()
          If useTextField is true, falls through to standard com.smartgwt.client.widgets.form.fields.FormItem#getSelectionRange implementation on this items freeform text entry field.
 DateItemSelectorFormat getSelectorFormat()
          If showing date selectors rather than the date text field (so when this.useTextField is false), this property allows customization of the order of the day, month and year selector fields.
 Date getStartDate()
          Minimum date the selectors will allow the user to pick.
 Alignment getTextAlign()
          If useTextField is true this property governs the alignment of text within the text field.
 Boolean getUseTextField()
          Should we show the date in a text field, or as 3 select boxes?
 void selectValue()
          If useTextField is true, falls through to standard com.smartgwt.client.widgets.form.fields.FormItem#selectValue implementation on this items freeform text entry field.
 void setCenturyThreshold(int centuryThreshold)
          Only used if we're showing the date in a text field.
 void setDateFormatter(DateDisplayFormat dateFormatter)
          If dateFormatter is set at init time, it will be used instead of displayFormat to govern how dates are displayed in this item.
 void setDisplayFormat(DateDisplayFormat displayFormat)
          If useTextField is true this property can be used to customize the format in which dates are displayed.
Should be set to a standard DateDisplayFormat or a function which will return a formatted date string.
 void setEndDate(Date endDate)
          Maximum date the selectors will allow the user to pick.
 void setEnforceDate(Boolean enforceDate)
          Can this field be set to a non-date value [other than null]?
 void setInputFormat(String inputFormat)
          If useTextField is true this property can be used to specify the input format for date strings.
 void setInvalidDateStringMessage(String invalidDateStringMessage)
          Validation error message to display if the user enters an invalid date
 void setMaskDateSeparator(String maskDateSeparator)
          If useTextField and useMask are both true this value is the separator between date components.
 void setPickerIconPrompt(String pickerIconPrompt)
          Prompt to show when the user hovers the mouse over the picker icon for this DateItem.
 void setSelectionRange(int start, int end)
          If useTextField is true, falls through to standard com.smartgwt.client.widgets.form.fields.FormItem#setSelectionRange implementation on this items freeform text entry field.
 void setSelectorFormat(DateItemSelectorFormat selectorFormat)
          If showing date selectors rather than the date text field (so when this.useTextField is false), this property allows customization of the order of the day, month and year selector fields.
 void setStartDate(Date startDate)
          Minimum date the selectors will allow the user to pick.
 void setTextAlign(Alignment textAlign)
          If useTextField is true this property governs the alignment of text within the text field.
 void setUseMask(Boolean useMask)
          If useTextField is not false this property determines if an input mask should be used.
 void setUseTextField(Boolean useTextField)
          Should we show the date in a text field, or as 3 select boxes?
 
Methods inherited from class com.smartgwt.client.widgets.form.fields.FormItem
addBlurHandler, addChangedHandler, addChangeHandler, addClickHandler, addDoubleClickHandler, addFocusHandler, addIconClickHandler, addIconKeyPressHandler, addItemHoverHandler, addKeyDownHandler, addKeyPressHandler, addKeyUpHandler, addTitleHoverHandler, blurItem, clearValue, disable, enable, focusInItem, getAccessKey, getAlign, getAttribute, getAttributeAsBoolean, getAttributeAsDate, getAttributeAsDouble, getAttributeAsFloat, getAttributeAsInt, getAttributeAsJavaScriptObject, getAttributeAsString, getCellStyle, getConfig, getCriteriaField, getCriterion, getDataPath, getDateFormatter, getDefaultIconSrc, getDisabled, getDisplayField, getDisplayFieldName, getDisplayValue, getDisplayValue, getEmptyDisplayValue, getEmptyValueIcon, getEndRow, getErrorIconHeight, getErrorIconSrc, getErrorIconWidth, getErrorMessageWidth, getFetchMissingValues, getFieldName, getFilterLocally, getForm, getGlobalTabIndex, getHeight, getHint, getHintStyle, getHoverAlign, getHoverDelay, getHoverHeight, getHoverOpacity, getHoverStyle, getHoverVAlign, getHoverWidth, getIconHeight, getIconPageRect, getIconPrompt, getIconRect, getIconVAlign, getIconWidth, getImageURLPrefix, getImageURLSuffix, getLeft, getName, getOperator, getOptionCriteria, getOptionFilterContext, getOptionOperationId, getPickerIconHeight, getPickerIconSrc, getPickerIconWidth, getPrompt, getRejectInvalidValueOnChange, getRequired, getRowSpan, getSelectOnFocus, getShouldSaveValue, getShowDisabled, getShowErrorIcon, getShowErrorStyle, getShowErrorText, getShowFocused, getShowFocusedIcons, getShowFocusedPickerIcon, getShowHint, getShowIcons, getShowOverIcons, getShowPickerIcon, getShowTitle, getShowValueIconOnly, getStartRow, getSuppressValueIcon, getTabIndex, getTextBoxStyle, getTimeFormatter, getTitle, getTitleAlign, getTitleOrientation, getTitleStyle, getTooltip, getTop, getType, getValidateOnChange, getValue, getValueField, getValueFieldName, getValueIconHeight, getValueIconLeftPadding, getValueIconRightPadding, getValueIconSize, getValueIconWidth, getVisible, getWidth, getWrapTitle, hide, isCreated, isDisabled, isDrawn, redraw, setAccessKey, setAlign, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setCellStyle, setColSpan, setColSpan, setCriteriaField, setDataPath, setDefaultIconSrc, setDefaultValue, setDefaultValue, setDefaultValue, setDefaultValue, setDefaultValue, setDisabled, setDisplayField, setEditorType, setEditorValueFormatter, setEditorValueParser, setEmptyDisplayValue, setEmptyValueIcon, setEndRow, setErrorFormatter, setErrorIconHeight, setErrorIconSrc, setErrorIconWidth, setErrorMessageWidth, setErrorOrientation, setFetchMissingValues, setFilterLocally, setGlobalTabIndex, setHeight, setHeight, setHint, setHintStyle, setHoverAlign, setHoverDelay, setHoverHeight, setHoverOpacity, setHoverStyle, setHoverVAlign, setHoverWidth, setIconHeight, setIconPrompt, setIcons, setIconVAlign, setIconWidth, setImageURLPrefix, setImageURLSuffix, setInputTransformer, setItemHoverFormatter, setItemTitleHoverFormatter, setLeft, setName, setOperator, setOptionCriteria, setOptionDataSource, setOptionFilterContext, setOptionOperationId, setPickerIconHeight, setPickerIconSrc, setPickerIconWidth, setPrompt, setProperty, setProperty, setProperty, setProperty, setRedrawOnChange, setRejectInvalidValueOnChange, setRequired, setRowSpan, setSelectOnFocus, setShouldSaveValue, setShowDisabled, setShowErrorIcon, setShowErrorStyle, setShowErrorText, setShowFocused, setShowFocusedIcons, setShowFocusedPickerIcon, setShowHint, setShowIcons, setShowIfCondition, setShowOverIcons, setShowPickerIcon, setShowTitle, setShowValueIconOnly, setStartRow, setSuppressValueIcon, setTabIndex, setTextBoxStyle, setTimeFormatter, setTitle, setTitleAlign, setTitleOrientation, setTitleStyle, setTooltip, setTop, setType, setValidateOnChange, setValidators, setValue, setValue, setValue, setValue, setValue, setValue, setValueField, setValueFormatter, setValueIconHeight, setValueIconLeftPadding, setValueIconRightPadding, setValueIcons, setValueIconSize, setValueIconWidth, setValueMap, setValueMap, setVisible, setWidth, setWidth, setWrapTitle, show, stopHover, updateState
 
Methods inherited from class com.smartgwt.client.core.RefDataClass
getRef, getRef
 
Methods inherited from class com.smartgwt.client.core.DataClass
doAddHandler, fireEvent, getAttributeAsIntArray, getAttributeAsMap, getAttributeAsObject, getAttributeAsStringArray, getAttributes, getHandlerCount, getJsObj, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute
 
Methods inherited from class com.smartgwt.client.core.JsObject
setJsObj
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface com.google.gwt.event.shared.HasHandlers
fireEvent
 

Constructor Detail

DateItem

public DateItem()

DateItem

public DateItem(JavaScriptObject jsObj)

DateItem

public DateItem(String name)

DateItem

public DateItem(String name,
                String title)
Method Detail

getOrCreateRef

public static DateItem getOrCreateRef(JavaScriptObject jsObj)

setUseTextField

public void setUseTextField(Boolean useTextField)
Should we show the date in a text field, or as 3 select boxes?

Parameters:
useTextField - useTextField Default value is null

getUseTextField

public Boolean getUseTextField()
Should we show the date in a text field, or as 3 select boxes?

Returns:
Boolean

setTextAlign

public void setTextAlign(Alignment textAlign)
If useTextField is true this property governs the alignment of text within the text field.

Overrides:
setTextAlign in class FormItem
Parameters:
textAlign - textAlign Default value is Canvas.RIGHT

getTextAlign

public Alignment getTextAlign()
If useTextField is true this property governs the alignment of text within the text field.

Overrides:
getTextAlign in class FormItem
Returns:
Alignment

setUseMask

public void setUseMask(Boolean useMask)
If useTextField is not false this property determines if an input mask should be used. The format of the mask is determined by the inputFormat or displayFormat (in that order).

NOTE: If neither inputFormat nor displayFormat is set (default), the mask for input format MDY is used.

Note : This is an advanced setting

Parameters:
useMask - useMask Default value is null

setMaskDateSeparator

public void setMaskDateSeparator(String maskDateSeparator)
If useTextField and useMask are both true this value is the separator between date components.

Note : This is an advanced setting

Parameters:
maskDateSeparator - maskDateSeparator Default value is "/"

setEnforceDate

public void setEnforceDate(Boolean enforceDate)
Can this field be set to a non-date value [other than null]?

When set to true, FormItem.setValue(int) will return false without setting the item value and log a warning if passed something other than a valid date value. If the dateItem is showing a 'free-form text entry field', and a user enters a text value which cannot be parsed into a valid date, the item will automatically redraw and display the invalidDateStringMessage (though at this point calling FormItem.getValue() will return the string entered by the user).

When set to false, a user may enter value that is not a valid date (for example, "Not applicable") and the value will not immediately be flagged as an error. However note that for the value to actually pass validation you would need to declare the field as not of "date" type, for example:

   
 {name:"startDate", type:"dateOrOther", editorType:"DateItem", useTextField:true },
 
The type "dateOrOther" could be declared as a SimpleType, with validators that will accept either a valid date or certain special Strings (like "Not Available").

Only applies to dateItems where useTextField is true. Non-Date values are never supported in items where useTextField is false.

Note : This is an advanced setting

Parameters:
enforceDate - enforceDate Default value is false

getEnforceDate

public Boolean getEnforceDate()
Can this field be set to a non-date value [other than null]?

When set to true, FormItem.setValue(int) will return false without setting the item value and log a warning if passed something other than a valid date value. If the dateItem is showing a 'free-form text entry field', and a user enters a text value which cannot be parsed into a valid date, the item will automatically redraw and display the invalidDateStringMessage (though at this point calling FormItem.getValue() will return the string entered by the user).

When set to false, a user may enter value that is not a valid date (for example, "Not applicable") and the value will not immediately be flagged as an error. However note that for the value to actually pass validation you would need to declare the field as not of "date" type, for example:

   
 {name:"startDate", type:"dateOrOther", editorType:"DateItem", useTextField:true },
 
The type "dateOrOther" could be declared as a SimpleType, with validators that will accept either a valid date or certain special Strings (like "Not Available").

Only applies to dateItems where useTextField is true. Non-Date values are never supported in items where useTextField is false.

Returns:
Boolean

setInvalidDateStringMessage

public void setInvalidDateStringMessage(String invalidDateStringMessage)
Validation error message to display if the user enters an invalid date

Parameters:
invalidDateStringMessage - invalidDateStringMessage Default value is "Invalid date"

getInvalidDateStringMessage

public String getInvalidDateStringMessage()
Validation error message to display if the user enters an invalid date

Returns:
String

setPickerIconPrompt

public void setPickerIconPrompt(String pickerIconPrompt)
Prompt to show when the user hovers the mouse over the picker icon for this DateItem. May be overridden for localization of your application.

Parameters:
pickerIconPrompt - pickerIconPrompt Default value is "Show Date Chooser"

getPickerIconPrompt

public String getPickerIconPrompt()
Prompt to show when the user hovers the mouse over the picker icon for this DateItem. May be overridden for localization of your application.

Returns:
String

setStartDate

public void setStartDate(Date startDate)
Minimum date the selectors will allow the user to pick.

Parameters:
startDate - startDate Default value is 1/1/1995

getStartDate

public Date getStartDate()
Minimum date the selectors will allow the user to pick.

Returns:
java.util.Date

setEndDate

public void setEndDate(Date endDate)
Maximum date the selectors will allow the user to pick.

Parameters:
endDate - endDate Default value is 12/31/2015

getEndDate

public Date getEndDate()
Maximum date the selectors will allow the user to pick.

Returns:
java.util.Date

setCenturyThreshold

public void setCenturyThreshold(int centuryThreshold)
Only used if we're showing the date in a text field. When parsing a date, if the year is specified with only 2 digits and is less than the centuryThreshold, then the year will be assumed to be 20xx; otherwise it will be interpreted according to default browser behaviour, which will consider it to be 19xx.

Parameters:
centuryThreshold - centuryThreshold Default value is 25

getCenturyThreshold

public int getCenturyThreshold()
Only used if we're showing the date in a text field. When parsing a date, if the year is specified with only 2 digits and is less than the centuryThreshold, then the year will be assumed to be 20xx; otherwise it will be interpreted according to default browser behaviour, which will consider it to be 19xx.

Returns:
int

setDateFormatter

public void setDateFormatter(DateDisplayFormat dateFormatter)
If dateFormatter is set at init time, it will be used instead of displayFormat to govern how dates are displayed in this item.

Note : This is an advanced setting

Overrides:
setDateFormatter in class FormItem
Parameters:
dateFormatter - dateFormatter Default value is null

setDisplayFormat

public void setDisplayFormat(DateDisplayFormat displayFormat)
If useTextField is true this property can be used to customize the format in which dates are displayed.
Should be set to a standard DateDisplayFormat or a function which will return a formatted date string.

If unset, the standard shortDate format as set up via com.smartgwt.client..Date#setShortDisplayFormat will be used.

NOTE: you may need to update the 'inputFormat' to ensure the DateItem is able to parse user-entered date strings back into Dates

Parameters:
displayFormat - displayFormat Default value is null

getDisplayFormat

public DateDisplayFormat getDisplayFormat()
If useTextField is true this property can be used to customize the format in which dates are displayed.
Should be set to a standard DateDisplayFormat or a function which will return a formatted date string.

If unset, the standard shortDate format as set up via com.smartgwt.client..Date#setShortDisplayFormat will be used.

NOTE: you may need to update the 'inputFormat' to ensure the DateItem is able to parse user-entered date strings back into Dates

Returns:
DateDisplayFormat

setInputFormat

public void setInputFormat(String inputFormat)
If useTextField is true this property can be used to specify the input format for date strings. If unset, the input format will be determined based on the specified displayFormat if possible (see getInputFormat()), otherwise picked up from the Date class (see com.smartgwt.client..Date#setInputFormat).

Should be set to a standard com.smartgwt.client..DateInputFormat or a function which will take a date string as a parameter and return a Javascript Date object.

Parameters:
inputFormat - inputFormat Default value is null

getInputFormat

public String getInputFormat()
If useTextField is true this property can be used to specify the input format for date strings. If unset, the input format will be determined based on the specified displayFormat if possible (see getInputFormat()), otherwise picked up from the Date class (see com.smartgwt.client..Date#setInputFormat).

Should be set to a standard com.smartgwt.client..DateInputFormat or a function which will take a date string as a parameter and return a Javascript Date object.

Returns:
If useTextField is true this method returns a standard com.smartgwt.client..DateInputFormat, or parsing function, determining how values entered by the user are to be converted to Javascript Date objects.

If an explicit inputFormat has been specified it will be returned.

Otherwise, if an explicit displayFormat has been specified as one of toUSShortDate, toEuropeanShortDate or toJapanShortDate this method will return the appropriate DateInputFormat to parse strings entered in the specified displayFormat.

If no inputFormat can be derived, the method will return null, meaning the standard input format for Date objects (specified via com.smartgwt.client..Date#setInputFormat) will be used.


setSelectorFormat

public void setSelectorFormat(DateItemSelectorFormat selectorFormat)
If showing date selectors rather than the date text field (so when this.useTextField is false), this property allows customization of the order of the day, month and year selector fields. If unset these fields will match the specified inputFormat for this item.

Note: selectors may be ommitted entirely by setting selectorFormat to (for example) "MD". In this case the value for the omitted selector will match the ${isc.DocUtils.linkForRef('defaultValue')} specified for the item. For example, if the selector format is "MD" (month and day only), the year comes from the Date specified as the defaultValue.

Parameters:
selectorFormat - selectorFormat Default value is null

getSelectorFormat

public DateItemSelectorFormat getSelectorFormat()
If showing date selectors rather than the date text field (so when this.useTextField is false), this property allows customization of the order of the day, month and year selector fields. If unset these fields will match the specified inputFormat for this item.

Note: selectors may be ommitted entirely by setting selectorFormat to (for example) "MD". In this case the value for the omitted selector will match the ${isc.DocUtils.linkForRef('defaultValue')} specified for the item. For example, if the selector format is "MD" (month and day only), the year comes from the Date specified as the defaultValue.

Returns:
DateItemSelectorFormat

setSelectionRange

public void setSelectionRange(int start,
                              int end)
If useTextField is true, falls through to standard com.smartgwt.client.widgets.form.fields.FormItem#setSelectionRange implementation on this items freeform text entry field. Otherwise has no effect.

Parameters:
start - character index for start of new selection
end - character index for end of new selection

selectValue

public void selectValue()
If useTextField is true, falls through to standard com.smartgwt.client.widgets.form.fields.FormItem#selectValue implementation on this items freeform text entry field. Otherwise has no effect.


deselectValue

public void deselectValue()
If useTextField is true, falls through to standard com.smartgwt.client.widgets.form.fields.FormItem#deselectValue implementation on this items freeform text entry field. Otherwise has no effect.


deselectValue

public void deselectValue(boolean start)
If useTextField is true, falls through to standard com.smartgwt.client.widgets.form.fields.FormItem#deselectValue implementation on this items freeform text entry field. Otherwise has no effect.

Parameters:
start - If this parameter is passed, new cursor insertion position will be moved to the start, rather than the end of this item's value.

getSelectionRange

public int[] getSelectionRange()
If useTextField is true, falls through to standard com.smartgwt.client.widgets.form.fields.FormItem#getSelectionRange implementation on this items freeform text entry field. Otherwise has no effect.

Returns:
2 element array indicating start/end character index of current selection within our text entry field. Returns null if this item is undrawn or doesn't have focus.