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

java.lang.Object
  extended by net.rim.device.api.ui.Field
      extended by net.rim.device.api.ui.ScrollView
          extended by net.rim.device.api.ui.Manager
              extended by net.rim.device.api.ui.Screen
                  extended by net.rim.device.api.ui.container.FullScreen
                      extended by net.rim.device.api.ui.container.MainScreen
All Implemented Interfaces:
AdjustmentListener
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 banner section, 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.
 AccessibleContext getAccessibleContext()
          Returns accessible representation of the field for a screen reader.
 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.
 ToolbarManager getToolbar()
          Gets the toolbar.
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.
 void setToolbar(ToolbarManager toolbar)
          Sets the toolbar for this screen.
 
Methods inherited from class net.rim.device.api.ui.container.FullScreen
sublayout
 
Methods inherited from class net.rim.device.api.ui.Screen
add, addInputSettings, addKeyListener, addScreenUiEngineAttachedListener, addTrackwheelListener, clearInputSettings, close, cursorClick, cursorUnclick, delete, deleteRange, doPaint, ensureRegionVisible, getApplication, getContextMenuProvider, getDefaultMenuItem, getDelegate, getFieldAtLocation, getFocusRect, getGraphics, getInputHelper, getInputSettings, getLeafFieldWithFocus, getMenu, getScreenAbove, getScreenBelow, getServiceMode, getTitleBar, 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, removeInputSettings, removeKeyListener, removeScreenUiEngineAttachedListener, removeTrackwheelListener, replace, save, scroll, setBackdoorAltStatus, setContextMenuProvider, setCursorInputMode, setDefaultClose, setDirty, setFocus, setFocus, setHorizontalQuantization, setInputHelper, setPositionDelegate, setServiceMode, setServiceModeImpl, setTitleBar, setTrackballFilter, setTrackballSensitivityXOffset, setTrackballSensitivityYOffset, setVerticalQuantization, suggestServiceMode, touchEvent, trackwheelClick, trackwheelClickUnhandled, trackwheelRoll, trackwheelUnclick, updateDisplay
 
Methods inherited from class net.rim.device.api.ui.Manager
addAll, cursorMovement, deleteAll, getHorizontalScroll, getPreferredHeightOfChild, getPreferredWidthOfChild, getVerticalScroll, getVirtualHeight, getVirtualWidth, insertAll, invalidateFieldRange, isDownArrowShown, isUpArrowShown, isValidLayout, layout, layoutChild, moveFocus, moveFocus, nextFocus, nextFocus, paintChild, setFocus, setPositionChild, setScrollingInertial, setVirtualExtent, shouldCursorScroll, subpaint
 
Methods inherited from class net.rim.device.api.ui.ScrollView
configurationChanged, getHorizontalAdjustment, getVerticalAdjustment, getVisibleHeight, getVisibleWidth, setCurrentLocation, setExtent, setHorizontalAdjustment, setHorizontalScroll, setHorizontalScroll, setScrollListener, setVerticalAdjustment, setVerticalScroll, setVerticalScroll, valueChanged, waitForScrolling
 
Methods inherited from class net.rim.device.api.ui.Field
drawFocus, drawHighlightRegion, fieldChangeNotify, focusAdd, focusRemove, getBackground, getBackground, getBorder, getBorder, getBorder, getChangeListener, getCommandItemProvider, getContentHeight, getContentLeft, getContentRect, getContentRect, getContentTop, getContentWidth, getContextMenu, getCookie, getExtent, getExtent, getFieldStyle, getFocusListener, getFont, getHeight, getIndex, getLeft, getManager, getMargin, getMarginBottom, getMarginLeft, getMarginRight, getMarginTop, getOriginal, getPadding, getPaddingBottom, getPaddingLeft, getPaddingRight, getPaddingTop, getPreferredHeight, getPreferredWidth, getScreen, getStyle, getTextFillColor, getTextStrokeColor, getTop, getVisualState, getWidth, isEditable, isEnabled, isLeftToRight, isPasteable, isScrollCopyable, isSelectable, isSelectionCopyable, isSelectionCutable, isSelectionDeleteable, isSpellCheckable, isStyle, isVisible, makeContextMenu, onVisibilityChange, paste, select, selectionCopy, selectionCut, selectionDelete, setBackground, setBackground, setBorder, setBorder, setBorder, setBorder, setChangeListener, setCommandItemProvider, setCookie, setEditable, setEnabled, setFocusListener, setFont, setFont, setMargin, setMargin, setMuddy, setNonSpellCheckable, setPadding, setPadding, 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 - The 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 - The menu item to add.
Since:
BlackBerry API 3.6.0

getAccessibleContext

public AccessibleContext getAccessibleContext()
Returns accessible representation of the field for a screen reader.

Overrides:
getAccessibleContext in class Screen
Returns:
AccessibleContext
Since:
BlackBerry API 6.0.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:
The 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:
The field in the 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:
The 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 - The index position of the field to return.
Returns:
The field at the specified position in this screen's scrollable section.
Throws:
IndexOutOfBoundsException - if index is 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.

getToolbar

public ToolbarManager getToolbar()
Gets the toolbar. Toolbar is only supported on Touchscreen devices.

Returns:
The toolbar, or null if one does not exist.
Since:
BlackBerry API 6.0.0

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 - The character generated.
status - The modified key status.
time - The number of milliseconds since the device was turned on.
Returns:
true if the event was consumed, false otherwise.

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 - The 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.
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 the 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 - The 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. The banner is an area of the screen just above the title 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 - The 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 - The new title field.

setTitle

public void setTitle(String title)
Sets the contents of this screen's title section.

Parameters:
title - The 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 - The resource bundle containing title text.
id - The resource item ID identifying title text to use.
Since:
BlackBerry API 3.6.0

setToolbar

public void setToolbar(ToolbarManager toolbar)
Sets the toolbar for this screen. This method does nothing if the return value of ToolbarManager.isToolbarSupported() is false.

Parameters:
toolbar - The ToolbarManager for this toolbar.
Since:
BlackBerry API 6.0.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





Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal