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".
*
* Warning: Swing is not thread safe. For more * information see Swing's Threading * Policy. *
* 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 JavaBeansTM
* has been added to the java.beans package.
* Please see {@link java.beans.XMLEncoder}.
*
* @beaninfo
* attribute: isContainer true
* description: A component which displays commonly used controls or Actions.
*
* @author Georges Saab
* @author Jeff Shapiro
* @see Action
*/
public class JToolBar extends JComponent implements SwingConstants, Accessible
{
/**
* @see #getUIClassID
* @see #readObject
*/
private static final String uiClassID = "ToolBarUI";
private boolean paintBorder = true;
private Insets margin = null;
private boolean floatable = true;
private int orientation = HORIZONTAL;
/**
* Creates a new tool bar; orientation defaults to HORIZONTAL.
*/
public JToolBar()
{
this( HORIZONTAL );
}
/**
* Creates a new tool bar with the specified orientation.
* The orientation must be either HORIZONTAL
* or VERTICAL.
*
* @param orientation the orientation desired
*/
public JToolBar( int orientation )
{
this(null, orientation);
}
/**
* 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.
*
* @param name the name of the tool bar
* @since 1.3
*/
public JToolBar( String name ) {
this(name, HORIZONTAL);
}
/**
* 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.
*
* @param name the name of the tool bar
* @param orientation the initial orientation -- it must be
* either HORIZONTAL or VERTICAL
* @exception IllegalArgumentException if orientation is neither
* HORIZONTAL nor VERTICAL
* @since 1.3
*/
public JToolBar( String name , int orientation) {
setName(name);
checkOrientation( orientation );
this.orientation = orientation;
DefaultToolBarLayout layout = new DefaultToolBarLayout( orientation );
setLayout( layout );
addPropertyChangeListener( layout );
updateUI();
}
/**
* Returns the tool bar's current UI.
* @see #setUI
*/
public ToolBarUI getUI() {
return (ToolBarUI)ui;
}
/**
* Sets the L&F object that renders this component.
*
* @param ui the ToolBarUI L&F object
* @see UIDefaults#getUI
* @beaninfo
* bound: true
* hidden: true
* attribute: visualUpdate true
* description: The UI object that implements the Component's LookAndFeel.
*/
public void setUI(ToolBarUI ui) {
super.setUI(ui);
}
/**
* Notification from the UIFactory that the L&F has changed.
* Called to replace the UI with the latest version from the
* UIFactory.
*
* @see JComponent#updateUI
*/
public void updateUI() {
setUI((ToolBarUI)UIManager.getUI(this));
// GTKLookAndFeel installs a different LayoutManager, and sets it
// to null after changing the look and feel, so, install the default
// if the LayoutManager is null.
if (getLayout() == null) {
setLayout(new DefaultToolBarLayout(getOrientation()));
}
invalidate();
}
/**
* Returns the name of the L&F class that renders this component.
*
* @return the string "ToolBarUI"
* @see JComponent#getUIClassID
* @see UIDefaults#getUI
*/
public String getUIClassID() {
return uiClassID;
}
/**
* Returns the index of the specified component.
* (Note: Separators occupy index positions.)
*
* @param c the Component to find
* @return an integer indicating the component's position,
* where 0 is first
*/
public int getComponentIndex(Component c) {
int ncomponents = this.getComponentCount();
Component[] component = this.getComponents();
for (int i = 0 ; i < ncomponents ; i++) {
Component comp = component[i];
if (comp == c)
return i;
}
return -1;
}
/**
* Returns the component at the specified index.
*
* @param i the component's position, where 0 is first
* @return the Component at that position,
* or null for an invalid index
*
*/
public Component getComponentAtIndex(int i) {
int ncomponents = this.getComponentCount();
if ( i >= 0 && i < ncomponents) {
Component[] component = this.getComponents();
return component[i];
}
return null;
}
/**
* 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).
*
* @param m an Insets object that defines the space
* between the border and the buttons
* @see Insets
* @beaninfo
* description: The margin between the tool bar's border and contents
* bound: true
* expert: true
*/
public void setMargin(Insets m)
{
Insets old = margin;
margin = m;
firePropertyChange("margin", old, m);
revalidate();
repaint();
}
/**
* Returns the margin between the tool bar's border and
* its buttons.
*
* @return an Insets object containing the margin values
* @see Insets
*/
public Insets getMargin()
{
if(margin == null) {
return new Insets(0,0,0,0);
} else {
return margin;
}
}
/**
* Gets the borderPainted property.
*
* @return the value of the borderPainted property
* @see #setBorderPainted
*/
public boolean isBorderPainted()
{
return paintBorder;
}
/**
* 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.
*
* @param b if true, the border is painted
* @see #isBorderPainted
* @beaninfo
* description: Does the tool bar paint its borders?
* bound: true
* expert: true
*/
public void setBorderPainted(boolean b)
{
if ( paintBorder != b )
{
boolean old = paintBorder;
paintBorder = b;
firePropertyChange("borderPainted", old, b);
revalidate();
repaint();
}
}
/**
* Paints the tool bar's border if the borderPainted property
* is true.
*
* @param g the Graphics context in which the painting
* is done
* @see JComponent#paint
* @see JComponent#setBorder
*/
protected void paintBorder(Graphics g)
{
if (isBorderPainted())
{
super.paintBorder(g);
}
}
/**
* Gets the floatable property.
*
* @return the value of the floatable property
*
* @see #setFloatable
*/
public boolean isFloatable()
{
return floatable;
}
/**
* 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.
*
* @param b if true, the tool bar can be moved;
* false otherwise
* @see #isFloatable
* @beaninfo
* description: Can the tool bar be made to float by the user?
* bound: true
* preferred: true
*/
public void setFloatable( boolean b )
{
if ( floatable != b )
{
boolean old = floatable;
floatable = b;
firePropertyChange("floatable", old, b);
revalidate();
repaint();
}
}
/**
* Returns the current orientation of the tool bar. The value is either
* HORIZONTAL or VERTICAL.
*
* @return an integer representing the current orientation -- either
* HORIZONTAL or VERTICAL
* @see #setOrientation
*/
public int getOrientation()
{
return this.orientation;
}
/**
* 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.
*
* @param o the new orientation -- either HORIZONTAL or
* VERTICAL
* @exception IllegalArgumentException if orientation is neither
* HORIZONTAL nor VERTICAL
* @see #getOrientation
* @beaninfo
* description: The current orientation of the tool bar
* bound: true
* preferred: true
* enum: HORIZONTAL SwingConstants.HORIZONTAL
* VERTICAL SwingConstants.VERTICAL
*/
public void setOrientation( int o )
{
checkOrientation( o );
if ( orientation != o )
{
int old = orientation;
orientation = o;
firePropertyChange("orientation", old, o);
revalidate();
repaint();
}
}
/**
* 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.
*
* @param rollover true for rollover toolbar buttons; otherwise false
* @since 1.4
* @beaninfo
* bound: true
* preferred: true
* attribute: visualUpdate true
* description: Will draw rollover button borders in the toolbar.
*/
public void setRollover(boolean rollover) {
putClientProperty("JToolBar.isRollover",
rollover ? Boolean.TRUE : Boolean.FALSE);
}
/**
* Returns the rollover state.
*
* @return true if rollover toolbar buttons are to be drawn; otherwise false
* @see #setRollover(boolean)
* @since 1.4
*/
public boolean isRollover() {
Boolean rollover = (Boolean)getClientProperty("JToolBar.isRollover");
if (rollover != null) {
return rollover.booleanValue();
}
return false;
}
private void checkOrientation( int orientation )
{
switch ( orientation )
{
case VERTICAL:
case HORIZONTAL:
break;
default:
throw new IllegalArgumentException( "orientation must be one of: VERTICAL, HORIZONTAL" );
}
}
/**
* Appends a separator of default size to the end of the tool bar.
* The default size is determined by the current look and feel.
*/
public void addSeparator()
{
addSeparator(null);
}
/**
* Appends a separator of a specified size to the end
* of the tool bar.
*
* @param size the Dimension of the separator
*/
public void addSeparator( Dimension size )
{
JToolBar.Separator s = new JToolBar.Separator( size );
add(s);
}
/**
* Adds a new JButton which dispatches the action.
*
* @param a the Action object to add as a new menu item
* @return the new button which dispatches the action
*/
public JButton add(Action a) {
JButton b = createActionComponent(a);
b.setAction(a);
add(b);
return b;
}
/**
* Factory method which creates the JButton for
* Actions added to the JToolBar.
* The default name is empty if a null action is passed.
*
* @param a the Action for the button to be added
* @return the newly created button
* @see Action
* @since 1.3
*/
protected JButton createActionComponent(Action a) {
JButton b = new JButton() {
protected PropertyChangeListener createActionPropertyChangeListener(Action a) {
PropertyChangeListener pcl = createActionChangeListener(this);
if (pcl==null) {
pcl = super.createActionPropertyChangeListener(a);
}
return pcl;
}
};
if (a != null && (a.getValue(Action.SMALL_ICON) != null ||
a.getValue(Action.LARGE_ICON_KEY) != null)) {
b.setHideActionText(true);
}
b.setHorizontalTextPosition(JButton.CENTER);
b.setVerticalTextPosition(JButton.BOTTOM);
return 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.
*
* @return null
*/
protected PropertyChangeListener createActionChangeListener(JButton b) {
return null;
}
/**
* If a JButton is being added, it is initially
* set to be disabled.
*
* @param comp the component to be enhanced
* @param constraints the constraints to be enforced on the component
* @param index the index of the component
*
*/
protected void addImpl(Component comp, Object constraints, int index) {
if (comp instanceof Separator) {
if (getOrientation() == VERTICAL) {
( (Separator)comp ).setOrientation(JSeparator.HORIZONTAL);
} else {
( (Separator)comp ).setOrientation(JSeparator.VERTICAL);
}
}
super.addImpl(comp, constraints, index);
if (comp instanceof JButton) {
((JButton)comp).setDefaultCapable(false);
}
}
/**
* A toolbar-specific separator. An object with dimension but
* no contents used to divide buttons on a tool bar into groups.
*/
static public class Separator extends JSeparator
{
private Dimension separatorSize;
/**
* Creates a new toolbar separator with the default size
* as defined by the current look and feel.
*/
public Separator()
{
this( null ); // let the UI define the default size
}
/**
* Creates a new toolbar separator with the specified size.
*
* @param size the Dimension of the separator
*/
public Separator( Dimension size )
{
super( JSeparator.HORIZONTAL );
setSeparatorSize(size);
}
/**
* Returns the name of the L&F class that renders this component.
*
* @return the string "ToolBarSeparatorUI"
* @see JComponent#getUIClassID
* @see UIDefaults#getUI
*/
public String getUIClassID()
{
return "ToolBarSeparatorUI";
}
/**
* Sets the size of the separator.
*
* @param size the new Dimension of the separator
*/
public void setSeparatorSize( Dimension size )
{
if (size != null) {
separatorSize = size;
} else {
super.updateUI();
}
this.invalidate();
}
/**
* Returns the size of the separator
*
* @return the Dimension object containing the separator's
* size (This is a reference, NOT a copy!)
*/
public Dimension getSeparatorSize()
{
return separatorSize;
}
/**
* Returns the minimum size for the separator.
*
* @return the Dimension object containing the separator's
* minimum size
*/
public Dimension getMinimumSize()
{
if (separatorSize != null) {
return separatorSize.getSize();
} else {
return super.getMinimumSize();
}
}
/**
* Returns the maximum size for the separator.
*
* @return the Dimension object containing the separator's
* maximum size
*/
public Dimension getMaximumSize()
{
if (separatorSize != null) {
return separatorSize.getSize();
} else {
return super.getMaximumSize();
}
}
/**
* Returns the preferred size for the separator.
*
* @return the Dimension object containing the separator's
* preferred size
*/
public Dimension getPreferredSize()
{
if (separatorSize != null) {
return separatorSize.getSize();
} else {
return super.getPreferredSize();
}
}
}
/**
* See readObject and writeObject in
* JComponent for more
* information about serialization in Swing.
*/
private void writeObject(ObjectOutputStream s) throws IOException {
s.defaultWriteObject();
if (getUIClassID().equals(uiClassID)) {
byte count = JComponent.getWriteObjCounter(this);
JComponent.setWriteObjCounter(this, --count);
if (count == 0 && ui != null) {
ui.installUI(this);
}
}
}
/**
* 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.
*
* @return a string representation of this JToolBar.
*/
protected String paramString() {
String paintBorderString = (paintBorder ?
"true" : "false");
String marginString = (margin != null ?
margin.toString() : "");
String floatableString = (floatable ?
"true" : "false");
String orientationString = (orientation == HORIZONTAL ?
"HORIZONTAL" : "VERTICAL");
return super.paramString() +
",floatable=" + floatableString +
",margin=" + marginString +
",orientation=" + orientationString +
",paintBorder=" + paintBorderString;
}
private class DefaultToolBarLayout
implements LayoutManager2, Serializable, PropertyChangeListener, UIResource {
BoxLayout lm;
DefaultToolBarLayout(int orientation) {
if (orientation == JToolBar.VERTICAL) {
lm = new BoxLayout(JToolBar.this, BoxLayout.PAGE_AXIS);
} else {
lm = new BoxLayout(JToolBar.this, BoxLayout.LINE_AXIS);
}
}
public void addLayoutComponent(String name, Component comp) {
lm.addLayoutComponent(name, comp);
}
public void addLayoutComponent(Component comp, Object constraints) {
lm.addLayoutComponent(comp, constraints);
}
public void removeLayoutComponent(Component comp) {
lm.removeLayoutComponent(comp);
}
public Dimension preferredLayoutSize(Container target) {
return lm.preferredLayoutSize(target);
}
public Dimension minimumLayoutSize(Container target) {
return lm.minimumLayoutSize(target);
}
public Dimension maximumLayoutSize(Container target) {
return lm.maximumLayoutSize(target);
}
public void layoutContainer(Container target) {
lm.layoutContainer(target);
}
public float getLayoutAlignmentX(Container target) {
return lm.getLayoutAlignmentX(target);
}
public float getLayoutAlignmentY(Container target) {
return lm.getLayoutAlignmentY(target);
}
public void invalidateLayout(Container target) {
lm.invalidateLayout(target);
}
public void propertyChange(PropertyChangeEvent e) {
String name = e.getPropertyName();
if( name.equals("orientation") ) {
int o = ((Integer)e.getNewValue()).intValue();
if (o == JToolBar.VERTICAL)
lm = new BoxLayout(JToolBar.this, BoxLayout.PAGE_AXIS);
else {
lm = new BoxLayout(JToolBar.this, BoxLayout.LINE_AXIS);
}
}
}
}
public void setLayout(LayoutManager mgr) {
LayoutManager oldMgr = getLayout();
if (oldMgr instanceof PropertyChangeListener) {
removePropertyChangeListener((PropertyChangeListener)oldMgr);
}
super.setLayout(mgr);
}
/////////////////
// Accessibility support
////////////////
/**
* 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.
*
* @return an AccessibleJToolBar that serves as the
* AccessibleContext of this JToolBar
*/
public AccessibleContext getAccessibleContext() {
if (accessibleContext == null) {
accessibleContext = new AccessibleJToolBar();
}
return accessibleContext;
}
/**
* This class implements accessibility support for the
* JToolBar class. It provides an implementation of the
* Java Accessibility API appropriate to toolbar user-interface elements.
*/
protected class AccessibleJToolBar extends AccessibleJComponent {
/**
* Get the state of this object.
*
* @return an instance of AccessibleStateSet containing the current
* state set of the object
* @see AccessibleState
*/
public AccessibleStateSet getAccessibleStateSet() {
AccessibleStateSet states = super.getAccessibleStateSet();
// FIXME: [[[WDW - need to add orientation from BoxLayout]]]
// FIXME: [[[WDW - need to do SELECTABLE if SelectionModel is added]]]
return states;
}
/**
* Get the role of this object.
*
* @return an instance of AccessibleRole describing the role of the object
*/
public AccessibleRole getAccessibleRole() {
return AccessibleRole.TOOL_BAR;
}
} // inner class AccessibleJToolBar
}