de.enough.polish.ui
Class DateField

java.lang.Object
  de.enough.polish.ui.Item
      de.enough.polish.ui.StringItem
          de.enough.polish.ui.DateField

All Implemented Interfaces:

Animatable, CommandListener, ItemCommandListener, UiElement, net.rim.device.api.ui.FieldChangeListener

public class DateField
extends StringItem
implements ItemCommandListener, CommandListener, net.rim.device.api.ui.FieldChangeListener

A DateField is an editable component for presenting date and time (calendar) information that may be placed into a Form. Value for this field can be initially set or left unset. If value is not set then the UI for the field shows this clearly. The field value for "not initialized state" is not valid value and getDate() for this state returns null.

Instance of a DateField can be configured to accept date or time information or both of them. This input mode configuration is done by DATE, TIME or DATE_TIME static fields of this class. DATE input mode allows to set only date information and TIME only time information (hours, minutes). DATE_TIME allows to set both clock time and date values.

In TIME input mode the date components of Date object must be set to the "zero epoch" value of January 1, 1970.

Calendar calculations in this field are based on default locale and defined time zone. Because of the calculations and different input modes date object may not contain same millisecond value when set to this field and get back from this field.

Since:

MIDP 1.0

Author:

Robert Virkus, robert@enough.de

Field Summary

static int	DATE Input mode for date information (day, month, year).
static int	DATE_TIME Input mode for date (day, month, year) and time (minutes, hours) information.
static int	TIME Input mode for time information (hours and minutes).

Fields inherited from class de.enough.polish.ui.StringItem

animateTextWrap, availableTextWidth, clipText, font, isHorizontalAnimationDirectionRight, isTextInitializationRequired, maxLines, maxLinesAppendix, maxLinesAppendixPosition, text, textColor, textEffect, textHorizontalAdjustment, textLayout, textLines, textVerticalAdjustment, textWidth, textWrapDirection, textWrapSpeed, useSingleLine, xOffset

Fields inherited from class de.enough.polish.ui.Item

_bbField, appearanceMode, availableHeight, availableWidth, availContentHeight, availContentWidth, background, backgroundHeight, backgroundWidth, backgroundYOffset, bgBorder, border, BUTTON, colSpan, commands, completeBackground, completeBackgroundPadding, completeBorder, contentHeight, contentWidth, contentX, contentXAdjustment, contentY, contentYAdjustment, cssSelector, defaultCommand, focusedStyle, HORIZONTAL, HYPERLINK, ignoreRepaintRequests, includeLabel, INTERACTIVE, internalHeight, internalWidth, internalX, internalY, isContentVisible, isFocused, isInlineLabel, isInvisible, isLayoutCenter, isLayoutExpand, isLayoutRight, isPressed, isShown, isStyleInitialised, itemCommandListener, itemHeight, itemWidth, label, labelStyle, landscapeStyle, layout, LAYOUT_2, LAYOUT_BOTTOM, LAYOUT_CENTER, LAYOUT_DEFAULT, LAYOUT_EXPAND, LAYOUT_LEFT, LAYOUT_NEWLINE_AFTER, LAYOUT_NEWLINE_BEFORE, LAYOUT_RIGHT, LAYOUT_SHRINK, LAYOUT_TOP, LAYOUT_VCENTER, LAYOUT_VEXPAND, LAYOUT_VSHRINK, marginBottom, marginLeft, marginRight, marginTop, maximumHeight, maximumWidth, minimumHeight, minimumWidth, NO_POSITION_SET, opacity, opacityPaintNormally, opacityRgbData, paddingBottom, paddingHorizontal, paddingLeft, paddingRight, paddingTop, paddingVertical, parent, PLAIN, portraitStyle, preferredHeight, preferredWidth, preserveViewType, relativeX, relativeY, rowSpan, screen, setView, style, TRANSPARENT, useSingleRow, VERTICAL, view, xAdjustment, yAdjustment

Fields inherited from interface net.rim.device.api.ui.FieldChangeListener

