com.ccg.awt
Class ImageButton

java.lang.Object
  java.awt.Component
      com.ccg.awt.TallButton
          com.ccg.awt.ImageButton

All Implemented Interfaces:

ImageObserver, MenuContainer, Serializable

public class ImageButton
extends TallButton

A lightweight push button which allows pressed/released images. This class extends the TallButton class and is intended to provide the ability to use GIF/JPG images for the purpose of drawing the button in its pressed, when the mouse is over the button, and its normal released state. Here is a set of highlights of the features you can adjust:

• You can still set the text to be displayed (it will be centered on top of your graphic images).
• You can fall back to the drawing of the buttons by setting the images to null (or specifiying zero length values in your run time configuration when you set the characteristics of the button.
• You can specify whether your graphics should be scaled if the components area is not the preferred size for its rendering. If you disable "scaling", then the button will be centered in the components area.
• Currently keyboard focus is only supported if its set to TallButton.AROUND_TEXT or TallButton.UNDERLINE_TEXT.
• The semi-pushed look is not supported if bitmaps are being used.
• The set(com.ccg.util.TagLookup, com.ccg.awt.ImageHolder) method has been enhanced to allow one to specify the bitmaps (and whether they are scaled) at run-time via a TagLookup table.
• You can set the image to be used if the button has been disabled.

I would highly recommend building and invoking the sample ButtonViewer.java application (it requires a Swing enabled JVM to run). This sample application allows one to play with almost all of the settings to create both TallButton and ImageButton objects and see how the behave. Assuming you have a JDK available and properly setup (check your CLASSPATH), if you saved the file to a directory named "/tmp", you should be able to do the following:

 cd /tmp
 javac ButtonViewer.java
 java ButtonViewer
 

If you have other bit maps you'd like to try (other than the defaults provided). You can specify their locations by typing in their full path name or a URL address (GIF/JPG format files only).

Note, this class does not yet properly serialize itself.

Since:

1.0

Version:

$Revision: 1.9 $

Author:

$Author: pkb $

See Also:

ImageUtility, Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class java.awt.Component

Component.AccessibleAWTComponent, Component.BltBufferStrategy, Component.FlipBufferStrategy

Field Summary

Fields inherited from class com.ccg.awt.TallButton

AROUND_TEXT, INSIDE, NONE, OUTSIDE, UNDERLINE_TEXT

Fields inherited from class java.awt.Component

BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT

Fields inherited from interface java.awt.image.ImageObserver

ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH

Constructor Summary

ImageButton()
Initializes the object to the default button images.

Method Summary

static Image	getDefaultPressedImage() Get default image to use for the "pressed" state.
static Image	getDefaultReleasedImage() Get default image to use for the "released" state.
static Image	getDefaultRolloverImage() Get default image to use for the "pressed" state.
Image	getDisabledImage() Get the image to display when button is disabled.
Dimension	getMaximumSize() Computes the maximum size of the button.
Dimension	getMinimumSize() Computes the minimum size of the button.
Dimension	getPreferredSize() Computes the preferred size of the button.
Image	getPressedImage() Get the image to display when button is pressed.
Image	getReleasedImage() Get the image to display when button is released.
Image	getRolloverImage() Get the image to display when the mouse moves over the button.
boolean	isImageScaled() Indicates whether images scaled to the size of the component set.
void	paint(Graphics g) Paints the component on a graphics context.
void	set(TagLookup info, ImageHolder ih) Set properties for button based on values in TagLookup table.
static void	setDefaultImages(Image released, Image pressed, Image over) Set the default images to use for the buttons.
static void	setDefaultPressedImage(Image val) Set default image to use for the "pressed" state.
static void	setDefaultReleasedImage(Image val) Set default image to use for the "released" state.
static void	setDefaultRolloverImage(Image val) Set default image to use for the "roll-over" state.
void	setDisabledImage(Image val) Set the image to display when button is disabled.
void	setImageScaled(boolean val) Set whether images scaled to the size of the component.
void	setPressedImage(Image val) Set the image to display when button is pressed.
void	setReleasedImage(Image val) Set the image to display when button is released.
void	setRolloverImage(Image val) Set the image to display when the mouse moves over the button.

Methods inherited from class com.ccg.awt.TallButton

addActionListener, getAlign, getButtonHeight, getButtonPressedColor, getDisabledButtonColor, getDisabledTextColor, getFocusColor, getFocusMode, getFocusModeChoices, getInsets, getMargin, getMouseOverColor, getMultiLineText, getSemiPush, getText, getTextEchoColor, getTextEchoReleasedColor, getTextPressedColor, isEmphasized, isFocusTraversable, isPressed, isTextEchoOn, paintInsets, paintText, processEvent, removeActionListener, set, setAlign, setButtonHeight, setButtonPressedColor, setEnabled, setFocusColor, setFocusMode, setInsets, setMargin, setMouseOverColor, setMultiLineText, setSemiPush, setText, setTextEchoColor, setTextEchoOn, setTextEchoReleasedColor, setTextPressedColor, update

Methods inherited from class java.awt.Component

action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, addNotify, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, bounds, checkImage, checkImage, coalesceEvents, contains, contains, createImage, createImage, createVolatileImage, createVolatileImage, deliverEvent, disable, disableEvents, dispatchEvent, doLayout, enable, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getAccessibleContext, getAlignmentX, getAlignmentY, getBackground, getBounds, getBounds, getColorModel, getComponentAt, getComponentAt, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeys, getFocusTraversalKeysEnabled, getFont, getFontMetrics, getForeground, getGraphics, getGraphicsConfiguration, getHeight, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getListeners, getLocale, getLocation, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getSize, getToolkit, getTreeLock, getWidth, getX, getY, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, invalidate, isBackgroundSet, isCursorSet, isDisplayable, isDoubleBuffered, isEnabled, isFocusable, isFocusCycleRoot, isFocusOwner, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isOpaque, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, layout, list, list, list, list, list, locate, location, lostFocus, minimumSize, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, paramString, postEvent, preferredSize, prepareImage, prepareImage, print, printAll, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removeNotify, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, repaint, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, reshape, resize, resize, setBackground, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeys, setFocusTraversalKeysEnabled, setFont, setForeground, setIgnoreRepaint, setLocale, setLocation, setLocation, setMaximumSize, setMinimumSize, setName, setPreferredSize, setSize, setSize, setVisible, show, show, size, toString, transferFocus, transferFocusBackward, transferFocusUpCycle, validate

Methods inherited from class java.lang.Object

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

Constructor Detail

ImageButton

public ImageButton()

Initializes the object to the default button images.

This method initializes the object to use the default image bitmaps for the pressed/released view of the button. After contstruction in this manner, you can use the various "set" methods to affect how the text is drawn on the images. You can also set either (or both) the pressed/released images to null, if you'd prefer to have the buttons drawn for you.

Since:

1.0

See Also:

set(com.ccg.util.TagLookup, com.ccg.awt.ImageHolder)

Method Detail

setDefaultImages

public static void setDefaultImages(Image released,
                                    Image pressed,
                                    Image over)

Set the default images to use for the buttons. This method allows one to set the default images to be used when a button is first created. You should call this button prior to creating buttons if you want to make use of it. If you don't use this method, the system default images will be used if available. Also, if you would prefer for either or both states of your button to be drawn (using the drawing methods in TallButton, you can set either (or both) of these values to null.

Parameters:

released - Default Image to display when the button is in the "released" state - or null if you want the button drawn.

pressed - Default Image to display when the button is in the "pressed" state - or null if you want the button drawn.

rollover - Default Image to display when the mouse rolls over the button - or null if you want the same image as the released image to be used.

Since:

1.0

See Also:

setReleasedImage(java.awt.Image), setPressedImage(java.awt.Image)

set

public void set(TagLookup info,
                ImageHolder ih)
         throws ParseException

Set properties for button based on values in TagLookup table. This method will set all of the properties it can find from the specified TagLookup table. Any images specified will first be searched for in the ImageHolder object passed - and if not found there, an attempt will be made to load them (using either the ImageHolder passed or directly via the ImageUtility class. The "keys" which we recognize are as follows:

pressedImage

A string which is specifies a Image resource. If a string value is specified that we can convert to a image resouce, the result will be passed to setPressedImage(java.awt.Image). If the string values specified has a zero length, then the pressed version of the button graphic will be drawn using the parent classes method.

releasedImage

A string which is specifies a Image resource. If a string value is specified that we can convert to a image resouce, the result will be passed to setPressedImage(java.awt.Image). If the string values specified has a zero length, then the released version of the button graphic will be drawn using the parent classes method.

rolloverImage

A string which is specifies a Image resource. If a string value is specified that we can convert to a image resouce, the result will be passed to setRolloverImage(java.awt.Image). If the string values specified has a zero length, then the released image will be used to display a button in this state (special highlighting of the text may still occur occur).

disabledImage

A string which is specifies a Image resource. If a string value is specified that we can convert to a image resouce, the result will be passed to setDisabledImage(java.awt.Image).

imageScaled

setImageScaled(boolean) - set to "true"/"false" (default is "true") indicating whether you want the bitmap to fill the components area (streched/shrunk).

text - TallButton.setText(java.lang.String)

The text to be displayed, it may contain new line characters (such as "Hello\nWorld") for multiline text.

font - Component.setFont(java.awt.Font)

Used to set a specific font for the object. See TagLookup.getFont(java.lang.String, java.awt.Font) for details on specifying font strings.

height - TallButton.setButtonHeight(int)

To set the button height (how tall it appears). This controls the number of pixels around the outside of the button used to draw the sloped edge (integer value).

margin - TallButton.setMargin(int)

This value is used to specify the minimum magin (in pixels) around the text which is drawn on the button when the button is in the released state.

semiPush - TallButton.setSemiPush(int)

This value controls how many pixels down the button should appear to "push" in when the user's mouse floats over it. The default value of 0 disables this "semi push" effect. The value should be less than or equal to the "height" of the button.

foreground - Component.setForeground(java.awt.Color)

The color used for the text when the button is in its released state. See TagLookup.getColor(java.lang.String, java.awt.Color) for details on specifying colors.

background - Component.setBackground(java.awt.Color)

The color used for the button when the button is in its released state. See TagLookup.getColor(java.lang.String, java.awt.Color) for details on specifying colors.

textPressedColor - TallButton.setTextPressedColor(java.awt.Color)

The color used for the text when the button is in its pressed state. See TagLookup.getColor(java.lang.String, java.awt.Color) for details on specifying colors.

textEchoOn - TallButton.setTextEchoOn(boolean)

Whether a "text shadow" effect should be used when the mouse pointer floats over a released button (this affect is disabled unless this is specified). See TagLookup.getBoolean(java.lang.String, java.lang.Boolean) for details on specifying colors (or use "true"/"false").

textEchoColor - TallButton.setTextEchoColor(java.awt.Color)

The color used for a "text shadow" when the mouse pointer floats over a released button (this affect is disabled unless this is specified). See TagLookup.getColor(java.lang.String, java.awt.Color) for details on specifying colors.

textEchoReleasedColor - TallButton.setTextEchoReleasedColor(java.awt.Color)

The color used for a "text shadow" when the button is released (up). The "textEchoOn" attribute must be set to true and this value must be non-null for it to take affect. See TagLookup.getColor(java.lang.String, java.awt.Color) for details on specifying colors.

buttonPressedColor - TallButton.setButtonPressedColor(java.awt.Color)

The color used for the button when the button is in its pressed state. See TagLookup.getColor(java.lang.String, java.awt.Color) for details on specifying colors.

focusMode - TallButton.setFocusMode(int)

Used to specify what type of "focus mode" is to be used to indicate the button has the keyboard focus. It must be one of the string choices returned by TallButton.getFocusModeChoices() and is used to set the focus mode.

focusColor - TallButton.setFocusColor(java.awt.Color)

The color used for the drawing the keyboard focus indicator. See TagLookup.getColor(java.lang.String, java.awt.Color) for details on specifying colors.

inset

Allows you to specify a single integer value to be used as a pixel gap (inset) of the button from its components area (see TallButton.setInsets(java.awt.Insets)).

align

Allows you to specify how lines of text should be aligned. Valid values: "c" - centered, "l" - left, "r" - right. This parameter has no affect if you have a single line of text.

pos

Allows you to specify how the area which contains the text is aligned. By default, this will be "cp.5,cp.5" which results in text centered on the button. Refer to Align.parse(java.lang.String) for details on the numerous ways to adjust the alignment.

Parameters:

tl - A TagLookup to fetch values from.

ih - A ImageHolder object used to fetch any named image from.

Throws:

ParseException

Since:

1.0

paint

public void paint(Graphics g)

Paints the component on a graphics context. This method takes care of drawing the button in its proper state. The following items are taken into consideration (the settings of the object determine color and whether or not they are done):

• If the button should be drawn in its "pressed" state. In which case, we will paint the pressed image if available (or fall back to parent class to draw button for us if not).
• If the button should be drawn in its "released" state. In which case, we will paint the released image if available (or fall back to parent class to draw button for us if not).
• If the button is in a "released" state, does it have the current keyboard focus and require enhancement (depends on the focus mode).
• If the mouse is over the button and the button has been configured to indicate this condition, then the text will be echoed (typically with a color combination that results in a etched look). If a special rollover image has been defined for the button, it will be used - otherwise the button will be drawn as if it were released.

Overrides:

paint in class TallButton

Parameters:

g - Graphics context to draw button image onto.

Since:

1.0

See Also:

TallButton.paint(java.awt.Graphics)

setReleasedImage

public void setReleasedImage(Image val)

Set the image to display when button is released.

Parameters:

val - New Image value to assign - if you set this value to null, then the released image will be drawn using the TallButton implementation.

See Also:

getReleasedImage()

getReleasedImage

public Image getReleasedImage()

Get the image to display when button is released.

Returns:

Current Image value assigned.

See Also:

setReleasedImage(java.awt.Image)

setPressedImage

public void setPressedImage(Image val)

Set the image to display when button is pressed.

Parameters:

val - New Image value to assign - if you set this value to null, then the released image will be drawn using the TallButton implementation.

See Also:

getPressedImage()

getPressedImage

public Image getPressedImage()

Get the image to display when button is pressed.

Returns:

Current Image value assigned.

See Also:

setPressedImage(java.awt.Image)

setDisabledImage

public void setDisabledImage(Image val)

Set the image to display when button is disabled.

Parameters:

val - New Image value to assign - if you set this value to null, then the released image will be drawn using the TallButton implementation.

See Also:

getDisabledImage()

getDisabledImage

public Image getDisabledImage()

Get the image to display when button is disabled.

Returns:

Current Image value assigned.

See Also:

setDisabledImage(java.awt.Image)

setRolloverImage

public void setRolloverImage(Image val)

Set the image to display when the mouse moves over the button.

If you would like to display a different image when the mouse enters the button area, you can set the image to display using this method. By default the ImageButton doesn't display a different "rollover" image.

Parameters:

val - New Image value to assign.

See Also:

getRolloverImage()

getRolloverImage

public Image getRolloverImage()

Get the image to display when the mouse moves over the button.

Returns:

Current Image value assigned.

See Also:

setRolloverImage(java.awt.Image)

getPreferredSize

public Dimension getPreferredSize()

Computes the preferred size of the button. Often layout managers will ask a component what size it would like to be. This method returns the minimum size of the component such that the button can be perfectly drawn (that is any images will be drawn without requiring bitmap scaling).

Overrides:

getPreferredSize in class TallButton

Returns:

The size required to properly draw the button.

Since:

1.0

getMaximumSize

public Dimension getMaximumSize()

Computes the maximum size of the button. If we have images available to draw our button with, we will indicate to anyone that asks us that our maximum/minimum/preferred sizes correspond to the size of our button images. If we allow "scaling" of bitmaps (which we may do in the future), then the maximum/minimum size of the component will not be forced (we will behave like normal components which can resize themselves).

Overrides:

getMaximumSize in class Component

Returns:

The size required to properly draw the button, or if scaling of the image has been enabled, we return the parent classes implementation.

Since:

1.0

getMinimumSize

public Dimension getMinimumSize()

Computes the minimum size of the button. If we have images available to draw our button with, we will indicate to anyone that asks us that our minimum/minimum/preferred sizes correspond to the size of our button images. If we allow "scaling" of bitmaps (which we may do in the future), then the minimum/minimum size of the component will not be forced (we will behave like normal components which can resize themselves).

Overrides:

getMinimumSize in class Component

Returns:

The size required to properly draw the button, or if scaling of the image has been enabled, we return the parent classes implementation.

Since:

1.0

setImageScaled

public void setImageScaled(boolean val)

Set whether images scaled to the size of the component.

Parameters:

val - New boolean value to assign. see #getImageScaled

isImageScaled

public boolean isImageScaled()

Indicates whether images scaled to the size of the component set.

Returns:

Current boolean value assigned. see #setImageScaled

setDefaultRolloverImage

public static void setDefaultRolloverImage(Image val)

Set default image to use for the "roll-over" state. Setting this value specifis the default for all ImageButtons created after the call is invoked.

Parameters:

val - New Image value to assign.

See Also:

getDefaultRolloverImage()

getDefaultRolloverImage

public static Image getDefaultRolloverImage()

Get default image to use for the "pressed" state.

Returns:

Current Image value assigned.

See Also:

setDefaultRolloverImage(java.awt.Image)

setDefaultPressedImage

public static void setDefaultPressedImage(Image val)

Set default image to use for the "pressed" state. Setting this value specifis the default for all ImageButtons created after the call is invoked.

Parameters:

val - New Image value to assign.

See Also:

getDefaultPressedImage()

getDefaultPressedImage

public static Image getDefaultPressedImage()

Get default image to use for the "pressed" state.

Returns:

Current Image value assigned.

See Also:

setDefaultPressedImage(java.awt.Image)

setDefaultReleasedImage

public static void setDefaultReleasedImage(Image val)

Set default image to use for the "released" state. Setting this value specifis the default for all ImageButtons created after the call is invoked.

Parameters:

val - New Image value to assign.

See Also:

getDefaultReleasedImage()

getDefaultReleasedImage

public static Image getDefaultReleasedImage()

Get default image to use for the "released" state.

Returns:

Current Image value assigned.

See Also:

setDefaultReleasedImage(java.awt.Image)