SHOW Framework

net.rim.device.api.ui
Class Screen

java.lang.Object
  |
  +--net.rim.device.api.ui.Field
        |
        +--net.rim.device.api.ui.Manager
              |
              +--net.rim.device.api.ui.Screen
All Implemented Interfaces:
IComponent, InputMethodListener, SoftkeyProvider
Direct Known Subclasses:
FullScreen, PopupScreen

public abstract class Screen
extends Manager
implements SoftkeyProvider

Base class for all screens. Each UiEngine presents an interface to the user by pushing screens onto its display stack, and popping them off when interaction with the managed fields on that screen is finished.

Delegate manager
Each screen object has a delegate manager, the single Manager object directly controlled by the screen to handle layout and scrolling for the entire screen. *

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


Field Summary
static long DEFAULT_CLOSE
          If specified, screen will provide a close action.
static long DEFAULT_MENU
          If specified, screen will provide a 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
ACTION_INVOKE, 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, STATUS_MOVE_FOCUS_HORIZONTALLY, STATUS_MOVE_FOCUS_VERTICALLY, USE_ALL_HEIGHT, USE_ALL_WIDTH
 
Constructor Summary
Screen(Manager delegate)
          Constructs a screen with provided delegate manager.
Screen(Manager delegate, long style)
          Constructs specific type of screen with provided delegate manager.
 
Method Summary
   void add(Field field)
          Adds a field to this screen's manager.
   void addKeyListener(KeyListener listener)
          Registers a key event listener for this screen.
   void addTrackwheelListener(TrackwheelListener listener)
          Registers a trackwheel event listener for this screen.
 Category: Framework  void close()
          Closes this screen.
   void delete(Field field)
          Deletes a field from this screen's manager.
   void deleteRange(int start, int count)
          Deletes a range of fields from this screen's manager.
 Category: Framework  void doPaint()
          Paints this screen.
 Category: Framework  void ensureRegionVisible(Field field, int x, int y, int width, int height)
          Attempts to make your provided region visible.
   Application getApplication()
          Retrieves this screen's application.
 Category: Framework  MenuItem getDefaultMenuItem(int instance)
          Retrieves the default menu item.
   Manager getDelegate()
          Retrieves this screen's delegate manager.
   Field getField(int index)
          Retrieves controlled field with specified index.
   int getFieldAtLocation(int x, int y)
          Retrieves index of field under provided point.
   int getFieldCount()
          Retrieves the number of controlled fields.
   Field getFieldWithFocus()
          Retrieves controlled field with focus.
   int getFieldWithFocusIndex()
          Retrieves index of controlled field with focus.
   void getFocusRect(XYRect rect)
          Retrieves current extent of the focus.
   Graphics getGraphics()
          Retrieves the graphics context for this screen.
   Field getLeafFieldWithFocus()
          Retrieves leaf field with focus.
   Menu getMenu(int instance)
          Retrieves the menu.
   Screen getScreenAbove()
          Retrieves handle for screen above this one.
   Screen getScreenBelow()
          Retrieves handle for screen below this one.
   UiEngine getUiEngine()
          Retrieves UiEngine that owns the display.
   void insert(Field field, int index)
          Inserts a field to this screen's manager.
   void invalidate()
          Invalidates a region of this screen.
   void invalidate(int x, int y, int width, int height)
          Invalidates a region of this screen.
   void invalidateAll(int x, int y, int width, int height)
          Invalidates a region of this screen.
   void invalidateLayout()
          Invalidates this screen's layout (including all controlled fields).
 Category: Framework protected  boolean invokeAction(int action)
          Invokes an action on this screen.
   boolean isDataValid()
          Computes and returns whether or not the data on this screen is valid.
   boolean isDirty()
          Determines if this screen is dirty.
   boolean isDisplayed()
          Determines if this screen is currently in use.
   boolean isFocusable()
          Verifies that the delegate manager accepts the focus.
   boolean isGlobal()
          Determines if this is a global screen.
   boolean isGlobalStatus()
          Deprecated. Use isGlobal()
   boolean isMuddy()
          Determines if this screen is muddy.
   boolean isSelecting()
          Determines if this screen has the focus.
  protected  boolean keyChar(char c, int status, int time)
          Delegates key generation event to the controlled field with focus.
  protected  boolean keyCharUnhandled(char key, int status, int time)
          Invoked when a keyChar event is unhandled.
  protected  boolean keyControl(char c, int status, int time)
          Delegates key generation event to the controlled field with focus.
  protected  boolean keyDown(int keycode, int time)
          Delegates key down event to controlled field with focus.
  protected  boolean keyRepeat(int keycode, int time)
          Delegates key repeat event to controlled field with focus.
  protected  boolean keyStatus(int keycode, int time)
          Delegates key status event to controlled field with focus.
  protected  boolean keyUp(int keycode, int time)
          Delegates key up event to controlled field with focus.
  protected  void layoutDelegate(int width, int height)
          Lays out this screen's delegate.
  protected  void makeMenu(Menu menu, int instance)
          Called from onMenu to populate the menu.
 Category: Framework protected  boolean navigationClick(int status, int time)
          Delegates navigational click events.
 Category: Framework protected  boolean navigationMovement(int dx, int dy, int status, int time)
          Invoked when a navigational motion occurs.
 Category: Framework protected  boolean navigationUnclick(int status, int time)
          Delegates navigation unclick events.
 Category: Framework  boolean onClose()
          Indicates a close event has occurred.
 Category: Framework protected  void onDisplay()
          Invoked when this screen is pushed onto the display stack.
 Category: Framework protected  void onExposed()
          Invoked when this screen is exposed.
 Category: Framework protected  void onFocus(int direction)
          Finds a controlled field to give the focus.
 Category: Framework protected  void onFocusNotify(boolean focus)
          Called whenever the screen has gained or lost focus.
 Category: Framework  boolean onMenu(int instance)
          Invoked when a menu needs displaying.
  protected  void onMenuDismissed()
          Deprecated. Use onMenuDismissed(Menu).
  protected  void onMenuDismissed(Menu menu)
          Called when the menu is dismissed.
 Category: Framework protected  void onObscured()
          Invoked when this screen is obscured.
 Category: Framework protected  boolean onSave()
          Invoked when the screen should save its contents.
 Category: Framework protected  boolean onSavePrompt()
          Invoked when the screen should prompt to save its contents.
 Category: Framework protected  void onUndisplay()
          Invoked when this screen is popped off the display stack.
 Category: Framework protected  void onUnfocus()
          Invoked when focus is removed from this screen.
  protected  boolean openDevelopmentBackdoor(int backdoorCode)
          Handles development backdoor key-sequences.
  protected  boolean openProductionBackdoor(int backdoorCode)
          Handles production backdoor key-sequences.
  protected  void paint(Graphics graphics)
          Paints this screen's visible region.
 Category: Framework protected  void paintBackground(Graphics graphics)
          Paint this screen's background.
 Category: Framework  void removeFocus()
          Removes focus from this screen.
   void removeKeyListener(KeyListener listener)
          Removes a key event listener from this screen.
   void removeTrackwheelListener(TrackwheelListener listener)
          Removes a trackwheel event listener from this screen.
   void replace(Field oldField, Field newField)
          Removes a field from this Screen and replaces it with another field.
   void save()
          Invoked when the screen should save its contents.
   boolean scroll(int direction)
          Scrolls the focus in specified direction.
  protected  void setBackdoorAltStatus(boolean altStatus)
          Sets whether backdoors key sequences use ALT'd or un-ALT'd keystrokes.
  protected  void setDefaultClose(boolean provideDefaultClose)
          This method controls whether the screen's menu contains a "close" menu item.
   void setDirty(boolean dirty)
          Cleans or dirties all controlled fields.
   void setFocus()
          Sets the focus to the delegate manager.
   boolean setFocus(Field field, int x, int y, int status, int time)
          Sets focus to exact position in current screen.
   void setHorizontalQuantization(int horizontalQuanta)
          Sets the horizontal quantization.
  protected  void setPositionDelegate(int x, int y)
          Set the position of this screen's layout manager (delegate).
   void setTrackballFilter(int filter)
          Sets the trackball filter for this Screen.
   void setTrackballSensitivityXOffset(int trackballSensitivityXOffset)
          Sets the relative trackball sensitivity for the X axis.
   void setTrackballSensitivityYOffset(int trackballSensitivityYOffset)
          Sets the relative trackball sensitivity for the X axis.
   void setVerticalQuantization(int verticalQuanta)
          Sets the vertical quantization.
  protected  boolean trackwheelClick(int status, int time)
          Delegates trackwheel click events.
  protected  boolean trackwheelClickUnhandled(int status, int time)
          Handles trackwheel click event if delegate passes it through.
  protected  boolean trackwheelRoll(int amount, int status, int time)
          Invoked when the trackwheel is rolled.
  protected  boolean trackwheelUnclick(int status, int time)
          Delegates trackwheel unclick events.
   void updateDisplay()
          Updates the display.
 
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, sublayout, subpaint
 
