RIM Device Java Library: Interface Choice

Choice defines an API for a user interface components implementing selection from predefined number of choices. Such UI components are List and ChoiceGroup. The contents of the Choice are represented with strings and optional images.

Each element of a Choice is composed of a text string and an optional image. The application may provide null for the image if the element does not have an image part. If the application provides an image, the implementation may choose to ignore the image if it exceeds the capacity of the device to display it. If the implementation displays the image, it will be displayed adjacent to the text string and the pair will be treated as a unit.

Images within any particular Choice object should all be of the same size, because the implementation is allowed to allocate the same amount of vertical space for every element.

If an element is too long to be displayed, the implementation will provide the user with means to see the whole element. If this is done by wrapping an element to multiple lines, the second and subsequent lines show a clear indication to the user that they are part of the same element and are not a new element.

After a Choice object has been created, elements may be inserted, appended, and deleted, and each element's string part and image part may be get and set. Elements within a Choice object are referred to by their indexes, which are consecutive integers in the range from zero to size()-1, with zero referring to the first element and size()-1 to the last element.

There are three types of Choices: implicit-choice (valid only for List), exclusive-choice, and multiple-choice.

The exclusive-choice presents a series of elements and interacts with the user. That is, when the user selects an element, that element is shown to be selected using a distinct visual representation. Exactly one element must be selected at any given time. If at any time a situation would result where there are elements in the exclusive-choice but none is selected, the implementation will choose an element and select it. This situation can arise when an element is added to an empty Choice, when the selected element is deleted from the Choice, or when a Choice is created and populated with elements by a constructor. In these cases, the choice of which element is selected is left to the implementation. Applications for which the selected element is significant should set the selection explicitly. There is no way for the user to unselect an element within an Exclusive Choice.

The implicit choice is an exclusive choice where the focused element is implicitly selected when a command is initiated.

A multiple-choice presents a series of elements and allows the user to select any number of elements in any combination. As with exclusive-choice, the multiple-choice interacts with the user in object-operation mode. The visual appearance of a multiple-choice will likely have a visual representation distinct from the exclusive-choice that shows the selected state of each element as well as indicating to the user that multiple elements may be selected.

The selected state of an element is a property of the element. This state stays with that element if other elements are inserted or deleted, causing elements to be shifted around. For example, suppose element n is selected, and a new element is inserted at index zero. The selected element would now have index n+1. A similar rule applies to deletion. Assuming n is greater than zero, deleting element zero would leave element n-1 selected. Setting the contents of an element leaves its selected state unchanged. When a new element is inserted or appended, it is always unselected (except in the special case of adding an element to an empty Exclusive Choice as mentioned above).

When a Choice is present on the display the user can interact with it indefinitely (for instance, traversing from element to element and possibly scrolling). These traversing and scrolling operations do not cause application-visible events. The system notifies the application either when some application-defined Command is fired, or when selection state of ChoiceGroup is changed. When command is fired a high-level event is delivered to the listener of the Screen. The event delivery is done with commandAction . In the case of ChoiceGroup the ItemStateListener is called when the user changes the selection state of the ChoiceGroup. At this time the application can query the Choice for information about the currently selected element(s).

Field Summary
`static int`	`EXCLUSIVE` EXCLUSIVE is a choice having exactly one element selected at time.
`static int`	`IMPLICIT` IMPLICIT is a choice in which the currently focused item is selected when a `Command` is initiated.
`static int`	`MULTIPLE` MULTIPLE is a choice that can have arbitrary number of elements selected at a time.
`static int`	`POPUP` `POPUP` is a choice having exactly one element selected at a time.
`static int`	`TEXT_WRAP_DEFAULT` Constant for indicating that the application has no preference as to wrapping or truncation of text element contents and that the implementation should use its default behavior.
`static int`	`TEXT_WRAP_OFF` Constant for hinting that text element contents should be limited to a single line.
`static int`	`TEXT_WRAP_ON` Constant for hinting that text element contents should be wrapped to to multiple lines if necessary to fit available content space.

