org.havi.ui
Class HTextButton

java.lang.Object
  extended byjava.awt.Component
      extended byorg.havi.ui.HComponent
          extended byorg.havi.ui.HVisible
              extended byorg.havi.ui.HStaticText
                  extended byorg.havi.ui.HText
                      extended byorg.havi.ui.HTextButton
All Implemented Interfaces:
HActionable, HActionInputPreferred, HMatteLayer, HNavigable, HNavigationInputPreferred, HNoInputPreferred, HState, java.awt.image.ImageObserver, java.io.Serializable, TestOpacity

public class HTextButton
extends HText
implements HActionable

The HTextButton is a user interface component representing a push-button with static read-only textual content. This component can be navigated to, i.e. it can have the input focus, and it can also be actioned as defined by the HActionable interface. By default it uses the HTextLook class to render itself.


The parameters to the constructors are as follows, in cases where parameters are not used, then the constructor should use the default values.

Default parameter values exposed in the constructors

ParameterDescriptionDefault value Set methodGet method
x x-coordinate of top left hand corner of this component in pixels, relative to its parent container (subject to layout management). --- java.awt.Component#setBounds java.awt.Component#getBounds
y y-coordinate of top left hand corner of this component in pixels, relative to its parent container (subject to layout management). --- java.awt.Component#setBounds java.awt.Component#getBounds
width width of this component in pixels (subject to layout management). --- java.awt.Component#setBounds java.awt.Component#getBounds
height height of this component in pixels (subject to layout management). --- java.awt.Component#setBounds java.awt.Component#getBounds
text The text to be used as the content for every permissible state of this component. null setTextContent getTextContent
tlm The text layout manager responsible for text formatting. An HDefaultTextLayoutManager object. setTextLayoutManager getTextLayoutManager
font The font for this component. --- java.awt.Component#setFont java.awt.Component#getFont
background The background color for this component. --- java.awt.Component#getBackground java.awt.Component#setBackground
foreground The foreground color for this component. --- java.awt.Component#getForeground java.awt.Component#setForeground

Default parameter values not exposed in the constructors

DescriptionDefault valueSet method Get method
Associated matte (HMatte). none (i.e. getMatte() returns null) setMatte getMatte
The text layout manager responsible for text formatting. An HDefaultTextLayoutManager object. HVisible.setTextLayoutManager(org.havi.ui.HTextLayoutManager) HVisible.getTextLayoutManager()
The background painting mode HVisible.NO_BACKGROUND_FILL HVisible.setBackgroundMode(int) HVisible.getBackgroundMode()
The default preferred size not set (i.e. NO_DEFAULT_SIZE) unless specified by width and height parameters HVisible.setDefaultSize(java.awt.Dimension) HVisible.getDefaultSize()
The horizontal content alignment HVisible.HALIGN_CENTER HVisible.setHorizontalAlignment(int) HVisible.getHorizontalAlignment()
The vertical content alignment HVisible.VALIGN_CENTER HVisible.setVerticalAlignment(int) HVisible.getVerticalAlignment()
The content scaling mode HVisible.RESIZE_NONE HVisible.setResizeMode(int) HVisible.getResizeMode()
The border mode true HVisible.setBordersEnabled(boolean) HVisible.getBordersEnabled()
The default "look" for this class. A platform specific HTextLook HTextButton.setDefaultLook HTextButton.getDefaultLook
The "look" for this object. The HTextLook returned from HTextButton.getDefaultLook when this object was created. HTextButton.setLook HTextButton.getLook
The gain focus sound. null setGainFocusSound getGainFocusSound
The lose focus sound. null setLoseFocusSound getLoseFocusSound
The action sound. null setActionSound getActionSound

See Also:
HStaticText, HText, HDefaultTextLayoutManager, HTextLayoutManager, HNavigable, HActionable, Serialized Form

Field Summary
 