Methods inherited from class net.rim.device.api.ui.Field
drawFocus, drawHighlightRegion, fieldChangeNotify, focusAdd, focusRemove, getChangeListener, getContentHeight, getContentLeft, getContentRect, getContentRect, getContentTop, getContentWidth, getContextMenu, getCookie, getExtent, getExtent, getFieldStyle, getFocusListener, getFont, getHeight, getIndex, getLeft, getManager, getOriginal, getPreferredHeight, getPreferredWidth, getScreen, getStyle, getTop, getWidth, isEditable, isFocus, isPasteable, isSelectable, isSelectionCopyable, isSelectionCutable, isSelectionDeleteable, isStyle, 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

DEFAULT_CLOSE

public static final long DEFAULT_CLOSE
If specified, screen will provide a close action.

When ESC is pressed, the close() method will be called, and a menu item is also provided to do this.

Since:
JDE 3.6.0

DEFAULT_MENU

public static final long DEFAULT_MENU
If specified, screen will provide a default menu.
Since:
JDE 3.6.0
Constructor Detail

Screen

public Screen(Manager delegate)
Constructs a screen with provided delegate manager.
Parameters:
delegate - Manager this screen uses as layout delegate.

Screen

public Screen(Manager delegate,
              long style)
Constructs specific type of screen with provided delegate manager.

Use this constructor to build a screen of a particular style.

Parameters:
delegate - Manager this screen uses as layout delegate.
style - Style the screen uses for instantiation
Method Detail

add

public void add(Field field)
Adds a field to this screen's manager.

Provided a field, this method invokes Manager.add(net.rim.device.api.ui.Field) on this screen's delegate manager, prompting the manager to add the field.

Overrides:
add in class Manager
Parameters:
field - Field to add.

addKeyListener

