de.enough.polish.ui
Class ChoiceTextField

java.lang.Object
  javax.microedition.lcdui.Item
      javax.microedition.lcdui.CustomItem
          de.enough.polish.ui.FakeCustomItem
              de.enough.polish.ui.FakeStringCustomItem
                  de.enough.polish.ui.FakeTextFieldCustomItem
                      de.enough.polish.ui.ChoiceTextField

All Implemented Interfaces:

ItemCommandListener, javax.microedition.lcdui.CommandListener

public class ChoiceTextField
extends FakeTextFieldCustomItem

Provides a TextField that provides the user with possible matches for the current input.

Copyright Enough Software 2006 - 2008

 history
        27-Feb-2006 - rob creation
 

Author:

Robert Virkus, j2mepolish@enough.de

Field Summary

static int	MATCH_INDEX_OF The matching mode that selects choices that contain the same characters as the current input
static int	MATCH_STARTS_WITH The matching mode that selects choices that start with the same characters as the current input

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

ANY, caretChar, CLEAR_CMD, CONSTRAINT_MASK, DECIMAL, DELETE_CMD, EMAILADDR, emailSeparatorChar, flashCaret, INITIAL_CAPS_SENTENCE, INITIAL_CAPS_WORD, isUneditable, lock, NON_PREDICTIVE, NUMERIC, PASSWORD, PHONENUMBER, SENSITIVE, showCaret, title, UNEDITABLE, URL

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

bitMapFont, bitMapFontViewer, clipText, font, text, textColor, textEffect, textHorizontalAdjustment, textLines, textVerticalAdjustment, useSingleLine, xOffset

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

_bbField, _bbFieldAdded, appearanceMode, background, backgroundHeight, backgroundWidth, backgroundYOffset, border, borderWidth, BUTTON, colSpan, commands, contentHeight, contentWidth, contentX, contentY, cssSelector, defaultCommand, focusedStyle, HORIZONTAL, HYPERLINK, includeLabel, INTERACTIVE, internalHeight, internalWidth, internalX, internalY, isFocused, isInitialized, isInvisible, isLayoutCenter, isLayoutExpand, isLayoutRight, isPressed, isShown, isStyleInitialised, itemCommandListener, itemHeight, itemWidth, label, labelStyle, 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, paddingBottom, paddingHorizontal, paddingLeft, paddingRight, paddingTop, paddingVertical, parent, PLAIN, preferredHeight, preferredWidth, preserveViewType, relativeX, relativeY, rowSpan, screen, style, TRANSPARENT, VERTICAL, view

Fields inherited from class javax.microedition.lcdui.CustomItem

KEY_PRESS, KEY_RELEASE, KEY_REPEAT, NONE, POINTER_DRAG, POINTER_PRESS, POINTER_RELEASE, TRAVERSE_HORIZONTAL, TRAVERSE_VERTICAL

Constructor Summary

ChoiceTextField(java.lang.String label, java.lang.String text, int maxSize, int constraints, java.lang.String[] availableChoices, boolean allowFreeTextEntry)
Creates a new ChoiceTextField.

ChoiceTextField(java.lang.String label, java.lang.String text, int maxSize, int constraints, java.lang.String[] availableChoices, boolean allowFreeTextEntry, boolean appendChoice, java.lang.String appendChoiceDelimiter)
Creates a new ChoiceTextField.

ChoiceTextField(java.lang.String label, java.lang.String text, int maxSize, int constraints, java.lang.String[] availableChoices, boolean allowFreeTextEntry, boolean appendChoice, java.lang.String appendChoiceDelimiter, Style style)
Creates a new ChoiceTextField.

ChoiceTextField(java.lang.String label, java.lang.String text, int maxSize, int constraints, java.lang.String[] availableChoices, boolean allowFreeTextEntry, Style style)
Creates a new ChoiceTextField.

Method Summary

