net.rim.device.api.ui
Class Screen

java.lang.Object
  net.rim.device.api.ui.Field
      net.rim.device.api.ui.ScrollView
          net.rim.device.api.ui.Manager
              net.rim.device.api.ui.Screen

All Implemented Interfaces:

AdjustmentListener

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. 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. Screen does not accept Field.FOCUSABLE_MASK or 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.
static long	NO_SYSTEM_MENU_ITEMS If specified, screen will not have system menu items.

Fields inherited from class net.rim.device.api.ui.Manager

BOTTOMMOST, DOWNWARD, HORIZONTAL_SCROLL, HORIZONTAL_SCROLLBAR, HORIZONTAL_SCROLLBAR_MASK, HORIZONTAL_SCROLL_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_SCROLLBAR, VERTICAL_SCROLLBAR_MASK, VERTICAL_SCROLL_MASK

Fields inherited from class net.rim.device.api.ui.Field

ACTION_INVOKE, AXIS_HORIZONTAL, AXIS_SEQUENTIAL, AXIS_VERTICAL, EDITABLE, EDITABLE_MASK, FIELD_BOTTOM, FIELD_HALIGN_MASK, FIELD_HCENTER, FIELD_LEADING, FIELD_LEFT, FIELD_RIGHT, FIELD_TOP, FIELD_TRAILING, FIELD_VALIGN_MASK, FIELD_VCENTER, FOCUSABLE, FOCUSABLE_MASK, HIGHLIGHT_FOCUS, HIGHLIGHT_SELECT, NON_FOCUSABLE, NON_SPELLCHECKABLE, READONLY, SPELLCHECKABLE, SPELLCHECKABLE_MASK, STATUS_MOVE_FOCUS_HORIZONTALLY, STATUS_MOVE_FOCUS_VERTICALLY, USE_ALL_HEIGHT, USE_ALL_WIDTH, VISUAL_STATE_ACTIVE, VISUAL_STATE_DISABLED, VISUAL_STATE_DISABLED_FOCUS, VISUAL_STATE_FOCUS, VISUAL_STATE_NORMAL

Constructor Summary

Screen(Manager delegate)
Constructs a new Screen instance with the provided delegate manager.

Screen(Manager delegate, long style)
Constructs a new Screen instance with the provided delegate manager and style.

