Name: bsC130419			Date: 05/22/2001


java version "1.3.0"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.3.0-C)
Java HotSpot(TM) Client VM (build 1.3.0-C, mixed mode)

As of J2SE 1.3.0 the methods JToolBar.add(Action),
JMenu.add(Action), and JPopupMenu.add(Action) have
been semi-deprecated. The javadoc says this:

"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."


For JMenu and JPopupMenu this isn't a problem because
	myMenu.add(myAction);
can pretty much be replaced with
	myMenu.add(new JMenuItem(myAction));
(Too bad the javadoc doesn't mention this, because this
is easier than using setAction(), but I digress.)


But for JToolBar, there is no simple replacement for
	myToolBar.add(myAction);
If you try something like
	myToolBar.add(new JButton(myAction));
you'll get a new button in the toolbar, but it will
look wrong. Instead, you have to do something like this:

JButton actionButton = new JButton();
actionButton.setHorizontalTextPosition(JButton.CENTER);
actionButton.setVerticalTextPosition(JButton.BOTTOM);
if (myAction.getValue(Action.SMALL_ICON) != null) {
    actionButton.putClientProperty("hideActionText", Boolean.TRUE);
}
actionButton.setAction(myAction);
myToolBar.add(actionButton);


This is bad because
(1) It now takes seven longish lines of code to replace
    what was a single line of code.
(2) These seven longish lines are not documented anywhere.
(3) putClientProperty("hideActionText", TRUE) is an
    undocumented hack that will (hopefully) disappear
    in future implementations. [A better way is to make a
    new Action that masks out the see bug 4457940 for]

Adding an action to a toolbar is a fairly common thing
for a program to do, and there should be a simple way
in which it can be done. Possibilities include:

(A) Promote JToolBar.add(Action) to again be the
    preferred method, but be sure to fix its bugs
    first. [see bugs 4347339, 4391622, 4106486,
    4266524, 4457940]

(B) Provide a new button class that behaves correctly.
    Using it would look something like this
	myToolBar.add(new DefaultToolBarButton(myAction);

(C) Leave JToolBar.add(Action) deprecated or semi-deprecated
    but provide a new method to replace it, maybe
    JToolBar.addButtonFor(Action) or JToolBar.addAsAction(Action).
(Review ID: 124836) 
======================================================================