public final void addKeyListener(KeyListener listener)
Registers a key event listener for this screen.
Parameters:
listener - Key event listener to handle key events passed to this screen.

addTrackwheelListener

public final void addTrackwheelListener(TrackwheelListener listener)
Registers a trackwheel event listener for this screen.
Parameters:
listener - Trackwheel event listener to handle trackwheel events pass to this screen.

close

public void close()
Closes this screen.

By default, this method pops this screen, and if the screen stack is empty, invokes System.exit(0). Derived classes can override this method to provide more particular functionality.

Since:
JDE 3.6.0
Category:
Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.

delete

public void delete(Field field)
Deletes a field from this screen's manager.

This method invokes Manager.delete(net.rim.device.api.ui.Field) on this screen's delegate manager to delete your provided field. Note that, after deletion, the list of fields gets compacted.

Overrides:
delete in class Manager
Parameters:
field - Field to delete.

deleteRange

public void deleteRange(int start,
                        int count)
Deletes a range of fields from this screen's manager.

This method invokes Manager.deleteRange(int, int) on this screen's delegate maanger to delete a range of fields. Note that, after deletion, the list of fields gets compacted.

Overrides:
deleteRange in class Manager
Parameters:
start - Index of first field to delete.
count - Number of fields to delete.

doPaint

public final void doPaint()
Paints this screen.

Invoke this method to force a repaint of this screen, its delegate manager, and all owned fields.

Category:
Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.

ensureRegionVisible

public void ensureRegionVisible(Field field,
                                int x,
                                int y,
                                int width,
                                int height)
Attempts to make your provided region visible.

Pass this method a field, and a region (extent), and this method attempts to scroll the screen to make as much of your region visible as possible.

If your region is smaller than the screen's visible extent, this method does as little work as possible to ensure the entire region appears on the screen.

If your region is larger than the screen's visible extent, this method produces the net effect of aligning the top left corner of your region with the top left corner of the screen's visible extent.

Parameters:
field - Field that contains your region.
x - Left edge of the region.
y - Top edge of the region.
width - Width (in pixels) of the region.
height - Height (in pixels) of the region.
Category:
Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.

getApplication

public Application getApplication()
Retrieves this screen's application.
Returns:
Application object which owns this screen; always non-null.
Since:
JDE 4.0.0

getDefaultMenuItem

public MenuItem getDefaultMenuItem(int instance)
Retrieves the default menu item.
Parameters:
instance - The instance of the desired menu. If your screen supports only one menu, this may be ignored. By default, it is 0.
Returns:
Default menu item.
Since:
JDE 4.0.0
Category:
Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.

getDelegate

public Manager getDelegate()
Retrieves this screen's delegate manager.
Returns:
Delegate manager for this screen.

getField

public Field getField(int index)
Retrieves controlled field with specified index.

This method invokes Manager.getField(int) on this screen's delegate manager to retrieve a particular field from its list.

Overrides:
getField in class Manager
Parameters:
index - Index of field to retrieve.
Returns:
Controlled field at specified index.
Throws:
IndexOutOfBoundsException - If index not valid.

getFieldAtLocation

public int getFieldAtLocation(int x,
                              int y)
Retrieves index of field under provided point.

This method invokes Manager.getFieldAtLocation(int, int) on this screen's delegate manager.

Overrides:
getFieldAtLocation in class Manager
Parameters:
x - Distance from left edge of screen's extent.
y - Distance from top edge of screen's extent.
Returns:
Index of the field; if no field found, return -1.

getFieldCount

public int getFieldCount()
Retrieves the number of controlled fields.

This method invokes Manager.getFieldCount() on this screen's delegate manager to retrieve the number of fields it controls.

Overrides:
getFieldCount in class Manager
Returns:
Number of fields controlled by delegate manager.

getFieldWithFocus

public Field getFieldWithFocus()
Retrieves controlled field with focus.

This method invokes Manager.getFieldWithFocus() on this screen's delegate manager to retrieve the currently focussed field.

Overrides:
getFieldWithFocus in class Manager
Returns:
Controlled field with focus; if no field has the focus, returns null.

getFieldWithFocusIndex

public int getFieldWithFocusIndex()
Retrieves index of controlled field with focus.

This method invokes Manager.getFieldWithFocusIndex() on this screen's delegate manager to retrieve the currently focussed field.

Overrides:
getFieldWithFocusIndex in class Manager
Returns:
Index of controlled field with focus; if no field has the focus, returns -1.

getFocusRect

public void getFocusRect(XYRect rect)
Retrieves current extent of the focus.

Invoke this method to retrieve the extent of the current focus region. Notice that the coordinates expressed are local to this screen's region.

Overrides:
getFocusRect in class Manager
Parameters:
rect - Object to receive retrieved extent data.
Returns:
Current extent of the focus region.

getGraphics

public Graphics getGraphics()
Retrieves the graphics context for this screen.

This method returns the graphics context for this screen, with a clipping region on top of the graphics stack set to the screen's entire extent.

The Graphics object returned by this call becomes invalid and should not be used after the end of the current UI event.

Note: We recommend against direct use of this method; instead, use the various invalidate() methods. It may be used for direct drawing to the display when the screen contains no fields.

Returns:
Graphics context object for this screen.

getLeafFieldWithFocus

public Field getLeafFieldWithFocus()
Retrieves leaf field with focus. A Screen may manage several fields, each of which may manage several other fields. A leaf field is a field that does not manage any other fields. Use this method to figure out which leaf field (which is managed by one of the managed components) has the focus.