PROGRAMMATIC

Constructor Summary

DateField(String label, int mode)
Creates a DateField object with the specified label and mode.

DateField(String label, int mode, Style style)
Creates a DateField object with the specified label and mode.

DateField(String label, int mode, TimeZone timeZone)
Creates a date field in which calendar calculations are based on specific TimeZone object and the default calendaring system for the current locale.

DateField(String label, int mode, TimeZone timeZone, Style style)
Creates a date field in which calendar calculations are based on specific TimeZone object and the default calendaring system for the current locale.

Method Summary

boolean	animate() Animates this item.
void	commandAction(Command cmd, Displayable box) Indicates that a command event has occurred on Displayable d.
void	commandAction(Command c, Item item) Called by the system to indicate that a command has been invoked on a particular item.
protected String	createCssSelector() Retrieves the CSS selector for this item.
protected void	defocus(Style originalStyle) Removes the focus from this item.
void	fieldChanged(net.rim.device.api.ui.Field field, int context)
protected Style	focus(Style newStyle, int direction) Focuses this item.
Date	getDate() Returns date value of this field.
String	getDateFormatPattern()
int	getInputMode() Gets input mode for this date field.
protected boolean	handleKeyPressed(int keyCode, int gameAction) Handles the key-pressed event.
protected boolean	handleKeyReleased(int keyCode, int gameAction) Handles the key-released event.
protected boolean	handlePointerReleased(int relX, int relY) Handles the event when a pointer has been released at the specified position.
protected void	initContent(int firstLineWidth, int availWidth, int availHeight) Initialises this item.
void	paintContent(int x, int y, int leftBorder, int rightBorder, Graphics g) Paints the content of this item.
void	setDate(Date date) Sets a new value for this field.
void	setInputMode(int mode) Set input mode for this date field.
void	setItemCommandListener(ItemCommandListener l) Sets a listener for Commands to this Item, replacing any previous ItemCommandListener.
void	setStyle(Style style) Sets the style of this item.
protected void	showNotify() Called by the system to notify the item that it is now at least partially visible, when it previously had been completely invisible.

Methods inherited from class de.enough.polish.ui.StringItem

addRepaintArea, animate, charWidth, getFont, getFontHeight, getLineHeight, getText, hideNotify, releaseResources, setContentWidth, setFont, setStyle, setText, setText, setTextColor, setTextEffect, stringWidth, toString

Methods inherited from class de.enough.polish.ui.Item

addCommand, addCommand, addCommand, addCommands, addRelativeToBackgroundRegion, addRelativeToBackgroundRegion, addRelativeToContentRegion, containsCommand, destroy, fireEvent, getAbsoluteX, getAbsoluteY, getAppearanceMode, getAttribute, getAttributes, getAvailableContentHeight, getAvailableContentWidth, getAvailableHeight, getAvailableWidth, getBackgroundHeight, getBackgroundWidth, getBackgroundX, getBackgroundY, getBorderWidthBottom, getBorderWidthLeft, getBorderWidthRight, getBorderWidthTop, getContentHeight, getContentWidth, getContentX, getContentY, getDefaultCommand, getFocusedStyle, getInternalHeight, getInternalWidth, getInternalX, getInternalY, getItemAreaHeight, getItemAt, getItemCommandListener, getItemCommands, getItemHeight, getItemHeight, getItemStateListener, getItemWidth, getItemWidth, getLabel, getLabelItem, getLayout, getMarginBottom, getMarginLeft, getMarginRight, getMarginTop, getMinimumHeight, getMinimumWidth, getParent, getPreferredHeight, getPreferredWidth, getScreen, getStyle, getUiEventListener, getView, getView, handleCommand, handleCommand, handleGesture, handleGestureHold, handleGestureSwipeLeft, handleGestureSwipeRight, handleKeyRepeated, handlePointerDragged, handlePointerPressed, handlePointerTouchDown, handlePointerTouchUp, init, initStyle, isInContentArea, isInContentWithPaddingArea, isInItemArea, isInItemArea, isInitialized, isInteractive, isLayoutBottom, isLayoutCenter, isLayoutExpand, isLayoutLeft, isLayoutNewlineAfter, isLayoutNewlineBefore, isLayoutRight, isLayoutShrink, isLayoutTop, isLayoutVerticalCenter, isLayoutVerticalExpand, isLayoutVerticalShrink, isPresed, isVisible, notifyItemPressedEnd, notifyItemPressedStart, notifyStateChanged, notifyUnvisited, notifyVisited, onScreenSizeChanged, paint, paintBackground, paintBackgroundAndBorder, paintBorder, paintCommands, paintFilter, removeAttribute, removeCommand, repaint, repaint, repaintFully, requestInit, setAbsoluteY, setAppearanceMode, setAttribute, setBackground, setBorder, setContentHeight, setDefaultCommand, setDefaultCommand, setInitialized, setItemCommandListener, setItemHeight, setItemStateListener, setItemTransition, setLabel, setLayout, setParent, setParent, setPreferredSize, setUiEventListener, setView, setVisible, show, showCommands, toImage, toRgbImage, updateInternalArea