Method Summary
void	add(Field field) Adds a field to this screen's manager.
void	addInputSettings(InputSettings settings) Applies attributes in the specified InputSettings object to this screen.
void	addKeyListener(KeyListener listener) Registers a key event listener for this screen.
void	addScreenUiEngineAttachedListener(ScreenUiEngineAttachedListener listener) Registers a ScreenUiEngineAttachedListener event listener for this screen.
void	addTrackwheelListener(TrackwheelListener listener) Registers a trackwheel event listener for this screen.
void	clearInputSettings() Removes all custom input settings for this screen and revert to defaults.
void	close() Closes this screen.
protected boolean	cursorClick(int x, int y, int status, int time) Delegates cursor click events.
protected boolean	cursorUnclick(int x, int y, int status, int time) Delegates cursor unclick events.
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	doPaint() Paints this screen.
void	ensureRegionVisible(Field field, int x, int y, int width, int height) Attempts to make your provided region visible.
AccessibleContext	getAccessibleContext() Gets the accessible representation of the field for a screen reader.
Application	getApplication() Retrieves this screen's application.
ContextMenuProvider	getContextMenuProvider() Returns the context menu provider.
MenuItem	getDefaultMenuItem(int instance) Retrieves the default menu item.
Manager	getDelegate() Retrieves this screen's delegate manager.
Field	getField(int index) Retrieves the controlled field with the specified index.
int	getFieldAtLocation(int x, int y) Retrieves the index of the field under the provided point.
int	getFieldCount() Retrieves the number of controlled fields.
Field	getFieldWithFocus() Retrieves the controlled field with focus.
int	getFieldWithFocusIndex() Retrieves the index of the controlled field with focus.
void	getFocusRect(XYRect rect) Retrieves the current extent of the focus.
Graphics	getGraphics() Retrieves the graphics context for this screen.
InputHelperBase	getInputHelper() Gets the InputHelperBase instance associated with this screen.
void	getInputSettings(InputSettings settings) Retrieves the values for the attributes in the specified InputSettings object for this screen.
Field	getLeafFieldWithFocus() Retrieves the leaf field with focus.
Menu	getMenu(int instance) Retrieves the menu.
Screen	getScreenAbove() Retrieves the handle for the local screen above this one.
Screen	getScreenBelow() Retrieves the handle for the local screen below this one.
ServiceMode	getServiceMode() Gets the current service mode for this screen.
TitleBar	getTitleBar() Retrieves the current TitleBar object used by this screen.
UiEngine	getUiEngine() Retrieves the UiEngine that owns this screen.
VirtualKeyboard	getVirtualKeyboard() Retrieves the VirtualKeyboard object associated with this screen.
void	insert(Field field, int index) Inserts a field to this screen's manager.
void	invalidate() Invalidates the entire 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).
protected boolean	invokeAction(int action) Invokes an action on this screen.
boolean	isDataValid() Computes and returns whether or not the data on this screen is valid.
boolean	isDirty() Determines if this screen is dirty.
boolean	isDisplayed() Determines if this screen is currently in use.
boolean	isFocus() Determines if this screen currently has the focus.
boolean	isFocusable() Verifies that the delegate manager accepts the focus.
boolean	isGlobal() Determines if this is a global screen.
boolean	isGlobalStatus() Deprecated. Use isGlobal()
boolean	isMuddy() Determines if this screen is muddy.
boolean	isSelecting() Determines if this screen has the focus.
protected boolean	keyChar(char c, int status, int time) Delegates key generation event to the controlled field with focus.
protected boolean	keyCharUnhandled(char key, int status, int time) Invoked when a keyChar event is unhandled.
protected boolean	keyControl(char c, int status, int time) Delegates a key generation event to the controlled field with focus.
protected boolean	keyDown(int keycode, int time) Delegates a key down event to controlled field with focus.
protected boolean	keyRepeat(int keycode, int time) Delegates a key repeat event to controlled field with focus.
protected boolean	keyStatus(int keycode, int time) Delegates a key status event to controlled field with focus.
protected boolean	keyUp(int keycode, int time) Delegates a 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 Screen.onMenu(int) to populate the menu.
protected boolean	navigationClick(int status, int time) Delegates navigational click events.
protected boolean	navigationMovement(int dx, int dy, int status, int time) Invoked when a navigational motion occurs.
protected boolean	navigationUnclick(int status, int time) Delegates navigation unclick events.
boolean	onClose() Indicates that a close event has occurred.
protected void	onDisplay() Deprecated. Use onUiEngineAttached
protected void	onExposed() Invoked when this screen is exposed.
protected void	onFocus(int direction) Finds a controlled field to give the focus.
protected void	onFocusNotify(boolean focus) Called whenever the screen has gained or lost focus.
boolean	onMenu(int instance) Invoked when displaying a menu.
protected void	onMenuDismissed() Deprecated. Use onMenuDismissed(Menu).
protected void	onMenuDismissed(Menu menu) Called when the menu is dismissed.
protected void	onObscured() Invoked when this screen is obscured.
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	onUiEngineAttached(boolean attached) Called whenever the screen is attached or detached from a UiEngine.
protected void	onUndisplay() Deprecated. Use onUiEngineAttached
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.
protected void	paintBackground(Graphics graphics) Paint this screen's background.
void	removeFocus() Removes focus from this screen.
void	removeInputSettings(InputSettings settings) Removes attributes in the specified InputSettings object from this screen.
void	removeKeyListener(KeyListener listener) Removes a key event listener from this screen.
void	removeScreenUiEngineAttachedListener(ScreenUiEngineAttachedListener listener) Removes a ScreenUiEngineAttachedListener event listener from this screen.
void	removeTrackwheelListener(TrackwheelListener listener) Removes a trackwheel event listener from this screen.
void	replace(Field oldField, Field newField) Removes a field from this Screen and replaces it with another field.
void	save() Invoked when the screen should save its contents.
boolean	scroll(int direction) Scrolls the focus in the specified direction.
protected void	setBackdoorAltStatus(boolean altStatus) Sets whether backdoors key sequences use ALT'd or un-ALT'd keystrokes.
void	setContextMenuProvider(ContextMenuProvider contextMenuProvider) Sets the context menu provider.
void	setCursorInputMode(boolean enable) Enables or disables cursor mode.
protected void	setDefaultClose(boolean provideDefaultClose) Controls whether the screen's menu contains a "close" menu item.
void	setDirty(boolean dirty) Cleans or dirties all controlled fields.
void	setFocus() Sets the focus to the delegate manager.
boolean	setFocus(Field field, int x, int y, int status, int time) Sets focus to an exact position on the current screen.
void	setHorizontalQuantization(int horizontalQuanta) Sets the horizontal quantization.
void	setInputHelper(InputHelperBase hlp) Associates an InputHelperBase instance with this screen, to dispatch events to.
protected void	setPositionDelegate(int x, int y) Sets the position of this screen's layout manager (delegate).
void	setServiceMode(ServiceMode serviceMode) Set the current service mode for this screen.
protected void	setServiceModeImpl(ServiceMode serviceMode) Implementation that backs the Screen.setServiceMode(ServiceMode) method, used to set the current service mode for this screen.
void	setTitleBar(TitleBar titleBar) Sets the TitleBar object for this screen.
void	setTrackballFilter(int filter) Sets the trackball filter for this screen.
void	setTrackballSensitivityXOffset(int trackballSensitivityXOffset) Sets the relative trackball sensitivity for the X axis.
void	setTrackballSensitivityYOffset(int trackballSensitivityYOffset) Sets the relative trackball sensitivity for the Y axis.
void	setVerticalQuantization(int verticalQuanta) Sets the vertical quantization.
boolean	suggestServiceMode(ServiceMode serviceMode) Suggests a new service mode for this screen.
protected boolean	touchEvent(TouchEvent message) Handles touch input events.
protected boolean	trackwheelClick(int status, int time) Delegates trackwheel click events.
protected boolean	trackwheelClickUnhandled(int status, int time) Handles trackwheel click event if delegate passes it through.
protected boolean	trackwheelRoll(int amount, int status, int time) Invoked when the trackwheel is rolled.
protected boolean	trackwheelUnclick(int status, int time) Delegates trackwheel unclick events.
void	updateDisplay() Updates the display.

Methods inherited from class net.rim.device.api.ui.Manager

addAll, cursorMovement, deleteAll, getHorizontalScroll, getPreferredHeightOfChild, getPreferredWidthOfChild, getVerticalScroll, getVirtualHeight, getVirtualWidth, insertAll, invalidateFieldRange, isDownArrowShown, isUpArrowShown, isValidLayout, layout, layoutChild, moveFocus, moveFocus, nextFocus, nextFocus, paintChild, setFocus, setPositionChild, setScrollingInertial, setVirtualExtent, shouldCursorScroll, sublayout, subpaint

Methods inherited from class net.rim.device.api.ui.ScrollView

configurationChanged, getHorizontalAdjustment, getVerticalAdjustment, getVisibleHeight, getVisibleWidth, setCurrentLocation, setExtent, setHorizontalAdjustment, setHorizontalScroll, setHorizontalScroll, setScrollListener, setVerticalAdjustment, setVerticalScroll, setVerticalScroll, valueChanged, waitForScrolling

Methods inherited from class net.rim.device.api.ui.Field

