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

Direct Known Subclasses:

ZoomScreen

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

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

DEFAULT_CLOSE, DEFAULT_MENU, NO_SYSTEM_MENU_ITEMS

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

BOTTOMMOST, DOWNWARD, HORIZONTAL_SCROLL, HORIZONTAL_SCROLLBAR, HORIZONTAL_SCROLLBAR_MASK, HORIZONTAL_SCROLL_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_SCROLLBAR, VERTICAL_SCROLLBAR_MASK, VERTICAL_SCROLL_MASK

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

ACTION_INVOKE, AXIS_HORIZONTAL, AXIS_SEQUENTIAL, AXIS_VERTICAL, EDITABLE, EDITABLE_MASK, FIELD_BOTTOM, FIELD_HALIGN_MASK, FIELD_HCENTER, FIELD_LEADING, FIELD_LEFT, FIELD_RIGHT, FIELD_TOP, FIELD_TRAILING, FIELD_VALIGN_MASK, FIELD_VCENTER, FOCUSABLE, FOCUSABLE_MASK, HIGHLIGHT_FOCUS, HIGHLIGHT_SELECT, NON_FOCUSABLE, NON_SPELLCHECKABLE, READONLY, SPELLCHECKABLE, SPELLCHECKABLE_MASK, STATUS_MOVE_FOCUS_HORIZONTALLY, STATUS_MOVE_FOCUS_VERTICALLY, USE_ALL_HEIGHT, USE_ALL_WIDTH, VISUAL_STATE_ACTIVE, VISUAL_STATE_DISABLED, VISUAL_STATE_DISABLED_FOCUS, VISUAL_STATE_FOCUS, VISUAL_STATE_NORMAL

Constructor Summary

MainScreen()
Constructs a new main screen instance.

