libjava/javax/swing/JToolBar.java

   1 /* JToolBar.java --
   2    Copyright (C) 2002, 2004, 2005  Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38
  39 package javax.swing;
  40
  41 import java.awt.Component;
  42 import java.awt.Container;
  43 import java.awt.Dimension;
  44 import java.awt.Graphics;
  45 import java.awt.Insets;
  46 import java.awt.LayoutManager;
  47 import java.beans.PropertyChangeListener;
  48
  49 import javax.accessibility.Accessible;
  50 import javax.accessibility.AccessibleContext;
  51 import javax.accessibility.AccessibleRole;
  52 import javax.accessibility.AccessibleStateSet;
  53 import javax.swing.plaf.ToolBarUI;
  54
  55 /**
  56  * JToolBar is a component that provides a toolbar to Swing programs. Users
  57  * can add buttons (or actions that will be represented by JButtons) as well
  58  * as other components to the JToolBar. JToolBars can be dragged in and out
  59  * of their parent components. If the JToolBar is dragged out of the parent,
  60  * then it will be displayed in its own RootPaneContainer. For dragging to
  61  * work properly, JToolBars need to be placed in a Container that has a
  62  * BorderLayout. That parent Container cannot have components in the NORTH,
  63  * EAST, SOUTH,  or WEST components (that is not the JToolBar).
  64  */
  65 public class JToolBar extends JComponent implements SwingConstants, Accessible
  66 {
  67   /**
  68    * AccessibleJToolBar
  69    */
  70   protected class AccessibleJToolBar extends AccessibleJComponent
  71   {
  72     /** DOCUMENT ME! */
  73     private static final long serialVersionUID = -5516888265903814215L;
  74
  75     /**
  76      * Constructor AccessibleJToolBar
  77      */
  78     protected AccessibleJToolBar()
  79     {
  80     }
  81
  82     /**
  83      * getAccessibleStateSet
  84      *
  85      * @return AccessibleStateSet
  86      */
  87     public AccessibleStateSet getAccessibleStateSet()
  88     {
  89       return null; // TODO
  90     }
  91
  92     /**
  93      * getAccessibleRole
  94      *
  95      * @return AccessibleRole
  96      */
  97     public AccessibleRole getAccessibleRole()
  98     {
  99       return AccessibleRole.TOOL_BAR;
 100     }
 101   }
 102
 103   /**
 104    * This is the private JToolBar layout manager.
 105    */
 106   private class DefaultToolBarLayout implements LayoutManager
 107   {
 108     /**
 109      * This method is called when a new component is added to the container.
 110      *
 111      * @param name The name of the component added.
 112      * @param comp The component that was added.
 113      */
 114     public void addLayoutComponent(String name, Component comp)
 115     {
 116       // Do nothing.
 117     }
 118
 119     /**
 120      * This method is called to lay out the given container  to position and
 121      * size the child components.
 122      *
 123      * @param c The container to lay out.
 124      *
 125      * @throws Error DOCUMENT ME!
 126      */
 127     public void layoutContainer(Container c)
 128     {
 129       if (! (c instanceof JToolBar))
 130         throw new Error("DefaultToolBarLayout can only be used on JToolBars.");
 131       Insets insets = getInsets();
 132       Insets margin = getMargin();
 133       int middle;
 134       if (margin != null)
 135         {
 136           insets.left += margin.left;
 137           insets.top += margin.top;
 138           insets.bottom += margin.bottom;
 139           insets.right += margin.right;
 140         }
 141       Component[] components = c.getComponents();
 142       Dimension tdims = c.getSize();
 143       int start = 0;
 144       Dimension pref;
 145
 146       if (getOrientation() == SwingUtilities.HORIZONTAL)
 147         {
 148           start += insets.left;
 149           for (int i = 0; i < components.length; i++)
 150             {
 151               if (components[i] != null && components[i].isVisible())
 152                 {
 153                   pref = components[i].getPreferredSize();
 154                   if (pref != null)
 155                     {
 156                       middle = (tdims.height - pref.height) / 2;
 157                       components[i].setBounds(start, middle, pref.width,
 158                                               pref.height);
 159                       start += pref.width;
 160                     }
 161                 }
 162             }
 163         }
 164       else
 165         {
 166           start += insets.top;
 167           for (int i = 0; i < components.length; i++)
 168             {
 169               if (components[i] != null && components[i].isVisible())
 170                 {
 171                   pref = components[i].getPreferredSize();
 172                   if (pref != null)
 173                     {
 174                       middle = (tdims.width - pref.width) / 2;
 175                       components[i].setBounds(middle, start, pref.width,
 176                                               pref.height);
 177                       start += pref.height;
 178                     }
 179                 }
 180             }
 181         }
 182     }
 183
 184     /**
 185      * This method returns the minimum size of the given container given the
 186      * child components.
 187      *
 188      * @param parent The container to measure.
 189      *
 190      * @return The minimum size of the given container.
 191      */
 192     public Dimension minimumLayoutSize(Container parent)
 193     {
 194       return preferredLayoutSize(parent);
 195     }
 196
 197     /**
 198      * This method returns the preferred size of the given container given the
 199      * child components.
 200      *
 201      * @param parent The container to measure.
 202      *
 203      * @return The preferred size of the given container.
 204      */
 205     public Dimension preferredLayoutSize(Container parent)
 206     {
 207       int orientation = getOrientation();
 208       Component[] components = getComponents();
 209
 210       int limit = 0;
 211       int total = 0;
 212       Dimension dims;
 213
 214       int w = 0;
 215       int h = 0;
 216
 217       if (orientation == SwingConstants.HORIZONTAL)
 218         {
 219           for (int i = 0; i < components.length; i++)
 220             {
 221               dims = components[i].getPreferredSize();
 222               if (dims != null)
 223                 {
 224                   if (dims.height > limit)
 225                     limit = dims.height;
 226                   total += dims.width;
 227                 }
 228             }
 229           w = total;
 230           h = limit;
 231         }
 232       else
 233         {
 234           for (int i = 0; i < components.length; i++)
 235             {
 236               dims = components[i].getPreferredSize();
 237               if (dims != null)
 238                 {
 239                   if (dims.width > limit)
 240                     limit = dims.width;
 241                   total += dims.height;
 242                 }
 243             }
 244           w = limit;
 245           h = total;
 246         }
 247
 248       Insets insets = getInsets();
 249       w += insets.left + insets.right;
 250       h += insets.top + insets.bottom;
 251
 252       Insets margin = getMargin();
 253       if (margin != null)
 254         {
 255           w += margin.left + margin.right;
 256           h += margin.top + margin.bottom;
 257         }
 258
 259       return new Dimension(w, h);
 260     }
 261
 262     /**
 263      * This method is called when the given component  is removed from the
 264      * container.
 265      *
 266      * @param comp The component removed.
 267      */
 268     public void removeLayoutComponent(Component comp)
 269     {
 270       // Do nothing.
 271     }
 272   }
 273
 274   /**
 275    * This is an extension of JSeparator used in toolbars. Unlike JSeparator,
 276    * nothing is painted for this Separator, it is only blank space that
 277    * separates components.
 278    */
 279   public static class Separator extends JSeparator
 280   {
 281     /** DOCUMENT ME! */
 282     private static final long serialVersionUID = -1656745644823105219L;
 283
 284     /**
 285      * Creates a new Separator object.
 286      */
 287     public Separator()
 288     {
 289       super();
 290     } // Separator()
 291
 292     /**
 293      * Creates a new Separator object with the given size.
 294      *
 295      * @param size The size of the separator.
 296      */
 297     public Separator(Dimension size)
 298     {
 299       setPreferredSize(size);
 300     } // Separator()
 301
 302     /**
 303      * This method returns the String ID of the UI class of  Separator.
 304      *
 305      * @return The UI class' String ID.
 306      */
 307     public String getUIClassID()
 308     {
 309       return "ToolBarSeparatorUI";
 310     } // getUIClassID()
 311
 312     /**
 313      * This method returns the preferred size of the Separator.
 314      *
 315      * @return The preferred size of the Separator.
 316      */
 317     public Dimension getPreferredSize()
 318     {
 319       return super.getPreferredSize();
 320     } // getPreferredSize()
 321
 322     /**
 323      * This method returns the maximum size of the Separator.
 324      *
 325      * @return The maximum size of the Separator.
 326      */
 327     public Dimension getMaximumSize()
 328     {
 329       return super.getPreferredSize();
 330     } // getMaximumSize()
 331
 332     /**
 333      * This method returns the minimum size of the Separator.
 334      *
 335      * @return The minimum size of the Separator.
 336      */
 337     public Dimension getMinimumSize()
 338     {
 339       return super.getPreferredSize();
 340     } // getMinimumSize()
 341
 342     /**
 343      * This method returns the size of the Separator.
 344      *
 345      * @return The size of the Separator.
 346      */
 347     public Dimension getSeparatorSize()
 348     {
 349       return super.getPreferredSize();
 350     } // getSeparatorSize()
 351
 352     /**
 353      * This method sets the size of the Separator.
 354      *
 355      * @param size The new size of the Separator.
 356      */
 357     public void setSeparatorSize(Dimension size)
 358     {
 359       setPreferredSize(size);
 360     } // setSeparatorSize()
 361   } // Separator
 362
 363   /** DOCUMENT ME! */
 364   private static final long serialVersionUID = -1269915519555129643L;
 365
 366   /** Whether the JToolBar paints its border. */
 367   private transient boolean paintBorder = true;
 368
 369   /** The extra insets around the JToolBar. */
 370   private transient Insets margin;
 371
 372   /** Whether the JToolBar can float (and be dragged around). */
 373   private transient boolean floatable = true;
 374
 375   /** Whether the buttons will have rollover borders. */
 376   private transient boolean rollover;
 377
 378   /** The orientation of the JToolBar. */
 379   private int orientation = HORIZONTAL;
 380
 381   /**
 382    * This method creates a new JToolBar object with horizontal orientation
 383    * and no name.
 384    */
 385   public JToolBar()
 386   {
 387     this(null, HORIZONTAL);
 388   } // JToolBar()
 389
 390   /**
 391    * This method creates a new JToolBar with the given orientation and  no
 392    * name.
 393    *
 394    * @param orientation JToolBar orientation (HORIZONTAL or VERTICAL)
 395    */
 396   public JToolBar(int orientation)
 397   {
 398     this(null, orientation);
 399   } // JToolBar()
 400
 401   /**
 402    * This method creates a new JToolBar object with the given name and
 403    * horizontal orientation.
 404    *
 405    * @param name Name assigned to undocked tool bar.
 406    */
 407   public JToolBar(String name)
 408   {
 409     this(name, HORIZONTAL);
 410   } // JToolBar()
 411
 412   /**
 413    * This method creates a new JToolBar object with the given name and
 414    * orientation.
 415    *
 416    * @param name Name assigned to undocked tool bar.
 417    * @param orientation JToolBar orientation (HORIZONTAL or VERTICAL)
 418    */
 419   public JToolBar(String name, int orientation)
 420   {
 421     setName(name);
 422     setOrientation(orientation);
 423     setLayout(new DefaultToolBarLayout());
 424     revalidate();
 425     updateUI();
 426   } // JToolBar()
 427
 428   /**
 429    * This method adds a new JButton that performs the given Action to the
 430    * JToolBar.
 431    *
 432    * @param action The Action to add to the JToolBar.
 433    *
 434    * @return The JButton that wraps the Action.
 435    */
 436   public JButton add(Action action)
 437   {
 438     JButton b = createActionComponent(action);
 439     add(b);
 440     return b;
 441   } // add()
 442
 443   /**
 444    * This method paints the border if the borderPainted property is true.
 445    *
 446    * @param graphics The graphics object to paint with.
 447    */
 448   protected void paintBorder(Graphics graphics)
 449   {
 450     if (paintBorder && isFloatable())
 451       super.paintBorder(graphics);
 452   } // paintBorder()
 453
 454   /**
 455    * This method returns the UI class used to paint this JToolBar.
 456    *
 457    * @return The UI class for this JToolBar.
 458    */
 459   public ToolBarUI getUI()
 460   {
 461     return (ToolBarUI) ui;
 462   } // getUI()
 463
 464   /**
 465    * This method sets the UI used with the JToolBar.
 466    *
 467    * @param ui The UI used with the JToolBar.
 468    */
 469   public void setUI(ToolBarUI ui)
 470   {
 471     super.setUI(ui);
 472   } // setUI()
 473
 474   /**
 475    * This method resets the UI used to the Look and Feel defaults.
 476    */
 477   public void updateUI()
 478   {
 479     setUI((ToolBarUI) UIManager.getUI(this));
 480     revalidate();
 481     repaint();
 482   } // updateUI()
 483
 484   /**
 485    * This method returns the String identifier for the UI class to the used
 486    * with the JToolBar.
 487    *
 488    * @return The String identifier for the UI class.
 489    */
 490   public String getUIClassID()
 491   {
 492     return "ToolBarUI";
 493   } // getUIClassID()
 494
 495   /**
 496    * This method sets the rollover property for the JToolBar. In rollover
 497    * mode, JButtons inside the JToolBar will only display their borders when
 498    * the mouse is moving over them.
 499    *
 500    * @param b The new rollover property.
 501    */
 502   public void setRollover(boolean b)
 503   {
 504     if (b != rollover)
 505       {
 506         rollover = b;
 507         firePropertyChange("rollover", ! rollover, rollover);
 508         revalidate();
 509         repaint();
 510       }
 511   }
 512
 513   /**
 514    * This method returns the rollover property.
 515    *
 516    * @return The rollover property.
 517    */
 518   public boolean isRollover()
 519   {
 520     return rollover;
 521   }
 522
 523   /**
 524    * This method returns the index of the given component.
 525    *
 526    * @param component The component to find.
 527    *
 528    * @return The index of the given component.
 529    */
 530   public int getComponentIndex(Component component)
 531   {
 532     Component[] components = getComponents();
 533     if (components == null)
 534       return -1;
 535
 536     for (int i = 0; i < components.length; i++)
 537       if (components[i] == component)
 538         return i;
 539
 540     return -1;
 541   } // getComponentIndex()
 542
 543   /**
 544    * This method returns the component at the given index.
 545    *
 546    * @param index The index of the component.
 547    *
 548    * @return The component at the given index.
 549    */
 550   public Component getComponentAtIndex(int index)
 551   {
 552     return getComponent(index);
 553   } // getComponentAtIndex()
 554
 555   /**
 556    * This method returns the margin property.
 557    *
 558    * @return The margin property.
 559    */
 560   public Insets getMargin()
 561   {
 562     return margin;
 563   } // getMargin()
 564
 565   /**
 566    * This method sets the margin property. The margin property determines the
 567    * extra space between the children components of the JToolBar and the
 568    * border.
 569    *
 570    * @param margin The margin property.
 571    */
 572   public void setMargin(Insets margin)
 573   {
 574     if ((this.margin != null && margin == null)
 575         || (this.margin == null && margin != null)
 576         || (margin != null && this.margin != null
 577         && (margin.left != this.margin.left
 578         || margin.right != this.margin.right || margin.top != this.margin.top
 579         || margin.bottom != this.margin.bottom)))
 580       {
 581         Insets oldMargin = this.margin;
 582         this.margin = margin;
 583         firePropertyChange("margin", oldMargin, this.margin);
 584         revalidate();
 585         repaint();
 586       }
 587   } // setMargin()
 588
 589   /**
 590    * This method returns the borderPainted property.
 591    *
 592    * @return The borderPainted property.
 593    */
 594   public boolean isBorderPainted()
 595   {
 596     return paintBorder;
 597   } // isBorderPainted()
 598
 599   /**
 600    * This method sets the borderPainted property. If set to false, the border
 601    * will not be painted.
 602    *
 603    * @param painted Whether the border will be painted.
 604    */
 605   public void setBorderPainted(boolean painted)
 606   {
 607     if (painted != paintBorder)
 608       {
 609         paintBorder = painted;
 610         firePropertyChange("borderPainted", ! paintBorder,
 611                            paintBorder);
 612         repaint();
 613       }
 614   } // setBorderPainted()
 615
 616   /**
 617    * This method returns the floatable property.
 618    *
 619    * @return The floatable property.
 620    */
 621   public boolean isFloatable()
 622   {
 623     return floatable;
 624   } // isFloatable()
 625
 626   /**
 627    * This method sets the floatable property. If set to false, the JToolBar
 628    * cannot be dragged.
 629    *
 630    * @param floatable Whether the JToolBar can be dragged.
 631    */
 632   public void setFloatable(boolean floatable)
 633   {
 634     if (floatable != this.floatable)
 635       {
 636         this.floatable = floatable;
 637         firePropertyChange("floatable", ! floatable, floatable);
 638       }
 639   } // setFloatable()
 640
 641   /**
 642    * This method returns the orientation of the JToolBar.
 643    *
 644    * @return The orientation of the JToolBar.
 645    */
 646   public int getOrientation()
 647   {
 648     return orientation;
 649   } // getOrientation()
 650
 651   /**
 652    * This method sets the layout manager to be used with the JToolBar.
 653    *
 654    * @param mgr The Layout Manager used with the JToolBar.
 655    */
 656   public void setLayout(LayoutManager mgr)
 657   {
 658     super.setLayout(mgr);
 659     revalidate();
 660     repaint();
 661   } // setLayout()
 662
 663   /**
 664    * This method sets the orientation property for JToolBar.
 665    *
 666    * @param orientation The new orientation for JToolBar.
 667    *
 668    * @throws IllegalArgumentException If the orientation is not HORIZONTAL or
 669    *         VERTICAL.
 670    */
 671   public void setOrientation(int orientation)
 672   {
 673     if (orientation != HORIZONTAL && orientation != VERTICAL)
 674       throw new IllegalArgumentException(orientation
 675                                          + " is not a legal orientation");
 676     if (orientation != this.orientation)
 677       {
 678         int oldOrientation = this.orientation;
 679         this.orientation = orientation;
 680         firePropertyChange("orientation", oldOrientation, this.orientation);
 681         revalidate();
 682         repaint();
 683       }
 684   } // setOrientation()
 685
 686   /**
 687    * This method adds a Separator of default size to the JToolBar.
 688    */
 689   public void addSeparator()
 690   {
 691     add(new Separator());
 692   } // addSeparator()
 693
 694   /**
 695    * This method adds a Separator with the given size to the JToolBar.
 696    *
 697    * @param size The size of the Separator.
 698    */
 699   public void addSeparator(Dimension size)
 700   {
 701     add(new Separator(size));
 702   } // addSeparator()
 703
 704   /**
 705    * This method is used to create JButtons which can be added to the JToolBar
 706    * for the given action.
 707    *
 708    * @param action The action to create a JButton for.
 709    *
 710    * @return The JButton created from the action.
 711    */
 712   protected JButton createActionComponent(Action action)
 713   {
 714     return new JButton(action);
 715   } // createActionComponent()
 716
 717   /**
 718    * This method creates a pre-configured PropertyChangeListener which updates
 719    * the control as changes are made to the Action. However, this is no
 720    * longer the recommended way of adding Actions to Containers. As such,
 721    * this method returns null.
 722    *
 723    * @param button The JButton to configure a PropertyChangeListener for.
 724    *
 725    * @return null.
 726    */
 727   protected PropertyChangeListener createActionChangeListener(JButton button)
 728   {
 729     // XXX: As specified, this returns null. But seems kind of strange, usually deprecated methods don't just return null, verify!
 730     return null;
 731   } // createActionChangeListener()
 732
 733   /**
 734    * This method overrides Container's addImpl method. If a JButton is added,
 735    * it is disabled.
 736    *
 737    * @param component The Component to add.
 738    * @param constraints The Constraints placed on the component.
 739    * @param index The index to place the Component at.
 740    */
 741   protected void addImpl(Component component, Object constraints, int index)
 742   {
 743     // XXX: Sun says disable button but test cases show otherwise.
 744     super.addImpl(component, constraints, index);
 745   } // addImpl()
 746
 747   /**
 748    * This method returns a String description of the JToolBar.
 749    *
 750    * @return A String description of the JToolBar.
 751    */
 752   protected String paramString()
 753   {
 754     return "JToolBar";
 755   } // paramString()
 756
 757   /**
 758    * getAccessibleContext
 759    *
 760    * @return AccessibleContext
 761    */
 762   public AccessibleContext getAccessibleContext()
 763   {
 764     if (accessibleContext == null)
 765       accessibleContext = new AccessibleJToolBar();
 766
 767     return accessibleContext;
 768   }
 769 }