lejos.nxt
Class Button

java.lang.Object
  lejos.nxt.Button

All Implemented Interfaces:

ListenerCaller

public class Button
extends Object
implements ListenerCaller

Abstraction for an NXT button. Example:

   Button.ENTER.waitForPressAndRelease();
   Sound.playTone (1000, 1);
 

Notions: The API is designed around two notions: states (up / down) and events (press / release). It is said that a button is pressed (press event), if its state changes from up to down. Similarly, it is said that a button is released (release event), if its states changed from down to up. Thread Safety: All methods that return buttons states can be used safely from multiple threads, even while a call to one of the waitFor* methods active. However, it is not safe to invoke waitFor* methods in parallel from different threads. This includes the waitFor* methods of different buttons. For example Button.ENTER.waitForPress() must not be invoked in parallel to Button.ESCAPE.waitForPress() or the static Button.waitForAnyEvent(). In case this is needed, it is strongly recommended that you write your own Thread, which waits for button events and dispatches the events to anyone who's interested.

Field Summary

static Button[]	BUTTONS Deprecated. this array will be removed
static Button	ENTER The Enter button.
static Button	ESCAPE The Escape button.
static int	ID_ENTER
static int	ID_ESCAPE
static int	ID_LEFT
static int	ID_RIGHT
static Button	LEFT The Left button.
static Button	RIGHT The Right button.
static String	VOL_SETTING

Method Summary

void	addButtonListener(ButtonListener aListener) Adds a listener of button events.
int	callListeners() Call Button Listeners.
static void	discardEvents() This method discards and events.
int	getId() Return the ID of the button.
static int	getKeyClickLength() Return the current key click length.
static int	getKeyClickTone(int key) Return the click freq for a particular key.
static int	getKeyClickVolume() Return the current key click volume.
boolean	isDown() Check if the current state of the button is down.
boolean	isPressed() Deprecated. use isDown() instead.
boolean	isUp() Check if the current state of the button is up.
static void	loadSettings() Deprecated. replaced by loadSystemSettings().
static void	loadSystemSettings() Load the current system settings associated with this class.
static int	readButtons() Low-level API that reads status of buttons.
static void	setKeyClickLength(int len) Set the len used for key clicks
static void	setKeyClickTone(int key, int freq) Set the frequency used for a particular key.
static void	setKeyClickVolume(int vol) Set the volume used for key clicks
static int	waitForAnyEvent(int timeout) Waits for some button to be pressed or released.
static int	waitForAnyPress() Waits for some button to be pressed.
static int	waitForAnyPress(int timeout) Waits for some button to be pressed.
void	waitForPress() Wait until the button is released.
void	waitForPressAndRelease() Wait until the button is released.

Methods inherited from class java.lang.Object

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

Field Detail

ID_ENTER

public static final int ID_ENTER

See Also:

Constant Field Values

ID_LEFT

public static final int ID_LEFT

See Also:

Constant Field Values

ID_RIGHT

public static final int ID_RIGHT

See Also:

Constant Field Values

ID_ESCAPE

public static final int ID_ESCAPE

See Also:

Constant Field Values

VOL_SETTING

public static final String VOL_SETTING

See Also:

Constant Field Values

ENTER

public static final Button ENTER

The Enter button.

LEFT

public static final Button LEFT

The Left button.

RIGHT

public static final Button RIGHT

The Right button.

ESCAPE

public static final Button ESCAPE

The Escape button.

BUTTONS

@Deprecated
public static final Button[] BUTTONS

Deprecated. this array will be removed

Array containing ENTER, LEFT, RIGHT, ESCAPE, in that order.

Method Detail

getId

public final int getId()

Return the ID of the button. One of 1, 2, 4 or 8.

Returns:

the button Id

isPressed

@Deprecated
public final boolean isPressed()

Deprecated. use isDown() instead.

isDown

public final boolean isDown()

Check if the current state of the button is down.

Returns:

true if button is down, false if up.

isUp

public final boolean isUp()

Check if the current state of the button is up.

Returns:

true if button is down, false if up.

waitForPress

public final void waitForPress()

Wait until the button is released.

waitForPressAndRelease

public final void waitForPressAndRelease()

Wait until the button is released.

discardEvents

public static void discardEvents()

This method discards and events. In contrast to readButtons(), this method doesn't beep if a button is pressed.

waitForAnyEvent

public static int waitForAnyEvent(int timeout)

Waits for some button to be pressed or released. Which buttons have been released or pressed is returned as a bitmask. The lower eight bits (bits 0 to 7) indicate, which buttons have been pressed. Bits 8 to 15 indicate which buttons have neem released.

Parameters:

timeout - The maximum number of milliseconds to wait

Returns:

the bitmask

See Also:

ID_ENTER, ID_LEFT, ID_RIGHT, ID_ESCAPE

waitForAnyPress

public static int waitForAnyPress(int timeout)

Waits for some button to be pressed. If a button is already pressed, it must be released and pressed again.

Parameters:

timeout - The maximum number of milliseconds to wait

Returns:

the ID of the button that has been pressed or in rare cases a bitmask of button IDs, 0 if the given timeout is reached

waitForAnyPress

public static int waitForAnyPress()

Waits for some button to be pressed. If a button is already pressed, it must be released and pressed again.

Returns:

the ID of the button that has been pressed or in rare cases a bitmask of button IDs

addButtonListener

public void addButtonListener(ButtonListener aListener)

Adds a listener of button events. Each button can serve at most 4 listeners.

Parameters:

aListener - The new listener

readButtons

public static int readButtons()

Low-level API that reads status of buttons.

Returns:

An integer with possibly some bits set: ID_ENTER (ENTER button pressed) ID_LEFT (LEFT button pressed), ID_RIGHT (RIGHT button pressed), ID_ESCAPE (ESCAPE button pressed). If all buttons are released, this method returns 0.

callListeners

public int callListeners()

Call Button Listeners. Used by ListenerThread.

Specified by:

callListeners in interface ListenerCaller

Returns:

New event filter

setKeyClickVolume

public static void setKeyClickVolume(int vol)

Set the volume used for key clicks

Parameters:

vol -

getKeyClickVolume

public static int getKeyClickVolume()

Return the current key click volume.

Returns:

current click volume

setKeyClickLength

public static void setKeyClickLength(int len)

Set the len used for key clicks

Parameters:

len - the click duration

getKeyClickLength

public static int getKeyClickLength()

Return the current key click length.

Returns:

key click duration

setKeyClickTone

public static void setKeyClickTone(int key,
                                   int freq)

Set the frequency used for a particular key. Setting this to 0 disables the click. Note that key may also be a corded set of keys.

Parameters:

key - the NXT key

freq - the frequency

getKeyClickTone

public static int getKeyClickTone(int key)

Return the click freq for a particular key.

Parameters:

key - The key to obtain the tone for

Returns:

key click duration

loadSettings

@Deprecated
public static void loadSettings()

Deprecated. replaced by loadSystemSettings().

loadSystemSettings

public static void loadSystemSettings()

Load the current system settings associated with this class. Called automatically to initialize the class. May be called if it is required to reload any settings.