SHOW Colour 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
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
  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 doLayout()
          Lays out all controlled fields.
 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 invalidateLayout()
          Invalidates this screen's layout (including all controlled fields).
   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 isGlobalStatus()
          Determines if this is a global status screen.
   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  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 revealed by a screen getting popped off the display stack, or a global screen is dismissed.
 Category: Framework protected  void onFocus(int direction)
          Finds a controlled field to give the focus.
 Category: Framework  boolean onMenu(int instance)
          Invoked when a menu needs displaying.
  protected  void onMenuDismissed()
          Calls onMenuDismissed() on all the fields and managers that are currently in focus.
 Category: Framework protected  void onObscured()
          Invoked when this screen is obscured by a new screen pushed on the display stack, or a global screen is displayed.
 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 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)
           
   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)
          Places this screen's delegate.
   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 for this screen only.
 
Methods inherited from class net.rim.device.api.ui.Manager
deleteAll, getHorizontalScroll, 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, getContextMenu, getCookie, getExtent, getExtent, getFieldStyle, getFocusListener, getFont, getHeight, getIndex, getLeft, getManager, getOriginal, getPreferredHeight, getPreferredWidth, getScreen, getStyle, getTop, getWidth, isEditable, 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_MENU

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

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
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.
Since:
JDE 4.0.2

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.
Since:
JDE 4.0.2

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.
Since:
JDE 4.0.2

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.
Since:
JDE 4.0.2

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.
Since:
JDE 4.0.2

doLayout

public void doLayout()
Lays out all controlled fields.

This method is automatically invoked when a screen is pushed onto the display stack.

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.
Since:
JDE 4.0.2
Category:
Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.

getUiEngine

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

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.

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 GlobalStatus screens, this indicates whether this screen is the current one displayed. Any GlobalStatus that has been queued or that has had its display preempted by a higher priority GlobalStatus 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.

isGlobalStatus

public boolean isGlobalStatus()
Determines if this is a global status screen.
Returns:
True if this screen is being displayed or is queued for display as a global status screen; otherwise, false.

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.

getApplication

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

getDelegate

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

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.
Since:
JDE 4.0.2

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.
Since:
JDE 4.0.2

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.

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

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.
Since:
JDE 4.0.2

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.2
Category:
Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.

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.

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.

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

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.
Since:
JDE 4.0.2

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.
Since:
JDE 4.0.2

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.
Since:
JDE 4.0.2

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

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.
Since:
JDE 4.0.2

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.
Since:
JDE 4.0.2

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.
Since:
JDE 4.0.2

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.
Since:
JDE 4.0.2

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.
Since:
JDE 4.0.2

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 4.0.2
See Also:
onMenu(int)

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 revealed by a screen getting popped off the display stack, or a global screen is dismissed.

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.
Since:
JDE 4.0.2
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 4.0.2
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()
Calls onMenuDismissed() on all the fields and managers that are currently in focus.
Overrides:
onMenuDismissed in class Field
Since:
JDE 4.0.2

onObscured

protected void onObscured()
Invoked when this screen is obscured by a new screen pushed on the display stack, or a global screen is displayed.

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 #onValidate 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.

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.
Since:
JDE 4.0.2

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.
Since:
JDE 4.0.2
Category:
Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.

save

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

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.

setDefaultClose

protected void setDefaultClose(boolean provideDefaultClose)
Since:
JDE 4.0.2

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
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.0.0
See Also:
Field.invalidate(int,int,int,int)

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.
Since:
JDE 4.0.2
See Also:
Field.invalidate(int,int,int,int)

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.
Since:
JDE 4.0.2

trackwheelClick

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

This listener 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.
Since:
JDE 4.0.2

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 4.0.2

trackwheelUnclick

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

This listener 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.
Since:
JDE 4.0.2

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.

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.
Since:
JDE 4.0.2

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.

getLeafFieldWithFocus

public Field getLeafFieldWithFocus()
Retrieves leaf field with 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.

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.
Since:
JDE 4.0.2

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.
Since:
JDE 4.0.2

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.
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.
Since:
JDE 4.0.2

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: net.rim.device.api.ui.Field
Throws:
IllegalStateException - If the field is not attached to a screen or if called on a Field that does not accept the focus.

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
Since:
JDE 4.0.2

setHorizontalQuantization

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

The real horizontal size must be a multiple of your provided value.

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

setPositionDelegate

protected final void setPositionDelegate(int x,
                                         int y)
Places this screen's delegate.
Parameters:
x - Left edge position for this screen's delegate.
y - Top edge position for this screen's delegate.
Since:
JDE 4.0.2

setVerticalQuantization

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

The real vertical szie must be a multiple of your provided value.

Overrides:
setVerticalQuantization in class Manager
Parameters:
verticalQuanta - Vertical quantization in pixels.
Since:
JDE 4.0.2

updateDisplay

public final void updateDisplay()
Updates the display for this screen only.


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