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

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_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.6

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.6

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.6

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.6

onSavePrompt

protected boolean onSavePrompt()
Invoked when the screen should prompt to save its contents.
Overrides:
onSavePrompt in class Screen
Returns:
true if successful
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.


removeMenuItem

public void removeMenuItem(MenuItem item)
Removes a menu item from the screen's menu.
Since:
JDE 3.6

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.6

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.6

setTitle

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

setTitle

public void setTitle(ResourceBundleFamily family,
                     int id)
Sets the contents of this screen's title section.
Since:
JDE 3.6


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