Reply

JGoodies: Using the Button Builders

At 2:20 AM on Mar 2, 2005, R.J. Lorimer wrote:

Buttons are commonplace in most UIs. It's unlikely that there are many UIs that don't incorporate buttons in some fashion to manage user interaction. Going one step further, the concept of bars of buttons are also quite common. Often times when buttons are used they are placed in related groups where each button represents a particular action that can be taken at that point in time. To simplify my incoherent ramblings, I have taken a screenshot from three different programs, each of which utilized this UI design concept:

Upon closer inspection we can learn a few more things. 1.) All of the buttons are the same size (height and width). It is common practice (and common law in the world of UI design guidelines) for buttons associated in a bar like those seen above to all be the same size. 2.) Buttons of a similar intent (related buttons) are organized together. Organizing buttons of a like type together is also a common design guideline, but more importantly gives the user a sense of grouping between various behaviors. 3.) The spacing between the buttons seems to be some sort of constant amount (even in these varying applications). It turns out that there is a whole world of spacing guidelines out there. A common unit of measurement that is introduced in JGoodies Forms (and is commonly used in guidelines) is the DLU (dialog box unit). DLUs are special because rather than being a pixel width, they are relative to the width of a system font - which means that if the system font changes, so does the spacing on elements. While it's been a while since I brushed up, I believe that the standard space for button components like these while varying from platform to platform is between 3-5 dlus (Yes, that's right, it changes between platforms). 4.) Vertical and horizontal button bars exist. This implies that we need a way to build button bars in both axes. To accurately write our own code to handle these special button groups for each platform, we're already picking up a fairly hefty coding assignment. We have to write code to unify the size of each button, figure out the spacing for a certain platform, and then glue spacing and buttons together in many (potentially complex) groups. Let's talk about how we can utilize JGoodies Forms package to make our button bars with ease.

JGoodies Forms comes with two classes: com.jgoodies.forms.builder.ButtonBarBuilder and com.jgoodies.forms.builder.ButtonStackBuilder . These two classes are very similar, so I will only be describing one of them actively in this tip - ButtonBarBuilder.

To quickly get up and running, download the forms distribution, add it to your classpath, and then stuff this code in somewhere to be executed:

  JFrame frame = new JFrame();
  JPanel panel = new JPanel();
 
  ButtonBarBuilder builder = ButtonBarBuilder.createLeftToRightBuilder();
 
  JButton ok = new JButton("OK");
  JButton cancel = new JButton("Cancel");
  builder.addGriddedButtons( new JButton[] { ok, cancel } );
  
  frame.getContentPane().add(builder.getPanel());
 
  frame.pack();
  frame.setVisible(true);

We have effectively replaced the potential of many, many lines in our 'write-your-own' case with one line that ensures the utmost in platform accuracy without any effort on our part. Let's talk in more detail about the features available on this builder.

Gridded components (as we created above) are buttons that will have the same height and width as other components that are gridded. On the other hand, fixed components are components that maintain their own internal preferred dimensions. The power of the button builders become immediately apparent when you begin mixing fixed and gridded buttons. Here is a more complicated example that uses individual calls to the builder as opposed to the array format used above:

  JButton ok = new JButton("OK");
  JButton notSame = new JButton("This is not the same");
  JButton cancel = new JButton("Cancel");
  builder.addGridded(ok);
  builder.addRelatedGap();
  builder.addFixed(notSame);
  builder.addRelatedGap();
  builder.addGridded(cancel);
 
  frame.getContentPane().add(builder.getPanel());
 
  frame.pack();
  frame.setVisible(true);

Note that in this example, while 'This is not the same' is wide enough to fit the appropriate text size for itself, it doesn't cause the other buttons, 'OK' and 'Cancel', to also share that width. Instead they share a common width between each other (the 'OK' button is wider than usual to account for the width of it's gridded sibling, the 'Cancel' button). Also note the use of the addRelatedGap method. While this was handled automatically by the array method above, we must now handle this ourselves if we perform these operations sequentially. The reason we must call this explicitly is because there are actually two types of gaps in a common button bar. The other is an UN -related gap. You would use addUnrelatedGap when the buttons on either side belong in the same bar, but should appear to the user to be grouped independently of each other. Here is the above example, modified to account for usage of this feature:

JButton ok = new JButton("OK");
  JButton notSame = new JButton("This is not the same");
  JButton cancel = new JButton("Cancel");
  builder.addGridded(ok);
  builder.addRelatedGap();
  builder.addGridded(cancel);
  builder.addUnrelatedGap();
  builder.addFixed(notSame);
   
  frame.getContentPane().add(builder.getPanel());
 
  frame.pack();
  frame.setVisible(true);

There is one more component addition method to be concerned about - addGriddedGrowing(JComponent) (and addGriddedGrowingButtons(JButton[]) ). The only difference between gridded buttons and gridded+growing buttons is the fact that gridded and growing buttons will consume extra horizontal real-estate as it becomes available (if you expand or contract the window, the width of the growing buttons will change accordingly). Note that multiple gridded+growing buttons will all equally share the new usable space, and as such will all remain equal in size. Note that growing buttons are NOT available through the ButtonStackBuilder . Button stacks are generally not meant to be included in a scenario where they grow horizontally, and vertically growing buttons is just bizarre, therefore JGoodies doesn't account for it.

Of final note is the com.jgoodies.forms.factories.ButtonBarFactory class. While I don't have time to go into the minute details of each method on this class, be sure to check there first if you find yourself needing a button bar for a certain scenario (such as Ok, Cancel). The factory accounts for the common paradigms of button bars seen in popular software, and makes them immediately usable simply by using its plethora of static methods.