net.rim.device.api.ui.container
Class MainScreen

java.lang.Object
  |
  +--net.rim.device.api.ui.Field
        |
        +--net.rim.device.api.ui.Manager
              |
              +--net.rim.device.api.ui.Screen
                    |
                    +--net.rim.device.api.ui.container.FullScreen
                          |
                          +--net.rim.device.api.ui.container.MainScreen

All Implemented Interfaces:

IComponent, InputMethodListener

public class MainScreen

extends FullScreen

Full screen providing features common to standard RIM device applications.

Behaviour
Main screen objects contain a title section, a separator element, and a main scrollable section (actually a single vertical field manager used to maintain a list of fields). When the screen gets to handle an ENTER key event (i.e. when the event is not consumed by one the fields managed by its contained vertical field manager), the screen consumes the key to scroll its list forward.

styles
Screen does not accept Field.FOCUSABLE_MASK, Field.EDITABLE_MASK.

See Also:

VerticalFieldManager

Field Summary

static long	NO_STATUS_SEPARATOR
static long	NO_TITLE_SEPARATOR

Fields inherited from class net.rim.device.api.ui.Screen

DEFAULT_CLOSE, DEFAULT_MENU

Fields inherited from class net.rim.device.api.ui.Manager

BOTTOMMOST, DOWNWARD, HORIZONTAL_SCROLL, HORIZONTAL_SCROLL_MASK, HORIZONTAL_SCROLLBAR, HORIZONTAL_SCROLLBAR_MASK, LEAVE_BLANK_SPACE, LEFTMOST, LEFTWARD, NO_HORIZONTAL_SCROLL, NO_HORIZONTAL_SCROLLBAR, NO_SCROLL_RESET, NO_VERTICAL_SCROLL, NO_VERTICAL_SCROLLBAR, QUANTA_FONT, RIGHTMOST, RIGHTWARD, TOPMOST, UPWARD, VERTICAL_SCROLL, VERTICAL_SCROLL_MASK, VERTICAL_SCROLLBAR, VERTICAL_SCROLLBAR_MASK

Fields inherited from class net.rim.device.api.ui.Field

EDITABLE, EDITABLE_MASK, FIELD_BOTTOM, FIELD_HALIGN_MASK, FIELD_HCENTER, FIELD_LEFT, FIELD_RIGHT, FIELD_TOP, FIELD_VALIGN_MASK, FIELD_VCENTER, FOCUSABLE, FOCUSABLE_MASK, HIGHLIGHT_FOCUS, HIGHLIGHT_SELECT, NON_FOCUSABLE, READONLY, USE_ALL_HEIGHT, USE_ALL_WIDTH

Constructor Summary

MainScreen()
Constructs a new main screen object.

MainScreen(long style)
Constructs a new main screen object with provided style.

Method Summary

void	addMenuItem(MenuItem item) Adds a menu item to the screen's menu.
Field	getField(int index) Retrieves the field at specified position in the scrollable section.
int	getFieldCount() Retrieves the number of fields in the scrollable section.
Field	getFieldWithFocus() Retrieves the field from the scrollable section that currently has the focus.
int	getFieldWithFocusIndex() Retrieves index of field from the scrollable section that currently has the focus.
Manager	getMainManager() Retrieves this screen's subordinate, vertical field manager.
protected boolean	keyCharUnhandled(char key, int status, int time) Invoked when a keyChar event is unhandled.
protected void	makeMenu(Menu menu, int instance) Called from onMenu to populate the menu.
protected boolean	onSavePrompt() Invoked when the screen should prompt to save its contents.
void	removeAllMenuItems() Removes all menu items from the screen's menu.
void	removeMenuItem(MenuItem item) Removes a menu item from the screen's menu.
void	setStatus(Field status) Sets the contents of this screen's status section.
void	setTitle(Field title) Sets the contents of this screen's title section.
void	setTitle(ResourceBundleFamily family, int id) Sets the contents of this screen's title section.
void	setTitle(String title) Sets the contents of this screen's title section.

Methods inherited from class net.rim.device.api.ui.container.FullScreen

sublayout

Methods inherited from class net.rim.device.api.ui.Screen

add, addKeyListener, addTrackwheelListener, close, delete, deleteRange, doLayout, doPaint, ensureRegionVisible, getDelegate, getFieldAtLocation, getFocusRect, getGraphics, getLeafFieldWithFocus, getUiEngine, insert, invalidate, invalidateLayout, isDirty, isDisplayed, isFocusable, isGlobalStatus, isMuddy, isSelecting, keyChar, keyControl, keyDown, keyRepeat, keyStatus, keyUp, layoutDelegate, onClose, onDisplay, onExposed, onFocus, onMenu, onObscured, onSave, onUndisplay, onUnfocus, paint, paintBackground, removeFocus, removeKeyListener, removeTrackwheelListener, save, scroll, setDirty, setFocus, setFocus, setHorizontalQuantization, setPositionDelegate, setVerticalQuantization, trackwheelClick, trackwheelClickUnhandled, trackwheelRoll, trackwheelUnclick, updateDisplay

Methods inherited from class net.rim.device.api.ui.Manager

deleteAll, getHorizontalScroll, getVerticalScroll, getVirtualHeight, getVirtualWidth, getVisibleHeight, getVisibleWidth, invalidate, isDownArrowShown, isUpArrowShown, isValidLayout, layout, layoutChild, moveFocus, moveFocus, nextFocus, paintChild, setFocus, setHorizontalScroll, setPositionChild, setScrollListener, setVerticalScroll, setVirtualExtent, subpaint