Methods inherited from class java.lang.Object

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

Field Detail

DATE

public static final int DATE

Input mode for date information (day, month, year). With this mode this DateField presents and allows only to modify date value. The time information of date object is ignored.

Value 1 is assigned to DATE.

See Also:

Constant Field Values

TIME

public static final int TIME

Input mode for time information (hours and minutes). With this mode this DateField presents and allows only to modify time. The date components should be set to the "zero epoch" value of January 1, 1970 and should not be accessed.

Value 2 is assigned to TIME.

See Also:

Constant Field Values

DATE_TIME

public static final int DATE_TIME

Input mode for date (day, month, year) and time (minutes, hours) information. With this mode this DateField presents and allows to modify both time and date information.

Value 3 is assigned to DATE_TIME.

See Also:

Constant Field Values

Constructor Detail

DateField

public DateField(String label,
                 int mode)

Creates a DateField object with the specified label and mode. This call is identical to DateField(label, mode, null).

Parameters:

label - item label

mode - the input mode, one of DATE, TIME or DATE_TIME

Throws:

IllegalArgumentException - if the input mode's value is invalid

DateField

public DateField(String label,
                 int mode,
                 Style style)

Creates a DateField object with the specified label and mode. This call is identical to DateField(label, mode, null).

Parameters:

label - item label

mode - the input mode, one of DATE, TIME or DATE_TIME

style - the CSS style for this item

Throws:

IllegalArgumentException - if the input mode's value is invalid

DateField

public DateField(String label,
                 int mode,
                 TimeZone timeZone)

Creates a date field in which calendar calculations are based on specific TimeZone object and the default calendaring system for the current locale. The value of the DateField is initially in the "uninitialized" state. If timeZone is null, the system's default time zone is used.

Parameters:

label - item label

mode - the input mode, one of DATE, TIME or DATE_TIME

timeZone - a specific time zone, or null for the default time zone

Throws:

IllegalArgumentException - if the input mode's value is invalid

DateField

public DateField(String label,
                 int mode,
                 TimeZone timeZone,
                 Style style)

Creates a date field in which calendar calculations are based on specific TimeZone object and the default calendaring system for the current locale. The value of the DateField is initially in the "uninitialized" state. If timeZone is null, the system's default time zone is used.

Parameters:

label - item label

mode - the input mode, one of DATE, TIME or DATE_TIME

timeZone - a specific time zone, or null for the default time zone

style - the CSS style for this item

Throws:

IllegalArgumentException - if the input mode's value is invalid

Method Detail

getDate

public Date getDate()

Returns date value of this field. Returned value is null if field value is not initialized. The date object is constructed according the rules of locale specific calendaring system and defined time zone. In TIME mode field the date components are set to the "zero epoch" value of January 1, 1970. If a date object that presents time beyond one day from this "zero epoch" then this field is in "not initialized" state and this method returns null. In DATE mode field the time component of the calendar is set to zero when constructing the date object.

