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
 
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_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
ACTION_INVOKE, 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(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.Screen
add, addKeyListener, addScreenUiEngineAttachedListener, addTrackwheelListener, close, delete, deleteRange, doPaint, ensureRegionVisible, 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
deleteAll, getHorizontalScroll, getPreferredHeightOfChild, getPreferredWidthOfChild, getVerticalScroll, getVirtualHeight, getVirtualWidth, getVisibleHeight, getVisibleWidth, invalidateFieldRange, 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, 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 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:
JDE 3.6.0

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.

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.

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.
isntance - The instance of the desired menu. If your screen supports only one menu, this may be ignored. By default, it is 0.
Since:
JDE 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.
Since:
JDE 3.6.0
See Also:
Screen.onSave()

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:
JDE 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:
JDE 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:
JDE 4.2.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.
Since:
JDE 4.0.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(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:
JDE 3.6.0

setTitle

public void setTitle(String title)
Sets the contents of this screen's title section.
Parameters:
title - Title text for this screen.
Since:
JDE 3.6.0



Copyright 1999-2009 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.