org.eclipse.ercp.swt.mobile
Class Command

java.lang.Object
  org.eclipse.swt.widgets.Widget
      org.eclipse.swt.widgets.Item
          org.eclipse.ercp.swt.mobile.Command

public class Command

extends Item

Command is a metaphor that represents a general action. Command contains no information about the behavior that happens when a command is activated. The concrete action is defined in a SelectionListener. Commands may be implemented using any user interface construct that has semantics for activating a single action. Some implementations may implement commands as widgets, such as buttons or menu items, or voice tags. However, the implementation should not adversely affect an application's layout when realizing commands.

A Command must be associated with a control and only becomes accessible when that control is in the current focus context. The current focus context includes the control that currently has focus and all of its visible ancestor controls up through the lowest level Shell. The term visible above refers to widgets which are not explicitly hidden by calling setVisible(false). The focus contenxt does not include siblings of the control with focus or ancestors of the lowest level Shell.

The implementation guarantees that all commands within the current focus context are accessible. However, the concrete method for doing this is device-specific and implementation-dependent. Commands may be bound to hardware keys or device softkeys. As various devices have a different number of keys, the conventional way to place commands by indexing is not appropriate, especially as there may be more commands than available keys. The placement of commands is also dynamic. For example, new commands can be added by the implementation at run-time in order to facilitate some context-related operations. Therefore, the implementation uses various information to place commands:

• Command type is a hint used by the implementation to associate commands with specific keys. It is common to bind more than one command of the same type to a control. In such cases, command precedence rules are used to determine which command is assigned to a key and which others are placed on a menu. Command type is not used for ordering within menus.


• When multiple commands are in competition for key or menu assignment, the priority argument is used to help determine assignment and order. The lowest value (zero) has the lowest precedence (and appears visually lowest in menus). If priority values of competing commands are the same, higher precedence is given to commands created first. Commands bound to the currently focused control are always given higher precedence than commands bounds to ancestor controls regardless of their priority value. Commands and CommandGroups within the same command menu are ordered by priority value.

A default command means that a command can be activated via a device selection key or any other "short-cut" like the concept of default button in a shell. Usually the default command has a different visual style to make it distinguishable from other commands. Within a focus context, there can only be one default command at any time. A command becomes the default one via the method "setDefaultCommand", and any previous default command becomes non-default.

When pressing the key associated with a command, a SelectionEvent will be delivered to all the command's SelectionListeners, if any.

Commands can have a long label (setLongLabel(String)), which is typically used for when a command is assigned to a menu. The long label is optional. If the long label is not present on a command, the default text label (setText(String)) is used. The default label should be as short as possible so that it consumes a minimum of screen real estate. The long label can be longer and more descriptive, but it should be no longer than a few words. For example, a command's default label might be "Play", and its long label might be "Play Sound Clip". Labeling of command menus is implementation-dependent.

Note that although this class is a subclass of Item and allows setting the image even if the underlying platform does not. But in this case the image is not displayed.

Example 1: Single Command per Control (within a focus context of List and its parent)

 List list = new List(parent, SWT.SINGLE); // a single selection list
 Command cmd1 = new Command(list, Command.SELECT, 1);
 cmd1.setText("Open");
 cmd1.addSelectionListener(new SelectionListener() {
 	public void widgetSelected(SelectionEvent e) {
 		System.out.println("Command " + e.data + " pressed.");
 		// e.widget contains the Command object. 
 	}
 });
 Command cmd2 = new Command(parent, Command.GENERAL, 0);
 cmd2.setText("New");
 cmd2.addSelectionListener(new SelectionListener() {
 	public void widgetSelected(SelectionEvent e) {
 		System.out.println("Command " + e.data + " pressed.");
 		// e.widget contains the Command object. 
 	}
 });
 

Example 2: Multiple Commands per Control and DefaultCommand

 List list = new List(composite1, SWT.SINGLE);
 Command cmd1 = new Command(list, Command.SELECT, 0);
 cmd1.setText("Open");
 cmd1.setDefaultCommand();
 Command cmd2 = new Command(list, Command.SELECT, 0);
 cmd2.setText("Edit");
 Command cmd3 = new Command(list, Command.SELECT, 0);
 cmd3.setText("Delete");
 Command cmd4 = new Command(composite1, Command.EXIT, 0); // create a EXIT type
 cmd4.setText("Exit");
 

Command types:

COMMANDGROUP: represents a special command that contains sub-commands

GENERAL, SELECT, OK, CANCEL, DELETE, BACK, EXIT, STOP, HELP: Logical command types

Events:

Selection

IMPORTANT: This class is not intended to be subclassed.

Field Summary

static int	BACK A command that hints to the implementation to navigate backward.
static int	CANCEL A command that is a standard negative answer to an action.
static int	COMMANDGROUP A special command used for grouping commands.
static int	DELETE This command hints to the implementation to destroy data.
static int	EXIT A command that indicates an exiting action.
static int	GENERAL A command that can be bound to any hardware keys or softkeys.
static int	HELP A command that specifies a request for on-line help.
static int	OK A navigation command that returns the user to the logical OK action.
static int	SELECT A command that represents the context-sensitive action.
static int	STOP A command that stops some currently running process, operation, etc.