Fields inherited from class org.havi.ui.HVisible
ADJUSTMENT_VALUE_CHANGE, ANIMATE_CONTENT_CHANGE, ANIMATION_POSITION_CHANGE, BACKGROUND_FILL, BORDER_CHANGE, CARET_POSITION_CHANGE, CONTENT_CHANGE, ECHO_CHAR_CHANGE, EDIT_MODE_CHANGE, FIRST_CHANGE, GRAPHIC_CONTENT_CHANGE, HALIGN_CENTER, HALIGN_JUSTIFY, HALIGN_LEFT, HALIGN_RIGHT, ITEM_VALUE_CHANGE, LAST_CHANGE, LIST_CONTENT_CHANGE, LIST_ICONSIZE_CHANGE, LIST_LABELSIZE_CHANGE, LIST_MULTISELECTION_CHANGE, LIST_SCROLLPOSITION_CHANGE, LIST_SELECTION_CHANGE, MIN_MAX_CHANGE, NO_BACKGROUND_FILL, NO_DEFAULT_HEIGHT, NO_DEFAULT_SIZE, NO_DEFAULT_WIDTH, ORIENTATION_CHANGE, REPEAT_COUNT_CHANGE, RESIZE_ARBITRARY, RESIZE_NONE, RESIZE_PRESERVE_ASPECT, SIZE_CHANGE, STATE_CHANGE, TEXT_CONTENT_CHANGE, TEXT_VALUE_CHANGE, THUMB_OFFSETS_CHANGE, UNKNOWN_CHANGE, VALIGN_BOTTOM, VALIGN_CENTER, VALIGN_JUSTIFY, VALIGN_TOP
 
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
 
Fields inherited from interface org.havi.ui.HState
ACTIONED_FOCUSED_STATE, ACTIONED_STATE, ACTIONED_STATE_BIT, ALL_STATES, DISABLED_ACTIONED_FOCUSED_STATE, DISABLED_ACTIONED_STATE, DISABLED_FOCUSED_STATE, DISABLED_STATE, DISABLED_STATE_BIT, FIRST_STATE, FOCUSED_STATE, FOCUSED_STATE_BIT, LAST_STATE, NORMAL_STATE
 
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
 
Constructor Summary
HTextButton()
          Creates an HTextButton object.
HTextButton(java.lang.String text)
          Creates an HTextButton object.
HTextButton(java.lang.String text, java.awt.Font font, java.awt.Color foreground, java.awt.Color background, HTextLayoutManager tlm)
          Creates an HTextButton object.
HTextButton(java.lang.String text, int x, int y, int width, int height)
          Creates an HTextButton object.
HTextButton(java.lang.String text, int x, int y, int width, int height, java.awt.Font font, java.awt.Color foreground, java.awt.Color background, HTextLayoutManager tlm)
          Creates an HTextButton object.
 
Method Summary
 void addHActionListener(HActionListener l)
          Adds the specified HActionListener to receive HActionEvent events sent from this HTextButton.
 void addHFocusListener(HFocusListener l)
          Adds the specified HFocusListener to receive HFocusEvent events sent from this HNavigable: If the listener has already been added further calls will add further references to the listener, which will then receive multiple copies of a single event.
 java.lang.String getActionCommand()
          Gets the command name for the HActionEvent event fired by this HTextButton.
 HSound getActionSound()
          Return the last action sound set by the setActionSound() method or null if no action sound has been set.
static HTextLook getDefaultLook()
          Returns the currently set default HLook for HTextButton components.
 HSound getGainFocusSound()
          Get the sound associated with the gain focus event.
 HSound getLoseFocusSound()
          Get the sound associated with the lost focus event.
 HNavigable getMove(int keyCode)
          Provides the HNavigable object that is navigated to when a particular key is pressed.
 int[] getNavigationKeys()
          Retrieve the set of key codes which this component maps to navigation targets.
 boolean isSelected()
          Indicates if this component has focus.
 void processHActionEvent(HActionEvent evt)
          Process an HActionEvent sent to this HTextButton.
 void processHFocusEvent(HFocusEvent evt)
          Process an HFocusEvent sent to this HTextButton.
 void removeHActionListener(HActionListener l)
          Removes the specified HActionListener so that it no longer receives HActionEvent events from this HTextButton.
 void removeHFocusListener(HFocusListener l)
          Removes the specified HFocusListener so that it no longer receives HFocusEvent events from this HNavigable.
 void setActionCommand(java.lang.String command)
          Sets the command name for the HActionEvent event fired by this HTextButton.
 void setActionSound(HSound sound)
          Associate a sound to be played when the interaction state of the HTextButton makes the following transitions: _NORMAL_STATE to _ACTIONED_STATE _FOCUSED_STATE to _ACTIONED_FOCUSED_STATE