drawFocus, drawHighlightRegion, fieldChangeNotify, focusAdd, focusRemove, getBackground, getBackground, getBorder, getBorder, getBorder, getChangeListener, getCommandItemProvider, getContentHeight, getContentLeft, getContentRect, getContentRect, getContentTop, getContentWidth, getContextMenu, getCookie, getExtent, getExtent, getFieldStyle, getFocusListener, getFont, getHeight, getIndex, getLeft, getManager, getMargin, getMarginBottom, getMarginLeft, getMarginRight, getMarginTop, getOriginal, getPadding, getPaddingBottom, getPaddingLeft, getPaddingRight, getPaddingTop, getPreferredHeight, getPreferredWidth, getScreen, getStyle, getTextFillColor, getTextStrokeColor, getTop, getVisualState, getWidth, isEditable, isEnabled, isLeftToRight, isPasteable, isScrollCopyable, isSelectable, isSelectionCopyable, isSelectionCutable, isSelectionDeleteable, isSpellCheckable, isStyle, isVisible, makeContextMenu, onVisibilityChange, paste, select, selectionCopy, selectionCut, selectionDelete, setBackground, setBackground, setBorder, setBorder, setBorder, setBorder, setChangeListener, setCommandItemProvider, setCookie, setEditable, setEnabled, setFocusListener, setFont, setFont, setMargin, setMargin, setMuddy, setNonSpellCheckable, setPadding, setPadding, setPosition, setVisualState, 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 menu includes the following items:

• Close (if DEFAULT_CLOSE style flag is set)
• context menu items for the field that has focus
• any menu items from child screens, check MainScreen.addMenuItem(MenuItem) method for details
• system menu items, such as Switch Application, if NO_SYSTEM_MENU style flag is not set

See Also:

Constant Field Values

Since:

BlackBerry API 3.6.0

DEFAULT_CLOSE

public static final long DEFAULT_CLOSE

If specified, screen will provide a close action.

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

See Also:

Constant Field Values

Since:

BlackBerry API 3.6.0

NO_SYSTEM_MENU_ITEMS

public static final long NO_SYSTEM_MENU_ITEMS

If specified, screen will not have system menu items. The constant should be used in conjunction with DEFAULT_MENU style flag.

See Also:

Constant Field Values

Since:

BlackBerry API 4.7.0

Constructor Detail

Screen

public Screen(Manager delegate)

Constructs a new Screen instance with the provided delegate manager.

Parameters:

delegate - The Manager this screen uses as layout delegate.

Screen

public Screen(Manager delegate,
              long style)

Constructs a new Screen instance with the provided delegate manager and style.

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

Parameters:

delegate - The Manager this screen uses as layout delegate.

style - The style the screen uses for instantiation.

Method Detail

setTitleBar

public void setTitleBar(TitleBar titleBar)

Sets the TitleBar object for this screen.

If a TitleBar object already exists, passing null removes the TitleBar from the Screen. Otherwise, passing null has no effect.

Parameters:

titleBar - A predefined TitleBar object, can be null.

See Also:

StandardTitleBar

Since:

BlackBerry API 6.0.0

getTitleBar

public TitleBar getTitleBar()

Retrieves the current TitleBar object used by this screen.

Returns:

The current TitleBar object, or null if no TitleBar is defined.

Since:

BlackBerry API 6.0.0

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 - The field to add.

addKeyListener

public final void addKeyListener(KeyListener listener)

Registers a key event listener for this screen.

Parameters:

listener - The key event listener to handle key events passed to this screen.

addScreenUiEngineAttachedListener

public void addScreenUiEngineAttachedListener(ScreenUiEngineAttachedListener listener)

Registers a ScreenUiEngineAttachedListener event listener for this screen.

Parameters:

listener - The ScreenUiEngineAttachedListener event listener to register.

Since:

BlackBerry API 4.3.0

addTrackwheelListener

public final void addTrackwheelListener(TrackwheelListener listener)

Registers a trackwheel event listener for this screen.

Parameters:

listener - The trackwheel event listener to handle trackwheel events that are passed to this screen.

close

public void close()

Closes this screen.

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

Since:

BlackBerry API 3.6.0

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 - The field to delete.

deleteRange

public void deleteRange(int start,
                        int count)

Deletes a range of fields from this screen's manager.

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

Overrides:

deleteRange in class Manager

Parameters:

start - The index of the first field to delete.

count - The number of fields to delete.

doPaint

public final void doPaint()

Paints this screen.

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

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 - The field that contains your region.

x - The left edge of the region.

y - The top edge of the region.

width - The width (in pixels) of the region.

height - The height (in pixels) of the region.

getApplication

public Application getApplication()

Retrieves this screen's application.

Returns:

The application object that owns this screen, or null if the screen is not attached to any application.

Since:

BlackBerry API 4.0.0

getDelegate

public Manager getDelegate()

Retrieves this screen's delegate manager.

Returns:

The delegate manager for this screen.

getFieldAtLocation

public int getFieldAtLocation(int x,
                              int y)

Retrieves the index of the field under the provided point.

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

Overrides:

getFieldAtLocation in class Manager

Parameters:

x - The distance from the left edge of the screen's extent.

y - The distance from the top edge of the screen's extent.

Returns:

The index of the field, or -1 if no field is found.

getFocusRect

public void getFocusRect(XYRect rect)

Retrieves the 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 - The XYRect object to receive the retrieved extent data.

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 Screen.invalidate() methods. It may be used for direct drawing to the display when the screen contains no fields.

Returns:

The graphics context for this screen.

getMenu

public Menu getMenu(int instance)

Retrieves the menu.

Parameters:

instance - The instance of the desired menu. If this screen supports only one menu, this may be ignored. By default, it is 0.

Returns:

The menu for this screen.

See Also:

Screen.onMenu(int)

Since:

BlackBerry API 4.0.0

getScreenAbove

public Screen getScreenAbove()
                      throws IllegalArgumentException,
                             IllegalStateException

