libjava/javax/swing/JToolBar.java

   1 /* JToolBar.java --
   2    Copyright (C) 2002, 2004 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   /** Fired in a PropertyChangeEvent when the orientation property changes. */
 382         public static final String ORIENTATION_CHANGED_PROPERTY = "orientation";
 383
 384   /** Fired in a PropertyChangeEvent when the floatable property changes. */
 385   public static final String FLOATABLE_CHANGED_PROPERTY = "floatable";
 386
 387   /** Fired in a PropertyChangeEvent when the borderPainted property changes. */
 388   public static final String BORDER_PAINTED_CHANGED_PROPERTY = "borderPainted";
 389
 390   /** Fired in a PropertyChangeEvent when the margin property changes. */
 391   public static final String MARGIN_CHANGED_PROPERTY = "margin";
 392
 393   /** Fired in a PropertyChangeEvent when the rollover property changes. */
 394   public static final String ROLLOVER_CHANGED_PROPERTY = "rollover";
 395
 396         /**
 397    * This method creates a new JToolBar object with horizontal orientation
 398    * and no name.
 399          */
 400   public JToolBar()
 401   {
 402     this(null, HORIZONTAL);
 403         } // JToolBar()
 404
 405         /**
 406    * This method creates a new JToolBar with the given orientation and  no
 407    * name.
 408    *
 409          * @param orientation JToolBar orientation (HORIZONTAL or VERTICAL)
 410          */
 411   public JToolBar(int orientation)
 412   {
 413           this(null, orientation);
 414         } // JToolBar()
 415
 416         /**
 417    * This method creates a new JToolBar object with the given name and
 418    * horizontal orientation.
 419    *
 420          * @param name Name assigned to undocked tool bar.
 421          */
 422   public JToolBar(String name)
 423   {
 424           this(name, HORIZONTAL);
 425         } // JToolBar()
 426
 427         /**
 428    * This method creates a new JToolBar object with the given name and
 429    * orientation.
 430    *
 431          * @param name Name assigned to undocked tool bar.
 432          * @param orientation JToolBar orientation (HORIZONTAL or VERTICAL)
 433          */
 434   public JToolBar(String name, int orientation)
 435   {
 436                 setName(name);
 437     setOrientation(orientation);
 438     setLayout(new DefaultToolBarLayout());
 439     revalidate();
 440                 updateUI();
 441         } // JToolBar()
 442
 443         /**
 444    * This method adds a new JButton that performs the given Action to the
 445    * JToolBar.
 446    *
 447    * @param action The Action to add to the JToolBar.
 448    *
 449    * @return The JButton that wraps the Action.
 450          */
 451   public JButton add(Action action)
 452   {
 453     JButton b = createActionComponent(action);
 454     add(b);
 455     return b;
 456         } // add()
 457
 458         /**
 459    * This method paints the border if the borderPainted property is true.
 460    *
 461    * @param graphics The graphics object to paint with.
 462          */
 463   protected void paintBorder(Graphics graphics)
 464   {
 465     if (paintBorder && isFloatable())
 466       super.paintBorder(graphics);
 467         } // paintBorder()
 468
 469         /**
 470    * This method returns the UI class used to paint this JToolBar.
 471    *
 472    * @return The UI class for this JToolBar.
 473          */
 474   public ToolBarUI getUI()
 475   {
 476                 return (ToolBarUI) ui;
 477         } // getUI()
 478
 479         /**
 480    * This method sets the UI used with the JToolBar.
 481    *
 482    * @param ui The UI used with the JToolBar.
 483          */
 484   public void setUI(ToolBarUI ui)
 485   {
 486                 super.setUI(ui);
 487         } // setUI()
 488
 489         /**
 490    * This method resets the UI used to the Look and Feel defaults.
 491          */
 492   public void updateUI()
 493   {
 494           setUI((ToolBarUI)UIManager.getUI(this));
 495     revalidate();
 496     repaint();
 497         } // updateUI()
 498
 499         /**
 500    * This method returns the String identifier for the UI class to the used
 501    * with the JToolBar.
 502    *
 503    * @return The String identifier for the UI class.
 504          */
 505   public String getUIClassID()
 506   {
 507     return "ToolBarUI";
 508         } // getUIClassID()
 509
 510         /**
 511    * This method sets the rollover property for the JToolBar. In rollover
 512    * mode, JButtons inside the JToolBar will only display their borders when
 513    * the mouse is moving over them.
 514    *
 515    * @param b The new rollover property.
 516          */
 517   public void setRollover(boolean b)
 518   {
 519     if (b != rollover)
 520       {
 521         rollover = b;
 522         firePropertyChange(ROLLOVER_CHANGED_PROPERTY, ! rollover, rollover);
 523         revalidate();
 524         repaint();
 525       }
 526   }
 527
 528   /**
 529    * This method returns the rollover property.
 530    *
 531    * @return The rollover property.
 532    */
 533   public boolean isRollover()
 534   {
 535     return rollover;
 536   }
 537
 538   /**
 539    * This method returns the index of the given component.
 540    *
 541    * @param component The component to find.
 542    *
 543    * @return The index of the given component.
 544    */
 545   public int getComponentIndex(Component component)
 546   {
 547     Component[] components = getComponents();
 548     if (components == null)
 549       return -1;
 550
 551     for (int i = 0; i < components.length; i++)
 552       if (components[i] == component)
 553         return i;
 554
 555     return -1;
 556         } // getComponentIndex()
 557
 558         /**
 559    * This method returns the component at the given index.
 560    *
 561    * @param index The index of the component.
 562    *
 563    * @return The component at the given index.
 564          */
 565   public Component getComponentAtIndex(int index)
 566   {
 567     return getComponent(index);
 568         } // getComponentAtIndex()
 569
 570         /**
 571    * This method returns the margin property.
 572    *
 573    * @return The margin property.
 574          */
 575   public Insets getMargin()
 576   {
 577     return margin;
 578         } // getMargin()
 579
 580         /**
 581    * This method sets the margin property. The margin property determines the
 582    * extra space between the children components of the JToolBar and the
 583    * border.
 584    *
 585    * @param margin The margin property.
 586          */
 587   public void setMargin(Insets margin)
 588   {
 589     if ((this.margin != null && margin == null)
 590         || (this.margin == null && margin != null)
 591         || (margin != null && this.margin != null
 592         && (margin.left != this.margin.left
 593         || margin.right != this.margin.right || margin.top != this.margin.top
 594         || margin.bottom != this.margin.bottom)))
 595       {
 596         Insets oldMargin = this.margin;
 597         this.margin = margin;
 598         firePropertyChange(MARGIN_CHANGED_PROPERTY, oldMargin, this.margin);
 599         revalidate();
 600         repaint();
 601       }
 602         } // setMargin()
 603
 604         /**
 605    * This method returns the borderPainted property.
 606    *
 607    * @return The borderPainted property.
 608          */
 609   public boolean isBorderPainted()
 610   {
 611     return paintBorder;
 612         } // isBorderPainted()
 613
 614         /**
 615    * This method sets the borderPainted property. If set to false, the border
 616    * will not be painted.
 617    *
 618    * @param painted Whether the border will be painted.
 619          */
 620   public void setBorderPainted(boolean painted)
 621   {
 622     if (painted != paintBorder)
 623       {
 624         paintBorder = painted;
 625         firePropertyChange(BORDER_PAINTED_CHANGED_PROPERTY, ! paintBorder,
 626                            paintBorder);
 627         repaint();
 628       }
 629         } // setBorderPainted()
 630
 631         /**
 632    * This method returns the floatable property.
 633    *
 634    * @return The floatable property.
 635          */
 636   public boolean isFloatable()
 637   {
 638     return floatable;
 639         } // isFloatable()
 640
 641         /**
 642    * This method sets the floatable property. If set to false, the JToolBar
 643    * cannot be dragged.
 644    *
 645    * @param floatable Whether the JToolBar can be dragged.
 646          */
 647   public void setFloatable(boolean floatable)
 648   {
 649     if (floatable != this.floatable)
 650       {
 651         this.floatable = floatable;
 652         firePropertyChange(FLOATABLE_CHANGED_PROPERTY, ! floatable, floatable);
 653       }
 654         } // setFloatable()
 655
 656         /**
 657    * This method returns the orientation of the JToolBar.
 658    *
 659    * @return The orientation of the JToolBar.
 660          */
 661   public int getOrientation()
 662   {
 663     return orientation;
 664         } // getOrientation()
 665
 666         /**
 667    * This method sets the layout manager to be used with the JToolBar.
 668    *
 669    * @param mgr The Layout Manager used with the JToolBar.
 670          */
 671   public void setLayout(LayoutManager mgr)
 672   {
 673             super.setLayout(mgr);
 674     revalidate();
 675     repaint();
 676         } // setLayout()
 677
 678         /**
 679    * This method sets the orientation property for JToolBar.
 680    *
 681    * @param orientation The new orientation for JToolBar.
 682    *
 683    * @throws IllegalArgumentException If the orientation is not HORIZONTAL or
 684    *         VERTICAL.
 685          */
 686   public void setOrientation(int orientation)
 687   {
 688                 if (orientation != HORIZONTAL && orientation != VERTICAL)
 689       throw new IllegalArgumentException(orientation
 690                                          + " is not a legal orientation");
 691             if (orientation != this.orientation)
 692             {
 693                 int oldOrientation = this.orientation;
 694                 this.orientation = orientation;
 695                 firePropertyChange(ORIENTATION_CHANGED_PROPERTY, oldOrientation,
 696                         this.orientation);
 697         revalidate();
 698         repaint();
 699             }
 700         } // setOrientation()
 701
 702         /**
 703    * This method adds a Separator of default size to the JToolBar.
 704          */
 705   public void addSeparator()
 706   {
 707     add(new Separator());
 708         } // addSeparator()
 709
 710         /**
 711    * This method adds a Separator with the given size to the JToolBar.
 712    *
 713    * @param size The size of the Separator.
 714          */
 715   public void addSeparator(Dimension size)
 716   {
 717     add(new Separator(size));
 718         } // addSeparator()
 719
 720         /**
 721    * This method is used to create JButtons which can be added to the JToolBar
 722    * for the given action.
 723    *
 724    * @param action The action to create a JButton for.
 725    *
 726    * @return The JButton created from the action.
 727          */
 728   protected JButton createActionComponent(Action action)
 729   {
 730     return new JButton(action);
 731         } // createActionComponent()
 732
 733         /**
 734    * This method creates a pre-configured PropertyChangeListener which updates
 735    * the control as changes are made to the Action. However, this is no
 736    * longer the recommended way of adding Actions to Containers. As such,
 737    * this method returns null.
 738    *
 739    * @param button The JButton to configure a PropertyChangeListener for.
 740    *
 741    * @return null.
 742          */
 743   protected PropertyChangeListener createActionChangeListener(JButton button)
 744   {
 745     // XXX: As specified, this returns null. But seems kind of strange, usually deprecated methods don't just return null, verify!
 746     return null;
 747         } // createActionChangeListener()
 748
 749         /**
 750    * This method overrides Container's addImpl method. If a JButton is added,
 751    * it is disabled.
 752    *
 753    * @param component The Component to add.
 754    * @param constraints The Constraints placed on the component.
 755    * @param index The index to place the Component at.
 756   */
 757   protected void addImpl(Component component, Object constraints, int index)
 758   {
 759     // XXX: Sun says disable button but test cases show otherwise.
 760     super.addImpl(component, constraints, index);
 761   } // addImpl()
 762
 763         /**
 764    * This method returns a String description of the JToolBar.
 765    *
 766    * @return A String description of the JToolBar.
 767          */
 768   protected String paramString()
 769   {
 770     return "JToolBar";
 771         } // paramString()
 772
 773   /**
 774    * getAccessibleContext
 775    *
 776    * @return AccessibleContext
 777    */
 778   public AccessibleContext getAccessibleContext()
 779   {
 780     if (accessibleContext == null)
 781       accessibleContext = new AccessibleJToolBar();
 782
 783     return accessibleContext;
 784   }
 785 }