Methods inherited from class net.rim.device.api.ui.Field

drawFocus, drawHighlightRegion, fieldChangeNotify, focusAdd, focusRemove, getChangeListener, getContextMenu, getCookie, getExtent, getFieldStyle, getFocusListener, getFont, getHeight, getIndex, getLeft, getManager, getOriginal, getPreferredHeight, getPreferredWidth, getScreen, getStyle, getTop, getWidth, isEditable, isPasteable, isSelectable, isSelectionCopyable, isSelectionCutable, isSelectionDeleteable, isVisible, makeContextMenu, onVisibilityChange, paste, select, selectionCopy, selectionCut, selectionDelete, setChangeListener, setCookie, setEditable, setExtent, setFocusListener, setFont, setMuddy, setPosition, updateLayout

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

NO_TITLE_SEPARATOR

public static final long NO_TITLE_SEPARATOR

NO_STATUS_SEPARATOR

public static final long NO_STATUS_SEPARATOR

Constructor Detail

MainScreen

public MainScreen()

Constructs a new main screen object.

This method builds a new main screen with no particular style.

MainScreen

public MainScreen(long style)

Constructs a new main screen object with provided style.

Parameters:

style - Style(s) for this new screen.

Method Detail

addMenuItem

public void addMenuItem(MenuItem item)

Adds a menu item to the screen's menu.

MainScreen brings up a Menu by default when onMenu is called. If the makeMenu method is not overridden, it will add these MenuItems to the Menu. The close menu item it added by default.

Since:

JDE 3.7.0

getFieldCount

public int getFieldCount()

Retrieves the number of fields in the scrollable section.

Prompts this screen's vertical field manager to return the number of fields it controls. Note that this value does not include the fields used for this screen's title, separator, or status section, nor does it include the subordinate vertical field manager itself.

Overrides:

getFieldCount in class Screen

Returns:

Number of fields in this screen's scrollable section.

getFieldWithFocus

public Field getFieldWithFocus()

Retrieves the field from the scrollable section that currently has the focus.

Prompts this screen's vertical field manager to return its controlled field that currently has the focus.

Overrides:

getFieldWithFocus in class Screen

Returns:

Field in scrollable section with focus, or null if no field has the focus.

getFieldWithFocusIndex

public int getFieldWithFocusIndex()

Retrieves index of field from the scrollable section that currently has the focus.

Prompts this screen's vertical field manager to return the index of the controlled field that currently has the focus.

Overrides:

getFieldWithFocusIndex in class Screen

Returns:

Index of the field with the focus, or -1 if no field has the focus.

getField

public Field getField(int index)

Retrieves the field at specified position in the scrollable section.

Prompts this screen's vertical field manager to return the field at a particular position in its list.

Overrides:

getField in class Screen

Parameters:

index - Index position of field you want returned.

Returns:

Field at specified position in this screen's scrollable section.

Throws:

IndexOutOfBoundsException - If index not valid.

Since:

JDE 3.7.0

getMainManager

public Manager getMainManager()

Retrieves this screen's subordinate, vertical field manager.

Use this method to retrieve the vertical field manager this screen uses to manage the list of fields shown in its scrollable section.

Returns:

This screen's subordinate, vertical field manager.

keyCharUnhandled

protected boolean keyCharUnhandled(char key,
                                   int status,
                                   int time)

Invoked when a keyChar event is unhandled.

If none of this screen's controlled fields handle an ENTER key event, and this screen is not currently in select mode, this method consumes the key event and attempts to advance the focus on to the next field in its scrollable section.

Overrides:

keyCharUnhandled in class Screen

Parameters:

key - Character generated.

status - Modified key status.

time - Ticks since device reset.

Returns:

True if event was consumed; otherwise, false.

Since:

JDE 3.7.0

makeMenu

protected void makeMenu(Menu menu,
                        int instance)

Called from onMenu to populate the menu.

If you override this function, you must call super.makeMenu(menu) so that the MainScreen's items are added to the menu.

Overrides:

makeMenu in class Screen

Since:

JDE 3.7.0

onSavePrompt

protected boolean onSavePrompt()

Invoked when the screen should prompt to save its contents.

Overrides:

onSavePrompt in class Screen

Returns:

true if successful

Since:

JDE 3.6.0

See Also:

Screen.onSave()

removeAllMenuItems

public void removeAllMenuItems()

Removes all menu items from the screen's menu.

This can be called right after construction to ensure the default menu items are not present in the menu.

Since:

JDE 3.6.0

removeMenuItem

public void removeMenuItem(MenuItem item)

Removes a menu item from the screen's menu.

Since:

JDE 3.7.0

setStatus

public void setStatus(Field status)

Sets the contents of this screen's status section.

This method adds your provided field to this screen's status section, even if it already contains a field.

Parameters:

status - New status field.

Since:

JDE 3.7.0

setTitle

public void setTitle(Field title)

Sets the contents of this screen's title section.

This method either simply adds the title field to this screen's title section, or replaces the existing title field your provided one.

Parameters:

title - New title field.

Since:

JDE 3.7.0

setTitle

public void setTitle(String title)

Sets the contents of this screen's title section.

Since:

JDE 3.7.0

setTitle

public void setTitle(ResourceBundleFamily family,
                     int id)

Sets the contents of this screen's title section.

Since:

JDE 3.7.0