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.
*
Registers a trackwheel event listener for this screen.
Parameters:
listener - Trackwheel event listener to handle trackwheel events
pass to this screen.
close
public void close()
Closes this screen.
By default, this method pops this screen, and if the
screen stack is empty, invokes
System.exit(0). Derived classes can override this
method to provide more particular functionality.
Since:
JDE 3.6.0
Category:
Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.
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.
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.
public void ensureRegionVisible(Field field,
int x,
int y,
int width,
int height)
Attempts to make your provided region visible.
Pass this method a field, and a region (extent), and this method
attempts to scroll the screen to make as much of your region visible as
possible.
If your region is smaller than the screen's visible extent, this
method does as little work as possible to ensure the entire region
appears on the screen.
If your region is larger than the screen's visible extent, this
method produces the net effect of aligning the top left corner of your
region with the top left corner of the screen's visible extent.
Parameters:
field - Field that contains your region.
x - Left edge of the region.
y - Top edge of the region.
width - Width (in pixels) of the region.
height - Height (in pixels) of the region.
Category:
Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.
This will return true iff this screen is on a display stack. Its
position within the stack does not matter; this function does not
indicate visibility. A screen is deemed displayed as soon as it is pushed
onto the display stack, and not displayed as soon as it is popped from
the display stack.
For Global Screens, this indicates whether this screen is the
current one displayed. Any Global Screen that has been queued or that has
had its display preempted by a higher priority Global Screen is deemed not
displayed.
Returns:
True if the screen is currently being displayed; otherwise, false.
isFocusable
public boolean isFocusable()
Verifies that the delegate manager accepts the focus.
This method invokes Manager.isFocusable() on this screen's
delegate manager to determine whether the delegate manager (and thus the
screen) accepts the focus.
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.
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.
index - Position in manager's list of controlled fields at which to
insert new field.
invokeAction
protected boolean invokeAction(int action)
Invokes an action on this screen. First invokeAction(action) is invoked on the
object returned from getDelegate(). If Manager.invokeAction(int) returns
true then true is returned. Otherwise, the following logic is performed:
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.
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).
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.
direction - If 1, start at the top of the delegate manager's field
list and search foward. If -1, start at the bottom of the delegate
manager's field list and search backward.
Category:
Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.
onFocusNotify
protected void onFocusNotify(boolean focus)
Called whenever the screen has gained or lost focus.
Parameters:
focus - true if this screen has gained the focus or false if this screen has lost focus.
Since:
JDE 4.2.0
Category:
Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.
onMenu
public boolean onMenu(int instance)
Invoked when a menu needs displaying.
If you specify the DEFAULT_MENU style, this method creates a
menu and call #makeMenuWithContext(Menu,int).
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().
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.
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.
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.
graphics - Graphics context used to draw the background.
Category:
Framework: This element may be called by the underlying framework. Members that are invoked by the framework may not behave exactly as documented.
replace
public void replace(Field oldField,
Field newField)
Removes a field from this Screen and replaces it with another field.
This method simply invokes replace(oldField, newField) on the Manager
returned from getDelegate().
See Manager.replace(Field, Field) for more details about how this method behaves,
including exceptions that can be thrown.
This method controls whether the screen's menu contains a "close" menu item.
For example,if you pass in a value of false, the menu will not include a "close" item
Parameters:
provideDefaultClose - Flag for specifying if menu
is to include a close item
Since:
JDE 4.0.2
navigationClick
protected boolean navigationClick(int status,
int time)
Retrieves leaf field with focus. A Screen may manage several fields, each of
which may manage several other fields. A leaf field is a field that does not manage
any other fields. Use this method to figure out which leaf field (which is managed by
one of the managed components) has the focus.
This method invokes Manager.getLeafFieldWithFocus() on this
screen's delegate manager to retrieve the (bottom-most, non-manager) leaf
field that has the focus.
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.
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.
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.
horizontalQuanta - Horizontal quantization in pixels.
setPositionDelegate
protected final void setPositionDelegate(int x,
int y)
Set the position of this screen's layout manager (delegate).
Parameters:
x - Left edge position for this screen's delegate.
y - Top edge position for this screen's delegate.
setTrackballFilter
public void setTrackballFilter(int filter)
Sets the trackball filter for this Screen.
Parameters:
filter - -100 to 100 or Integer.MAX_VALUE
Throws:
IllegalArgumentException - if trackballSensitivityXOffset is not -100 to 100 or Integer.MAX_VALUE.
Since:
JDE 4.2.0
setTrackballSensitivityXOffset
public void setTrackballSensitivityXOffset(int trackballSensitivityXOffset)
Sets the relative trackball sensitivity for the X axis.
If the value is Integer.MAX_VALUE, then it is treated as unset. Otherwise, the value is added
to the user set sensitivity when this Screen has focus.
Parameters:
trackballSensitivityXOffset - -100 to 100 or Trackball.SENSITIVITY_UNSET
Throws:
IllegalArgumentException - if trackballSensitivityXOffset is not -100 to 100 or Integer.MAX_VALUE.
Since:
JDE 4.2.0
setTrackballSensitivityYOffset
public void setTrackballSensitivityYOffset(int trackballSensitivityYOffset)
Sets the relative trackball sensitivity for the X axis.
If the value is Integer.MAX_VALUE, then it is treated as unset. Otherwise, the value is added
to the user set sensitivity when this Screen has focus.
Parameters:
trackballSensitivityXOffset - -100 to 100 or Trackball.SENSITIVITY_UNSET
Throws:
IllegalArgumentException - if trackballSensitivityXOffset is not -100 to 100 or Integer.MAX_VALUE.
Since:
JDE 4.2.0
setVerticalQuantization
public void setVerticalQuantization(int verticalQuanta)
Sets the vertical quantization.
When a screen's layout manager or delegate is laying out components on the screen, the layout manager
uses the vertical quantization to determine how many columns can be fully displayed.
By default, the delegate uses the font size as the vertical quantization value.
The actual vertical display length will be a multiple of the value you specify.
Copyright 1999-2006 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved. Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. Copyright 2002-2003 Nokia Corporation All Rights Reserved. Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