Retrieves the handle for the local screen above this one.

If there is no screen above this, this method returns null. If the only screen above this is global, this method returns null regardless of whether or not the global screen is active.

Returns:

The screen above this one, or null if there is no screen above this one that is not a global screen.

Throws:

IllegalArgumentException - if this screen is not a local screen.

IllegalStateException - if this screen is not attached to a UiEngine.

Since:

BlackBerry API 4.0.0

getScreenBelow

public Screen getScreenBelow()
                      throws IllegalArgumentException,
                             IllegalStateException

Retrieves the handle for the local screen below this one.

If there is no screen below this, this method returns null. If the only screen below this is global, this method returns null regardless of whether or not the global screen is active.

Returns:

The screen below this one, or null if there is no screen below this one that is not a global screen.

Throws:

IllegalArgumentException - if this screen is not a local screen.

IllegalStateException - if this screen is not attached to a UiEngine.

Since:

BlackBerry API 4.0.0

getUiEngine

public final UiEngine getUiEngine()

Retrieves the UiEngine that owns this screen.

Returns:

The UiEngine that owns this screen.

Since:

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

isDataValid

public boolean isDataValid()

Computes and returns whether or not the data on this screen is valid.

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

Overrides:

isDataValid in class Manager

Returns:

true if the data of all fields on this screen is valid, false if the data of at least one field on this screen is not valid.

See Also:

Manager.isDataValid(), Screen.getDelegate()

Since:

BlackBerry API 4.2.0

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 Screen.setDirty(boolean) was invoked (which is also passed on to the delegate manager), false otherwise.

See Also:

Field.isMuddy(), Field.setDirty(boolean)

isDisplayed

public final boolean isDisplayed()

Determines if this screen is currently in use.

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

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

Returns:

true if the screen is currently on a display stack (even if not currently visible), false otherwise.

isFocus

public boolean isFocus()

Determines if this screen currently has the focus.

Overrides:

isFocus in class Field

Returns:

true if this screen has the focus, false otherwise.

Since:

BlackBerry API 4.7.0

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 the delegate manager accepts the focus, false otherwise.

isGlobal

public boolean isGlobal()

Determines if this is a global screen.

A global screen is one that appears over other applications.

Returns:

true if this screen is attached to a UiEngine as a global screen, false otherwise.

Since:

BlackBerry API 4.2.0

isGlobalStatus

public boolean isGlobalStatus()

Deprecated. Use isGlobal()

isMuddy

public boolean isMuddy()

Determines if this screen is muddy.

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

Overrides:

isMuddy in class Manager

Returns:

true if a controlled field has changed and the focus has not been moved or left the field since the change, false otherwise.

See Also:

Field.isDirty(), Field.setMuddy(boolean)

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, false otherwise.

See Also:

Field.select(boolean)

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 - The field to insert.

index - The position in the manager's list of controlled fields at which to insert the new field.

invokeAction

protected boolean invokeAction(int action)

Invokes an action on this screen.

First invokeAction(action) is invoked on the object returned from Screen.getDelegate(). If Manager.invokeAction(int) returns true then true is returned. Otherwise, the following logic is performed:

1. If action is not Field.ACTION_INVOKE then false is returned.
2. If Screen.getLeafFieldWithFocus() returns null then false is returned.
3. Otherwise, some selection logic is performed on the leaf field with focus, and true is returned.

Overrides:

invokeAction in class Manager

Parameters:

action - The action to be performed, as described above.

Returns:

true if the action was consumed, false if the action was not consumed.

Since:

BlackBerry API 4.2.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:

The default menu item.

Since:

BlackBerry API 4.0.0

invalidate

public void invalidate()

Invalidates the entire screen.

This method marks the entire screen as requiring a repaint. The main event dispatch thread handles the repaint at a later time.

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

Overrides:

invalidate in class Manager

See Also:

Field.invalidate()

Since:

BlackBerry API 4.0.0

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 - The left edge of the region in ContentRect coordinates.

y - The top edge of the region in ContentRect coordinates.

width - The width (in pixels) of the region.

height - The height (in pixels) of the region.

See Also:

Field.invalidate(int,int,int,int)

invalidateAll

public void invalidateAll(int x,
                          int y,
                          int width,
                          int height)

Invalidates a region of this screen.

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

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

Overrides:

invalidateAll in class Field

Parameters:

x - The left edge of the region in field coordinates.

y - The top edge of the region in field coordinates.

width - The width (in pixels) of the region.

height - The height (in pixels) of the region.

See Also:

Field.invalidate(int,int,int,int)

Since:

BlackBerry API 4.2.0

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 - The backdoor code to open.

Returns:

false.

Since:

BlackBerry API 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 - The backdoor code to open.

Returns:

false.

Since:

BlackBerry API 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 - The character that was generated.

status - The modifier key status.

time - The number of milliseconds since the device was turned on.

Returns:

true if the event was consumed, false otherwise.

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 - The character that was generated.

status - The modifier key status.

time - The number of milliseconds since the device was turned on.

Returns:

true if the key provided was the ESCAPE key and this screen closed, false otherwise.

keyControl

protected boolean keyControl(char c,
                             int status,
                             int time)

Delegates a 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 - The character that was generated.

status - The modifier key status.

time - The number of milliseconds since the device was turned on.

Returns:

true if the event was consumed, false otherwise.

keyDown

protected boolean keyDown(int keycode,
                          int time)

Delegates a 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 - The key scan code of the key that was pressed, ignoring any effects of modifier keys.

time - The number of milliseconds since the device was turned on.

Returns:

true if the event was consumed, false otherwise.

keyUp

protected boolean keyUp(int keycode,
                        int time)

Delegates a 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 - The key scan code of the key that was released, ignoring any effects of modifier keys.

time - The number of milliseconds since the device was turned on.

Returns:

true if the event was consumed, false otherwise.

keyRepeat