Constructor Summary

Command(Command command, int type, int priority)
Constructs a new instance of this class given an associated Command, a type value describing its behaviour and priority for positioning hints.

Command(Control control, int type, int priority)
Constructs a new instance of this class given an associated Control, a type value describing its behaviour and priority for positioning hints.

Method Summary

void	addSelectionListener(SelectionListener listener) Adds the listener to the collection of listeners who will be notified when the command is activated, by sending it one of the messages defined in the SelectionListener interface.
boolean	getEnabled() Returns true if the receiver is enabled, and false otherwise.
java.lang.String	getLongLabel() Returns the command's long label, which shall be null if it has never been set.
int	getPriority() Returns the command's priority value.
boolean	isDefaultCommand() Returns true if the command is a Default Command, and false otherwise.
boolean	isEnabled() Returns true if the receiver is enabled and all of the receiver's ancestors are enabled, and false otherwise.
void	removeSelectionListener(SelectionListener listener) Removes the listener from the collection of listeners who will be notified when the command is activated.
void	setAccelerator(int accelerator) Sets the command accelerator.
void	setDefaultCommand() Sets the default command.
void	setEnabled(boolean enabled) Enables the command if the argument is true, and disables it otherwise.
void	setLongLabel(java.lang.String label) Sets the command's long label text.

Methods inherited from class org.eclipse.swt.widgets.Item

checkSubclass, getImage, getText, setImage, setText

Methods inherited from class org.eclipse.swt.widgets.Widget

addDisposeListener, addListener, checkWidget, dispose, getData, getData, getDisplay, getStyle, isDisposed, isListening, notifyListeners, removeDisposeListener, removeListener, removeListener, setData, setData, toString

Methods inherited from class java.lang.Object

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

Field Detail

GENERAL

public static final int GENERAL

A command that can be bound to any hardware keys or softkeys.

Value 1 is assigned to GENERAL.

See Also:

Constant Field Values

SELECT

public static final int SELECT

A command that represents the context-sensitive action.

Value 2 is assigned to SELECT.

See Also:

Constant Field Values

COMMANDGROUP

public static final int COMMANDGROUP

A special command used for grouping commands. This command does not fire SelectionEvents if there are any commands associated. Instead, pressing down the command results in displaying sub-commands.

Value 10 is assigned to COMMANDGROUP.

See Also:

Constant Field Values

OK

public static final int OK

A navigation command that returns the user to the logical OK action.

Value 3 is assigned to OK.

See Also:

Constant Field Values

CANCEL

public static final int CANCEL

A command that is a standard negative answer to an action.

With this command type, the application hints to the implementation that the user wants to dismiss the current action.

Value 4 is assigned to CANCEL.

See Also:

Constant Field Values

DELETE

public static final int DELETE

This command hints to the implementation to destroy data.

Value 5 is assigned to DELETE.

See Also:

Constant Field Values

BACK

public static final int BACK

A command that hints to the implementation to navigate backward.

Value 6 is assigned to BACK.

See Also:

Constant Field Values

EXIT

public static final int EXIT

A command that indicates an exiting action.

Value 7 is assigned to EXIT.

See Also:

Constant Field Values

STOP

public static final int STOP

A command that stops some currently running process, operation, etc. Nothing is stopped automatically by the implementation.

Value 8 is assigned to STOP.

See Also:

Constant Field Values

HELP

public static final int HELP

A command that specifies a request for on-line help. No help information is shown automatically by the implementation. The application is responsible for answering the event.

Value 9 is assigned to HELP.

See Also:

Constant Field Values

Constructor Detail

Command

public Command(Command command,
               int type,
               int priority)

Constructs a new instance of this class given an associated Command, a type value describing its behaviour and priority for positioning hints.

The constructor creates a command associated with a Command (cannot be null and must be COMMANDGROUP type). The implementation must group commands within the same command group.

Parameters:

command - the associated Command. It must be COMMANDGROUP type. Otherwise throw an exception.

type - the type of Command to construct

priority - the priority value. The lowest value (zero) has the lowest precedence.

Throws:

java.lang.IllegalArgumentException -

• ERROR_INVALID_ARGUMENT - if the command type is not COMMANDGROUP
• ERROR_INVALID_ARGUMENT - if the type is not one of the valid command types
• ERROR_INVALID_ARGUMENT - if the priority is less than zero
• ERROR_NULL_ARGUMENT - if the command is null

SWTException -

• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent
• ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass

See Also:

GENERAL, SELECT, OK, CANCEL, DELETE, BACK, EXIT, STOP, HELP

Command

public Command(Control control,
               int type,
               int priority)

Constructs a new instance of this class given an associated Control, a type value describing its behaviour and priority for positioning hints.

The type value is one of the type constants defined in class Command