MainScreen(long style)
Constructs a new main screen instance 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 Screen.onMenu(int) to populate the menu.
protected boolean	onSavePrompt() Invoked when the screen should prompt to save its contents.
void	removeAllMenuItems() Removes all menu items from this screen's menu.
void	removeMenuItem(MenuItem item) Removes a menu item from the screen's menu.
void	setBanner(Field banner) Sets the contents of this screen's banner section.
void	setId(String idName) Sets the ID for this field.
void	setStatus(Field status) Sets the contents of this screen's status section.
void	setTitle(String 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(Field 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, addScreenUiEngineAttachedListener, addTrackwheelListener, close, delete, deleteRange, doPaint, ensureRegionVisible, getAccessibleContext, getApplication, getDefaultMenuItem, getDelegate, getFieldAtLocation, getFocusRect, getGraphics, getLeafFieldWithFocus, getMenu, getScreenAbove, getScreenBelow, getUiEngine, getVirtualKeyboard, insert, invalidate, invalidate, invalidateAll, invalidateLayout, invokeAction, isDataValid, isDirty, isDisplayed, isFocus, isFocusable, isGlobal, isGlobalStatus, isMuddy, isSelecting, keyChar, keyControl, keyDown, keyRepeat, keyStatus, keyUp, layoutDelegate, navigationClick, navigationMovement, navigationUnclick, onClose, onDisplay, onExposed, onFocus, onFocusNotify, onMenu, onMenuDismissed, onMenuDismissed, onObscured, onSave, onUiEngineAttached, onUndisplay, onUnfocus, openDevelopmentBackdoor, openProductionBackdoor, paint, paintBackground, removeFocus, removeKeyListener, removeScreenUiEngineAttachedListener, removeTrackwheelListener, replace, save, scroll, setBackdoorAltStatus, setDefaultClose, setDirty, setFocus, setFocus, setHorizontalQuantization, setPositionDelegate, setTrackballFilter, setTrackballSensitivityXOffset, setTrackballSensitivityYOffset, setVerticalQuantization, touchEvent, trackwheelClick, trackwheelClickUnhandled, trackwheelRoll, trackwheelUnclick, updateDisplay

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

addAll, deleteAll, getHorizontalScroll, getPreferredHeightOfChild, getPreferredWidthOfChild, getVerticalScroll, getVirtualHeight, getVirtualWidth, getVisibleHeight, getVisibleWidth, invalidateFieldRange, isDownArrowShown, isUpArrowShown, isValidLayout, layout, layoutChild, moveFocus, moveFocus, nextFocus, nextFocus, paintChild, setFocus, setHorizontalScroll, setHorizontalScroll, setPositionChild, setScrollListener, setScrollingInertial, setVerticalScroll, setVirtualExtent, subpaint

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

drawFocus, drawHighlightRegion, fieldChangeNotify, focusAdd, focusRemove, getBackground, getBackground, getBorder, getBorder, getBorder, getChangeListener, getContentHeight, getContentLeft, getContentRect, getContentRect, getContentTop, getContentWidth, getContextMenu, getCookie, getExtent, getExtent, getFieldStyle, getFocusListener, getFont, getHeight, getIndex, getLeft, getManager, getOriginal, getPreferredHeight, getPreferredWidth, getScreen, getStyle, getTop, getVisualState, getWidth, isEditable, isPasteable, isSelectable, isSelectionCopyable, isSelectionCutable, isSelectionDeleteable, isSpellCheckable, isStyle, isVisible, makeContextMenu, onVisibilityChange, paste, select, selectionCopy, selectionCut, selectionDelete, setBackground, setBackground, setBorder, setBorder, setBorder, setBorder, setChangeListener, setCookie, setEditable, setExtent, setFocusListener, setFont, setMuddy, setNonSpellCheckable, setPosition, setVisualState, updateLayout

Methods inherited from class java.lang.Object

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

Constructor Detail

MainScreen

public MainScreen()

Constructs a new main screen instance.

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

MainScreen

public MainScreen(long style)

Constructs a new main screen instance 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.

A main screen brings up a menu by default when Screen.onMenu(int) is invoked. If the MainScreen.makeMenu(net.rim.device.api.ui.component.Menu, int) method is not overridden, it will add these menu items to the menu. The close menu item is added by default.

Parameters:

item - Menu item to add.

Since:

BlackBerry API 3.6.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.

See Also:

Manager.getLeafFieldWithFocus()

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.

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 - Number of milliseconds since the device was turned on.

Returns:

True if event was consumed; otherwise, false.

makeMenu

protected void makeMenu(Menu menu,
                        int instance)

Called from Screen.onMenu(int) to populate the menu.

If you override this function, you must call this method on the parent class so that the main screen's items are added to the menu.

Overrides:

makeMenu in class Screen

Parameters:

menu - Menu to which items should be added.

instance - The instance of the desired menu. If your screen supports only one menu, this may be ignored. By default, it is 0.

See Also:

Screen.onMenu(int)

Since:

BlackBerry API 3.6.0

onSavePrompt

protected boolean onSavePrompt()

Invoked when the screen should prompt to save its contents.

Overrides:

onSavePrompt in class Screen

Returns:

True, if prompt's resulting choice is to save; false if the prompt's resulting choice is to cancel.

See Also:

Screen.onSave()

Since:

BlackBerry API 3.6.0

removeAllMenuItems

public void removeAllMenuItems()

Removes all menu items from this screen's menu.

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

Since:

BlackBerry API 3.6.0

removeMenuItem

public void removeMenuItem(MenuItem item)

Removes a menu item from the screen's menu.

Parameters:

item - Menu item to remove.

Since:

BlackBerry API 3.6.0

setBanner

public void setBanner(Field banner)

Sets the contents of this screen's banner section. If a banner field is already set then it is removed and replaced with the specified field.

Parameters:

banner - the field to set for this screen's banner section, or null to remove the banner field if one is set.

Since:

BlackBerry API 4.2.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.

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 with your provided one.

Parameters:

title - New title field.

setTitle

public void setTitle(String title)

Sets the contents of this screen's title section.

Parameters:

title - Title text for this screen.

Since:

BlackBerry API 3.6.0

setTitle

public void setTitle(ResourceBundleFamily family,
                     int id)

Sets the contents of this screen's title section.

Parameters:

family - Resource bundle containing title text.

id - Resource item ID identifying title text to use.

Since:

BlackBerry API 3.6.0

setId

public void setId(String idName)

Sets the ID for this field.

Overrides:

setId in class Field

Parameters:

idName - The ID for the field where the ID may contain any combination of lowercase letters and the '-' character, except the first character may not be a '-'.

Throws:

IllegalArgumentException - if idName contains upper case letters or spaces.

See Also:

Field.getId()

Since:

BlackBerry API 4.0.0