protected boolean keyRepeat(int keycode,
                            int time)

Delegates a 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 - The key scan code of the key that was repeated, ignoring any effects of modifier keys.

time - The number of milliseconds since the device was turned on.

Returns:

true if the event was consumed, false otherwise.

keyStatus

protected boolean keyStatus(int keycode,
                            int time)

Delegates a 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 - The key scan code of character shown, before any effects of modifier keys.

time - The number of milliseconds since the device was turned on.

Returns:

true if the event was consumed, false otherwise.

setInputHelper

public void setInputHelper(InputHelperBase hlp)

Associates an InputHelperBase instance with this screen, to dispatch events to.

Parameters:

hlp - The InputHelperBase instance to associate with this screen.

Since:

BlackBerry API 6.0.0

getInputHelper

public InputHelperBase getInputHelper()

Gets the InputHelperBase instance associated with this screen.

Returns:

The InputHelperBase instance associated with this screen.

Since:

BlackBerry API 6.0.0

layoutDelegate

protected final void layoutDelegate(int width,
                                    int height)

Lays out this screen's delegate.

Parameters:

width - The amount of available horizontal space.

height - The amount of available vertical space.

makeMenu

protected void makeMenu(Menu menu,
                        int instance)

Called from Screen.onMenu(int) to populate the menu.

Overrides:

makeMenu in class Manager

Parameters:

menu - The 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:

BlackBerry API 3.6.0

onClose

public boolean onClose()

Indicates that a close event has occurred.

By setting the Screen.DEFAULT_CLOSE style for this screen, you use the default closing behaviour (if the screen is dirty, the framework calls Screen.onSavePrompt() to verify with the user that closing the screen is OK, and then calls Screen.close() if successful).

Returns:

true if the screen closes, false otherwise.

Since:

BlackBerry API 3.6.0

onDisplay

protected void onDisplay()

Deprecated. Use onUiEngineAttached

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 focused region stays on the screen).

The complementary callback is Screen.onUndisplay().

Overrides:

onDisplay in class Field

onExposed

protected void onExposed()

Invoked when this screen is exposed. A Screen is exposed when it becomes the topmost by means of:

1. a screen is popped off the display stack (since 3.0)
2. a global screen is popped (since 4.0)
3. this screen's application receives foreground (since 4.2)
4. this screen is pushed and it is deemed exposed by the above rules (since 4.2)

Subclasses of screen should override this method for special handling.

The complementing callback is Screen.onObscured().

Overrides:

onExposed in class Manager

See Also:

Screen.onUiEngineAttached(boolean), 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 forward. If -1, start at the bottom of the delegate manager's field list and search backward.

onFocusNotify

protected void onFocusNotify(boolean focus)

Called whenever the screen has gained or lost focus.

Parameters:

focus - true if this screen has gained the focus, false if this screen has lost focus.

Since:

BlackBerry API 4.2.0

onMenu

public boolean onMenu(int instance)

Invoked when displaying a menu.

If you set the Screen.DEFAULT_MENU style, this method creates a menu and adds a context menu.

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

If you set the Menu.MENU_POPUP style, this method creates and displays a popup menu.

Parameters:

instance - The 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, false otherwise.

Since:

BlackBerry API 3.6.0

onMenuDismissed

protected void onMenuDismissed(Menu menu)

Called when the menu is dismissed.

This method calls onMenuDismissed(Menu) on all the fields and managers that are currently in focus. It also calls onMenuDismissed().

Overrides:

onMenuDismissed in class Field

Parameters:

menu - The menu to be dismissed.

Since:

BlackBerry API 4.2.0

onMenuDismissed

protected void onMenuDismissed()

Deprecated. Use onMenuDismissed(Menu).

Called when the menu is dismissed.

Overrides:

onMenuDismissed in class Field

Since:

BlackBerry API 4.0.2

onObscured

protected void onObscured()

Invoked when this screen is obscured. A screen is considered obscured when it was the topmost screen and no longer is because of one of these reasons:

1. a new screen pushed on the display stack (since 3.0)
2. a global screen is displayed above this screen (since 4.0)
3. this screen's application goes into the background (since 4.2)
4. this screen is pushed and it is deemed obscured by the above rules (since 4.2)

Derived classes should override this method for special handling.

The complementing callback is Screen.onExposed().

Overrides:

onObscured in class Field

See Also:

Screen.onUiEngineAttached(boolean), Field.onVisibilityChange(boolean)

onSave

protected boolean onSave()

Invoked when the screen should save its contents.

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

Returns:

true if the save was successful, false otherwise.

Since:

BlackBerry API 3.6.0

onSavePrompt

protected boolean onSavePrompt()

Invoked when the screen should prompt to save its contents.

Overriding classes should provide a dialog and call Screen.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, false otherwise.

See Also:

MainScreen.onSavePrompt()

Since:

BlackBerry API 3.6.0

onUndisplay

protected void onUndisplay()

Deprecated. Use onUiEngineAttached

Invoked when this screen is popped off the display stack.

Derived classes should override this method for special handling.

The complementing callback is Screen.onDisplay().

Overrides:

onUndisplay in class Field

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

onUiEngineAttached

protected void onUiEngineAttached(boolean attached)

Called whenever the screen is attached or detached from a UiEngine.

Replaces Screen.onDisplay() and Screen.onUndisplay().

Parameters:

attached - If true the event is an attach event, if false the event is a detach event.

See Also:

Screen.onExposed(), Screen.onFocusNotify(boolean)

Since:

BlackBerry API 4.3.0

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 - The graphics context used for painting.

paintBackground

protected void paintBackground(Graphics graphics)

Paint this screen's background.

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

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

Overrides:

paintBackground in class Field

Parameters:

graphics - The graphics context used to draw the background.

replace

public void replace(Field oldField,
                    Field newField)

Removes a field from this Screen and replaces it with another field.

