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.
	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.
	void	doLayout() Lays out all controlled fields.
	void	doPaint() Paints this screen.
	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.
	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).
	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.
	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) Invoked when a menu needs displaying.
	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() Invoked when focus is removed from this screen.
	protected void	paint(Graphics graphics) Paints this screen'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) 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

clearCustomScrollArrows, deleteAll, getHorizontalScroll, getVerticalScroll, getVirtualHeight, getVirtualWidth, getVisibleHeight, getVisibleWidth, invalidateFieldRange, isDownArrowShown, isUpArrowShown, isValidLayout, layout, layoutChild, moveFocus, moveFocus, nextFocus, paintChild, setFocus, setHorizontalScroll, setNonfocusableOverride, 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.0

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

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

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

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

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

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

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

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

See Also:

onMenu(int), makeMenuWithContext(net.rim.device.api.ui.component.Menu, int)

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

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.

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

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

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

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

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

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

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

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

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

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.

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

onObscured

protected void onObscured()

Invoked when this screen is obscured by a new screen pushed on the display stack.

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

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

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.

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

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

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

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

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

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

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

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

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

Since:

JDE 4.0.0

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

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

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

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

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

updateDisplay

public final void updateDisplay()

Updates the display for this screen only.