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
Direct Known Subclasses:
FullScreen, PopupScreen

public abstract class Screen
extends Manager

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_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.
 void close()
          Closes the 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.
 void doLayout()
          Lays out all controlled fields.
 void doPaint()
          Paints the screen.
 void ensureRegionVisible(Field field, int x, int y, int width, int height)
          Attempts to make your provided region visible.
 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.
 UiEngine getUiEngine()
          Retrieves UiEngine that owns the display.
 void insert(Field field, int index)
          Inserts a field to this screen's manager.
 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()
          Determine if this screen is currently in use.
 boolean isFocusable()
          Verify 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.
 boolean onClose()
          Indicates a close event has occurred.
protected  void onDisplay()
          Invoked when this screen is pushed onto the display stack.
protected  void onExposed()
          Invoked when this screen is revealed by a screen getting popped off the display stack.
protected  void onFocus(int direction)
          Finds a controlled field to give the focus.
 boolean onMenu(int instance)
          Called when a menu should be displayed.
protected  void onObscured()
          Invoked when this screen is obscured by a new screen pushed on the display stack.
protected  boolean onSave()
          Invoked when the screen should save its contents.
protected  boolean onSavePrompt()
          Invoked when the screen should prompt to save its contents.
protected  void onUndisplay()
          Invoked when this screen is popped off the display stack.
protected  void onUnfocus()
          Removes focus from this screen.
protected  void paint(Graphics graphics)
          Paints this manager's visible region.
protected  void paintBackground(Graphics graphics)
          Paint this screen's background.
 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.
 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)
           
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, invalidate, 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, getFieldStyle, getFocusListener, getFont, getHeight, getIndex, getLeft, getManager, getOriginal, getPreferredHeight, getPreferredWidth, getScreen, getStyle, getTop, getWidth, isEditable, isPasteable, isSelectable, isSelectionCopyable, isSelectionCutable, isSelectionDeleteable, isVisible, makeContextMenu, onVisibilityChange, paste, select, selectionCopy, selectionCut, selectionDelete, setChangeListener, setCookie, setEditable, setExtent, setFocusListener, setFont, setMuddy, setPosition, updateLayout
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_MENU

public static final long DEFAULT_MENU
If specified, screen will provide a default menu.

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

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 3.6

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 3.6

close

public void close()
Closes the screen. The default implementation pops this screen, and if the screen stack is empty, System.exit(0) is called.

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 3.6

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 3.6

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 3.6

getUiEngine

public final UiEngine getUiEngine()
Retrieves UiEngine that owns the display.

Returns:
Engine that owns the current display.

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()
Determine if this screen is currently in use.

This will return true iff this screen is on a display stack. Its position withing 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 GlocbalStatus is deems not displayed.

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

isFocusable

public boolean isFocusable()
Verify 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.

doLayout

public void doLayout()
Lays out all controlled fields.

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


doPaint

public final void doPaint()
Paints the screen.

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


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 3.6

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
Returns:
Current extent of the focus region.
Since:
JDE 3.6

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

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

Returns:
Graphics context object for this screen.

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 3.6

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

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 - Ticks since device reset.
Returns:
True if event was consumed; otherwise, false.
Since:
JDE 3.6

keyCharUnhandled

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

Subclasses 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 - Ticks since device reset.
Returns:
False.
Since:
JDE 3.6

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 - Ticks since device reset.
Returns:
True if event was consumed; otherwise, false.
Since:
JDE 3.6

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 - Ticks since device reset.
Returns:
True if event was consumed; otherwise, false.
Since:
JDE 3.6

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 - Ticks since device reset.
Returns:
True if event was consumed; otherwise, false.
Since:
JDE 3.6

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 - Ticks since device reset.
Returns:
True if event was consumed; otherwise, false.
Since:
JDE 3.6

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 - Ticks since device reset.
Returns:
True if event was consumed; otherwise, false.
Since:
JDE 3.6

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 3.6

makeMenu

protected void makeMenu(Menu menu,
                        int instance)
Called from onMenu to populate the menu.
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
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 sucessful.


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 complimenting callback is onUndisplay().

See Also:
onUndisplay(), onExposed(), Field.onVisibilityChange(boolean)

onExposed

protected void onExposed()
Invoked when this screen is revealed by a screen getting popped off the display stack.

Subclasses of screen should override this method for special handling.

The complimenting callback is onObscured().

See Also:
onObscured(), onDisplay(), Field.onVisibilityChange(boolean)

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 3.6

onMenu

public boolean onMenu(int instance)
Called when a menu should be displayed. Please use this instead of overriding trackwheelClick -- this may be called in other events, such as a menu button.

If the DEFAULT_MENU style is specified, this will create a menu and call makeMenu(Menu). Then menu.show() will be called, and MenuItem.run() will be used to activate the selected 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.
Since:
JDE 3.6

onObscured

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

Subclasses of screen should override this method for special handling.

The complimenting callback is onExposed().

See Also:
onExposed(), onUndisplay(), Field.onVisibilityChange(boolean)

onSave

protected boolean onSave()
Invoked when the screen should save its contents.
Returns:
true iff successful

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 framwork will calll onClose.

Returns:
true if the screen should close
See Also:
MainScreen.onSavePrompt()

onUndisplay

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

Subclasses of screen should override this method for special handling.

The complimenting callback is onDisplay().

See Also:
onDisplay(), onObscured(), Field.onVisibilityChange(boolean)

onUnfocus

protected void onUnfocus()
Removes focus 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

paint

protected void paint(Graphics graphics)
Description copied from class: Manager
Paints this manager's visible region.

Invoke this method to prompt this manager to paint itself. if you extend manager to create a custom layout manager, you may want to implement the subpaint method, as this method invokes it.

This method also draws the focus indicator as required.

Overrides:
paint in class Manager
Since:
JDE 3.6

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.

Parameters:
graphics - Graphics context used to draw the background.
Since:
JDE 3.6

save

public void save()
          throws IOException
Invoked when the screen should save its contents.

removeFocus

public void removeFocus()
Removes focus from this screen.

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, as long as no layout update or scrolling occurs.

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

trackwheelRoll

protected boolean trackwheelRoll(int amount,
                                 int status,
                                 int time)
Invoked when the trackwheel is rolled.

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 - Ticks since device reset.
Returns:
True if event was consumed; otherwise, false.
Since:
JDE 3.6

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 - Ticks since device reset.
Returns:
True if delegate manager consumed the event; otherwise false.
Since:
JDE 3.6

trackwheelClickUnhandled

protected boolean trackwheelClickUnhandled(int status,
                                           int time)
Since:
JDE 3.6

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 - Ticks since device reset.
Returns:
True if delegate manager consumed the event; otherwise false.
Since:
JDE 3.6

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 3.6

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 3.6

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 3.6

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:
True if this method succesfully moved the focus to a new field; otherwise, false.
Since:
JDE 3.6

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 3.6

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 - Ticks since device reset.
Returns:
True if field under desired point accepts the focus; otherwise, false.
Throws:
IllegalArgumentException - if field does not belong to this screen
Since:
JDE 3.6

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 3.6

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 3.6

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 3.6

updateDisplay

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



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