static void setDefaultLook(HTextLook hlook)
          Sets the default HLook for further HTextButton components.
 void setFocusTraversal(HNavigable up, HNavigable down, HNavigable left, HNavigable right)
          Set the focus control for an HNavigable component.
 void setGainFocusSound(HSound sound)
          Associate a sound with gaining focus, i.e. when the HNavigable receives a HFocusEvent event of type FOCUS_GAINED.
 void setLoseFocusSound(HSound sound)
          Associate a sound with losing focus, i.e. when the HNavigable receives a HFocusEvent event of type FOCUS_LOST.
 void setMove(int keyCode, HNavigable target)
          Defines the navigation path from the current HNavigable to another HNavigable when a particular key is pressed.
 
Methods inherited from class org.havi.ui.HStaticText
setLook
 
Methods inherited from class org.havi.ui.HVisible
getAnimateContent, getBackgroundMode, getBordersEnabled, getContent, getDefaultSize, getGraphicContent, getHorizontalAlignment, getInteractionState, getLook, getLookData, getMaximumSize, getMinimumSize, getPreferredSize, getResizeMode, getTextContent, getTextLayoutManager, getVerticalAlignment, isFocusTraversable, isOpaque, paint, setAnimateContent, setBackgroundMode, setBordersEnabled, setContent, setDefaultSize, setEnabled, setGraphicContent, setHorizontalAlignment, setInteractionState, setLookData, setResizeMode, setTextContent, setTextLayoutManager, setVerticalAlignment, update
 
Methods inherited from class org.havi.ui.HComponent
getMatte, isDoubleBuffered, isEnabled, processEvent, setMatte
 
Methods inherited from class java.awt.Component
addComponentListener, addFocusListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, addNotify, addPropertyChangeListener, areFocusTraversalKeysSet, checkImage, checkImage, coalesceEvents, contains, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, doLayout, enableEvents, enableInputMethods, firePropertyChange, getAlignmentX, getAlignmentY, getBackground, getBounds, getBounds, getColorModel, getComponentAt, getComponentAt, getComponentListeners, getCursor, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeys, getFocusTraversalKeysEnabled, getFont, getFontMetrics, getForeground, getGraphics, getGraphicsConfiguration, getHeight, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMouseWheelListeners, getName, getParent, getPropertyChangeListeners, getSize, getSize, getToolkit, getTreeLock, getWidth, getX, getY, hasFocus, imageUpdate, invalidate, isBackgroundSet, isCursorSet, isDisplayable, isFocusable, isFocusCycleRoot, isFocusOwner, isFontSet, isForegroundSet, isLightweight, isShowing, isValid, isVisible, list, list, list, list, list, paintAll, paramString, prepareImage, prepareImage, print, printAll, processComponentEvent, processFocusEvent, processInputMethodEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, processMouseWheelEvent, removeComponentListener, removeFocusListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removeNotify, removePropertyChangeListener, repaint, repaint, repaint, repaint, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, setBackground, setBounds, setBounds, setCursor, setFocusable, setFocusTraversalKeys, setFocusTraversalKeysEnabled, setFont, setForeground, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, setVisible, toString, transferFocus, transferFocusBackward, transferFocusUpCycle, validate
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

HTextButton

public HTextButton()
Creates an HTextButton object. See the class description for details of constructor parameters and default values. For constructors which specify content as parameters, see 'State-based content' in HVisible for unspecified content associated with other HStates.


HTextButton

public HTextButton(java.lang.String text,
                   int x,
                   int y,
                   int width,
                   int height)
Creates an HTextButton object. See the class description for details of constructor parameters and default values. For constructors which specify content as parameters, see 'State-based content' in HVisible for unspecified content associated with other HStates.


HTextButton

public HTextButton(java.lang.String text,
                   int x,
                   int y,
                   int width,
                   int height,
                   java.awt.Font font,
                   java.awt.Color foreground,
                   java.awt.Color background,
                   HTextLayoutManager tlm)
Creates an HTextButton object. See the class description for details of constructor parameters and default values. For constructors which specify content as parameters, see 'State-based content' in HVisible for unspecified content associated with other HStates.


HTextButton

public HTextButton(java.lang.String text)
Creates an HTextButton object. See the class description for details of constructor parameters and default values. For constructors which specify content as parameters, see 'State-based content' in HVisible for unspecified content associated with other HStates.


HTextButton

public HTextButton(java.lang.String text,
                   java.awt.Font font,
                   java.awt.Color foreground,
                   java.awt.Color background,
                   HTextLayoutManager tlm)
Creates an HTextButton object. See the class description for details of constructor parameters and default values. For constructors which specify content as parameters, see 'State-based content' in HVisible for unspecified content associated with other HStates.

