edu.mines.jtk.awt
Class Mode

java.lang.Object
  javax.swing.AbstractAction
      edu.mines.jtk.awt.Mode

All Implemented Interfaces:

java.awt.event.ActionListener, java.io.Serializable, java.lang.Cloneable, java.util.EventListener, javax.swing.Action

Direct Known Subclasses:

MouseTrackMode, OrbitViewMode, SelectDragMode, TileZoomMode

public abstract class Mode
extends javax.swing.AbstractAction

An abstract mode of interaction.

A mode can be activated or deactivated, by setting its active state. An active mode responds to input events in some mode-specific manner. An inactive mode ignores all input events.

A mode is an action, so it can be used to construct toggle buttons and menu items. A mode, like any action, may be enabled or disabled. While enabled, a mode may be active or inactive. While disabled, a mode is inactive, and cannot be activated.

A mode has a manager, which coordinates the activation of modes that may be mutually exclusive. When an exclusive mode is activated, the mode's manager first deactivates any other exclusive modes, thereby ensuring that no more than one exclusive mode is active at any time. By default, modes are exclusive, but this property may be overridden.

Version:

2004.12.29

Author:

Dave Hale, Colorado School of Mines

See Also:

Serialized Form

Field Summary

Fields inherited from class javax.swing.AbstractAction

changeSupport, enabled

Fields inherited from interface javax.swing.Action

ACCELERATOR_KEY, ACTION_COMMAND_KEY, DEFAULT, LONG_DESCRIPTION, MNEMONIC_KEY, NAME, SHORT_DESCRIPTION, SMALL_ICON

Constructor Summary

protected

Mode(ModeManager manager) Constructs a mode with specified manager, name, and icon.

Method Summary

void	actionPerformed(java.awt.event.ActionEvent event) Toggles the active state of this mode.
java.awt.Cursor	getCursor() Gets the cursor for this mode.
boolean	isActive() Determines whether this mode is active.
boolean	isExclusive() Determines whether or not this mode is exclusive.
protected static java.awt.Cursor	loadCursor(java.lang.Class<?> cls, java.lang.String res, int x, int y) Loads a cursor from the specified resource name.
protected static javax.swing.Icon	loadIcon(java.lang.Class<?> cls, java.lang.String res) Loads an icon from the specified resource name.
void	setAcceleratorKey(javax.swing.KeyStroke ak) Sets the accelerator key stroke for this mode.
void	setActive(boolean active) Activates or deactivates this mode.
protected abstract void	setActive(java.awt.Component component, boolean active) Activates or deactivates this mode for the specified component.
void	setCursor(java.awt.Cursor cursor) Sets the cursor for this mode.
void	setEnabled(boolean enabled)
void	setIcon(javax.swing.Icon icon) Sets the icon for this mode.
void	setLongDescription(java.lang.String ld) Sets the long description for this mode.
void	setMnemonicKey(int mk) Sets the mnemonic key for this mode.
void	setName(java.lang.String name) Sets the name (text) for this mode.
void	setShortDescription(java.lang.String sd) Sets the short description for this mode.

Methods inherited from class javax.swing.AbstractAction

addPropertyChangeListener, clone, firePropertyChange, getKeys, getPropertyChangeListeners, getValue, isEnabled, putValue, removePropertyChangeListener

Methods inherited from class java.lang.Object

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

Constructor Detail

Mode

protected Mode(ModeManager manager)

Constructs a mode with specified manager, name, and icon.

Parameters:

manager - the manager.

Method Detail

setActive

public void setActive(boolean active)

Activates or deactivates this mode. If this mode is not enabled, this method does nothing.

Parameters:

active - true, to activate; false, to deactivate.

isActive

public boolean isActive()

Determines whether this mode is active.

Returns:

true, if active; false, if inactive.

isExclusive

public boolean isExclusive()

Determines whether or not this mode is exclusive. Exclusive modes cannot coexist with other exclusive modes that have the same manager. This implementation simply returns true. Non-exclusive modes should override this method to return false.

Returns:

true, if exclusive; false, otherwise.

actionPerformed

public void actionPerformed(java.awt.event.ActionEvent event)

Toggles the active state of this mode.

Parameters:

event - the action event (ignored).

setEnabled

public void setEnabled(boolean enabled)

Specified by:

setEnabled in interface javax.swing.Action

Overrides:

setEnabled in class javax.swing.AbstractAction

setName

public void setName(java.lang.String name)

Sets the name (text) for this mode. Used for mode menu items.

Typically, this method is called by constructors in classes that extend this abstract base class.

Parameters:

name - the name.

setIcon

public void setIcon(javax.swing.Icon icon)

Sets the icon for this mode. Used for mode toggle buttons.

Typically, this method is called by constructors in classes that extend this abstract base class.

Parameters:

icon - the icon.

setMnemonicKey

public void setMnemonicKey(int mk)

Sets the mnemonic key for this mode. Used for mode menu items.

Typically, this method is called by constructors in classes that extend this abstract base class.

Parameters:

mk - the mnemonic key; e.g., KeyEvent.VK_K.

setAcceleratorKey

public void setAcceleratorKey(javax.swing.KeyStroke ak)

Sets the accelerator key stroke for this mode.

Typically, this method is called by constructors in classes that extend this abstract base class.

Parameters:

ak - the accelerator key stroke.

setShortDescription

public void setShortDescription(java.lang.String sd)

Sets the short description for this mode. Used in tool tips for mode menu items and toggle buttons.

Typically, this method is called by constructors in classes that extend this abstract base class.

Parameters:

sd - the short description.

setLongDescription

public void setLongDescription(java.lang.String ld)

Sets the long description for this mode.

Typically, this method is called by constructors in classes that extend this abstract base class.

Parameters:

ld - the long description.

setCursor

public void setCursor(java.awt.Cursor cursor)

Sets the cursor for this mode. If not null, the specified cursor is used when this mode is active.

Parameters:

cursor - the cursor; null, if the default cursor should be used.

getCursor

public java.awt.Cursor getCursor()

Gets the cursor for this mode.

Returns:

the cursor; null, if the default cursor should be used.

loadIcon

protected static javax.swing.Icon loadIcon(java.lang.Class<?> cls,
                                           java.lang.String res)

Loads an icon from the specified resource name. The resource with specified name is found relative to the specified class.

Parameters:

cls - the class used to find the resource.

res - the name of the resource that contains the icon.

loadCursor

protected static java.awt.Cursor loadCursor(java.lang.Class<?> cls,
                                            java.lang.String res,
                                            int x,
                                            int y)

Loads a cursor from the specified resource name. The resource with specified name is found relative to the specified class.

Parameters:

cls - the class used to find the resource.

res - the name of the resource that contains the cursor image.

x - the x coordinate of the cursor hot spot

y - the y coordinate of the cursor hot spot

setActive

protected abstract void setActive(java.awt.Component component,
                                  boolean active)

Activates or deactivates this mode for the specified component. Typically, in their implementations of this method, modes add or remove input event listeners, when the mode is applicable to the specified component or type of component.

This method should not be called directly. The mode's manager calls this method for all of its components. Implementations of this method should do nothing for components for which the mode is inapplicable.

Parameters:

component - the component for which to enable the mode.

active - true, to activate; false, to deactivate.