Method Summary
`int`	`append(String stringPart, Image imagePart)` Appends an element to the Choice.
`void`	`delete(int elementNum)` Deletes the element referenced by elementNum.
`void`	`deleteAll()` Deletes all elements from this `Choice`, leaving it with zero elements.
`int`	`getFitPolicy()` Gets the application's preferred policy for fitting `Choice` element contents to the available screen space.
`Font`	`getFont(int elementNum)` Gets the application's preferred font for rendering the specified element of this `Choice`.
`Image`	`getImage(int elementNum)` Gets the Image part of the element referenced by elementNum.
`int`	`getSelectedFlags(boolean[] selectedArray_return)` Queries the state of a Choice and returns the state of all elements in the boolean array selectedArray_return.
`int`	`getSelectedIndex()` Returns the index number of an element in the Choice that is selected.
`String`	`getString(int elementNum)` Gets the String part of the element referenced by elementNum.
`void`	`insert(int elementNum, String stringPart, Image imagePart)` Inserts an element into the Choice just prior to the element specified.
`boolean`	`isSelected(int elementNum)` Gets a boolean value indicating whether this element is selected.
`void`	`set(int elementNum, String stringPart, Image imagePart)` Sets the element referenced by elementNum to the specified element, replacing the previous contents of the element.
`void`	`setFitPolicy(int fitPolicy)` Sets the application's preferred policy for fitting `Choice` element contents to the available screen space.
`void`	`setFont(int elementNum, Font font)` Sets the application's preferred font for rendering the specified element of this `Choice`.
`void`	`setSelectedFlags(boolean[] selectedArray)` Attempts to set the selected state of every element in the Choice.
`void`	`setSelectedIndex(int elementNum, boolean selected)` For MULTIPLE, this simply sets an individual element's selected state.
`int`	`size()` Gets the number of elements present.

IMPLICIT

public static final int IMPLICIT

IMPLICIT is a choice in which the currently focused item is selected when a Command is initiated. (Note: IMPLICIT is not accepted by ChoiceGroup)

Value 3 is assigned to IMPLICIT.

POPUP

public static final int POPUP

POPUP is a choice having exactly one element selected at a time. The selected element is always shown. The other elements should be hidden until the user performs a particular action to show them. When the user performs this action, all elements become accessible. For example, an implementation could use a popup menu to display the elements of a ChoiceGroup of type POPUP.

The POPUP type is not valid for List objects.

Value 4 is assigned to POPUP.

Since:: MIDP 2.0

TEXT_WRAP_DEFAULT

public static final int TEXT_WRAP_DEFAULT

Constant for indicating that the application has no preference as to wrapping or truncation of text element contents and that the implementation should use its default behavior.

Field has the value 0.

See Also:: getFitPolicy(), setFitPolicy(int)
Since:: MIDP 2.0

TEXT_WRAP_ON

public static final int TEXT_WRAP_ON

Constant for hinting that text element contents should be wrapped to to multiple lines if necessary to fit available content space. The Implementation may limit the maximum number of lines that it will actually present.

Field has the value 1.

See Also:: getFitPolicy(), setFitPolicy(int)
Since:: MIDP 2.0

TEXT_WRAP_OFF

public static final int TEXT_WRAP_OFF

Constant for hinting that text element contents should be limited to a single line. Line ending is forced, for example by cropping, if there is too much text to fit to the line. The implementation should provide some means to present the full element contents. This may be done, for example, by using a special pop-up window or by scrolling the text of the focused element.

Implementations should indicate that cropping has occurred, for example, by placing an ellipsis at the point where the text contents have been cropped.

Field has the value 2.

See Also:: getFitPolicy(), setFitPolicy(int)
Since:: MIDP 2.0

getString

public String getString(int elementNum)

Gets the String part of the element referenced by elementNum. The elementNum parameter must be within the range [0..size()-1], inclusive.