Method Detail

setDefaultLook

public static void setDefaultLook(HTextLook hlook)
Sets the default HLook for further HTextButton components.

Parameters:
hlook - The HLook that will be used by default when creating a new HTextButton. Note that this parameter may be null, in which case newly created components shall not draw themselves until a non-null look is set using the setLook method.

getDefaultLook

public static HTextLook getDefaultLook()
Returns the currently set default HLook for HTextButton components.

Returns:
The HLook that is used by default when creating a new HTextButton.

setMove

public void setMove(int keyCode,
                    HNavigable target)
Defines the navigation path from the current HNavigable to another HNavigable when a particular key is pressed.

Note that setFocusTraversal is equivalent to multiple calls to setMove, where the key codes VK_UP, VK_DOWN, VK_LEFT, VK_RIGHT are used.

Specified by:
setMove in interface HNavigable
Overrides:
setMove in class HText
Parameters:
keyCode - The key code of the pressed key. Any numerical keycode is allowed, but the platform may not be able to generate all keycodes. Application authors should only use keys for which HRcCapabilities.isSupported() or HKeyCapabilities.isSupported() returns true.
target - The target HNavigable object that should be navigated to. If a target is to be removed from a particular navigation path, then null shall be specified.

getMove

public HNavigable getMove(int keyCode)
Provides the HNavigable object that is navigated to when a particular key is pressed.

Specified by:
getMove in interface HNavigable
Overrides:
getMove in class HText
Parameters:
keyCode - The key code of the pressed key.
Returns:
Returns the HNavigable object or null if no HNavigable is associated with the keyCode.

setFocusTraversal

public void setFocusTraversal(HNavigable up,
                              HNavigable down,
                              HNavigable left,
                              HNavigable right)
Set the focus control for an HNavigable component. Note setFocusTraversal is a convenience function for application programmers where a standard up, down, left and right focus traversal between components is required.

Note setFocusTraversal is equivalent to multiple calls to setMove, where the key codes VK_UP, VK_DOWN, VK_LEFT, VK_RIGHT are used.

Note that this API does not prevent the creation of "isolated" HNavigable components --- authors should endeavor to avoid confusing the user.

Specified by:
setFocusTraversal in interface HNavigable
Overrides:
setFocusTraversal in class HText
Parameters:
up - The HNavigable component to move to, when the user generates a VK_UP KeyEvent. If there is no HNavigable component to move "up" to, then null shall be specified.
down - The HNavigable component to move to, when the user generates a VK_DOWN KeyEvent. If there is no HNavigable component to move "down" to, then null shall be specified.
left - The HNavigable component to move to, when the user generates a VK_LEFT KeyEvent. If there is no HNavigable component to move "left" to, then null shall be specified.
right - The HNavigable component to move to, when the user generates a VK_RIGHT KeyEvent. If there is no HNavigable component to move "right" to, then null shall be specified.

isSelected

public boolean isSelected()
Indicates if this component has focus.

Specified by:
isSelected in interface HNavigable
Overrides:
isSelected in class HText
Returns:
true if the component has focus, otherwise returns false.

setGainFocusSound

public void setGainFocusSound(HSound sound)
Associate a sound with gaining focus, i.e. when the HNavigable receives a HFocusEvent event of type FOCUS_GAINED. This sound will start to be played when an object implementing this interface gains focus. It is not guaranteed to be played to completion. If the object implementing this interface loses focus before the audio completes playing, the audio will be truncated. Applications wishing to ensure the audio is always played to completion must implement special logic to slow down the focus transitions.

By default, an HNavigable object does not have any gain focus sound associated with it.

Note that the ordering of playing sounds is dependent on the order of the focus lost, gained events.

Specified by:
setGainFocusSound in interface HNavigable
Overrides:
setGainFocusSound in class HText
Parameters:
sound - the sound to be played, when the component gains focus. If sound content is already set, the original content is replaced. To remove the sound specify a null HSound.

setLoseFocusSound

public void setLoseFocusSound(HSound sound)
Associate a sound with losing focus, i.e. when the HNavigable receives a HFocusEvent event of type FOCUS_LOST. This sound will start to be played when an object implementing this interface loses focus. It is not guaranteed to be played to completion. It is implementation dependent whether and when this sound will be truncated by any gain focus sound played by the next object to gain focus.

By default, an HNavigable object does not have any lose focus sound associated with it.