This method invokes Manager.getLeafFieldWithFocus() on this screen's delegate manager to retrieve the (bottom-most, non-manager) leaf field that has the focus.

Overrides:
getLeafFieldWithFocus in class Manager
Returns:
Controlled leaf field with focus; if no field has the focus, returns null.

getMenu

public Menu getMenu(int instance)
Retrieves the menu.
Parameters:
instance - Instance of the desired menu; if this screen supports only one menu, this may be ignored. By default, it is 0.
Returns:
Menu for this screen.
Since:
JDE 4.0.0
See Also:
onMenu(int), #makeMenuWithContext

getScreenAbove

public Screen getScreenAbove()
Retrieves handle for screen above this one.
Returns:
Screen above this one.
Since:
JDE 4.0.0

getScreenBelow

public Screen getScreenBelow()
Retrieves handle for screen below this one.
Returns:
Screen below this one.
Since:
JDE 4.0.0

getUiEngine

public final UiEngine getUiEngine()
Retrieves UiEngine that owns the display.
Returns:
Engine that owns the current display.
Since:
JDE 3.6.0

insert

public void insert(Field field,
                   int index)
Inserts a field to this screen's manager.

Provided a field and an index, this method invokes Manager.insert(Field,int) on this screen's delegate manager, prompting the manager to insert the field at the specified position in its list.

Overrides:
insert in class Manager
Parameters:
field - Field to insert.
index - Position in manager's list of controlled fields at which to insert new field.

invalidate

public void invalidate()
Invalidates a region of this screen.

This method marks a region of this screen as needing a repaint. The repainting is handled later by the main event dispatch thread.

Note: Any thread can safely invoke this method, and does not require to synchronize on the event lock.

Overrides:
invalidate in class Manager
Since:
JDE 4.0.0
See Also:
Field.invalidate()

invalidate

public void invalidate(int x,
                       int y,
                       int width,
                       int height)
Invalidates a region of this screen.

This method marks a region of this screen as needing a repaint. The repainting is handled later by the main event dispatch thread.

Note: Any thread can safely invoke this method, and does not require to synchronize on the event lock.

Overrides:
invalidate in class Manager
Parameters:
x - Left edge of the region in ContentRect coordinates.
y - Top edge of the region in ContentRect coordinates.
width - Width (in pixels) of the region.
height - Height (in pixels) of the region.
See Also:
Field.invalidate(int,int,int,int)

invalidateAll

public void invalidateAll(int x,
                          int y,
                          int width,
                          int height)
Invalidates a region of this screen.

This method marks a region of this screen as needing a repaint. The repainting is handled later by the main event dispatch thread.

Note: Any thread can safely invoke this method, and does not require to synchronize on the event lock.

Overrides:
invalidateAll in class Field
Parameters:
x - Left edge of the region in field coordinates.
y - Top edge of the region in field coordinates.
width - Width (in pixels) of the region.
height - Height (in pixels) of the region.
Since:
JDE 4.2.0
See Also:
Field.invalidate(int,int,int,int)

invalidateLayout

public void invalidateLayout()
Invalidates this screen's layout (including all controlled fields).

This method prompts this screen's delegate manager to invalidate this screen's layout.

Throws:
IllegalStateException - If this method is called while the screen is displayed.

invokeAction

protected boolean invokeAction(int action)
Invokes an action on this screen. First invokeAction(action) is invoked on the object returned from getDelegate(). If Manager.invokeAction(int) returns true then true is returned. Otherwise, the following logic is performed:
  1. If action is not Field.ACTION_INVOKE then false is returned.
  2. If getLeafFieldWithFocus() returns null then false is returned.
  3. Otherwise, some selection logic is performed on the leaf field with focus, and true is returned.
Overrides:
invokeAction in class Manager
Parameters:
action - the action to be performed as described above.
Returns:
true if the action was consumed; false if the action was not consumed.
Since:
JDE 4.2.0
Category:
Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.

isDataValid

public boolean isDataValid()
Computes and returns whether or not the data on this screen is valid.

The current implementation simply returns this.getDelegate().isDataValid().

Overrides:
isDataValid in class Manager
Returns:
true if the data of all fields on this screen are valid or false if the data of at least one field on this screen is not valid.
Since:
JDE 4.2.0
See Also:
Manager.isDataValid(), getDelegate()

isDirty

public boolean isDirty()
Determines if this screen is dirty.

This method invokes Manager.isDirty() on this screen's delegate manager.

Overrides:
isDirty in class Manager
Returns:
True if the delegate manager has changed since construction, or setDirty(boolean) was invoked (which is also passed on to the delegate manager); otherwise, false.

isDisplayed

public final boolean isDisplayed()
Determines if this screen is currently in use.

This will return true iff this screen is on a display stack. Its position within the stack does not matter; this function does not indicate visibility. A screen is deemed displayed as soon as it is pushed onto the display stack, and not displayed as soon as it is popped from the display stack.

For Global Screens, this indicates whether this screen is the current one displayed. Any Global Screen that has been queued or that has had its display preempted by a higher priority Global Screen is deemed not displayed.

Returns:
True if the screen is currently being displayed; otherwise, false.

isFocusable

public boolean isFocusable()
Verifies that the delegate manager accepts the focus.

This method invokes Manager.isFocusable() on this screen's delegate manager to determine whether the delegate manager (and thus the screen) accepts the focus.

Overrides:
isFocusable in class Manager
Returns:
True if delegate manager accepts the focus; otherwise, false.

isGlobal