Parameters:: elementNum - the index of the element to be queried
Returns:: the string part of the element
Throws:: IndexOutOfBoundsException - if elementNum is invalid
Since:: JDE 4.0.0
See Also:: getImage(int)

getImage

public Image getImage(int elementNum)

Gets the Image part of the element referenced by elementNum. The elementNum parameter must be within the range [0..size()-1], inclusive.

Parameters:: elementNum - the index of the element to be queried
Returns:: the image part of the element, or null if there is no image
Throws:: IndexOutOfBoundsException - if elementNum is invalid
Since:: JDE 4.0.0
See Also:: getString(int)

append

public int append(String stringPart,
                  Image imagePart)

Appends an element to the Choice. The added element will be the last element of the Choice. The size of the Choice grows by one.

Parameters:: stringPart - the string part of the element to be added; imagePart - the image part of the element to be added, or null if there is no image part
Returns:: the assigned index of the element
Throws:: IllegalArgumentException - if the image is mutable; NullPointerException - if stringPart is null
Since:: JDE 4.0.0

insert

public void insert(int elementNum,
                   String stringPart,
                   Image imagePart)

Inserts an element into the Choice just prior to the element specified. The size of the Choice grows by one. The elementNum parameter must be within the range [0..size()], inclusive. The index of the last element is size()-1, and so there is actually no element whose index is size(). If this value is used for elementNum, the new element is inserted immediately after the last element. In this case, the effect is identical to append().

Parameters:: elementNum - the index of the element where insertion is to occur; stringPart - the string part of the element to be inserted; imagePart - the image part of the element to be inserted, or null if there is no image part
Throws:: IndexOutOfBoundsException - if elementNum is invalid; IllegalArgumentException - if the image is mutable; NullPointerException - if stringPart is null
Since:: JDE 4.0.0

delete

public void delete(int elementNum)

Deletes the element referenced by elementNum. The size of the Choice shrinks by one. It is legal to delete all elements from a Choice. The elementNum parameter must be within the range [0..size()-1], inclusive.

Parameters:: elementNum - the index of the element to be deleted
Throws:: IndexOutOfBoundsException - if elementNum is invalid
Since:: JDE 4.0.0

set

public void set(int elementNum,
                String stringPart,
                Image imagePart)

Sets the element referenced by elementNum to the specified element, replacing the previous contents of the element. The elementNum parameter must be within the range [0..size()-1], inclusive.

Parameters:: elementNum - the index of the element to be set; stringPart - the string part of the new element; imagePart - the image part of the element, or null if there is no image part
Throws:: IndexOutOfBoundsException - if elementNum is invalid; IllegalArgumentException - if the image is mutable; NullPointerException - if stringPart is null
Since:: JDE 4.0.0

isSelected

public boolean isSelected(int elementNum)

Gets a boolean value indicating whether this element is selected. The elementNum parameter must be within the range [0..size()-1], inclusive.

Parameters:: elementNum - the index of the element to be queried
Returns:: selection state of the element
Throws:: IndexOutOfBoundsException - if elementNum is invalid
Since:: JDE 4.0.0

getSelectedIndex

public int getSelectedIndex()

Returns the index number of an element in the Choice that is selected. For Choice types EXCLUSIVE and IMPLICIT there is at most one element selected, so this method is useful for determining the user's choice. Returns -1 if the Choice has no elements (and therefore has no selected elements).

For MULTIPLE, this always returns -1 because no single value can in general represent the state of such a Choice. To get the complete state of a MULTIPLE Choice, see getSelectedFlags.

Returns:: index of selected element, or -1 if none

getSelectedFlags

public int getSelectedFlags(boolean[] selectedArray_return)

Queries the state of a Choice and returns the state of all elements in the boolean array selectedArray_return. NOTE: this is a result parameter. It must be at least as long as the size of the Choice as returned by size(). If the array is longer, the extra elements are set to false.

