Java
http://www.modernminds.com
U sing the ButtonBar Class

There is extensive documentation included with the Ultimate Button BarTM package describing how ButtonBar.class functions, but it can sometimes be difficult to understand how a class is actually used in a program based solely on technical information.

In this document, we will take a look at how the class is used in an actual program. The program that will be examined is ButtonBarDemo.java which is used in the "Systems Control Panel" example.

Note: The documentation below contains only excerpts from the source code for illustrative purposes.

The Java program that we will be working with is an applet. The class declaration for the applet is:

public class ButtonBarDemo extends Applet implements ButtonBarObserver

Notice that the applet implements the ButtonBarObserver interface. This interface has one method -- buttonBarEvent -- that will be called by the ButtonBar class to inform the applet of ButtonBar events.

Since this applet implements a specifically designed ButtonBar, we do not need to read any parameters from the HTML. Instead, we call the ButtonBar constructor in the applet's init method with the specific parameters required to create our ButtonBar. The constructor is:

buttonBar = new ButtonBar(
    true,              /* barHorizontal*/
    getDocumentBase(), /* base */
    "Base.JPG",        /* baseBarName */
    "Over.JPG",        /* mouseOverBarName */
    (String)null,      /* mouseOverBar2Name */
    "Down.JPG",        /* mouseDownBarName */
    "DownOver.JPG",    /* mouseDownOverBarName */
    (String)null,      /* buttonsDisabledBarName */
    "Background.JPG",  /* backgroundImageName */
    24,                /* barXBackgroundPos */
    24,                /* barYBackgroundPos */
    0,                 /* drawButtonBorders */
    (Color)null,       /* borderColorTopLeft */
    (Color)null,       /* borderColorBottomRight */
    0,                 /* borderIntensityPercent */
    0,                 /* buttonBorderSize */
    false,             /* downShift */
    0,                 /* downShiftAmt */
    0,                 /* baseBrightenPct */
    null,              /* baseBrightenTint */
    0,                 /* mouseOverBrightenPct */
    null,              /* mouseOverBrightenTint */
    false,             /* mouseDownBrightenAll */
    0,                 /* mouseDownBrightenPct */
    null,              /* mouseDownBrightenTint */
    0,                 /* buttonsDisabledDimPct */
    0,                 /* grayBarBrighten */
    0,                 /* frameRate */
);

After creating the ButtonBar object, we next define each of the buttons that appears on the ButtonBar using ButtonRegion objects:

shields = new ButtonRegion("S", 2, 36);
phasers = new ButtonRegion("P", 45, 36);
torpedos = new ButtonRegion("T", 87, 36);
resetAll = new ButtonRegion("R", 155, 36);

Buttons are identified using the first String parameter in the ButtonRegion constructor. The second parameter is the offset to the beginning of the button, and the third parameter is the width (in this case) of the button.

The left three buttons on the ButtonBar (shields, phasers, and torpedos) are to be "sticky" buttons. When one of these buttons is clicked, it will remain "stuck" in a button state (on or off) until it is clicked again.

To tell the ButtonBar class that a button is a "sticky" button, we use the stickyButton method of the ButtonRegion class.

shields.stickyButton(true);
phasers.stickyButton(true);
torpedos.stickyButton(true);

Now we add the buttons to the ButtonBar using the addButton method of the ButtonBar class.

buttonBar.addButton(shields);
buttonBar.addButton(phasers);
buttonBar.addButton(torpedos);
buttonBar.addButton(resetAll);

In order to receive ButtonBar events, we must register the applet as an observer by using the addButtonObserver method of the ButtonBar class.

buttonBar.addButtonObserver(this);

Since we implement the ButtonBarObserver interface, the buttonBarEvent method in our applet (see below) will now be called whenever a ButtonBar event occurs.

The ButtonBar is ready to be added to the applet's display area.

setLayout(null);
add(buttonBar);

This is all of the code that we need in the applet's init method. The only other method that must be implemented is the buttonBarEvent method required by the ButtonBarObserver interface.

The declaration of the buttonBarEvent method is:

public void buttonBarEvent(ButtonBar barID, String buttonID, int buttonEvent)

Since we only have one ButtonBar in this applet, we can ignore the barID parameter. The value of the buttonID parameter will be equal to the String that was assigned when the ButtonRegion was created. We will use the buttonID to determine for what button the event occurred. The third parameter, buttonEvent, is an event code that tells us what type of event occurred.

The only code that is needed for the buttonBarEvent method is:

switch (buttonEvent) {
   case ButtonBar.IMAGES_READY:
     buttonBar.enable(true);
     break;
   case ButtonBar.BUTTON_DOWN:
     if (buttonID.charAt(0) == 'R') {
        shields.setStuck(false);
        phasers.setStuck(false);
        torpedos.setStuck(false);
     }
     break;
}

There are two events that we are interested in for this simple applet. The first is the IMAGES_READY event and the second is a BUTTON_DOWN event for the resetAll button.

When we receive the IMAGES_READY event, we know that all of the button images have been loaded and prepared. It is at this point that we will enable the ButtonBar for use. Note that we could have enabled the ButtonBar earlier and it would still have functioned, but the only image that would have been displayed is the base button image (and the background image) until all of the other images had loaded. For this applet it is important that the user know what state each button is in, so we deferred enabling the button bar until all of the button state images had loaded.

When the resetAll button is pressed, we want to reset the other three buttons on the button bar. We accomplish this by acting on a BUTTON_DOWN event for the resetAll button (buttonID = "R"). When we receive this event, we use the setStuck method of the ButtonRegion class to set the shields, phasers, and torpedos buttons off.

This is all we need in order to implement the "Systems Control Panel" applet. Of course, this was a very simple applet that doesn't do very much, but it should be easy to see that the ButtonBar class will allow you to concentrate on what happens when buttons are clicked, and forget about the details of how the buttons themselves are implemented.
Copyright © 1997 by Modern Minds, Inc.