public boolean isGlobal()
Determines if this is a global screen. A global screen is one that appears over other applications.
Returns:
True if this screen is attached to a UiEngine as a global screen; otherwise, false.
Since:
JDE 4.2.0

isGlobalStatus

public boolean isGlobalStatus()
Deprecated. Use isGlobal()


isMuddy

public boolean isMuddy()
Determines if this screen is muddy.

This method invokes Manager.isMuddy() on this screen's delegate manager.

Overrides:
isMuddy in class Manager
Returns:
True if a controlled field has changed and the focus has not been moved or left the field since the change; otherwise, false.

isSelecting

public boolean isSelecting()
Determines if this screen has the focus.

This method invokes Manager.isSelecting() on this screen's delegate manager.

Overrides:
isSelecting in class Manager
Returns:
True if one of the delegate manager's controlled fields currently has the focus; otherwise, false.

keyChar

protected boolean keyChar(char c,
                          int status,
                          int time)
Delegates key generation event to the controlled field with focus.

This method invokes Manager.keyChar(char, int, int) on this screen's delegate manager.

Overrides:
keyChar in class Manager
Parameters:
c - Character generated.
status - Modifier key status.
time - Number of milliseconds since the device was turned on.
Returns:
True if event was consumed; otherwise, false.

keyCharUnhandled

protected boolean keyCharUnhandled(char key,
                                   int status,
                                   int time)
Invoked when a keyChar event is unhandled.

Derived classes should override this event to provide custom handling of keyChar events that remain unhandled by any of their controlled fields.

Parameters:
key - Character generated.
status - Modifier key status.
time - Number of milliseconds since the device was turned on.
Returns:
If the key provided was the ESCAPE key, then this method returns true if this screen closes; otherwise, this method returns false.

keyControl

protected boolean keyControl(char c,
                             int status,
                             int time)
Delegates key generation event to the controlled field with focus.

This method invokes Manager.keyControl(char, int, int) on this screen's delegate manager.

Overrides:
keyControl in class Manager
Parameters:
c - Character generated.
status - Modifier key status.
time - Number of milliseconds since the device was turned on.
Returns:
True if event was consumed; otherwise, false.

keyDown

protected boolean keyDown(int keycode,
                          int time)
Delegates key down event to controlled field with focus.

This method invokes Manager.keyDown(int, int) on this screen's delegate manager.

Overrides:
keyDown in class Manager
Parameters:
keycode - Key scan code of the key pressed, ignoring any effects of modifier keys.
time - Number of milliseconds since the device was turned on.
Returns:
True if event was consumed; otherwise, false.

keyRepeat

protected boolean keyRepeat(int keycode,
                            int time)
Delegates key repeat event to controlled field with focus.

This method invokes Manager.keyRepeat(int, int) on this screen's delegate manager.

Overrides:
keyRepeat in class Manager
Parameters:
keycode - Key scan code of key to repeat, ignoring any effects of modifier keys.
time - Number of milliseconds since the device was turned on.
Returns:
True if event was consumed; otherwise, false.

keyStatus

protected boolean keyStatus(int keycode,
                            int time)
Delegates key status event to controlled field with focus.

This method invokes Manager.keyStatus(int, int) on this screen's delegate manager.

Overrides:
keyStatus in class Manager
Parameters:
keycode - Key scan code of character shown, before any effects of modifier keys.
time - Number of milliseconds since the device was turned on.
Returns:
True if event was consumed; otherwise, false.

keyUp

protected boolean keyUp(int keycode,
                        int time)
Delegates key up event to controlled field with focus.

This method invokes Manager.keyUp(int, int) on this screen's delegate manager.

Overrides:
keyUp in class Manager
Parameters:
keycode - Key scan code of the key released, ignoring any effects of modifier keys.
time - Number of milliseconds since the device was turned on.
Returns:
True if event was consumed; otherwise, false.

layoutDelegate

protected final void layoutDelegate(int width,
                                    int height)
Lays out this screen's delegate.
Parameters:
width - Amount of available horizontal space.
height - Amount of available vertical space.

makeMenu

protected void makeMenu(Menu menu,
                        int instance)
Called from onMenu to populate the menu.
Overrides:
makeMenu in class Manager
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.
Since:
JDE 3.6.0
See Also:
onMenu(int)

navigationClick

protected boolean navigationClick(int status,
                                  int time)
Delegates navigational click events.

This method passes on navigation click events to this screen's delegate manager by invoking Manager.navigationClick(int, int).

Overrides:
navigationClick in class Manager
Parameters:
status - State of the modifier keys.
time - Number of milliseconds since the device was turned on. One scenario that calls this method is when a Screen object is pushed to an application and a Navigation event is injected into the same application. When this scenario occurs, this method is called using 0 for the time parameter.
Returns:
True if delegate manager consumed the event; otherwise false.
Since:
JDE 4.2.0
Category:
Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.

navigationMovement

protected boolean navigationMovement(int dx,
                                     int dy,
                                     int status,
                                     int time)
Invoked when a navigational motion occurs. The source of the navigation event can be determined by checking the KeypadListener.STATUS_TRACKWHEEL and KeypadListener.STATUS_FOUR_WAY bits in the status parameter; exactly one of these will be set.
Overrides:
navigationMovement in class Manager
Parameters:
dx - Magnitude of navigational motion: negative for a move left and postive for a move right.
dy - Magnitude of navigational motion: negative for an upwards move, and positive for a downwards move.
status - Modifier key status at time of move.
time - Number of milliseconds since the device was turned on. One scenario that calls this method is when a Screen object is pushed to an application and a Navigation event is injected into the same application. When this scenario occurs, this method is called using 0 for the time parameter.
Returns:
True if event was consumed; otherwise, false.
Since:
JDE 4.2.0
Category:
Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.