This call is valid for all types of Choices. For MULTIPLE, any number of elements may be selected and set to true in the result array. For EXCLUSIVE and IMPLICIT exactly one element will be selected (unless there are zero elements in the Choice).

Parameters:: selectedArray_return - array to contain the results
Returns:: the number of selected elements in the Choice
Throws:: IllegalArgumentException - if selectedArray_return is shorter than the size of the Choice.; NullPointerException - if selectedArray_return is null
Since:: JDE 4.0.0

setSelectedIndex

public void setSelectedIndex(int elementNum,
                             boolean selected)

For MULTIPLE, this simply sets an individual element's selected state.

For EXCLUSIVE, this can be used only to select any element, that is, the selected parameter must be true. When an element is selected, the previously selected element is deselected. If selected is false , this call is ignored. If element was already selected, the call has no effect.

For IMPLICIT, this can be used only to select any element, that is, the selected parameter must be true. When an element is selected, the previously selected element is deselected. If selected is false , this call is ignored. If element was already selected, the call has no effect.

The call to setSelectedIndex does not cause implicit activation of any Command.

For all list types, the elementNum parameter must be within the range [0..size()-1], inclusive.

Parameters:: elementNum - the index of the element, starting from zero; selected - the state of the element, where true means selected and false means not selected
Throws:: IndexOutOfBoundsException - if elementNum is invalid
Since:: JDE 4.0.0

setSelectedFlags

public void setSelectedFlags(boolean[] selectedArray)

Attempts to set the selected state of every element in the Choice. The array must be at least as long as the size of the Choice. If the array is longer, the additional values are ignored.

For Choice objects of type MULTIPLE, this sets the selected state of every element in the Choice. An arbitrary number of elements may be selected.

For Choice objects of type EXCLUSIVE and IMPLICIT, exactly one array element must have the value true. If no element is true, the first element in the Choice will be selected. If two or more elements are true, the implementation will choose the first true element and select it.

Parameters:: selectedArray - an array in which the method collect the selection status
Throws:: IllegalArgumentException - if selectedArray is shorter than the size of the Choice; NullPointerException - if selectedArray is null
Since:: JDE 4.0.0

setFitPolicy

public void setFitPolicy(int fitPolicy)

Sets the application's preferred policy for fitting Choice element contents to the available screen space. The set policy applies for all elements of the Choice object. Valid values are TEXT_WRAP_DEFAULT, TEXT_WRAP_ON, and TEXT_WRAP_OFF. Fit policy is a hint, and the implementation may disregard the application's preferred policy.

Parameters:: fitPolicy - preferred content fit policy for choice elements
Throws:: IllegalArgumentException - if fitPolicy is invalid
Since:: MIDP 2.0
See Also:: getFitPolicy()

getFitPolicy

public int getFitPolicy()

Gets the application's preferred policy for fitting Choice element contents to the available screen space. The value returned is the policy that had been set by the application, even if that value had been disregarded by the implementation.

Returns:: one of TEXT_WRAP_DEFAULT, TEXT_WRAP_ON, or TEXT_WRAP_OFF
Since:: MIDP 2.0
See Also:: setFitPolicy(int)

setFont

public void setFont(int elementNum,
                    Font font)

Sets the application's preferred font for rendering the specified element of this Choice. An element's font is a hint, and the implementation may disregard the application's preferred font.

The elementNum parameter must be within the range [0..size()-1], inclusive.

The font parameter must be a valid Font object or null. If the font parameter is null, the implementation must use its default font to render the element.

Parameters:: elementNum - the index of the element, starting from zero; font - the preferred font to use to render the element
Throws:: IndexOutOfBoundsException - if elementNum is invalid
Since:: MIDP 2.0
See Also:: getFont(int)

getFont

public Font getFont(int elementNum)

Gets the application's preferred font for rendering the specified element of this Choice. The value returned is the font that had been set by the application, even if that value had been disregarded by the implementation. If no font had been set by the application, or if the application explicitly set the font to null, the value is the default font chosen by the implementation.