Returns:

date object representing time or date depending on input mode

See Also:

setDate(java.util.Date)

setDate

public void setDate(Date date)

Sets a new value for this field. null can be passed to set the field state to "not initialized" state. The input mode of this field defines what components of passed Date object is used.

In TIME input mode the date components must be set to the "zero epoch" value of January 1, 1970. If a date object that presents time beyond one day then this field is in "not initialized" state. In TIME input mode the date component of Date object is ignored and time component is used to precision of minutes.

In DATE input mode the time component of Date object is ignored.

In DATE_TIME input mode the date and time component of Date are used but only to precision of minutes.

Parameters:

date - new value for this field

See Also:

getDate()

getDateFormatPattern

public String getDateFormatPattern()

getInputMode

public int getInputMode()

Gets input mode for this date field. Valid input modes are DATE, TIME and DATE_TIME.

Returns:

input mode of this field

See Also:

setInputMode(int)

setInputMode

public void setInputMode(int mode)

Set input mode for this date field. Valid input modes are DATE, TIME and DATE_TIME.

Parameters:

mode - the input mode, must be one of DATE, TIME or DATE_TIME

Throws:

IllegalArgumentException - if an invalid value is specified

See Also:

getInputMode()

paintContent

public void paintContent(int x,
                         int y,
                         int leftBorder,
                         int rightBorder,
                         Graphics g)

Description copied from class: Item

Paints the content of this item. The background has already been painted and the border will be added after this method returns.

Overrides:

paintContent in class StringItem

Parameters:

x - the left start position

y - the upper start position

leftBorder - the left border, nothing must be painted left of this position

rightBorder - the right border, nothing must be painted right of this position

g - the Graphics on which this item should be painted.

initContent

protected void initContent(int firstLineWidth,
                           int availWidth,
                           int availHeight)

Description copied from class: Item

Initialises this item. The implementation needs to calculate and set the contentWidth and contentHeight fields. The implementation should take the fields preferredWidth and preferredHeight into account.

Overrides:

initContent in class StringItem

Parameters:

firstLineWidth - the maximum width of the first line

availWidth - the available maximum width of this item in pixels

availHeight - the available maximum height of this item in pixels

See Also:

Item.contentWidth, Item.contentHeight, Item.preferredWidth, Item.preferredHeight

createCssSelector

protected String createCssSelector()

Description copied from class: Item

Retrieves the CSS selector for this item. The CSS selector is used for the dynamic assignment of styles - that is the styles are assigned by the usage of the item and not by a predefined style-name. With the #style preprocessing command styles are set fix, this method yields in a faster GUI and is recommended. When in a style-sheet dynamic styles are used, e.g. "Form>p", than the selector of the item is needed.
This abstract method needs only be implemented, when dynamic styles are used: #ifdef polish.useDynamicStyles
The returned selector needs to be in lower case.

Overrides:

createCssSelector in class StringItem

Returns:

the appropriate CSS selector for this item. The selector needs to be in lower case.

setStyle

public void setStyle(Style style)

Description copied from class: Item

Sets the style of this item.

Specified by:

setStyle in interface UiElement

Overrides:

setStyle in class StringItem

Parameters:

style - the new style for this item.

animate

public boolean animate()

Description copied from class: Item

Animates this item. Subclasses can override this method to create animations. The default implementation returns false

Overrides:

animate in class Item

Returns:

true when this item has been animated.

See Also:

Item.animate(long, ClippingRegion)

defocus

protected void defocus(Style originalStyle)

Description copied from class: Item

Removes the focus from this item.

Overrides:

defocus in class StringItem

Parameters:

originalStyle - the original style which will be restored.

focus

protected Style focus(Style newStyle,
                      int direction)

Description copied from class: Item

Focuses this item.

Overrides:

focus in class Item

Parameters:

newStyle - the style which is used to indicate the focused state

direction - the direction from which this item is focused, either Canvas.UP, Canvas.DOWN, Canvas.LEFT, Canvas.RIGHT or 0. When 0 is given, the direction is unknown.