navigationUnclick

protected boolean navigationUnclick(int status,
                                    int time)
Delegates navigation unclick events.

This method passes on navigation unclick events to this screen's delegate manager by invoking Manager.navigationUnclick(int, int).

Overrides:
navigationUnclick in class Manager
Parameters:
status - State of the modifier keys.
time - Number of milliseconds since the device was turned on. One scenario that calls this method is when a Screen object is pushed to an application and a Navigation event is injected into the same application. When this scenario occurs, this method is called using 0 for the time parameter.
Returns:
True if delegate manager consumed the event; otherwise false.
Since:
JDE 4.2.0
Category:
Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.

onClose

public boolean onClose()
Indicates a close event has occurred.

The default implementation is activated by specifying DEFAULT_CLOSE. It will call onSavePrompt() if the screen is dirty, then call close() if successful.

Returns:
True if the screen closes; otherwise, false.
Since:
JDE 3.6.0
Category:
Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.

onDisplay

protected void onDisplay()
Invoked when this screen is pushed onto the display stack.

This method is invoked by the system after this screen is pushed onto the stack and layout has been done, but before any painting occurs.

If no controlled field has the focus, this method attempts to assign the focus to the first field that will accept it, starting with the first field in the delegate manager's field list. Additionally, this method makes the focus visible, and resets scrolling to 0 if possible (ensuring the focussed region stays on the screen).

The complementary callback is onUndisplay().

Overrides:
onDisplay in class Field
See Also:
onExposed(), Field.onVisibilityChange(boolean)
Category:
Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.

onExposed

protected void onExposed()
Invoked when this screen is exposed. A Screen is exposed when it becomes the topmost by means of:
  1. a screen is popped off the display stack (since 3.0)
  2. a global screen is popped (since 4.0)
  3. this screen's application receives foreground (since 4.2)
  4. this screen is pushed and it is deemed exposed by the above rules (since 4.2)

Subclasses of screen should override this method for special handling.

The complimenting callback is onObscured().

Overrides:
onExposed in class Field
See Also:
onDisplay(), Field.onVisibilityChange(boolean)
Category:
Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.

onFocus

protected void onFocus(int direction)
Finds a controlled field to give the focus.

This method invokes Manager.onFocus(int) on this screen's delegate manager, thus starting with the delegate manager's controlled field list, looking for a field to give the focus. This method passes the focus to the first found field that accepts it.

Overrides:
onFocus in class Manager
Parameters:
direction - If 1, start at the top of the delegate manager's field list and search foward. If -1, start at the bottom of the delegate manager's field list and search backward.
Category:
Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.

onFocusNotify

protected void onFocusNotify(boolean focus)
Called whenever the screen has gained or lost focus.
Parameters:
focus - true if this screen has gained the focus or false if this screen has lost focus.
Since:
JDE 4.2.0
Category:
Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.

onMenu

public boolean onMenu(int instance)
Invoked when a menu needs displaying.

If you specify the DEFAULT_MENU style, this method creates a menu and call #makeMenuWithContext(Menu,int).

Then menu.show() will be invoked, and MenuItem.run() used to activate the selected item.

Note: Please use this instead of overriding trackwheelClick(int, int); this may be called in other events, such as a menu button.

Parameters:
instance - Instance of the menu to display. If your screen supports only one menu, this may be ignored. By default, it is 0.
Returns:
True if the menu is created; otherwise, false.
Since:
JDE 3.6.0
Category:
Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.

onMenuDismissed

protected void onMenuDismissed()
Deprecated. Use onMenuDismissed(Menu).

Called when the menu is dismissed.
Overrides:
onMenuDismissed in class Field
Since:
JDE 4.0.2

onMenuDismissed

protected void onMenuDismissed(Menu menu)
Called when the menu is dismissed. This method calls onMenuDismissed(Menu) on all the fields and managers that are currently in focus. It also calls onMenuDismissed().
Overrides:
onMenuDismissed in class Field
Parameters:
menu - Menu to be dismissed
Since:
JDE 4.2.0

onObscured

protected void onObscured()
Invoked when this screen is obscured. A Screen is obscured when it is was the topmost and is no longer by means of:
  1. a new screen pushed on the display stack (since 3.0)
  2. a global screen is displayed above this screen (since 4.0)
  3. this screen's application goes into the background (since 4.2)
  4. this screen is pushed and it is deemed obscured by the above rules (since 4.2)

Derived classes should override this method for special handling.

The complimenting callback is onExposed().

Overrides:
onObscured in class Field
See Also:
onUndisplay(), Field.onVisibilityChange(boolean)
Category:
Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.

onSave

protected boolean onSave()
Invoked when the screen should save its contents.

If isDataValid() returns true, this method then calls save() (and displays an error dialog if save() throws an IOException).

Returns:
True if successful; otherwise, false.
Since:
JDE 3.6.0
Category:
Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.

onSavePrompt

protected boolean onSavePrompt()
Invoked when the screen should prompt to save its contents.

The default implementation is empty. Overriding classes should provide a dialog and call onSave if the user has chosen to save. If the return is true, the framework will call onClose.

Returns:
True if the screen should close; otherwise, false
Since:
JDE 3.6.0
See Also:
MainScreen.onSavePrompt()
Category:
Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.