Parameters:

control - the associated Control

type - the type of Command to construct

priority - the priority value. The lowest value (zero) has the lowest precedence.

Throws:

java.lang.IllegalArgumentException -

• ERROR_INVALID_ARGUMENT - if the type is not one of the valid command types
• ERROR_INVALID_ARGUMENT - if the priority is less than zero
• ERROR_NULL_ARGUMENT - if the control is null

SWTException -

• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent
• ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass

See Also:

GENERAL, SELECT, OK, CANCEL, DELETE, BACK, EXIT, STOP, HELP

Method Detail

addSelectionListener

public void addSelectionListener(SelectionListener listener)

Adds the listener to the collection of listeners who will be notified when the command is activated, by sending it one of the messages defined in the SelectionListener interface.

When widgetSelected is called, the stateMask field of the event object is valid. widgetDefaultSelected is not called.

Parameters:

listener - the listener which should be notified

Throws:

java.lang.IllegalArgumentException -

• ERROR_NULL_ARGUMENT - if the listener is null

SWTException -

• ERROR_WIDGET_DISPOSED - if the receiver has been disposed
• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent

See Also:

SelectionListener, removeSelectionListener(org.eclipse.swt.events.SelectionListener)

getEnabled

public boolean getEnabled()

Returns true if the receiver is enabled, and false otherwise. A disabled control is typically not selectable from the user interface and draws with an inactive or "grayed" look.

Returns:

the receiver's enabled state

Throws:

SWTException -

• ERROR_WIDGET_DISPOSED - if the receiver has been disposed
• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent

See Also:

isEnabled()

getLongLabel

public java.lang.String getLongLabel()

Returns the command's long label, which shall be null if it has never been set.

Returns:

the receiver's text. Can be null.

Throws:

SWTException -

• ERROR_WIDGET_DISPOSED - if the receiver has been disposed
• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent

See Also:

setLongLabel(String)

getPriority

public int getPriority()

Returns the command's priority value.

Returns:

the priority value.

Throws:

SWTException -

• ERROR_WIDGET_DISPOSED - if the receiver has been disposed
• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent

isDefaultCommand

public boolean isDefaultCommand()

Returns true if the command is a Default Command, and false otherwise. By default a command is not a default one.

Returns:

boolean the command's state

Throws:

SWTException -

• ERROR_WIDGET_DISPOSED - if the receiver has been disposed
• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent

See Also:

setDefaultCommand()

isEnabled

public boolean isEnabled()

Returns true if the receiver is enabled and all of the receiver's ancestors are enabled, and false otherwise. A disabled control is typically not selectable from the user interface and draws with an inactive or "grayed" look.

Returns:

boolean the receiver's enabled state

Throws:

SWTException -

• ERROR_WIDGET_DISPOSED - if the receiver has been disposed
• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent

See Also:

getEnabled()

removeSelectionListener

public void removeSelectionListener(SelectionListener listener)

Removes the listener from the collection of listeners who will be notified when the command is activated.

Parameters:

listener - the listener which should be notified

Throws:

java.lang.IllegalArgumentException -

• ERROR_NULL_ARGUMENT - if the listener is null

SWTException -

• ERROR_WIDGET_DISPOSED - if the receiver has been disposed
• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent

See Also:

SelectionListener, addSelectionListener(org.eclipse.swt.events.SelectionListener)

setAccelerator

public void setAccelerator(int accelerator)

Sets the command accelerator. An accelerator is the bit-wise OR of zero or more modifier masks and a key. Examples: SWT.MOD1 | SWT.MOD2 | 'T', SWT.CONTROL | SWT.SHIFT | 'T'. This requires fullkeyboard or computer keyboard-like support and is an implementation-dependent feature. It will be gracefully ignored if the implementation does not support keyboard accelerator.

Parameters:

accelerator - an integer that is the bit-wise OR of masks and a key

Throws:

java.lang.IllegalArgumentException -

• ERROR_INVALID_ARGUMENT - if accelerator value is invalid

SWTException -

• ERROR_WIDGET_DISPOSED - if the receiver has been disposed
• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent

setDefaultCommand

public void setDefaultCommand()

Sets the default command.

setEnabled

public void setEnabled(boolean enabled)

Enables the command if the argument is true, and disables it otherwise. A disabled control is typically not selectable from the user interface and draws with an inactive or "grayed" look; or even completely removed from the user interface.

Parameters:

enabled - the new enabled state

Throws:

SWTException -

• ERROR_WIDGET_DISPOSED - if the receiver has been disposed
• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent

setLongLabel

public void setLongLabel(java.lang.String label)

Sets the command's long label text. Commands may optionally have long labels, enabling the application to specify a short form for button or softkey, and a more verbose form when realized as menu item.

Parameters:

label - the long descriptive label text. Can be null.

Throws:

SWTException -

• ERROR_WIDGET_DISPOSED - if the receiver has been disposed
• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent

See Also:

getLongLabel()