Returns:

the current style of this item

showNotify

protected void showNotify()

Description copied from class: Item

Called by the system to notify the item that it is now at least partially visible, when it previously had been completely invisible. The item may receive paint() calls after showNotify() has been called.

The default implementation of this method sets the isShown field to true and calls showNotify on style elements.

Overrides:

showNotify in class StringItem

handleKeyPressed

protected boolean handleKeyPressed(int keyCode,
                                   int gameAction)

Description copied from class: Item

Handles the key-pressed event. Please note, that implementation should first try to handle the given key-code, before the game-action is processed. The default implementation just handles the FIRE game-action when a default-command and an item-command-listener have been registered.

Overrides:

handleKeyPressed in class Item

Parameters:

keyCode - the code of the pressed key, e.g. Canvas.KEY_NUM2

gameAction - the corresponding game-action, e.g. Canvas.UP

Returns:

true when the key has been handled / recognized

handleKeyReleased

protected boolean handleKeyReleased(int keyCode,
                                    int gameAction)

Description copied from class: Item

Handles the key-released event. Please note, that implementation should first try to handle the given key-code, before the game-action is processed. The default implementation invokes the default command if one is present

Overrides:

handleKeyReleased in class Item

Parameters:

keyCode - the code of the pressed key, e.g. Canvas.KEY_NUM2

gameAction - the corresponding game-action, e.g. Canvas.UP

Returns:

true when the key has been handled / recognized

See Also:

Item.handleKeyPressed(int, int)

commandAction

public void commandAction(Command cmd,
                          Displayable box)

Description copied from interface: CommandListener

Indicates that a command event has occurred on Displayable d.

Specified by:

commandAction in interface CommandListener

Parameters:

cmd - - a Command object identifying the command. This is either one of the applications have been added to Displayable with addCommand(Command) or is the implicit SELECT_COMMAND of List.

box - - the Displayable on which this event has occurred

setItemCommandListener

public void setItemCommandListener(ItemCommandListener l)

Description copied from class: Item

Sets a listener for Commands to this Item, replacing any previous ItemCommandListener. A null reference is allowed and has the effect of removing any existing listener. When no listener is registered, J2ME Polish notifies the command-listener of the current screen, when an item command has been selected.

It is illegal to call this method if this Item is contained within an Alert.

Overrides:

setItemCommandListener in class Item

Parameters:

l - the new listener, or null.

commandAction

public void commandAction(Command c,
                          Item item)

Description copied from interface: ItemCommandListener

Called by the system to indicate that a command has been invoked on a particular item.

Specified by:

commandAction in interface ItemCommandListener

Parameters:

c - the Command that was invoked

item - the Item on which the command was invoked

handlePointerReleased

protected boolean handlePointerReleased(int relX,
                                        int relY)

Description copied from class: Item

Handles the event when a pointer has been released at the specified position. The default method discards this event when relX/relY is outside of the item's area. When the event took place inside of the content area, the pointer-event is translated into an artificial FIRE game-action keyReleased event, which is subsequently handled bu the handleKeyPressed(-1, Canvas.FIRE) method. This method needs should be overwritten only when the "polish.hasPointerEvents" preprocessing symbol is defined: "//#ifdef polish.hasPointerEvents".

Overrides:

handlePointerReleased in class Item

Parameters:

relX - the x position of the pointer pressing relative to this item's left position

relY - the y position of the pointer pressing relative to this item's top position

Returns:

true when the pressing of the pointer was actually handled by this item.

See Also:

this method is used for determining whether the event belongs to this item, for a helper method for determining whether the event took place into the actual content area, Item.handleKeyPressed(int, int), for calculating the horizontal position relative to the content (relX - contentX), for calculating the vertical position relative to the content (relY - contentY)

fieldChanged

public void fieldChanged(net.rim.device.api.ui.Field field,
                         int context)

Specified by:

fieldChanged in interface net.rim.device.api.ui.FieldChangeListener