onUndisplay

protected void onUndisplay()
Invoked when this screen is popped off the display stack.

Derived classes should override this method for special handling.

The complimenting callback is onDisplay().

Overrides:
onUndisplay in class Manager
See Also:
onObscured(), Field.onVisibilityChange(boolean)
Category:
Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.

onUnfocus

protected void onUnfocus()
Invoked when focus is removed from this screen.

This method invokes Manager.onUnfocus() on this screen's delegate manager to remove the focus from this screen.

Overrides:
onUnfocus in class Manager
Category:
Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.

openDevelopmentBackdoor

protected boolean openDevelopmentBackdoor(int backdoorCode)
Handles development backdoor key-sequences.

Derived classes should override this method to provide support for development backdoor key-sequences.

Useful for backdoors in non-production devices.

Parameters:
backdoorCode - Backdoor code to open.
Returns:
False.
Since:
JDE 4.0.2

openProductionBackdoor

protected boolean openProductionBackdoor(int backdoorCode)
Handles production backdoor key-sequences.

Derived classes should override this method to provide support for production backdoor key-sequences.

Useful for backdoors in production devices.

Parameters:
backdoorCode - Backdoor code to open.
Returns:
False.
Since:
JDE 4.0.2

paint

protected void paint(Graphics graphics)
Paints this screen's visible region.

Invoke this method to prompt the screen to paint itself. If you extend Screen to create a custom layout, you may want to implement the base class's Manager.subpaint(net.rim.device.api.ui.Graphics) method, as this method invokes it.

This method also draws the focus indicator as required.

Overrides:
paint in class Manager
Parameters:
graphics - Graphics context used for painting.

paintBackground

protected void paintBackground(Graphics graphics)
Paint this screen's background.

The system calls this method before painting begins in order to clear this screen's background, initializing your provided graphics context to this screen's extent.

By default, this method simple invokes Graphics.clear(); for more complex handling, you should override this method in extending classes.

Overrides:
paintBackground in class Field
Parameters:
graphics - Graphics context used to draw the background.
Category:
Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.

removeFocus

public void removeFocus()
Removes focus from this screen.
Category:
Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.

removeKeyListener

public final void removeKeyListener(KeyListener listener)
Removes a key event listener from this screen.
Parameters:
listener - Key event listener to de-register for this screen.

removeTrackwheelListener

public final void removeTrackwheelListener(TrackwheelListener listener)
Removes a trackwheel event listener from this screen.
Parameters:
listener - Trackwheel event listener to de-register for this screen.

replace

public void replace(Field oldField,
                    Field newField)
Removes a field from this Screen and replaces it with another field. This method simply invokes replace(oldField, newField) on the Manager returned from getDelegate().

See Manager.replace(Field, Field) for more details about how this method behaves, including exceptions that can be thrown.

Overrides:
replace in class Manager
Parameters:
oldField - the field to be replaced
newField - the field to replace it
Since:
JDE 4.2.0

save

public void save()
          throws IOException
Invoked when the screen should save its contents.
Since:
JDE 3.6.0

scroll

public final boolean scroll(int direction)
Scrolls the focus in specified direction.

The parameter passed to this method indicates the direction and amount of movement required.

To control vertical movement use Manager.UPWARD and Manager.DOWNWARD to move the focus one screen up or down; use Manager.TOPMOST and Manager.BOTTOMMOST to move the focus all the way to the top edge or bottom edge of the manager's region.

To control horizontal movement use Manager.LEFTWARD and Manager.RIGHTWARD to move the focus one screen left or right; use Manager.LEFTMOST and Manager.RIGHTMOST to move the focus all the way to the left or right edge of the manager's region.

You can combine one vertical movement constant and one horizontal movement constant to effectively move the focus diagonally. However, this method performs the vertical movement first, and then the horizontal movement, in order to simulate diagonal motion.

Note: Focus movement is constrained in all directions by the extent of this manager. If the focus is currently less than one screen from an edge of the manager's extent it must move towards, it stops at that edge. Also, this method scrolls the visible region of this manager as required to ensure the focus remains visible.

Parameters:
direction - Combination of constant values to indicate in which direction, and how much, the focus is to move.
Returns:
This method always returns true.

setBackdoorAltStatus

protected void setBackdoorAltStatus(boolean altStatus)
Sets whether backdoors key sequences use ALT'd or un-ALT'd keystrokes.
Parameters:
altStatus - True to require ALT key sequences, or false if un-ALT'd keystrokes can be used as backdoors.
Since:
JDE 4.0.2

setDefaultClose

protected void setDefaultClose(boolean provideDefaultClose)
This method controls whether the screen's menu contains a "close" menu item. For example,if you pass in a value of false, the menu will not include a "close" item
Parameters:
provideDefaultClose - Flag for specifying if menu is to include a close item
Since:
JDE 4.0.2

setDirty

public void setDirty(boolean dirty)
Cleans or dirties all controlled fields.

This method invokes Manager.setDirty(boolean) on this screen's delegate manager to clean (or dirty) all this screen's controlled fields.

Overrides:
setDirty in class Manager
Parameters:
dirty - True if dirtying the fields; false if cleaning them.

setFocus

public void setFocus()
Sets the focus to the delegate manager.

This method assigns the focus to the delegate manager through invoking Field.setFocus() on the delegete manager.

Overrides:
setFocus in class Field

Following copied from class: Field
Throws:
IllegalStateException - If the field is not attached to a screen.