This method simply invokes replace(oldField, newField) on the Manager returned from Screen.getDelegate().

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

Overrides:

replace in class Manager

Parameters:

oldField - The field to be replaced.

newField - The field to replace it.

See Also:

Manager.delete(Field), Manager.insert(Field, int), Field.getIndex(), Field.getManager(), Field.setFocus()

Since:

BlackBerry API 4.2.0

save

public void save()
          throws IOException

Invoked when the screen should save its contents.

Throws:

IOException

Since:

BlackBerry API 3.6.0

addInputSettings

public void addInputSettings(InputSettings settings)

Applies attributes in the specified InputSettings object to this screen.

May be invoked multiple times to apply additional input settings. Does nothing if this screen does not accept input and/or the specified InputSettings object is not associated with a supported input device. Note that the settings are applied when this screen gains focus or immediately if already in focus. Note also that this only *adds* settings. If a particular setting is omitted from the InputSettings list it is not removed/reverted. To remove one or more settings (reverting them to defaults), use Screen.removeInputSettings(net.rim.device.api.ui.input.InputSettings).

Parameters:

settings - The InputSettings object to be applied to this screen.

Throws:

IllegalArgumentException - if settings is null or associated with an unrecognized input device (see net.rim.device.api.ui.input for a list of available (recognized) input devices.

Since:

BlackBerry API 6.0.0

removeInputSettings

public void removeInputSettings(InputSettings settings)

Removes attributes in the specified InputSettings object from this screen.

May be invoked multiple times to remove input settings. Does nothing if this screen does not accept input and/or the specified attributes do not exist or InputSettings object is not associated with a supported input device. Note that the updated settings are applied when this screen gains focus or immediately if already in focus.

Parameters:

settings - The InputSettings object to be removed from this screen.

Throws:

IllegalArgumentException - if settings is null or associated with an unrecognized input device (see net.rim.device.api.ui.input for a list of available (recognized) input devices.

Since:

BlackBerry API 6.0.0

clearInputSettings

public void clearInputSettings()

Removes all custom input settings for this screen and revert to defaults.

Does nothing if this screen does not accept input and/or no custom input settings exist. Note that default settings are applied when this screen gains focus or immediately if already in focus.

Since:

BlackBerry API 6.0.0

getInputSettings

public void getInputSettings(InputSettings settings)

Retrieves the values for the attributes in the specified InputSettings object for this screen.

The values can be obtained by invoking InputSettings.get(int) once the method returns. Does nothing if this screen does not accept input and/or the specified attributes do not exist or InputSettings object is not associated with a supported input device.

Parameters:

settings - The InputSettings object to be populated with values.

Throws:

IllegalArgumentException - if settings is null or associated with an unrecognized input device (see net.rim.device.api.ui.input for a list of available (recognized) input devices.

Since:

BlackBerry API 6.0.0

removeFocus

public void removeFocus()

Removes focus from this screen.

Overrides:

removeFocus in class Manager

setBackdoorAltStatus

protected void setBackdoorAltStatus(boolean altStatus)

Sets whether backdoors key sequences use ALT'd or un-ALT'd keystrokes.

Parameters:

altStatus - If true ALT key sequences are required, if false un-ALT'd keystrokes can be used as backdoors.

Since:

BlackBerry API 4.0.2

setDefaultClose

protected void setDefaultClose(boolean provideDefaultClose)

Controls whether the screen's menu contains a "close" menu item.

Parameters:

provideDefaultClose - If true the menu includes a close item, if false the menu does not include a close item.

Since:

BlackBerry API 4.0.2

getVirtualKeyboard

public final VirtualKeyboard getVirtualKeyboard()

Retrieves the VirtualKeyboard object associated with this screen.

Returns:

A VirtualKeyboard object containing properties such as visibility, or null on non-touchscreen devices.

Since:

BlackBerry API 4.7.0

navigationClick

protected boolean navigationClick(int status,
                                  int time)

Delegates navigational click events.

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

One scenario that calls this method is when a Screen object is pushed to an application and a Navigation event is injected into the same application. When this scenario occurs, this method is called using 0 for the time parameter.

Overrides:

navigationClick in class Manager

Parameters:

status - The state of the modifier keys.

time - The number of milliseconds since the device was turned on.

Returns:

true if the delegate manager consumed the event, false otherwise.

Since:

BlackBerry API 4.2.0

navigationMovement

protected boolean navigationMovement(int dx,
                                     int dy,
                                     int status,
                                     int time)

Invoked when a navigational motion occurs.

The source of the navigation event can be determined by checking the KeypadListener.STATUS_TRACKWHEEL and KeypadListener.STATUS_FOUR_WAY bits in the status parameter; exactly one of these will be set.

One scenario that calls this method is when a Screen object is pushed to an application and a Navigation event is injected into the same application. When this scenario occurs, this method is called using 0 for the time parameter.

Overrides:

navigationMovement in class Manager

Parameters:

dx - The magnitude of navigational motion: negative for a move left and positive for a move right.

dy - The magnitude of navigational motion: negative for an upwards move, and positive for a downwards move.

status - The modifier key status at the time of the move.

time - The number of milliseconds since the device was turned on.

Returns:

true if the event was consumed, false otherwise.

Since:

BlackBerry API 4.2.0

cursorClick

protected boolean cursorClick(int x,
                              int y,
                              int status,
                              int time)

Delegates cursor click events.

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

Overrides:

cursorClick in class Manager

Parameters:

x - X coordinate of the event.

y - Y coordinate of the event.

status - State of the modifier keys.

time - Number of milliseconds since the device was turned on.

Returns:

True if this method consumed the event; otherwise, false.

Since:

BlackBerry API 7.0.0

cursorUnclick

protected boolean cursorUnclick(int x,
                                int y,
                                int status,
                                int time)

Delegates cursor unclick events.

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

Overrides:

cursorUnclick in class Manager

Parameters:

x - X coordinate of the event.

y - Y coordinate of the event.

status - State of the modifier keys.

time - Number of milliseconds since the device was turned on.

Returns:

True if this method consumed the event; otherwise, false.

Since:

BlackBerry API 7.0.0

navigationUnclick

protected boolean navigationUnclick(int status,
                                    int time)

Delegates navigation unclick events.

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

One scenario that calls this method is when a Screen object is pushed to an application and a Navigation event is injected into the same application. When this scenario occurs, this method is called using 0 for the time parameter.

Overrides:

navigationUnclick in class Manager

Parameters:

status - The state of the modifier keys.

time - The number of milliseconds since the device was turned on.

Returns:

true if the delegate manager consumed the event, false otherwise.

Since:

BlackBerry API 4.2.0

trackwheelClick

protected boolean trackwheelClick(int status,
                                  int time)

Delegates trackwheel click events.

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

Overrides:

trackwheelClick in class Manager

Parameters:

status - The state of the modifier keys.

time - The number of milliseconds since the device was turned on.

Returns:

true if the delegate manager consumed the event, false otherwise.

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 Screen.trackwheelClick(int, int).

Parameters:

status - The modifier key status (currently ignored).

time - The number of milliseconds since the device was turned on (currently ignored).

Returns:

true if the event was consumed, false otherwise.

Since:

BlackBerry API 3.6.0

trackwheelRoll

protected boolean trackwheelRoll(int amount,
                                 int status,
                                 int time)

Invoked when the trackwheel is rolled.

Overrides:

trackwheelRoll in class Manager

Parameters:

amount - The number of scrolling positions: negative for an upwards roll, and positive for a downwards roll.

status - The modifier key status at the time of the roll.

time - The number of milliseconds since the device was turned on.

Returns:

true if the event was consumed, false otherwise.

trackwheelUnclick

protected boolean trackwheelUnclick(int status,
                                    int time)

Delegates trackwheel unclick events.

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

Overrides:

trackwheelUnclick in class Manager

Parameters:

status - The state of the modifier keys.

time - The number of milliseconds since the device was turned on.

Returns:

true if the delegate manager consumed the event, false otherwise.

touchEvent

protected boolean touchEvent(TouchEvent message)

Handles touch input events.

The message parameter contains various input parameters including the event type and touch coordinates. The coordinates reflect the location of the touch event with respect to this screen. The x-y coordinates are then further mapped to the top-left corner of the delegate.

Overrides:

touchEvent in class Manager

Parameters:

message - The TouchEvent object containing various input parameters, including the event type and touch coordinates.

Returns:

true if the event was consumed, false otherwise.

Throws:

IllegalArgumentException - if message is null.

Since:

BlackBerry API 4.7.0

setContextMenuProvider

public final void setContextMenuProvider(ContextMenuProvider contextMenuProvider)

Sets the context menu provider.

You can use this method to specify a context menu provider that this screen should use to build and display a pop-up menu. You can pass in a DefaultContextMenuProvider to get a default implementation of a pop-up menu. If you don't use this method to set a context menu provider (or provide null to this method), this screen uses the legacy context menu to build a pop-up menu.

See DefaultContextMenuProvider for more information on pop-up menus and how legacy context menus are supported.

Parameters:

contextMenuProvider - The context menu provider that this screen should use to build a pop-up menu, or null to use the legacy context menu support.

Since:

BlackBerry API 6.0.0

getContextMenuProvider

public final ContextMenuProvider getContextMenuProvider()

Returns the context menu provider.

Returns:

The current context menu provider, or null if it is not currently set.

Since:

BlackBerry API 6.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:

The number of fields controlled by the delegate manager.

getField

public Field getField(int index)

Retrieves the controlled field with the 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 - The index of the field to retrieve.

Returns:

The controlled field at the specified index.

Throws:

IndexOutOfBoundsException - if index is not valid.

getFieldWithFocus

public Field getFieldWithFocus()

Retrieves the controlled field with focus.

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

Overrides:

getFieldWithFocus in class Manager

Returns:

The controlled field with focus, or null if no field has the focus.

See Also:

Manager.getLeafFieldWithFocus()

getFieldWithFocusIndex

public int getFieldWithFocusIndex()

Retrieves the index of the controlled field with focus.

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

Overrides:

getFieldWithFocusIndex in class Manager

Returns:

The index of the controlled field with focus, or -1 if no field has the focus.

getLeafFieldWithFocus

public Field getLeafFieldWithFocus()

Retrieves the leaf field with focus.

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

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

Overrides:

getLeafFieldWithFocus in class Manager

Returns:

The controlled leaf field with focus, or null if no field has the focus.

See Also:

Manager.getFieldWithFocus()

removeKeyListener

public final void removeKeyListener(KeyListener listener)

Removes a key event listener from this screen.

Parameters:

listener - The key event listener to remove from this screen.

removeScreenUiEngineAttachedListener

public final void removeScreenUiEngineAttachedListener(ScreenUiEngineAttachedListener listener)

Removes a ScreenUiEngineAttachedListener event listener from this screen.

Parameters:

listener - The ScreenUiEngineAttachedListener event listener to remove from this screen.

Since:

BlackBerry API 4.3.0

removeTrackwheelListener

public final void removeTrackwheelListener(TrackwheelListener listener)

Removes a trackwheel event listener from this screen.

Parameters:

listener - The trackwheel event listener to remove from this screen.

scroll

public final boolean scroll(int direction)

Scrolls the focus in the 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 - A combination of constant values to indicate in which direction, and how much, the focus is to move.

Returns:

true.

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 - If true the fields will be dirtied, if false the fields will be cleaned.

See Also:

Field.isDirty(), Field.setMuddy(boolean)

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

Overrides:

setFocus in class Field

setFocus

public final boolean setFocus(Field field,
                              int x,
                              int y,
                              int status,
                              int time)

Sets focus to an exact position on the current screen.

Parameters:

field - The field in which to place the focus.

x - The distance from the left edge of the screen.

y - The distance from the top edge of the screen.

status - The state of modifier keys.

time - The number of milliseconds since the device was turned on.

Returns:

true if the field under the desired point accepts the focus, false otherwise.

Throws:

IllegalArgumentException - if field does not belong to this screen.

setCursorInputMode

public void setCursorInputMode(boolean enable)

Enables or disables cursor mode.

Cursor mode is an alternative to focus-based touchpad navigation.

In order to process cursor events fields should implement cursor related methods such as Field.cursorClick(int, int, int, int), Field.cursorUnclick(int, int, int, int), etc.

Note. Some components may not work as expected in cursor mode.

Parameters:

enable - True to enable cursor input mode; false to disable.

Since:

BlackBerry API 7.1.0

setHorizontalQuantization

public void setHorizontalQuantization(int horizontalQuanta)

Sets the horizontal quantization.

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

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

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

Overrides:

setHorizontalQuantization in class Manager

Parameters:

horizontalQuanta - The horizontal quantization (in pixels).

See Also:

Screen.setVerticalQuantization(int)

setPositionDelegate

protected final void setPositionDelegate(int x,
                                         int y)

Sets the position of this screen's layout manager (delegate).

Parameters:

x - The left edge position for this screen's delegate.

y - The top edge position for this screen's delegate.

setTrackballFilter

public void setTrackballFilter(int filter)

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

Parameters:

filter - A bitmask of the Trackball.FILTER_* constants.

Throws:

IllegalArgumentException - if filter is not a valid value, as described above.

Since:

BlackBerry API 4.2.0

setTrackballSensitivityXOffset

public void setTrackballSensitivityXOffset(int trackballSensitivityXOffset)

Sets the relative trackball sensitivity for the X axis.

If your provided sensitivity offset value is Integer.MAX_VALUE, then it is treated as unset. Otherwise, the value is added to the user-set sensitivity when this screen has the focus.

Parameters:

trackballSensitivityXOffset - The relative trackball sensitivity for the X axis, ranging from -100 to 100, or Trackball.SENSITIVITY_UNSET.

Throws:

IllegalArgumentException - if trackballSensitivityXOffset is not in the range of -100 to 100 or Integer.MAX_VALUE.

Since:

BlackBerry API 4.2.0

setTrackballSensitivityYOffset

public void setTrackballSensitivityYOffset(int trackballSensitivityYOffset)

Sets the relative trackball sensitivity for the Y axis. If your provided sensitivity offset value is Integer.MAX_VALUE, then it is treated as unset. Otherwise, the value is added to the user-set sensitivity when this screen has the focus.

Parameters:

trackballSensitivityYOffset - The relative trackball sensitivity for the Y axis, ranging from -100 to 100 or Trackball.SENSITIVITY_UNSET.

Throws:

IllegalArgumentException - if trackballSensitivityYOffset is not in the range of -100 to 100 or Integer.MAX_VALUE.

Since:

BlackBerry API 4.2.0

setVerticalQuantization

public void setVerticalQuantization(int verticalQuanta)

Sets the vertical quantization.

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

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

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

Overrides:

setVerticalQuantization in class Manager

Parameters:

verticalQuanta - The vertical quantization (in pixels).

See Also:

Screen.setHorizontalQuantization(int)

updateDisplay

public final void updateDisplay()

Updates the display.

getAccessibleContext

public AccessibleContext getAccessibleContext()

Gets the accessible representation of the field for a screen reader.

Overrides:

getAccessibleContext in class Manager

Returns:

An AccessibleContext instance that represents the field for a screen reader.

Since:

BlackBerry API 4.6.1

getServiceMode

public ServiceMode getServiceMode()

Gets the current service mode for this screen.

The return value should be a service mode that is representative of the data currently being managed by the screen. If a screen can manage data from multiple services and is currently in a state for which an appropriate service cannot be determined then the service mode should reflect this.

Classes that extend Screen should override this method to provide the desired implementation. By default this method will return null.

Returns:

The current service mode for this screen, may be null.

Since:

BlackBerry API 7.0.0

setServiceMode

public final void setServiceMode(ServiceMode serviceMode)

Set the current service mode for this screen.

This method is used to change the current service mode for a screen. When this method is called the screen must change its current service mode to the new specified service mode.

Note that the screen's service mode can only be modified by a core platform module or a module that the owning application explicitly depends on.

Parameters:

serviceMode - The new service mode for this screen, may be null.

Throws:

ControlledAccessException - if the caller is not allowed to modify this screen's service mode.

See Also:

Screen.setServiceModeImpl(ServiceMode)

Since:

BlackBerry API 7.0.0

setServiceModeImpl

protected void setServiceModeImpl(ServiceMode serviceMode)

Implementation that backs the Screen.setServiceMode(ServiceMode) method, used to set the current service mode for this screen.

Classes that extend Screen should override this method to provide the desired implementation of the setServiceMode(ServiceMode) method.

Parameters:

serviceMode - The new service mode for this screen, may be null.

See Also:

Screen.setServiceMode(ServiceMode)

Since:

BlackBerry API 7.0.0

suggestServiceMode

public boolean suggestServiceMode(ServiceMode serviceMode)

Suggests a new service mode for this screen.

Use this method to suggest to a screen a more appropriate service mode for this screen to operate in. This can happen as a result of data being passed to the screen from an external source that is associated with another service. As part of passing this data a suggestion to operate in the mode associated the data may be made.

Note that the screen does not need to always accept the suggested service mode. It is acceptable for the screen to reject suggestions.

Classes that extend Screen should override this method to provide the desired implementation. The default behavior is to reject all suggestions.

Parameters:

serviceMode - The new service mode being suggested for this screen, may be null.

Returns:

true if the new mode was accepted, false otherwise.

Since:

BlackBerry API 7.0.0