net.rim.device.api.ui
Class Trackball

java.lang.Object
  net.rim.device.api.ui.Trackball

public final class Trackball
extends Object

Provides low-level access to trackball on supporting BlackBerry devices.

Methods are provided for getting and/or setting trackball characteristics, such as sensitivity and filters. Sensitivity determines how far a user must roll the trackball along the X or Y axis before a navigation event is dispatched to the software layer. Physical trackball movement is measured by the hardware in "ticks", similar to the way mouse movement is measured in "mickeys". When the number of ticks along an axis surpasses the system's or the application's threshold, a navigation event along that axis is dispatched to the software layer and the tick count is reset to zero. The higher the sensitivity, the smaller the threshold. Tick counts are typically reset to zero after a certain amount of idle time. This prevents a small "nudge" from generating a navigation event if the user had previously rolled the trackball by an amount insufficient to surpass the tick threshold. See Trackball.FILTER_NO_TIME_WINDOW for an exception to this rule.

Filters are used to alter trackball movement as detected by hardware before it is dispatched to software. This is typically used to filter out noise or unwanted movements. However, it can also be used to change other settings, such as acceleration. In this case the movement reported to software is increasingly more than the actual movement detected by hardware, as long as the user continually rolls the trackball. In other words, the sensitivity temporarily increases as the user rolls the trackball without pausing. See the descriptions of the FILTER_* constants for more details.

Since:

BlackBerry API 4.2.1

Field Summary
static int	FILTER_ACCELERATION Acceleration filter.
static int	FILTER_DEFAULT Default filter.
static int	FILTER_NO_TIME_WINDOW No time window filter.
static int	FILTER_XY_SNAP X/Y snap filter.
static int	SENSITIVITY_OFF Sensitivity setting for off.
static int	SENSITIVITY_UNSET Sensitivity setting for being unset.

Method Summary
static int	getFilter() Retrieves the trackball movement filter for the calling process.
static int	getFilterForSystem() Retrieves the trackball movement filter for the system.
static int	getSensitivityIncrement() Retrieves the smallest meaningful increment to the sensitivity value.
static int	getSensitivityX() Retrieves the X-axis sensitivity setting for the calling process.
static int	getSensitivityXForSystem() Retrieves the X-axis sensitivity setting for the system.
static int	getSensitivityY() Retrieves the Y-axis sensitivity setting for the calling process.
static int	getSensitivityYForSystem() Retrieves the Y-axis sensitivity setting for the system.
static boolean	isFeedbackAudibleForSystem() Determines whether or not there is an audible click associated with rolling the trackball.
static boolean	isOpticalSupported() Determines whether or not the device supports an optical trackball or trackpad.
static boolean	isSupported() Determines whether or not the system supports a trackball device.
static void	setFilter(int filter) Sets the trackball movement filter for the calling process.
static void	setSensitivityX(int sensitivity) Sets the X-axis sensitivity for the calling process.
static void	setSensitivityY(int sensitivity) Sets the Y-axis sensitivity for the calling process.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

SENSITIVITY_UNSET

public static final int SENSITIVITY_UNSET

Sensitivity setting for being unset. If this setting is used by an application, then the sensitivity value will be inherited from the system.

See Also:

Constant Field Values

Since:

BlackBerry API 4.2.1

SENSITIVITY_OFF

public static final int SENSITIVITY_OFF

Sensitivity setting for off. If this setting is used by an application, then it will not receive any navigation events from the trackball for the axis whose sensitivity is turned off. This filter is useful for applications that must restrict trackball movement to one axis.

See Also:

Constant Field Values

Since:

BlackBerry API 4.2.1

FILTER_DEFAULT

public static final int FILTER_DEFAULT

Default filter. An application that applies this filter will inherit its filter settings from the system.

See Also:

Constant Field Values

Since:

BlackBerry API 4.2.1

FILTER_XY_SNAP

public static final int FILTER_XY_SNAP

X/Y snap filter. An application that applies this filter will not receive diagonal navigation events. Rather, trackball navigation events will be either horizontal (along the X axis) or vertical (along the Y axis).

See Also:

Constant Field Values

Since:

BlackBerry API 4.2.1

FILTER_NO_TIME_WINDOW

public static final int FILTER_NO_TIME_WINDOW