Note that the ordering of playing sounds is dependent on the order of the focus lost, gained events.

Specified by:
setLoseFocusSound in interface HNavigable
Overrides:
setLoseFocusSound in class HText
Parameters:
sound - the sound to be played, when the component loses focus. If sound content is already set, the original content is replaced. To remove the sound specify a null HSound.

getGainFocusSound

public HSound getGainFocusSound()
Get the sound associated with the gain focus event.

Specified by:
getGainFocusSound in interface HNavigable
Overrides:
getGainFocusSound in class HText
Returns:
The sound played when the component gains focus. If no sound is associated with gaining focus, then null shall be returned.

getLoseFocusSound

public HSound getLoseFocusSound()
Get the sound associated with the lost focus event.

Specified by:
getLoseFocusSound in interface HNavigable
Overrides:
getLoseFocusSound in class HText
Returns:
The sound played when the component loses focus. If no sound is associated with losing focus, then null shall be returned.

addHFocusListener

public void addHFocusListener(HFocusListener l)
Adds the specified HFocusListener to receive HFocusEvent events sent from this HNavigable: If the listener has already been added further calls will add further references to the listener, which will then receive multiple copies of a single event.

Specified by:
addHFocusListener in interface HNavigable
Overrides:
addHFocusListener in class HText
Parameters:
l - the HFocusListener to add

removeHFocusListener

public void removeHFocusListener(HFocusListener l)
Removes the specified HFocusListener so that it no longer receives HFocusEvent events from this HNavigable. If the specified listener is not registered, the method has no effect. If multiple references to a single listener have been registered it should be noted that this method will only remove one reference per call.

Specified by:
removeHFocusListener in interface HNavigable
Overrides:
removeHFocusListener in class HText
Parameters:
l - the HFocusListener to remove

getNavigationKeys

public int[] getNavigationKeys()
Retrieve the set of key codes which this component maps to navigation targets.

Specified by:
getNavigationKeys in interface HNavigationInputPreferred
Overrides:
getNavigationKeys in class HText
Returns:
an array of key codes, or null if no navigation targets are set on this component.

processHFocusEvent

public void processHFocusEvent(HFocusEvent evt)
Process an HFocusEvent sent to this HTextButton.

Specified by:
processHFocusEvent in interface HNavigationInputPreferred
Overrides:
processHFocusEvent in class HText
Parameters:
evt - the HFocusEvent to process.

addHActionListener

public void addHActionListener(HActionListener l)
Adds the specified HActionListener to receive HActionEvent events sent from this HTextButton. If the listener has already been added further calls will add further references to the listener, which will then receive multiple copies of a single event.

Specified by:
addHActionListener in interface HActionable
Parameters:
l - the HActionListener.

removeHActionListener

public void removeHActionListener(HActionListener l)
Removes the specified HActionListener so that it no longer receives HActionEvent events from this HTextButton. If the specified listener is not registered, the method has no effect. If multiple references to a single listener have been registered it should be noted that this method will only remove one reference per call.

Specified by:
removeHActionListener in interface HActionable
Parameters:
l - the HActionListener.

setActionCommand

public void setActionCommand(java.lang.String command)
Sets the command name for the HActionEvent event fired by this HTextButton.

Specified by:
setActionCommand in interface HActionable
Parameters:
command - a String used to set the action command. To remove the command specify a null command parameter.
See Also:
HActionEvent.getActionCommand()

setActionSound

public void setActionSound(HSound sound)
Associate a sound to be played when the interaction state of the HTextButton makes the following transitions:

Specified by:
setActionSound in interface HActionable
Parameters:
sound - the sound to be played, when the component is actioned. If sound content is already set, the original content is replaced. To remove the sound specify a null HSound.

getActionSound

public HSound getActionSound()
Return the last action sound set by the setActionSound() method or null if no action sound has been set.

Specified by:
getActionSound in interface HActionable

processHActionEvent

public void processHActionEvent(HActionEvent evt)
Process an HActionEvent sent to this HTextButton.

Specified by:
processHActionEvent in interface HActionInputPreferred
Parameters:
evt - the HActionEvent to process.

getActionCommand

public java.lang.String getActionCommand()
Gets the command name for the HActionEvent event fired by this HTextButton. If this HTextButton has no action command then an empty string shall be returned.

Specified by:
getActionCommand in interface HActionInputPreferred
Returns:
A String representing the command name of the HActionEvent fired by this HTextButton.