void	animate(long currentTime, ClippingRegion repaintRegion) Animates this item.
protected void	defocus(Style origStyle) Removes the focus from this item.
protected Style	focus(Style focStyle, int direction) Focuses this item.
int	getMatchMode() Retrieves the matching algorithm that is used for finding out whether an available choices matches the input of the user.
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	handlePointerPressed(int x, int y) Handles the event when a pointer has been pressed at the specified position.
protected boolean	handlePointerReleased(int x, int y) Handles the event when a pointer has been released at the specified position.
protected void	initContent(int firstLineWidth, int lineWidth) Initialises this item.
void	notifyStateChanged() Causes this Item's containing Form to notify the Item's ItemStateListener.
void	paintContent(int x, int y, int leftBorder, int rightBorder, javax.microedition.lcdui.Graphics g) Paints the content of this item.
void	setChoices(Item[] choices) Sets the available choices.
void	setChoices(java.lang.String[] choices) Sets the available choices.
void	setChoiceTrigger(char choiceTrigger, boolean allowChoicesBeforeTrigger) Enables that available choices should (only) be shown after the specified character is entered.
void	setMatchMode(int mode) Sets the matching algorithm that is used for finding out whether an available choices matches the input of the user.
void	setStyle(Style style) Sets the style of this item.

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

animate, commandAction, commandAction, createCssSelector, delete, fieldChanged, getCaretPosition, getChars, getConstraints, getDotSeparatedDecimalString, getMaxSize, getString, handleKeyRepeated, insert, insert, insertCharacter, setCaretPosition, setChars, setConstraints, setInitialInputMode, setInputMode, setItemCommandListener, setMaxSize, setString, size

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

getFont, getText, hideNotify, releaseResources, setFont, setText, setText, showNotify, toString

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

addCommand, addCommand, addCommands, addRelativeToBackgroundRegion, addRelativeToContentRegion, containsCommand, getAbsoluteX, getAbsoluteY, getAppearanceMode, getAttribute, getAttributes, getBackgroundHeight, getBackgroundWidth, getBackgroundX, getBackgroundY, getContentHeight, getContentWidth, getContentX, getContentY, getDefaultCommand, getFocusedStyle, getItemAt, getItemCommandListener, getItemHeight, getItemStateListener, getItemWidth, getLabel, getLabelItem, getLayout, getMinContentHeight, getMinContentWidth, getMinimumHeight, getMinimumWidth, getParent, getPrefContentHeight, getPrefContentWidth, getPreferredHeight, getPreferredWidth, getScreen, getStyle, handleCommand, init, initStyle, isInContentArea, isInItemArea, isVisible, notifyItemPressedEnd, notifyItemPressedStart, paint, paint, paintBackground, paintBackgroundAndBorder, paintBorder, removeCommand, repaintFully, requestInit, setAppearanceMode, setAttribute, setDefaultCommand, setItemCommandListener, setItemStateListener, setLabel, setLayout, setPreferredSize, setVisible, show, showCommands

Methods inherited from class javax.microedition.lcdui.CustomItem

getGameAction, getInteractionModes, invalidate, keyPressed, keyReleased, keyRepeated, pointerDragged, pointerPressed, pointerReleased, repaint, repaint, sizeChanged, traverse, traverseOut

Methods inherited from class java.lang.Object

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

Field Detail

MATCH_STARTS_WITH

public static final int MATCH_STARTS_WITH

The matching mode that selects choices that start with the same characters as the current input

See Also:

Constant Field Values

MATCH_INDEX_OF

public static final int MATCH_INDEX_OF

The matching mode that selects choices that contain the same characters as the current input

See Also:

Constant Field Values

Constructor Detail

ChoiceTextField

public ChoiceTextField(java.lang.String label,
                       java.lang.String text,
                       int maxSize,
                       int constraints,
                       java.lang.String[] availableChoices,
                       boolean allowFreeTextEntry)

Creates a new ChoiceTextField.

Parameters:

label - the label

text - the current text

maxSize - the maximum size for the input

constraints - input constraints, TextField.ANY for no constraints