setFocus

public final boolean setFocus(Field field,
                              int x,
                              int y,
                              int status,
                              int time)
Sets focus to exact position in current screen.
Parameters:
field - Field in which to place the focus.
x - Distance from left edge of screen.
y - Distance from top edge of screen.
status - State of modifier keys.
time - Number of milliseconds since the device was turned on.
Returns:
True if field under desired point accepts the focus; otherwise, false.
Throws:
IllegalArgumentException - If field parameter does not belong to this screen

setHorizontalQuantization

public void setHorizontalQuantization(int horizontalQuanta)
Sets the horizontal quantization.

When a screen's layout manager or delegate is laying out components on the screen, the layout manager uses the horizontal quantization to determine how many rows can be fully displayed on a screen. By default, the delegate uses the font size as the horizontal quantization value. For example: You want to display rows of text that use a font size of 11 on a screen that is 140 pixels in height. By default, the screen delegate can fully display 12 of these rows.

You may want to set the value if you are laying out non-text rows.

The actual horizontal display length will be a multiple of the value you specify.

Overrides:
setHorizontalQuantization in class Manager
Parameters:
horizontalQuanta - Horizontal quantization in pixels.

setPositionDelegate

protected final void setPositionDelegate(int x,
                                         int y)
Set the position of this screen's layout manager (delegate).
Parameters:
x - Left edge position for this screen's delegate.
y - Top edge position for this screen's delegate.

setTrackballFilter

public void setTrackballFilter(int filter)
Sets the trackball filter for this Screen. You can use different trackball filters to affect reported trackball movement versus actual trackball movement. This is typically used to filter out noise or unwanted movements. It can also be used to set acceleration, where the reported movement is increasingly more than the actual movement the hardware detects.

Parameters:
filter - A bitmask of the Trackball.FILTER_* constants.
Throws:
IllegalArgumentException - if filter is not a valid value, as described above.
Since:
JDE 4.2.0

setTrackballSensitivityXOffset

public void setTrackballSensitivityXOffset(int trackballSensitivityXOffset)
Sets the relative trackball sensitivity for the X axis. If the value is Integer.MAX_VALUE, then it is treated as unset. Otherwise, the value is added to the user set sensitivity when this Screen has focus.
Parameters:
trackballSensitivityXOffset - -100 to 100 or Trackball.SENSITIVITY_UNSET
Throws:
IllegalArgumentException - if trackballSensitivityXOffset is not -100 to 100 or Integer.MAX_VALUE.
Since:
JDE 4.2.0

setTrackballSensitivityYOffset

public void setTrackballSensitivityYOffset(int trackballSensitivityYOffset)
Sets the relative trackball sensitivity for the X axis. If the value is Integer.MAX_VALUE, then it is treated as unset. Otherwise, the value is added to the user set sensitivity when this Screen has focus.
Parameters:
trackballSensitivityXOffset - -100 to 100 or Trackball.SENSITIVITY_UNSET
Throws:
IllegalArgumentException - if trackballSensitivityXOffset is not -100 to 100 or Integer.MAX_VALUE.
Since:
JDE 4.2.0

setVerticalQuantization

public void setVerticalQuantization(int verticalQuanta)
Sets the vertical quantization.

When a screen's layout manager or delegate is laying out components on the screen, the layout manager uses the vertical quantization to determine how many columns can be fully displayed.

By default, the delegate uses the font size as the vertical quantization value.

The actual vertical display length will be a multiple of the value you specify.

Overrides:
setVerticalQuantization in class Manager
Parameters:
verticalQuanta - Vertical quantization in pixels.
See Also:
setHorizontalQuantization(int)

trackwheelClick

protected boolean trackwheelClick(int status,
                                  int time)
Delegates trackwheel click events.

This method passes on trackwheel click events to this screen's delegate manager by invoking Manager.trackwheelClick(int, int).

Overrides:
trackwheelClick in class Manager
Parameters:
status - State of the modifier keys.
time - Number of milliseconds since the device was turned on.
Returns:
True if delegate manager consumed the event; otherwise false.

trackwheelClickUnhandled

protected boolean trackwheelClickUnhandled(int status,
                                           int time)
Handles trackwheel click event if delegate passes it through.

Use this method to handle trackwheel click events that remained unhandled after invoking trackwheelClick(int, int).

Parameters:
status - Modifier key status (currently ignored)
time - Number of milliseconds since the device was turned on (currently ignored).
Returns:
True if event was consumed; otherwise, false.
Since:
JDE 3.6.0

trackwheelRoll

protected boolean trackwheelRoll(int amount,
                                 int status,
                                 int time)
Invoked when the trackwheel is rolled.
Overrides:
trackwheelRoll in class Manager
Parameters:
amount - Number of scrolling positions: negative for an upwards roll, and positive for a downwards roll.
status - Modifier key status at time of roll.
time - Number of milliseconds since the device was turned on.
Returns:
True if event was consumed; otherwise, false.

trackwheelUnclick

protected boolean trackwheelUnclick(int status,
                                    int time)
Delegates trackwheel unclick events.

This method passes on trackwheel unclick events to this screen's delegate manager by invoking Manager.trackwheelUnclick(int, int).

Overrides:
trackwheelUnclick in class Manager
Parameters:
status - State of the modifier keys.
time - Number of milliseconds since the device was turned on.
Returns:
True if delegate manager consumed the event; otherwise false.

updateDisplay

public final void updateDisplay()
Updates the display.


Copyright 1999-2007 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.