|
|||||||||
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.ScrollView
net.rim.device.api.ui.Manager
net.rim.device.api.ui.component.pane.TitleView
net.rim.device.api.ui.component.pane.HorizontalTabTitleView
public class HorizontalTabTitleView
An extension of TitleView
that presents the titles
of Pane
objects that are contained within the associated
PaneManagerModel
.
This class presents the titles as a series of separated tabs.
Displays three tabs by default. If there
are more tabs in the model, the user can scroll to bring them
into view. The number of tabs displayed can be changed by using HorizontalTabTitleView.setNumberOfDisplayedTabs(int)
.
The Field
objects used for representing the title are centered both
horizontally and vertically within their tab. To implement custom alignment have the
title use the style bits Field.USE_ALL_WIDTH
and Field.USE_ALL_HEIGHT
which
causes the title to occupy the same space as its containing tab.
This class is designed to use with HorizontalTabController
.
The scrolling of the tabs for the user is controlled by the framework.
No methods for programmatically changing the positions are supported: HorizontalTabTitleView.drag(int, int, int, int, int)
,
HorizontalTabTitleView.jumpBackwards(boolean, int)
, HorizontalTabTitleView.jumpForwards(boolean, int)
, HorizontalTabTitleView.jumpTo(int, int, int, boolean, int, int)
,
HorizontalTabTitleView.snapToCurrent(boolean, int, int)
. User interaction with the titles are handled through the framework.
Field Summary |
---|
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 |
Constructor Summary | ||
---|---|---|
HorizontalTabTitleView(long style)
Constructs a new HorizontalTabTitleView instance. |
Method Summary | ||
---|---|---|
void |
add(Field field)
Adds a field to this manager. |
|
void |
delete(Field field)
Removes a field from this manager. |
|
void |
deleteRange(int start,
int count)
Removes a range of fields from this manager. |
|
void |
drag(int dx,
int dy,
int index,
int leftIndex,
int rightIndex)
Updates the rendering state of this view. |
|
Field |
getField(int index)
Returns the controlled field with the specified index. |
|
int |
getNumberOfDisplayedPanes()
Returns the number of tabs currently configured to display. |
|
XYRect |
getRegionExtent(int index)
Returns the region of the Field that represents a title
within the currently pushed region. |
|
Background |
getTabBackground(int visual)
Returns the Background
set on the tabs that hold the titles. |
|
Border |
getTabBorder(int visual)
Returns the Border
set on the tabs that hold the titles. |
|
void |
insert(Field field,
int index)
Inserts a field into this manager. |
|
void |
insertAll(Field[] fields,
int index)
Inserts an array of fields into this manager. |
|
boolean |
isAnimating()
Indicates if the view is currently animating the transition between panes. |
|
void |
jumpBackwards(boolean animate,
int duration)
Updates the current rendering state of the view. |
|
void |
jumpForwards(boolean animate,
int duration)
Updates the current rendering state of the view. |
|
void |
jumpTo(int index,
int leftIndex,
int rightIndex,
boolean animate,
int direction,
int duration)
Updates the current rendering state of the view. |
|
protected int |
moveFocus(int amount,
int status,
int time)
Called by the framework to move focus within this manager. |
|
protected int |
nextFocus(int direction,
int axis)
Returns the index of the next field that should be given focus. |
|
protected void |
onDisplay()
Invoked when the screen this field is attached to is pushed onto the display stack. |
|
protected void |
onFocus(int direction)
Invoked by the framework when focus is gained. |
|
protected void |
onUnfocus()
Invoked by the framework when focus is lost. |
|
protected void |
paint(Graphics graphics)
Paints this manager's visible region. |
|
void |
replace(Field oldField,
Field newField)
Removes a field from this Manager and replaces it with another field. |
|
void |
setModel(PaneManagerModel model)
Associates a PaneManagerModel with this view. |
|
void |
setNumberOfDisplayedTabs(int numberToDisplay)
Sets the number of tabs to display. |
|
void |
setTabBackground(int visual,
Background background)
Specifies a Background to use for the tabs. |
|
void |
setTabBorder(int visual,
Border border)
Specifies a Border to use for the tabs. |
|
void |
snapToCurrent(boolean animate,
int duration,
int direction)
Updates the current rendering state of the view. |
|
protected 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. |
|
boolean |
touchEvent(TouchEvent message)
Handles touch input events (see TouchEvent ). |
Methods inherited from class net.rim.device.api.ui.component.pane.TitleView |
---|
getLeftArrow, getModel, getRightArrow, setLeftArrow, setRightArrow |
Methods inherited from class net.rim.device.api.ui.ScrollView |
---|
configurationChanged, getHorizontalAdjustment, getVerticalAdjustment, getVisibleHeight, getVisibleWidth, onUndisplay, setCurrentLocation, setExtent, setHorizontalAdjustment, setHorizontalScroll, setHorizontalScroll, setScrollListener, setVerticalAdjustment, setVerticalScroll, setVerticalScroll, valueChanged, waitForScrolling |
Methods inherited from class java.lang.Object |
---|
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
---|
public HorizontalTabTitleView(long style)
Constructs a new HorizontalTabTitleView
instance. This
constructor accepts a long
of style bit flags and sets the
Field.FOCUSABLE
style bit.
style
- The style bit flags to use for this Manager
.Method Detail |
---|
public void add(Field field)
The added field is wrapped for rendering the same sized tabs.
Invoke this method to add a new field at the end of this manager's list of controlled fields.
Only one manager is allowed to control any single field, and a field can never manage itself.
add
in class Manager
field
- The field to add.
IllegalStateException
- if the field has already been added to a
manager.
IllegalArgumentException
- if the field is being added to itself.
NullPointerException
- if the field is null
.public void delete(Field field)
Removes the field from its wrapper and removes the wrapper from this manager.
delete
in class Manager
field
- The field to remove.
IllegalArgumentException
- if the field does not belong to this
manager.
NullPointerException
- if the field is null
.public void deleteRange(int start, int count)
Removes the fields from their wrappers removes the wrappers from this manager.
Provide the index of the first field you want to delete, and the number of fields to delete.
deleteRange
in class Manager
start
- The index at which to begin deletion.count
- The number of fields to delete.
IndexOutOfBoundsException
- if start
or
count
are invalid.public void drag(int dx, int dy, int index, int leftIndex, int rightIndex)
Updates the rendering state of this view. It signals that the titles are being moved, usually by a user.
This rendering state can be cleared by calling HorizontalTabTitleView.jumpBackwards(boolean, int)
,
HorizontalTabTitleView.jumpForwards(boolean, int)
, HorizontalTabTitleView.jumpTo(int, int, int, boolean, int, int)
,
HorizontalTabTitleView.snapToCurrent(boolean, int, int)
.
drag
in class TitleView
dx
- Ignored.dy
- Ignored.index
- Ignored.leftIndex
- Ignored.rightIndex
- Ignored.public Field getField(int index)
Controlled fields are wrapped, this method returns the original field, not its wrapper.
getField
in class Manager
index
- The index of the field to return.
IndexOutOfBoundsException
- if index
is invalid.public int getNumberOfDisplayedPanes()
Returns the number of tabs currently configured to display. During animations, and while a user is scrolling, the number of tabs on screen may differ from the value returned by this method. There may be some tabs partially on screen.
The value returned by this method indicates the number of tabs displayed when the view is not animating.
This value can be controlled by HorizontalTabTitleView.setNumberOfDisplayedTabs(int)
.
getNumberOfDisplayedPanes
in class TitleView
public XYRect getRegionExtent(int index)
Returns the region of the Field
that represents a title
within the currently pushed region.
The index is that of the title.
If index
is invalid, an empty XYRect
is
returned.
getRegionExtent
in class TitleView
index
- The title of the region to be retrieved.
XYRect
of the title at the provided index.public Background getTabBackground(int visual)
Returns the Background
set on the tabs that hold the titles.
visual
- The visual state associated with background:
Field.VISUAL_STATE_NORMAL
,
Field.VISUAL_STATE_ACTIVE
, Field.VISUAL_STATE_FOCUS
,
Field.VISUAL_STATE_DISABLED
,
Field.VISUAL_STATE_DISABLED_FOCUS
.
Background
set for the tabs.
IllegalArgumentException
- if the visual state is invalid.public Border getTabBorder(int visual)
Returns the Border
set on the tabs that hold the titles.
visual
- The visual state associated with background:
Field.VISUAL_STATE_NORMAL
,
Field.VISUAL_STATE_ACTIVE
, Field.VISUAL_STATE_FOCUS
,
Field.VISUAL_STATE_DISABLED
,
Field.VISUAL_STATE_DISABLED_FOCUS
.
Border
set for the tabs.
IllegalArgumentException
- if the visual state is invalid.public void insert(Field field, int index)
The field passed in will be wrapped for rendering the same sized tabs.
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 want the new field to occupy.
insert
in class Manager
field
- The field to insert.index
- The 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.
NullPointerException
- if the field is null
.public void insertAll(Field[] fields, int index)
The added fields are wrapped to render the same sized tabs.
Invoke this method to insert new fields into this manager's list of controlled fields, triggering a single layout. Fields are inserted in the order provided.
insertAll
in class Manager
fields
- The fields to insert.index
- The index at which to begin inserting.
IndexOutOfBoundsException
- if index
is less than zero
or greater than Manager.getFieldCount()
.
IllegalStateException
- if any of the fields have already been
added to a manager.
IllegalArgumentException
- if any of the fields are being added to
itself.
NullPointerException
- if fields
is null
or contains any elements that are null
.public boolean isAnimating()
Indicates if the view is currently animating the transition between panes.
isAnimating
in class TitleView
true
if the view is currently animating the
transition between panes, false
otherwise.public void jumpBackwards(boolean animate, int duration)
Updates the current rendering state of the view. Does not change the position of titles. User interaction with the titles is controlled by the framework.
If HorizontalTabTitleView.drag(int, int, int, int, int)
has been called this will update the view so
that it represents the end of user interaction.
jumpBackwards
in class TitleView
animate
- Ignored.duration
- Ignored.public void jumpForwards(boolean animate, int duration)
Updates the current rendering state of the view. Does not change the position of titles. User interaction with the titles is controlled by the framework.
If
HorizontalTabTitleView.drag(int, int, int, int, int)
has been called this will update the view so
that it represents the end of user interaction.
jumpForwards
in class TitleView
animate
- Ignored.duration
- Ignored.public void jumpTo(int index, int leftIndex, int rightIndex, boolean animate, int direction, int duration)
Updates the current rendering state of the view. Causes the view to move from the currently selected pane to
the pane at the specified index
. The direction
controls the
animation of the change from the currently selected pane to the new pane.
If HorizontalTabTitleView.drag(int, int, int, int, int)
has been called this will update the view so
that it represents the end of user interaction.
jumpTo
in class TitleView
index
- The index of the pane to become the currently selected pane.leftIndex
- Ignored.rightIndex
- Ignored.animate
- Ignored.direction
- Ignored.duration
- Ignored.protected int moveFocus(int amount, int status, int time)
This method searches fields in their index order, attempting to pass the focus to the next available field.
The amount
parameter specifies the number of index
positions to skip 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 to the controlled fields. The
status
parameter should contain modifiers to the trackwheel
roll event, such as modifier keys held while rolling and direction of roll.
When the focus is moved from a controlled field, the
HorizontalTabTitleView.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 to 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. The sign of the amount is preserved to
retain the direction indicator.
moveFocus
in class Manager
amount
- The number of index positions to move focus; if positive,
move focus forward this many index positions; if negative, move focus
backwards this many index positions.status
- Trackwheel event modifiers.time
- The number of milliseconds since the device was turned on.
amount
parameter.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
.
nextFocus
in class Manager
direction
- The direction the focus is moving within the field.axis
- The axis of movement.
IllegalArgumentException
- if axis
is
Field.AXIS_HORIZONTAL
and direction
is invalid.protected void onDisplay()
This method is invoked by the system after the screen is pushed onto the stack and layout has been done, but before any painting occurs.
The complementing callback is #onUiEngineAttached
.
onDisplay
in class ScrollView
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
specified direction
parameter), until it reaches a field that accepts
focus.
onFocus
in class Manager
direction
- 1 to search forward from the first controlled
field in this manager's list, -1 to search backward from the last
controlled field in this manager's list.protected void onUnfocus()
onUnfocus
in class Manager
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 HorizontalTabTitleView.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 Manager
graphics
- The Graphics
object used for painting.public void replace(Field oldField, Field newField)
Manager
and replaces it with another field.
Removes the old field from its wrapper and wraps the new 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
is 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
.
replace
in class Manager
oldField
- The field to be replaced.newField
- 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
.HorizontalTabTitleView.delete(Field)
,
HorizontalTabTitleView.insert(Field, int)
,
Field.getIndex()
,
Field.getManager()
,
Field.setFocus()
public void setModel(PaneManagerModel model)
Associates a PaneManagerModel
with this view.
setModel
in class TitleView
model
- The PaneManagerModel
to associate to this view.public void setNumberOfDisplayedTabs(int numberToDisplay)
Sets the number of tabs to display. If there are more tabs in the model then this setting, the remainder can be scrolled to.
This will cause a relayout.
numberToDisplay
- The desired number of tabs to display.public void setTabBackground(int visual, Background background)
Specifies a Background
to use for the tabs.
This will not affect the settings of the Field
that is rendering the
actual title.
visual
- The visual state associated with background:
Field.VISUAL_STATE_NORMAL
,
Field.VISUAL_STATE_ACTIVE
, Field.VISUAL_STATE_FOCUS
,
Field.VISUAL_STATE_DISABLED
,
Field.VISUAL_STATE_DISABLED_FOCUS
.background
- The Background
to use for the tabs.
IllegalArgumentException
- if the visual state is invalid.public void setTabBorder(int visual, Border border)
Specifies a Border
to use for the tabs.
This will not affect the settings of the Field
that is rendering the
actual title.
visual
- The visual state associated with background:
Field.VISUAL_STATE_NORMAL
,
Field.VISUAL_STATE_ACTIVE
, Field.VISUAL_STATE_FOCUS
,
Field.VISUAL_STATE_DISABLED
,
Field.VISUAL_STATE_DISABLED_FOCUS
.border
- The Border
to use for the tabs.
IllegalArgumentException
- if the visual state is invalid.public void snapToCurrent(boolean animate, int duration, int direction)
Updates the current rendering state of the view. Does not change title positions. User interaction with the titles is controlled by the framework.
If
HorizontalTabTitleView.drag(int, int, int, int, int)
has been called this will update the view so
that it represents the end of user interaction.
snapToCurrent
in class TitleView
animate
- Ignored.duration
- Ignored.direction
- Ignored.protected void sublayout(int width, int height)
To implement 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.
sublayout
in class Manager
width
- The width available for this manager.height
- The 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:
HorizontalTabTitleView.paint(net.rim.device.api.ui.Graphics)
invokes this method to perform custom paint functions.
subpaint
in class Manager
graphics
- The Graphics
object used for painting.public boolean touchEvent(TouchEvent message)
TouchEvent
).
The coordinates reflect the location of the touch event with respect to the top-left of the associated view. The x, y coordinates are then further mapped to the top-left corner of the field with input.
touchEvent
in class Manager
message
- The TouchEvent
object containing various input
parameters including the event type and touch coordinates.
true
if the event is consumed,
false
otherwise.
IllegalArgumentException
- if message
is
null
.
|
|||||||||
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.