|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectnet.rim.device.api.ui.Field
net.rim.device.api.ui.Manager
public abstract class Manager
Provides fundamental functionality for all field managers.
Manager objects are used to contain fields. The various manager subclasses handle specific kinds of field layout. This Manager class itself deals with scrolling.
Implementing your own layout manager
If you have particular needs, you can implement your own manager. Extend the
Manager class, and implement
sublayout
,
getPreferredWidth
, and
getPreferredHeight
.
For efficiency, you may optionally override subpaint
.
The framework invokes sublayout
, prompting your manager to lay out the
controlled fields appropriately. For each field within this Manager, invoke
layoutChild
, which will call layout
for the field, and
setPositionChild
, which will call setPosition
for the field.
This will let each controlled field determine the size it requires.
subpaint
iterates through controlled fields,
instructing each to paint itself. You can optimize subpaint
by using details of the layout to determine which fields are in the current
visible region and skipping non-visible ones.
To paint a controlled field, invoke paintchild
.
Styles
The Manager class does not accept Field.FOCUSABLE_MASK
,
Field.EDITABLE_MASK
.
Field Summary | ||
---|---|---|
static int |
BOTTOMMOST
Indicates scrolling all the way to the bottom of the manager. |
|
static int |
DOWNWARD
Indicates downward scroll direction. |
|
static long |
HORIZONTAL_SCROLL
Manager style to turn on horizontal scrolling. |
|
static long |
HORIZONTAL_SCROLLBAR
Manager style to turn on horizontal scrollbars. |
|
protected static long |
HORIZONTAL_SCROLLBAR_MASK
Bitfield mask of the horizontal scrollbar style specifiers. |
|
protected static long |
HORIZONTAL_SCROLL_MASK
Bitfield mask of the horizontal scroll style specifiers. |
|
static long |
LEAVE_BLANK_SPACE
Manager style that leave blank space intact. |
|
static int |
LEFTMOST
Indicates scrolling all the way to the left of the manager. |
|
static int |
LEFTWARD
Indicates scroll direction is to the left. |
|
static long |
NO_HORIZONTAL_SCROLL
Manager will not support horizontal scrolling. |
|
static long |
NO_HORIZONTAL_SCROLLBAR
Manager will not show horizontal scrollbars. |
|
static long |
NO_SCROLL_RESET
Manager style to turn off resetting of scroll value when we leave the manager. |
|
static long |
NO_VERTICAL_SCROLL
Manager will not support vertical scrolling. |
|
static long |
NO_VERTICAL_SCROLLBAR
Manager will not show vertical scrollbars. |
|
static int |
QUANTA_FONT
Indicates that the size of a quanta should be adjusted to the size of the current font on layout. |
|
static int |
RIGHTMOST
Indicates scrolling all the way to the right of the manager. |
|
static int |
RIGHTWARD
Indicates scroll direction is to the right. |
|
static int |
TOPMOST
Indicates scrolling all the way to the top of the manager. |
|
static int |
UPWARD
Indicates upward scroll direction. |
|
static long |
VERTICAL_SCROLL
Manager style to turn on vertical scrolling. |
|
static long |
VERTICAL_SCROLLBAR
Manager style to turn on vertical scrollbars. |
|
protected static long |
VERTICAL_SCROLLBAR_MASK
Bitfield mask of the vertical scrollbar style specifiers. |
|
protected static long |
VERTICAL_SCROLL_MASK
Bitfield mask of the vertical scroll style specifiers. |
Constructor Summary | ||
---|---|---|
protected |
Manager(long style)
Constructs a manager. |
Method Summary | ||
---|---|---|
void |
add(Field field)
Adds a field to this manager. |
|
void |
addAll(Field[] fields)
Adds an array of fields to this manager. |
|
void |
delete(Field field)
Removes a field from this manager. |
|
void |
deleteAll()
Removes all fields from this manager. |
|
void |
deleteRange(int start,
int count)
Removes a range of fields from this manager. |
|
AccessibleContext |
getAccessibleContext()
Returns accessible representation of the field for a screen reader |
|
Field |
getField(int index)
Retrieves controlled field with specified index. |
|
int |
getFieldAtLocation(int x,
int y)
Retrieves index of field under a particular point. |
|
int |
getFieldCount()
Retrieves number of fields controlled by this manager. |
|
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. |
|
int |
getHorizontalScroll()
Returns current horizontal offset of scrolling region. |
|
Field |
getLeafFieldWithFocus()
Retrieves leaf field with focus. |
|
protected int |
getPreferredHeightOfChild(Field field)
Retrieves preferred height of a managed field. |
|
protected int |
getPreferredWidthOfChild(Field field)
Retrieves preferred width of a managed field. |
|
int |
getVerticalScroll()
Retrieves current vertical offset of scrolling region. |
|
int |
getVirtualHeight()
Retrieves this manager's virtual height. |
|
int |
getVirtualWidth()
Retrieves this manager's virtual width. |
|
int |
getVisibleHeight()
Retrieves height of this manager's visible region. |
|
int |
getVisibleWidth()
Retrieves width of this manager's visible region. |
|
void |
insert(Field field,
int index)
Inserts a field into this manager. |
|
void |
invalidate()
Marks this entire manager as requiring repainting. |
|
protected void |
invalidate(int x,
int y,
int width,
int height)
Marks a region as requiring repainting. |
|
protected void |
invalidateFieldRange(int lower,
int upper)
Invalidates this manager's controlled fieldsfrom lower to upper, inclusive. |
|
protected boolean |
invokeAction(int action)
Invokes an action on the field in this manager that currently has the focus. |
|
boolean |
isDataValid()
Indicates whether the data on the screen is valid. |
|
boolean |
isDirty()
Determines if any controlled field is dirty. |
|
protected boolean |
isDownArrowShown()
Determines whether the downward scroll arrow is to be drawn. |
|
boolean |
isFocusable()
Verify that this manager accepts the focus. |
|
boolean |
isMuddy()
Determines if any controlled field is muddy. |
|
boolean |
isSelecting()
Determines if the field with focus is in selection mode. |
|
protected boolean |
isUpArrowShown()
Determines whether the upward scroll arrow is to be drawn. |
|
boolean |
isValidLayout()
Verifies this manager has a completed layout for its fields. |
|
protected boolean |
keyChar(char ch,
int status,
int time)
Handles key generation events. |
|
protected boolean |
keyControl(char ch,
int status,
int time)
Sends key generation event to the controlled field with focus. |
|
protected boolean |
keyDown(int keycode,
int time)
Sends key down event to the controlled field with focus. |
|
protected boolean |
keyRepeat(int keycode,
int time)
Sends key repeat event to the controlled field with focus. |
|
protected boolean |
keyStatus(int keycode,
int time)
Sends key status event to the controlled field with focus. |
|
protected boolean |
keyUp(int keycode,
int time)
Sends key up event to the controlled field with focus. |
|
protected void |
layout(int width,
int height)
Layout this manager's controlled fields in a standardized manner. |
|
protected void |
layoutChild(Field field,
int width,
int height)
Prompts managed field to lay itself out. |
|
protected void |
makeMenu(Menu menu,
int instance)
Called from Screen.makeMenuWithContext(net.rim.device.api.ui.component.Menu, int) to populate the menu. |
|
protected int |
moveFocus(int amount,
int status,
int time)
Called by the framework to move focus within this manager. |
|
protected void |
moveFocus(int x,
int y,
int status,
int time)
Moves focus to an exact position within this manager. |
|
protected boolean |
navigationClick(int status,
int time)
Invoked when the navigational action is selected. |
|
protected boolean |
navigationMovement(int dx,
int dy,
int status,
int time)
Invoked when a navigational motion occurs. |
|
protected boolean |
navigationUnclick(int status,
int time)
Invoked when the navigational action is released. |
|
protected int |
nextFocus(int direction,
boolean alt)
Deprecated. Please use Manager.nextFocus(int, int) instead |
|
protected int |
nextFocus(int direction,
int axis)
Retrieves the index of the next field that should be given focus. |
|
protected void |
onFocus(int direction)
Invoked by the framework when focus is gained. |
|
protected void |
onUndisplay()
Invoked when the screen this field is attached to is popped off the display stack. |
|
protected void |
onUnfocus()
Invoked by the framework when focus is lost. |
|
protected void |
paint(Graphics graphics)
Paints this manager's visible region. |
|
protected void |
paintChild(Graphics graphics,
Field field)
Paints a controlled field. |
|
void |
replace(Field oldField,
Field newField)
Removes a field from this Manager and replaces it with another field. |
|
void |
setDirty(boolean dirty)
Cleans or dirties all controlled fields. |
|
boolean |
setFocus(int x,
int y,
int status)
Sets focus to exact position in current screen. |
|
void |
setHorizontalQuantization(int horizontalQuanta)
Sets this manager's horizontal quantization. |
|
void |
setHorizontalScroll(int position)
Sets this manager's horizontal scroll value. |
|
void |
setHorizontalScroll(int position,
boolean animate)
Sets this manager's horizontal scroll value. |
|
protected void |
setPositionChild(Field field,
int x,
int y)
Allows a Manager to set the position of one of its Fields. |
|
void |
setScrollListener(ScrollChangeListener listener)
Registers a listener for scroll changes. |
|
protected void |
setScrollingInertial(boolean isScrollingInertial)
Sets whether the scrolling on this Manager is inertial, overriding the system's default. |
|
void |
setVerticalQuantization(int verticalQuanta)
Sets this manager's vertical quantization. |
|
void |
setVerticalScroll(int position)
Sets this manager's vertical scroll value. |
|
protected void |
setVirtualExtent(int virtualWidth,
int virtualHeight)
Sets the virtual extent for this manager. |
|
protected abstract void |
sublayout(int width,
int height)
Implements custom layout features for this manager. |
|
protected void |
subpaint(Graphics graphics)
Implements custom paint features for this manager. |
|
protected boolean |
touchEvent(TouchEvent message)
Handles touch input events (see TouchEvent ). |
|
protected boolean |
trackwheelClick(int status,
int time)
Dispatches trackwheel event to the controlled field with focus. |
|
protected boolean |
trackwheelUnclick(int status,
int time)
Dispatches trackwheel released event to the controlled field with focus. |
Methods inherited from class java.lang.Object |
---|
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
protected static final long VERTICAL_SCROLL_MASK
public static final long VERTICAL_SCROLL
If the manager's virtual height is larger than its visible height, the region scrolls vertically as required.
public static final long NO_VERTICAL_SCROLL
protected static final long HORIZONTAL_SCROLL_MASK
public static final long HORIZONTAL_SCROLL
If the manager's virtual width is larger than its visible width the region scrolls horizontally as required.
public static final long NO_HORIZONTAL_SCROLL
protected static final long VERTICAL_SCROLLBAR_MASK
public static final long VERTICAL_SCROLLBAR
public static final long NO_VERTICAL_SCROLLBAR
protected static final long HORIZONTAL_SCROLLBAR_MASK
public static final long HORIZONTAL_SCROLLBAR
Note: this functionality has been implemented only for scroll arrows.
If VERTICAL_SCROLL_BAR
is enabled then HORIZONTAL_SCROLL_BAR
is ignored.
public static final long NO_HORIZONTAL_SCROLLBAR
public static final long LEAVE_BLANK_SPACE
This style specifies that the layout update logic should not attempt to adjust the scroll offset to eliminate blank space.
public static final long NO_SCROLL_RESET
public static final int UPWARD
public static final int DOWNWARD
public static final int LEFTWARD
public static final int RIGHTWARD
public static final int TOPMOST
public static final int BOTTOMMOST
public static final int LEFTMOST
public static final int RIGHTMOST
public static final int QUANTA_FONT
For vertical quantization, this is the font height. The value is reserved for future use with horizontal quantization.
Manager.setHorizontalQuantization(int)
,
Manager.setVerticalQuantization(int)
,
Constant Field ValuesConstructor Detail |
---|
protected Manager(long style)
Subclasses invoke this constructor in order to set the appropriate style bits for a new manager.
style
- Style bits for this manager. The styles
Field.FOCUSABLE
, Field.NON_FOCUSABLE
,
Field.EDITABLE
, Field.READONLY
are ignored; these
properties are controlled by the Manager's contents.
IllegalArgumentException
- Thrown if the style parameter specifies
an invalid or undefined style.Method Detail |
---|
public void add(Field field)
Invoke this method to add a new field at the end of this manager's list of controlled fields.
Notice that only one manager is allowed to control any single field, and a field can never manage itself.
field
- Field to add.
IllegalStateException
- If the field has already been added to a
manager.
IllegalArgumentException
- If the field is being added to itself.public void addAll(Field[] fields)
Invoke this method to add new fields to a manager via add() without triggering multiple layouts.
fields
- array of Fields to add.
IllegalStateException
- If the field has already been added to a
manager.
IllegalArgumentException
- If the field is being added to itself.public void delete(Field field)
Invoke this method to remove a field from this manager.
field
- Field to remove.
IllegalArgumentException
- If the field to be deleted does not
belong to this manager.public void deleteAll()
Invoking this method has the same effect as
manager.deleteRange( 0, manager.getFieldCount() )
public void deleteRange(int start, int count)
Provide the index of the first field you want to delete, and the number of fields to delete.
start
- Index at which to begin deletion.count
- Number of fields to delete.
IndexOutOfBoundsException
- If start or count are invalid.public AccessibleContext getAccessibleContext()
getAccessibleContext
in class Field
public Field getField(int index)
index
- Index of field to retrieve.
IndexOutOfBoundsException
- If index not valid.public int getFieldAtLocation(int x, int y)
Given a point in coordinates local to this manager's extent, this method returns the index of the controlled field under that point (or -1 if no field found under the specified point).
This method constrains its search to the extent of this manager: if you provide a coordinate outside this manager's extent, this method uses values along the edges of the extent as required.
By default, this method performs a linear search hit, testing each controlled field in turn. If you implement a manager, you can override this method to optimize its functionality.
x
- Distance from left edge of manager's extent.y
- Distance from top edge of manager's extent.
public int getFieldCount()
public Field getFieldWithFocus()
Invoke this method to retrieve the field controlled by this manager that has the focus. Notice that the field returned may in fact be another manager.
Manager.getLeafFieldWithFocus()
public int getFieldWithFocusIndex()
public void getFocusRect(XYRect rect)
Invoke this method to retrieve the extent of the current focus region. Notice that the coordinates expressed are local to this manager, and take scrolling into account (that is, the coordinates are local to the manager's visible region, not the virtual region).
getFocusRect
in class Field
rect
- Rect to contain extent of focus.public final int getHorizontalScroll()
Invoke this method to retrieve the current offset (from the left edge of this manager's virtual region) of the currently displayed part of the manager.
public Field getLeafFieldWithFocus()
Since managers can themselves control other managers, you can invoke this method to retrieve the leaf (bottom-most, non-manager) field that has the focus.
getLeafFieldWithFocus
in class Field
Manager.getFieldWithFocus()
protected final int getPreferredHeightOfChild(Field field)
Note: the returned value does not include field's margins, but includes border and padding.
field
- Field to examine.
NullPointerException
- if field
is null.protected final int getPreferredWidthOfChild(Field field)
Note: the returned value does not include field's margins, but includes border and padding.
field
- Field to examine.
NullPointerException
- if field
is null.public final int getVerticalScroll()
Invoke this method to retrieve the current offset (from the top edge of this manager's virtual region) of the currently displayed part of the manager.
public final int getVirtualHeight()
The manager's virtual height is the entire height of the field that can be displayed, either at once or by scrolling.
public final int getVirtualWidth()
The manager's virtual width may be wider than the manager's visible width, and can be displayed either all at once or by scrolling.
public int getVisibleHeight()
public int getVisibleWidth()
public void insert(Field field, int index)
Invoke this method to insert a new field into this manager's list of controlled fields. You provide the field to add, and the index position you wish the new field to occupy.
field
- Field to insert.index
- Index at which to insert.
IndexOutOfBoundsException
- If index is less than zero or greater
than Manager.getFieldCount()
.
IllegalStateException
- If the field has already been added to a
manager.
IllegalArgumentException
- If the field is being added to itself.public void invalidate()
Invoke this method to signal that this manager's entire region requires repainting.
It is safe to call this function without synchronizing on the
event lock
.
invalidate
in class Field
protected void invalidate(int x, int y, int width, int height)
Invoke this method to identify a region of this manager that requires repainting.
invalidate
in class Field
x
- Left edge of invalid rectangle.y
- Top edge of invalid rectangle.width
- Width of invalid rectangle.height
- Height of invalid rectangle.protected void invalidateFieldRange(int lower, int upper)
protected boolean invokeAction(int action)
invokeAction
in class Field
action
- the action to be performed on the field in this manager that currently has
the focus.
true
if the action was consumed by the field on which the action was
performed; false
if the action was not consumed or no field has the focus in
this manager.public boolean isDataValid()
Loops through all children and will return true if all children return true.
isDataValid
in class Field
public boolean isDirty()
Invoke this method to determine if any of this manager's controlled
fields are dirty. A field is dirty if it has changed since the last time
it was clean. A field is clean when it is first created, and also when
explicitly cleaned by invoking setDirty(false)
.
isDirty
in class Field
Field.isMuddy()
,
Field.setDirty(boolean)
protected boolean isDownArrowShown()
A custom manager can override this method to provide precise control over the downward scroll arrow. The framework can invoke this method at any time after performing a layout.
By default, this method returns true if the vertical scroll value plus this manager's visible height is less than this manager's virtual height.
public boolean isFocusable()
isFocusable
in class Field
public boolean isMuddy()
Invoke this method to determine if any of this manager's controlled fields are muddy. A field is muddy if it has changed and focus has not been moved or left the field since the change.
isMuddy
in class Field
Field.isDirty()
,
Field.setMuddy(boolean)
public boolean isSelecting()
isSelecting
in class Field
Field.select(boolean)
protected boolean isUpArrowShown()
A custom manager can override this method to provide precise control over the upward scroll arrow. The framework can invoke this method at any time after performing a layout.
By default, this method returns true if the vertical scroll value is positive.
public final boolean isValidLayout()
A manager's layout is valid after its screen has first been pushed onto the display stack.
protected boolean keyChar(char ch, int status, int time)
Sends the event to the field with focus. If no controlled field has the focus, this method does nothing and returns false.
keyChar
in class Field
ch
- Character generated.status
- Modifier key status.time
- Number of milliseconds since the device was turned on.
protected boolean keyControl(char ch, int status, int time)
If no controlled field has the focus, this method does nothing and returns false.
keyControl
in class Field
ch
- Character generated.status
- Modifier key status.time
- Number of milliseconds since the device was turned on.
protected boolean keyDown(int keycode, int time)
If no controlled field has the focus, this method does nothing and returns false.
keyDown
in class Field
keycode
- Code of key pressed.time
- Number of milliseconds since the device was turned on.
protected boolean keyRepeat(int keycode, int time)
If no controlled field has the focus, this method does nothing and returns false.
keyRepeat
in class Field
keycode
- Code of key repeated.time
- Number of milliseconds since the device was turned on.
protected boolean keyStatus(int keycode, int time)
If no controlled field has the focus, this method does nothing and returns false.
keyStatus
in class Field
keycode
- Code of status key.time
- Number of milliseconds since the device was turned on.
protected boolean keyUp(int keycode, int time)
If no controlled field has the focus, this method does nothing and returns false.
keyUp
in class Field
keycode
- Code of key released.time
- Number of milliseconds since the device was turned on.
protected final void layout(int width, int height)
If you are creating a customized layout by extending the Manager class, implement
the Manager.sublayout(int, int)
method in your subclass.
Invoking the Manager.sublayout(int, int)
method prompts your manager subclass to lay out the
controlled fields appropriately.
layout
in class Field
width
- Width in pixels available to this manager.height
- Height in pixels available to this manager.protected final void layoutChild(Field field, int width, int height)
Invoke this method to prompt this manager to tell one of its managed fields to lay itself out.
field
- Field managed by this manager.width
- Width in pixels available to the field.height
- Height in pixels available to the field.protected int moveFocus(int amount, int status, int time)
This method searches fields in their index order, attempting to pass the focus on to the next available field.
The amount
parameter specifies the number of index
positions to hop over when moving the focus. Use a negative amount to
move backwards in this manager's list of fields, a positive value to
forwards. Note that some controlled fields may support more than one
focus position (date fields, for example).
This method ignores the status
and time
parameters, but passes them on to the controlled fields. The
status
parameter should contain modifiers to the trackwheel
roll event, such as modifier keys held while rolling, direction of roll,
and so forth.
When the focus is moved from a controlled field, the
Manager.onUnfocus()
handler method is invoked. Then, Manager.isFocusable()
is invoked on the next controlled field to determine if it accepts the
focus.
As the focus passes over each field that accepts the focus, the
amount
parameter's absolute value is reduced by one, and
that field is provided with the chance to respond to a new focus
event. If the amount
parameter's absolute value is still
greater than zero, the focus passes on to the next field which accepts
it.
If either end of this manager's field list is reached (the top for
negative amount values, the bottom for positive amount values), either
because of a large amount value, or because there are no fields left that
accept the focus, this method returns the remaining amount
that wasn't used up. Notice that the sign for the amount is preserved, to
retain the direction indicator.
moveFocus
in class Field
amount
- If positive, move focus forward this many index positions;
if negative, move focus backwards this many index positions.status
- Trackwheel event modifiers.time
- Number of milliseconds since the device was turned on.
amount
parameter.protected void paint(Graphics graphics)
Invoke this method to prompt this manager to paint itself. if you
extend manager to create a custom layout manager, you may want to
implement the Manager.subpaint(net.rim.device.api.ui.Graphics)
method, as this method invokes it.
This method also draws the focus indicator as required.
paint
in class Field
graphics
- Graphics object used for painting.protected final void paintChild(Graphics graphics, Field field)
Invoke this method to paint a controlled field. This method ensures
the graphics stack and drawing attributes are ready before invoking the
Manager.paint(net.rim.device.api.ui.Graphics)
method on the field you provide.
graphics
- Graphics object used for painting.field
- Controlled field you wish to paint.public void replace(Field oldField, Field newField)
Manager
and replaces it with another field.
The specified oldField
must be a direct child of this manager and the
specified newField
must not be being managed by any Manager
,
including this one.
If oldField
had the focus and newField
is focusable,
then Field.setFocus()
will be invoked on newField
after it is added
to this manager.
This method is implemented as follows: After the runtime checks are passed then
delete(oldField)
is invoked, then insert(newField, index)
is invoked,
where index
if the index of oldField
when it was managed by this
Manager
, then newField.setFocus()
is invoked if oldField
had the focus when it was managed by this Manager
.
oldField
- the field to be replacednewField
- the field to replace it
IllegalArgumentException
- if any argument is null
, if oldField
is not being managed by this Manager
(ie. oldField.getManager() != this
),
or if newField
is being managed by another Manager
including this
one (ie. newField.getManager() != null
).
IllegalStateException
- if oldField.getIndex()
returns -1
.Manager.delete(Field)
,
Manager.insert(Field, int)
,
Field.getIndex()
,
Field.getManager()
,
Field.setFocus()
protected final void setScrollingInertial(boolean isScrollingInertial)
isScrollingInertial
- whether the scrolling for this Manager is "inertial", assuming that it is
supported on this device.protected abstract void sublayout(int width, int height)
If implementing a manager with custom layout features, extend the Manager class and implement this method.
Invoking the sublayout method prompts your manager subclass to lay out controlled fields appropriately.
Manager.layout(int, int)
invokes this method to perform custom layout handling.
A manager MUST call setPositionChild for each child during sublayout. Note that setExtent must also be called,
but it is the field's responsibility to do this in layout.
width
- Width available for this manager.height
- Height available for this manager.protected void subpaint(Graphics graphics)
Manager.paintChild(net.rim.device.api.ui.Graphics, net.rim.device.api.ui.Field)
.
By default, this method paints all child fields, without regard to the clipping region.
If implementing a custom manager that has requirements for special
paint handling, you can override this method for optimization:
Manager.paint(net.rim.device.api.ui.Graphics)
invokes this method to perform custom paint functions.
graphics
- Graphics object used for painting.protected void onFocus(int direction)
When the framework invokes this method, it starts either at the start
of the manager's controlled field list, or the end (depending on the
passed direction
parameter), looking for a field to give the
focus.
This method passes the focus to the first field it finds to accept it.
onFocus
in class Field
direction
- Specify 1 to search forward from the first controlled
field in this manager's list. Specify -1 to search backward from the last
controlled field in this manager's list.protected void onUnfocus()
onUnfocus
in class Field
protected int nextFocus(int direction, boolean alt)
Manager.nextFocus(int, int)
instead
This method is called by the framework during a trackwheel focus move operation.
The direction parameter indicates which direction the focus is moving: a value of 1 indicates that the focus is moving forward (generally down and to the right), a value of -1 indicates that the focus is moving backwards (generally up and to the left).
direction
- Direction the focus is moving within the field.alt
- True if ALT-rolling the trackwheel; otherwise, false.
IllegalArugmentException
- If direction parameter has a value other
than 1 or -1.protected int nextFocus(int direction, int axis)
This method is called by the framework during a trackball focus move operation.
The direction parameter indicates the direction in which the focus is moving: a value of 1 indicates that the focus is moving forward (generally down and to the right), while a value of -1 indicates that the focus is moving backwards (generally up and to the left).
The axis parameter indicates which axis of movement the direction is in.
This can be one of Field.AXIS_SEQUENTIAL
, Field.AXIS_HORIZONTAL
or Field.AXIS_VERTICAL
.
direction
- Direction the focus is moving within the field.axis
- The axis of movement.
IllegalArgumentException
- If direction parameter is a value other than 1 or -1.protected void moveFocus(int x, int y, int status, int time)
Invoke this method to place the focus on a precise point within this manager's region.
This method ignores the status and time parameters, but passes them on to the controlled fields. The status parameter should contain modifiers to the trackwheel roll event, such as modifier keys held while rolling, direction of roll, and so forth.
moveFocus
in class Field
x
- Distance from left edge of virtual region.y
- Distance from top edge of virtual region.status
- Trackwheel event modifiers.time
- Number of milliseconds since the device was turned on.public boolean setFocus(int x, int y, int status)
This method retrieves a handle to the current screen, and then
invokes setFocus
on it
(for the time parameter, it passes in a value of zero).
x
- Distance from left edge of screen.y
- Distance from top edge of screen.status
- Modifiers when the trackwheel roll occured, from KeyPad.
protected boolean navigationClick(int status, int time)
The system invokes this method when passing on a navigational click event.
The ALT-click combination will enter selection mode, or if in selection mode will copy.
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 them will be set.
navigationClick
in class Field
status
- Bitfield of values defined by KeypadListener
.time
- Number of milliseconds since the device was turned on.
protected boolean navigationMovement(int dx, int dy, int status, int time)
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 them will be set.
navigationMovement
in class Field
dx
- Magnitude of navigational motion: negative for a move left
and postive for a move right.dy
- Magnitude of navigational motion: negative for an upwards
move, and positive for a downwards move.status
- Bitfield of values defined by KeypadListener
.time
- Number of milliseconds since the device was turned on.
protected boolean navigationUnclick(int status, int time)
The system invokes this method when passing on a navigational release event.
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 them will be set.
navigationUnclick
in class Field
status
- Bitfield of values defined by KeypadListener
.time
- Number of milliseconds since the device was turned on.
public void setDirty(boolean dirty)
Pass true to this method to dirty all this manager's controlled fields. Pass false to this method to clean all the controlled fields.
setDirty
in class Field
dirty
- True if dirtying the fields; false if cleaning them.Field.isDirty()
,
Field.setMuddy(boolean)
public void setHorizontalQuantization(int horizontalQuanta)
The real horizontal size must be a multiple of your provided value.
horizontalQuanta
- Horizontal quantization in pixels.public void setHorizontalScroll(int position)
Invoke this method to adjust the vertical scroll value for this manager. This method is not normally invoked as focus movement deals with scrolling automatically.
If you use this function to set the scroll value for a screen that is not on the display stack you must push the screen onto the stack first, before invoking this method.
position
- New horizontal scroll position.
IllegalStateException
- If this manager is non scrollable.
IllegalArgumentException
- If position is negative.public void setHorizontalScroll(int position, boolean animate)
Invoke this method to adjust the horizontal scroll value for this manager. This method is not normally invoked as focus movement deals with scrolling automatically.
If you use this function to set the scroll value for a screen that is not on the display stack you must push the screen onto the stack first, before invoking this method.
position
- New horizontal scroll position.animate
- Animate the scrolling if true, jump to the new scroll position if false
IllegalStateException
- If this manager is non scrollable.
IllegalArgumentException
- If position is negative.protected final void setPositionChild(Field field, int x, int y)
field
- Field managed by this manager.x
- Offset of the left of the field in its manager.y
- Offset of the top of the field in its manager.public void setScrollListener(ScrollChangeListener listener)
To unregister a scroll listener, pass null into this method.
listener
- Object that listens for scroll changes.
IllegalStateException
- when there is already a listener set and
your listener parameter is non-null.public void setVerticalQuantization(int verticalQuanta)
The real vertical size must be a multiple of your provided value.
verticalQanta
- Veritcal quantization in pixels.public void setVerticalScroll(int position)
Invoke this method to adjust the vertical scroll value for this manager. This method is not normally invoked as focus movement deals with scrolling automatically.
If you use this function to set the scroll value for a screen that is not on the display stack you must push the screen onto the stack first, before invoking this method.
position
- New vertical scroll position.
IllegalStateException
- If this manager is non scrollable.
IllegalArgumentException
- If position is negative.protected final void setVirtualExtent(int virtualWidth, int virtualHeight)
Use this method to specify the size of the area that child controls inhabit. If this extent is larger than the manager's visible area, scrolling is used to bring the extra area into view.
Subclasses should invoke this method when layout is called.
virtualWidth
- Width of the manager's virtual extent.virtualHeight
- Height of the manager's virtual extent.protected boolean trackwheelClick(int status, int time)
If no controlled field has the focus, this method does nothing and returns false.
trackwheelClick
in class Field
status
- Trackwheel event modifiers.time
- Number of milliseconds since the device was turned on.
protected void makeMenu(Menu menu, int instance)
Screen.makeMenuWithContext(net.rim.device.api.ui.component.Menu, int)
to populate the menu.
If you override this function, you must call
super.makeMenu(menu, instance)
so that the sub
managers's items are added to the menu.
makeMenu
in class Field
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.protected boolean touchEvent(TouchEvent message)
TouchEvent
).
The coordinates reflect the location of the touch event with respect to the top-left of this Manager.
The x, y coordinates are then further mapped to the top-left corner of the field with input.
touchEvent
in class Field
message
- TouchEvent
object containing various input parameters
including the event type and touch coordinates.
IllegalArgumentException
- If message
is null.protected boolean trackwheelUnclick(int status, int time)
If no controlled field has the focus, this method does nothing and returns false.
trackwheelUnclick
in class Field
status
- Trackwheel event modifiers.time
- Number of milliseconds since the device was turned on.
protected void onUndisplay()
Field
The complementing callback is Field.onDisplay()
.
onUndisplay
in class Field
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Copyright 1999-2010 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. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.