net.rim.device.api.ui.component.pane
Class PaneManagerController

java.lang.Object
  extended by net.rim.device.api.ui.component.pane.PaneManagerController
Direct Known Subclasses:
HorizontalScrollableController, HorizontalTabController

public abstract class PaneManagerController
extends Object

PaneManagerController handles the input events received by a PaneManagerView.

The Pane Manager classes conform to the Model-View-Controller design pattern. PaneManagerController implements the Controller. It handles all user input received by the Pane Manager. PaneManagerView is the view and is responsible for the layout and rendering of the panes. Since the view extends Manager it receives input events from the framework. This class must be set as the controller for the view for input events to be redirected to it. PaneManagerModel is the model that is responsible for maintaining the current set of Pane objects that represent the data, as well as for tracking the current position within the model.

This class accepts the optional setting of a Command object. This object can be invoked on user input in order to provide additonal functionallity beyond the scope of the Pane Manager classes. It is recommened that the contextual object passed in when invoking the Command be this class. An example use is launching a drop down menu below the TitleView when the user interacts with the title for the currently selected Pane.

This class does not consume or process any input received. To extend the class, the only methods that need to be extended are those for events which you want to process and consume.

Since:
BlackBerry API 6.0.0

Constructor Summary
PaneManagerController()
          Class constructor.
 
Method Summary
 Command getCommand()
          Returns an optional Command object that can be used to provide additional functionality.
 PaneManagerModel getModel()
          Returns the PaneManagerModel for this controller.
 PaneManagerView getView()
          Returns the PaneManagerView for this controller.
 boolean isInBounds(TouchEvent message)
          Compares the x-y coordinates of the TouchEvent to the extent of the currently set view to see if they are contained within it.
 boolean keyChar(char character, int status, int time)
          Handles character generation events.
 boolean keyControl(char character, int status, int time)
          Handles control character generation events.
 boolean keyDown(int keycode, int time)
          Handles key down events.
 boolean keyRepeat(int keycode, int time)
          Handles key repeat events.
 boolean keyStatus(int keycode, int time)
          Handles key status events.
 boolean keyUp(int keycode, int time)
          Sends key up event to the controlled field with focus.
 boolean navigationClick(int status, int time)
          Invoked in response to a navigational action.
 boolean navigationMovement(int dx, int dy, int status, int time)
          Invoked in response to a navigational motion.
 void setCommand(Command command)
          Optionally set a Command object that this controller can invoke to provide additional functionality.
 void setModel(PaneManagerModel model)
          Lets you set the model to use with this controller.
 void setView(PaneManagerView view)
          Lets you set the view to use with this controller.
 boolean touchEvent(TouchEvent message)
          Handles touch input events (see TouchEvent).
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Constructor Detail

PaneManagerController

public PaneManagerController()
Class constructor.

Since:
BlackBerry API 6.0.0


Method Detail

getCommand

public Command getCommand()

Returns an optional Command object that can be used to provide additional functionality.

Returns:
the Command object, or null if none has been set
Since:
BlackBerry API 6.0.0

getModel

public PaneManagerModel getModel()

Returns the PaneManagerModel for this controller.

Returns:
the PaneManagerModel associated with this controller, or null if none has been set.
Since:
BlackBerry API 6.0.0

getView

public PaneManagerView getView()

Returns the PaneManagerView for this controller.

Returns:
the PaneManagerView associated with this controller, or null if none has been set.
Since:
BlackBerry API 6.0.0

isInBounds

public boolean isInBounds(TouchEvent message)

Compares the x-y coordinates of the TouchEvent to the extent of the currently set view to see if they are contained within it.

Parameters:
message - the TouchEvent to perform the bounds check on
Returns:
true if the coordinates fall within the extent of the associated view or false if they do not fall within the extent of the associated view or false if the view is null
Throws:
IllegalArgumentException - if the message is null.
Since:
BlackBerry API 6.0.0

keyChar

public boolean keyChar(char character,
                       int status,
                       int time)
Handles character generation events.

Special keystroke handling code should be implemented in the Field keyDown method

Parameters:
character - Character generated.
status - Modifier key status.
time - Time (ms) since the device was turned on.
Returns:
True if event was consumed, otherwise false.
Since:
BlackBerry API 6.0.0

keyControl

public boolean keyControl(char character,
                          int status,
                          int time)
Handles control character generation events.

Parameters:
character - Character generated.
status - Modifier key status.
time - Time (ms) since the device was turned on.
Returns:
True if event was consumed, otherwise false.
Since:
BlackBerry API 6.0.0

keyDown

public boolean keyDown(int keycode,
                       int time)
Handles key down events.

By default, this method returns false; custom controllers that specially handle key down events must override this method.

Parameters:
keycode - Code of key pressed.
time - Time (ms) since the device was turned on.
Returns:
True if event was consumed, otherwise false.
Since:
BlackBerry API 6.0.0

keyRepeat

public boolean keyRepeat(int keycode,
                         int time)
Handles key repeat events.

By default, this method returns false; custom controllers that specially handle key repeat events must override this method.

Parameters:
keycode - Code of key repeated.
time - Time (ms) since the device was turned on.
Returns:
True if event was consumed, otherwise false.
Since:
BlackBerry API 6.0.0

keyStatus

public boolean keyStatus(int keycode,
                         int time)
Handles key status events.

By default, this method returns false; custom controllers that specially handle key status events must override this method.

Parameters:
keycode - Code of status key.
time - Time (ms) since the device was turned on.
Returns:
True if event was consumed, otherwise false.
Since:
BlackBerry API 6.0.0

keyUp

public boolean keyUp(int keycode,
                     int time)
Sends key up event to the controlled field with focus.

Parameters:
keycode - Code of key released.
time - Time (ms) since the device was turned on.
Returns:
True if event was consumed, otherwise false.
Since:
BlackBerry API 6.0.0

navigationClick

public boolean navigationClick(int status,
                               int time)
Invoked in response to a navigational action.

The system invokes this method when passing on a navigational click 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.

Parameters:
status - Bitfield of values defined by KeypadListener.
time - Time (ms) since the device was turned on.
Returns:
True if this method consumed the event, otherwise false.
Since:
BlackBerry API 6.0.0

navigationMovement

public boolean navigationMovement(int dx,
                                  int dy,
                                  int status,
                                  int time)
Invoked in response to a navigational motion.

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.

Parameters:
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 - Time (ms) since the device was turned on.
Returns:
True if event was consumed; otherwise, false.
Since:
BlackBerry API 6.0.0

setCommand

public void setCommand(Command command)

Optionally set a Command object that this controller can invoke to provide additional functionality.

Parameters:
command - a Command object that the controller can invoke
Since:
BlackBerry API 6.0.0

setModel

public void setModel(PaneManagerModel model)

Lets you set the model to use with this controller. The model represents the set of Pane objects that this controller allows the user to navigate through.

Parameters:
model - the PaneManagerModel to be used as the data set.
Since:
BlackBerry API 6.0.0

setView

public void setView(PaneManagerView view)

Lets you set the view to use with this controller. The view lays out and renders the Pane objects that this controller can offset or change based on user interactions.

Parameters:
view - the PaneManagerView to be used as the data set.
Since:
BlackBerry API 6.0.0

touchEvent

public boolean touchEvent(TouchEvent message)
Handles touch input events (see 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.

Parameters:
message - TouchEvent object containing various input parameters including the event type and touch coordinates.
Returns:
True if event consumed; otherwise, false.
Since:
BlackBerry API 6.0.0





Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal