javax.swing
Class JToolBar

java.lang.Object
  java.awt.Component
      java.awt.Container
          javax.swing.JComponent
              javax.swing.JToolBar

All Implemented Interfaces:

javax.accessibility.Accessible, ImageObserver, MenuContainer, Serializable, SwingConstants

public class JToolBar

extends JComponent

implements SwingConstants, javax.accessibility.Accessible

JToolBar provides a component that is useful for displaying commonly used Actions or controls. For examples and information on using tool bars see How to Use Tool Bars, a section in The Java Tutorial.

With most look and feels, the user can drag out a tool bar into a separate window (unless the floatable property is set to false). For drag-out to work correctly, it is recommended that you add JToolBar instances to one of the four "sides" of a container whose layout manager is a BorderLayout, and do not add children to any of the other four "sides".

For the keyboard keys used by this component in the standard Look and Feel (L&F) renditions, see the JToolBar key assignments.

Warning: Serialized objects of this class will not be compatible with future Swing releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of Swing. As of 1.4, support for long term storage of all JavaBeans^TM has been added to the java.beans package. Please see XMLEncoder.

Author:

Georges Saab, Jeff Shapiro

See Also:

Action, Serialized Form

Nested Class Summary

protected class	JToolBar.AccessibleJToolBar This class implements accessibility support for the JToolBar class.
private class	JToolBar.DefaultToolBarLayout
static class	JToolBar.Separator A toolbar-specific separator.

Nested classes inherited from class javax.swing.JComponent

JComponent.AccessibleJComponent, JComponent.ActionStandin, JComponent.IntVector, JComponent.KeyboardState

Nested classes inherited from class java.awt.Container

Container.AccessibleAWTContainer

Nested classes inherited from class java.awt.Component

Component.AccessibleAWTComponent, Component.BltBufferStrategy, Component.FlipBufferStrategy

Field Summary

private boolean	floatable
private Insets	margin
private int	orientation
private boolean	paintBorder
private static String	uiClassID

Fields inherited from class javax.swing.JComponent

_bounds, accessibleContext, listenerList, paintingChild, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW

Fields inherited from class java.awt.Container

Fields inherited from class java.awt.Component

BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT

Fields inherited from interface javax.swing.SwingConstants

BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST

Fields inherited from interface java.awt.image.ImageObserver

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

Constructor Summary

JToolBar()
Creates a new tool bar; orientation defaults to HORIZONTAL.

JToolBar(int orientation)
Creates a new tool bar with the specified orientation.

JToolBar(String name)
Creates a new tool bar with the specified name.

JToolBar(String name, int orientation)
Creates a new tool bar with a specified name and orientation.

Method Summary

JButton	add(Action a) Adds a new JButton which dispatches the action.
protected void	addImpl(Component comp, Object constraints, int index) If a JButton is being added, it is initially set to be disabled.
void	addSeparator() Appends a separator of default size to the end of the tool bar.
void	addSeparator(Dimension size) Appends a separator of a specified size to the end of the tool bar.
private void	checkOrientation(int orientation)
protected java.beans.PropertyChangeListener	createActionChangeListener(JButton b) Returns a properly configured PropertyChangeListener which updates the control as changes to the Action occur, or null if the default property change listener for the control is desired.
protected JButton	createActionComponent(Action a) Factory method which creates the JButton for Actions added to the JToolBar.
javax.accessibility.AccessibleContext	getAccessibleContext() Gets the AccessibleContext associated with this JToolBar.
Component	getComponentAtIndex(int i) Returns the component at the specified index.
int	getComponentIndex(Component c) Returns the index of the specified component.
Insets	getMargin() Returns the margin between the tool bar's border and its buttons.
int	getOrientation() Returns the current orientation of the tool bar.
ToolBarUI	getUI() Returns the tool bar's current UI.
String	getUIClassID() Returns the name of the L&F class that renders this component.
boolean	isBorderPainted() Gets the borderPainted property.
boolean	isFloatable() Gets the floatable property.
boolean	isRollover() Returns the rollover state.
protected void	paintBorder(Graphics g) Paints the tool bar's border if the borderPainted property is true.
protected String	paramString() Returns a string representation of this JToolBar.
void	setBorderPainted(boolean b) Sets the borderPainted property, which is true if the border should be painted.
void	setFloatable(boolean b) Sets the floatable property, which must be true for the user to move the tool bar.
void	setLayout(LayoutManager mgr) Sets the layout manager for this container.
void	setMargin(Insets m) Sets the margin between the tool bar's border and its buttons.
void	setOrientation(int o) Sets the orientation of the tool bar.
void	setRollover(boolean rollover) Sets the rollover state of this toolbar.
void	setUI(ToolBarUI ui) Sets the L&F object that renders this component.
void	updateUI() Notification from the UIFactory that the L&F has changed.
private void	writeObject(ObjectOutputStream s) See readObject and writeObject in JComponent for more information about serialization in Swing.

Methods inherited from class javax.swing.JComponent

_paintImmediately, addAncestorListener, addNotify, addPropertyChangeListener, addPropertyChangeListener, addVetoableChangeListener, alwaysOnTop, checkIfChildObscuredBySibling, componentInputMapChanged, computeVisibleRect, computeVisibleRect, compWriteObjectNotify, contains, createToolTip, disable, enable, enableSerialization, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBorder, getBounds, getClientProperty, getComponentGraphics, getConditionForKeyStroke, getCreatedDoubleBuffer, getDebugGraphicsOptions, getDefaultLocale, getGraphics, getHeight, getInputMap, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getManagingFocusBackwardTraversalKeys, getManagingFocusForwardTraversalKeys, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPreferredSize, getPropertyChangeListeners, getPropertyChangeListeners, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getWriteObjCounter, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isMaximumSizeSet, isMinimumSizeSet, isOpaque, isOptimizedDrawingEnabled, isPaintingOrigin, isPaintingTile, isPreferredSizeSet, isRequestFocusEnabled, isValidateRoot, paint, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyBindings, processKeyBindingsForAllComponents, processKeyEvent, processMouseMotionEvent, putClientProperty, rectangleIsObscured, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removePropertyChangeListener, removePropertyChangeListener, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setCreatedDoubleBuffer, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFont, setForeground, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPaintingChild, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, setWriteObjCounter, shouldDebugGraphics, superProcessMouseMotionEvent, unregisterKeyboardAction, update

Methods inherited from class java.awt.Container

add, add, add, add, add, addContainerListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setFocusCycleRoot, setFocusTraversalKeys, setFocusTraversalPolicy, transferFocusBackward, transferFocusDownCycle, validate, validateTree

Methods inherited from class java.awt.Component

action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getFontMetrics, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMouseWheelListeners, getName, getParent, getPeer, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle

Methods inherited from class java.lang.Object

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

Field Detail

uiClassID

private static final String uiClassID

See Also:

getUIClassID(), JComponent.readObject(java.io.ObjectInputStream), Constant Field Values

paintBorder

private boolean paintBorder

margin

private Insets margin

floatable

private boolean floatable

orientation

private int orientation

Constructor Detail

JToolBar

public JToolBar()

Creates a new tool bar; orientation defaults to HORIZONTAL.

JToolBar

public JToolBar(int orientation)

Creates a new tool bar with the specified orientation. The orientation must be either HORIZONTAL or VERTICAL.

Parameters:

orientation - the orientation desired

JToolBar

public JToolBar(String name)

Creates a new tool bar with the specified name. The name is used as the title of the undocked tool bar. The default orientation is HORIZONTAL.

Parameters:

name - the name of the tool bar

Since:

1.3

JToolBar

public JToolBar(String name,
                int orientation)

Creates a new tool bar with a specified name and orientation. All other constructors call this constructor. If orientation is an invalid value, an exception will be thrown.

Parameters:

name - the name of the tool bar

orientation - the initial orientation -- it must be either HORIZONTAL or VERTICAL

Throws:

IllegalArgumentException - if orientation is neither HORIZONTAL nor VERTICAL

Since:

1.3

Method Detail

getUI

public ToolBarUI getUI()

Returns the tool bar's current UI.

See Also:

setUI(javax.swing.plaf.ToolBarUI)

setUI

public void setUI(ToolBarUI ui)

Sets the L&F object that renders this component.

Parameters:

ui - the ToolBarUI L&F object

See Also:

UIDefaults.getUI(javax.swing.JComponent)

updateUI

public void updateUI()

Notification from the UIFactory that the L&F has changed. Called to replace the UI with the latest version from the UIFactory.

Overrides:

updateUI in class JComponent

See Also:

JComponent.updateUI()

getUIClassID

public String getUIClassID()

Returns the name of the L&F class that renders this component.

Overrides:

getUIClassID in class JComponent

Returns:

the string "ToolBarUI"

See Also:

JComponent.getUIClassID(), UIDefaults.getUI(javax.swing.JComponent)

getComponentIndex

public int getComponentIndex(Component c)

Returns the index of the specified component. (Note: Separators occupy index positions.)

Parameters:

c - the Component to find

Returns:

an integer indicating the component's position, where 0 is first

getComponentAtIndex

public Component getComponentAtIndex(int i)

Returns the component at the specified index.

Parameters:

i - the component's position, where 0 is first

Returns:

the Component at that position, or null for an invalid index

setMargin

public void setMargin(Insets m)

Sets the margin between the tool bar's border and its buttons. Setting to null causes the tool bar to use the default margins. The tool bar's default Border object uses this value to create the proper margin. However, if a non-default border is set on the tool bar, it is that Border object's responsibility to create the appropriate margin space (otherwise this property will effectively be ignored).

Parameters:

m - an Insets object that defines the space between the border and the buttons

See Also:

Insets

getMargin

public Insets getMargin()

Returns the margin between the tool bar's border and its buttons.

Returns:

an Insets object containing the margin values

See Also:

Insets

isBorderPainted

public boolean isBorderPainted()

Gets the borderPainted property.

Returns:

the value of the borderPainted property

See Also:

setBorderPainted(boolean)

setBorderPainted

public void setBorderPainted(boolean b)

Sets the borderPainted property, which is true if the border should be painted. The default value for this property is true. Some look and feels might not implement painted borders; they will ignore this property.

Parameters:

b - if true, the border is painted

See Also:

isBorderPainted()

paintBorder

protected void paintBorder(Graphics g)

Paints the tool bar's border if the borderPainted property is true.

Overrides:

paintBorder in class JComponent

Parameters:

g - the Graphics context in which the painting is done

See Also:

JComponent.paint(java.awt.Graphics), JComponent.setBorder(javax.swing.border.Border)

isFloatable

public boolean isFloatable()

Gets the floatable property.

Returns:

the value of the floatable property

See Also:

setFloatable(boolean)

setFloatable

public void setFloatable(boolean b)

Sets the floatable property, which must be true for the user to move the tool bar. Typically, a floatable tool bar can be dragged into a different position within the same container or out into its own window. The default value of this property is true. Some look and feels might not implement floatable tool bars; they will ignore this property.

Parameters:

b - if true, the tool bar can be moved; false otherwise

See Also:

isFloatable()

getOrientation

public int getOrientation()

Returns the current orientation of the tool bar. The value is either HORIZONTAL or VERTICAL.

Returns:

an integer representing the current orientation -- either HORIZONTAL or VERTICAL

See Also:

setOrientation(int)

setOrientation

public void setOrientation(int o)

Sets the orientation of the tool bar. The orientation must have either the value HORIZONTAL or VERTICAL. If orientation is an invalid value, an exception will be thrown.

Parameters:

o - the new orientation -- either HORIZONTAL or VERTICAL

Throws:

IllegalArgumentException - if orientation is neither HORIZONTAL nor VERTICAL

See Also:

getOrientation()

setRollover

public void setRollover(boolean rollover)

Sets the rollover state of this toolbar. If the rollover state is true then the border of the toolbar buttons will be drawn only when the mouse pointer hovers over them. The default value of this property is false.

The implementation of a look and feel may choose to ignore this property.

Parameters:

rollover - true for rollover toolbar buttons; otherwise false

Since:

1.4

isRollover

public boolean isRollover()

Returns the rollover state.

Returns:

true if rollover toolbar buttons are to be drawn; otherwise false

Since:

1.4

See Also:

setRollover(boolean)

checkOrientation

private void checkOrientation(int orientation)

addSeparator

public void addSeparator()

Appends a separator of default size to the end of the tool bar. The default size is determined by the current look and feel.

addSeparator

public void addSeparator(Dimension size)

Appends a separator of a specified size to the end of the tool bar.

Parameters:

size - the Dimension of the separator

add

public JButton add(Action a)

Adds a new JButton which dispatches the action.

As of 1.3, this is no longer the preferred method for adding Actions to a container. Instead it is recommended to configure a control with an action using using setAction, and then add that control directly to the Container.

Parameters:

a - the Action object to add as a new menu item

Returns:

the new button which dispatches the action

createActionComponent

protected JButton createActionComponent(Action a)

Factory method which creates the JButton for Actions added to the JToolBar. The default name is empty if a null action is passed.

As of 1.3, this is no longer the preferred method for adding Actions to a Container. Instead it is recommended to configure a control with an action using setAction, and then add that control directly to the Container.

Parameters:

a - the Action for the button to be added

Returns:

the newly created button

See Also:

Action

createActionChangeListener

protected java.beans.PropertyChangeListener createActionChangeListener(JButton b)

Returns a properly configured PropertyChangeListener which updates the control as changes to the Action occur, or null if the default property change listener for the control is desired.

As of 1.3, this is no longer the preferred method for adding Actions to a Container. Instead it is recommended to configure a control with an action using setAction, and then add that control directly to the Container.

Returns:

null

addImpl

protected void addImpl(Component comp,
                       Object constraints,
                       int index)

If a JButton is being added, it is initially set to be disabled.

Overrides:

addImpl in class Container

Parameters:

comp - the component to be enhanced

constraints - the constraints to be enforced on the component

index - the index of the component

See Also:

Container.add(Component), Container.add(Component, int), Container.add(Component, java.lang.Object), LayoutManager, LayoutManager2

writeObject

private void writeObject(ObjectOutputStream s)
                  throws IOException

See readObject and writeObject in JComponent for more information about serialization in Swing.

Throws:

IOException

paramString

protected String paramString()

Returns a string representation of this JToolBar. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overrides:

paramString in class JComponent

Returns:

a string representation of this JToolBar.

setLayout

public void setLayout(LayoutManager mgr)

Description copied from class: Container

Sets the layout manager for this container.

Overrides:

setLayout in class Container

Parameters:

mgr - the specified layout manager

See Also:

Container.doLayout(), Container.getLayout()

getAccessibleContext

public javax.accessibility.AccessibleContext getAccessibleContext()

Gets the AccessibleContext associated with this JToolBar. For tool bars, the AccessibleContext takes the form of an AccessibleJToolBar. A new AccessibleJToolBar instance is created if necessary.

Specified by:

getAccessibleContext in interface javax.accessibility.Accessible

Overrides:

getAccessibleContext in class JComponent

Returns:

an AccessibleJToolBar that serves as the AccessibleContext of this JToolBar