No time window filter. An application that applies this filter will not have its tick counts reset to zero when the trackball remains idle.

See Also:

Constant Field Values

Since:

BlackBerry API 4.2.1

FILTER_ACCELERATION

public static final int FILTER_ACCELERATION

Acceleration filter. An application that applies this filter will receive trackball navigation events with increasing frequency if the user rolls the trackball without pausing. This filter is useful for paddle-based games, such as BrickBreaker.

See Also:

Constant Field Values

Since:

BlackBerry API 4.2.1

Method Detail

getFilter

public static int getFilter()

Retrieves the trackball movement filter for the calling process.

Returns:

A bitmask of the FILTER_* constants.

Since:

BlackBerry API 4.2.1

getFilterForSystem

public static int getFilterForSystem()

Retrieves the trackball movement filter for the system.

Returns:

A bitmask of the FILTER_* constants.

Since:

BlackBerry API 4.2.1

getSensitivityIncrement

public static int getSensitivityIncrement()

Retrieves the smallest meaningful increment to the sensitivity value. Incrementing the sensitivity by an amount less than this value is not guaranteed to cause a noticeable change in trackball sensitivity. For example, if the return result was 10, then increasing the sensitivity by 5 may not cause a noticeable change in trackball sensitivity.

Returns:

The integer 10 which is the smallest value you can use to increment the trackball sensitivity.

Since:

BlackBerry API 4.2.1

getSensitivityX

public static int getSensitivityX()

Retrieves the X-axis sensitivity setting for the calling process.

Returns:

Percentage value, Trackball.SENSITIVITY_UNSET or Trackball.SENSITIVITY_OFF.

Since:

BlackBerry API 4.2.1

getSensitivityXForSystem

public static int getSensitivityXForSystem()

Retrieves the X-axis sensitivity setting for the system.

Returns:

Percentage value.

Since:

BlackBerry API 4.2.1

getSensitivityY

public static int getSensitivityY()

Retrieves the Y-axis sensitivity setting for the calling process.

Returns:

Percentage value, Trackball.SENSITIVITY_UNSET or Trackball.SENSITIVITY_OFF.

Since:

BlackBerry API 4.2.1

getSensitivityYForSystem

public static int getSensitivityYForSystem()

Retrieves the Y-axis sensitivity setting for the system.

Returns:

Percentage value.

Since:

BlackBerry API 4.2.1

isFeedbackAudibleForSystem

public static boolean isFeedbackAudibleForSystem()

Determines whether or not there is an audible click associated with rolling the trackball.

Returns:

True if there is an audible click associated with rolling the trackball; false otherwise.

Since:

BlackBerry API 4.2.1

isSupported

public static boolean isSupported()

Determines whether or not the system supports a trackball device.

Returns:

True if the system supports a trackball device; false otherwise.

Since:

BlackBerry API 4.2.1

isOpticalSupported

public static boolean isOpticalSupported()

Determines whether or not the device supports an optical trackball or trackpad.

Returns:

true if the device supports an optical trackball or trackball; false otherwise.

Since:

BlackBerry API 5.0.0

setFilter

public static void setFilter(int filter)

Sets the trackball movement filter for the calling process.

Parameters:

filter - A bitmask of the FILTER_* constants.

Throws:

IllegalArgumentException - if filter is not a bitmask of the FILTER_* constants.

Since:

BlackBerry API 4.2.1

setSensitivityX

public static void setSensitivityX(int sensitivity)

Sets the X-axis sensitivity for the calling process.

Parameters:

sensitivity - Percentage value, Trackball.SENSITIVITY_UNSET or Trackball.SENSITIVITY_OFF.

Throws:

IllegalArgumentException - if sensitivity is not between 0-100, and is not SENSITIVITY_UNSET or SENSITIVITY_OFF.

Since:

BlackBerry API 4.2.1

setSensitivityY

public static void setSensitivityY(int sensitivity)

Sets the Y-axis sensitivity for the calling process.

Parameters:

sensitivity - Percentage value, Trackball.SENSITIVITY_UNSET or Trackball.SENSITIVITY_OFF.

Throws:

IllegalArgumentException - if sensitivity is not between 0-100, and is not SENSITIVITY_UNSET or SENSITIVITY_OFF.

Since:

BlackBerry API 4.2.1