availableChoices - a list of available texts for the user

allowFreeTextEntry - true when the user should be allowed to enter any text that does not match any existing choice

ChoiceTextField

public ChoiceTextField(java.lang.String label,
                       java.lang.String text,
                       int maxSize,
                       int constraints,
                       java.lang.String[] availableChoices,
                       boolean allowFreeTextEntry,
                       Style style)

Creates a new ChoiceTextField.

Parameters:

label - the label

text - the current text

maxSize - the maximum size for the input

constraints - input constraints, TextField.ANY for no constraints

availableChoices - a list of available texts for the user

allowFreeTextEntry - true when the user should be allowed to enter any text that does not match any existing choice

style - the style for this item

ChoiceTextField

public ChoiceTextField(java.lang.String label,
                       java.lang.String text,
                       int maxSize,
                       int constraints,
                       java.lang.String[] availableChoices,
                       boolean allowFreeTextEntry,
                       boolean appendChoice,
                       java.lang.String appendChoiceDelimiter)

Creates a new ChoiceTextField.

Parameters:

label - the label

text - the current text

maxSize - the maximum size for the input

constraints - input constraints, TextField.ANY for no constraints

availableChoices - a list of available texts for the user

allowFreeTextEntry - true when the user should be allowed to enter any text that does not match any existing choice

appendChoice - true when the selected choices should be appended to the text rather than replacing the text

appendChoiceDelimiter - the character that separates several selections, e.g. '\n' or ';'

ChoiceTextField

public ChoiceTextField(java.lang.String label,
                       java.lang.String text,
                       int maxSize,
                       int constraints,
                       java.lang.String[] availableChoices,
                       boolean allowFreeTextEntry,
                       boolean appendChoice,
                       java.lang.String appendChoiceDelimiter,
                       Style style)

Creates a new ChoiceTextField.

Parameters:

label - the label

text - the current text

maxSize - the maximum size for the input

constraints - input constraints, TextField.ANY for no constraints

availableChoices - a list of available texts for the user

allowFreeTextEntry - true when the user should be allowed to enter any text that does not match any existing choice

appendChoice - true when the selected choices should be appended to the text rather than replacing the text

appendChoiceDelimiter - the character that separates several selections, e.g. "\n" or ";" or null.

style - the style for this item

Method Detail

initContent

protected void initContent(int firstLineWidth,
                           int lineWidth)

Description copied from class: FakeCustomItem

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 FakeTextFieldCustomItem

Parameters:

firstLineWidth - the maximum width of the first line

lineWidth - the maximum width of any following lines

See Also:

FakeCustomItem.contentWidth, FakeCustomItem.contentHeight, FakeCustomItem.preferredWidth, FakeCustomItem.preferredHeight

setChoiceTrigger

public void setChoiceTrigger(char choiceTrigger,
                             boolean allowChoicesBeforeTrigger)

Enables that available choices should (only) be shown after the specified character is entered. This method automatically enables the append mode.

Parameters:

choiceTrigger - the trigger for showing choice

allowChoicesBeforeTrigger - true when the user should be able to add choices before he has entered the trigger character

setChoices

public void setChoices(java.lang.String[] choices)

Sets the available choices. Use this method in conjunction with an ItemStateListener for using complex rules for creating choices.

Parameters:

choices - the new choices, null when no choices are given

setChoices

public void setChoices(Item[] choices)

Sets the available choices. Use this method in conjunction with an ItemStateListener for using complex rules for creating choices. The given items should implement the "toString()" method and return the correct string value for the text field.

Parameters:

choices - the new choices, null when no choices are available

setMatchMode

public void setMatchMode(int mode)

Sets the matching algorithm that is used for finding out whether an available choices matches the input of the user.

Parameters:

mode - the matching mode, the default mode is ChoiceTextField.MATCH_STARTS_WITH, so the user input is compared with the start of the available choices.

See Also:

MATCH_STARTS_WITH, MATCH_INDEX_OF, for using complex matching rules, for using complex matching rules

getMatchMode

public int getMatchMode()

Retrieves the matching algorithm that is used for finding out whether an available choices matches the input of the user.

Returns:

the matching mode, the default mode is ChoiceTextField.MATCH_STARTS_WITH, so the user input is compared with the start of the available choices.

See Also:

MATCH_STARTS_WITH, MATCH_INDEX_OF, for using complex matching rules, for using complex matching rules

defocus

protected void defocus(Style origStyle)

Description copied from class: FakeCustomItem

Removes the focus from this item.

Overrides:

defocus in class FakeTextFieldCustomItem

Parameters:

origStyle - the original style which will be restored.

animate

public void animate(long currentTime,
                    ClippingRegion repaintRegion)

Description copied from class: FakeCustomItem

Animates this item. Subclasses can override this method to create animations. The default implementation animates the background and the item view if present.

Overrides:

animate in class FakeCustomItem

Parameters:

currentTime - the current time in milliseconds

repaintRegion - the repaint area that needs to be updated when this item is animated

See Also:

#addRelativeRegion(ClippingRegion, int, int, int, int)

focus

protected Style focus(Style focStyle,
                      int direction)

Description copied from class: FakeCustomItem

Focuses this item.

Overrides:

focus in class FakeTextFieldCustomItem

Parameters:

focStyle - 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

handleKeyPressed

protected boolean handleKeyPressed(int keyCode,
                                   int gameAction)

Description copied from class: FakeCustomItem

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 FakeTextFieldCustomItem

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: FakeCustomItem

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 does nothing.

Overrides:

handleKeyReleased in class FakeTextFieldCustomItem

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:

FakeCustomItem.handleKeyPressed(int, int)

handlePointerPressed

protected boolean handlePointerPressed(int x,
                                       int y)

Description copied from class: FakeTextFieldCustomItem

Handles the event when a pointer has been pressed at the specified position. The default method translates the pointer-event into an artificial pressing of the FIRE game-action, 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:

handlePointerPressed in class FakeTextFieldCustomItem

Parameters:

x - the x position of the pointer pressing

y - the y position of the pointer pressing

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

handlePointerReleased

protected boolean handlePointerReleased(int x,
                                        int y)

Description copied from class: FakeCustomItem

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 FakeCustomItem

Parameters:

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

y - 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, FakeCustomItem.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)

paintContent

public void paintContent(int x,
                         int y,
                         int leftBorder,
                         int rightBorder,
                         javax.microedition.lcdui.Graphics g)

Description copied from class: FakeCustomItem

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 FakeTextFieldCustomItem

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.

notifyStateChanged

public void notifyStateChanged()

Description copied from class: FakeCustomItem

Causes this Item's containing Form to notify the Item's ItemStateListener. The application calls this method to inform the listener on the Item that the Item's state has been changed in response to an action. Even though this method simply causes a call to another part of the application, this mechanism is useful for decoupling the implementation of an Item (in particular, the implementation of a CustomItem, though this also applies to subclasses of other items) from the consumer of the item.

If an edit was performed by invoking a separate screen, and the editor now wishes to "return" to the form which contained the selected Item, the preferred method is Display.setCurrent(Item) instead of Display.setCurrent(Displayable), because it allows the Form to restore focus to the Item that initially invoked the editor.

In order to make sure that the documented behavior of ItemStateListener is maintained, it is up to the caller (application) to guarantee that this function is not called unless:

• the Item's value has actually been changed, and
• the change was the result of a user action (an "edit") and NOT as a result of state change via calls to Item's APIs

The call to ItemStateListener.itemStateChanged may be delayed in order to be serialized with the event stream. The notifyStateChanged method does not block awaiting the completion of the itemStateChanged method.

Overrides:

notifyStateChanged in class FakeCustomItem

setStyle

public void setStyle(Style style)

Description copied from class: FakeCustomItem

Sets the style of this item.

Overrides:

setStyle in class FakeTextFieldCustomItem

Parameters:

style - the new style for this item.