Working with advanced components

This chapter shows you how to work with some of the more complex JBuilder components in the UI Designer.

You can find general reference information on a JBuilder Component in the JavaBeans Component Library Reference. You can also select it in the Structure pane of the Appbrowser, then drill down to the ancestor class to examine its source code in the editor, or read its online reference on the Doc tab.

The following components are discussed in this chapter:

TabsetPanel
TabsetControl
ButtonBar
SplitPanel


Using a TabsetPanel

TabsetPanel is a control that combines a set of tabs and a CardLayout panel into one control that is convenient to use in the UI Designer.

The basic concept of working with TabsetPanel is that you create a number of tabbed "pages", each with a unique tab label, then you put controls onto each page. At runtime, all the controls of all pages are instantiated, but only those on the selected tab page are shown.

With a TabsetPanel, all of your UI elements for all pages are instantiated at the beginning, and just one page at a time is shown.

During design, you use the selectedIndex property of the TabsetPanel to select which tab page of the TabsetPanel is visible, and therefore designable, in the UI Designer. The first page is selected by setting the selectedIndex property to 0, the second page by setting it to 1, and so on.

The basic steps for visually designing a TabsetPanel are:

  1. Open or create a project with a UI container file, such as a frame or panel.
  2. Select the UI file, then click the Design tab at the bottom of the AppBrowser.
  3. Select TabsetPanel from the JBCL Containers tab of the Component Palette, and add it to your UI.
  4. Double-click the labels property in the Inspector to display the property editor. For each tab label, click the Add button, enter the text you want for the label, then click OK.

    For example, to create three tabs on the TabsetPanel you could enter:

    Note: To delete a tab from the control, select the label you want to delete in the Labels property editor and click the Remove button.

  5. Set its selectedIndex property to 0 (representing the first tab). Note that the first tab comes to the top.
  6. Place a panel onto that page. Note that it fills the page.
  7. Set this panel's layout to XYLayout for prototyping purposes.
  8. Repeat steps 5-7 for each of the other tabs in the TabsetPanel, using a selectedIndex of 1 for page 2, and so forth.
  9. Select the TabsetPanel and set its selectedIndex property to 0 again.
  10. You can now add controls or nested panels onto the panel on the first page, creating a design for that page as needed.
  11. Repeat steps 9-10 for each page, completing the design of all pages, using a selectedIndex of 1 for page 2, and so forth.
Note: If you drop anything onto the TabsetPanel in excess of the number of tabs you have already defined, for example by dropping a component before setting the labels or by dropping the component in the label area, new tab pages are added with labels that either match the name of the dropped component, or that duplicate previous tab names.


Using a TabsetControl

The TabsetControl is just a set of tabs. Unlike the TabsetPanel, it doesn't provide the client "page" area, just the tabs. It's intended use is to provide tabs for controlling something else, such as the instantiating other UI elements or making them visible.

With a TabsetControl, you can explicitly instantiate each page only during the time the tab is active. However, you have to do the work of writing code in the selectionChanged event handler method to detect which tab has been selected (changes in the selectedIndex or selectedTab properties). You also have to code whatever you need done when the tab changes, such as destroying and rebuilding parts of your UI, or changing the attributes of the UI in some other way. Using TabsetControl is therefore more work than the automatic page maintenance provided with TabsetPanel, but gives you more custom control of what the tabs are for.

Example

This example uses a JBCL TabsetControl to set the colors of a text area:

  1. Open or create a project with a UI container file, such as a frame or panel. (For example, the Application Wizard creates a file called Frame1.java by default.)
  2. Select that UI file, then click the Design tab at the bottom of the AppBrowser to open the UI Designer.
  3. Select the BevelPanel on the JBCL Containers tab of the Component Palette, and add it to the UI design. This panel is where you will place the TabSetControl and the TextArea.
  4. Select this new panel in the UI Designer or the Component Tree.
  5. Double-click the panel's layout property in the Inspector and change it to BorderLayout.
  6. Add a TabsetControl from the JBCL Containers tab to the panel, drawing it across the top part of the panel.
  7. Select the TabSetControl in the Component Tree and do the following:
  8. Select the TextAreaControl on the JBCL tab of the Component Palette, and draw it to fill the rest of the panel.
  9. Select the TextAreaControl in the Component Tree.
  10. Do the following in the Inspector:
  11. Select the TabsetControl, and then select the Events tab on the inspector. Double-click on the value for the selectionChanged event, and you will be taken to a new event handler method for selectionChanged.
  12. Copy the two lines of code that set the color from jbInit() to this selectionChanged event, and then do some editing so the event handler code looks like:

      void tabsetControl1_selectionChanged(borland.jbcl.model.VectorSelectionEvent e) {
        if (tabsetControl1.getSelectedIndex() == 0) {
          textAreaControl1.setForeground(Color.black);
          textAreaControl1.setBackground(new Color(254, 254, 254));
        }
        else {
          textAreaControl1.setBackground(Color.black);
          textAreaControl1.setForeground(new Color(254, 254, 254));
        }
      }
    

  13. Run the program, type some text into the text area, and then toggle the tabs to see the text color and background invert.


Using a ButtonBar

A ButtonBar is a simple toolbar containing buttons. These buttons are created by using properties of the ButtonBar, rather than by dropping buttons into a panel. By using the buttonType, labels, and imageNames properties in the Inspector , you can choose the appearance and number of buttons, as well as optional labels or images.

Creating the buttons on a ButtonBar

The following steps guide you though adding buttons to a ButtonBar and attaching events to them:

  1. Open or create a project with a Frame container file. (For example, you can use the Application Wizard which creates a file called Frame1.java by default, or, you can choose File|New from an existing project and double-click the Frame icon to add a new frame to the project.)
  2. Select that frame file, then click the Design tab at the bottom of the AppBrowser to open the UI Designer.
  3. Select the ButtonBar component on the JBCL tab of the Component Palette, and add it to the Frame.
  4. Select the ButtonBar in the Component Tree and do the following:

Specifying images for a ButtonBar

If you are displaying images on the ButtonBar buttons, you need to indicate the location of the .GIF image files. You do this with the imageBase property in the Inspector.

  1. Put your .GIF files in an \image subdirectory of the same directory containing your class file (the one using the ButtonBar.)

    For example, in JBuilder, the images displayed by default on the ButtonBar control are in the /Image subdirectory of borland/jbcl/control where the ButtonBar.class is located with the rest of the JBCL classes. This directory is deployed as a .ZIP file (JBCL.ZIP) and placed in the JBuilder\lib directory.

    Therefore, if your project is named myButtonBar.jpr, and your outpath is specified as JBuilder\myClasses, put your images in JBuilder\myClasses\myButtonBar\images.

  2. Select the ButtonBar on the Component Tree.
  3. Double-click the imageBase property in the Inspector. In the ImageBase dialog, type the name of the image directory (for example, Image, as in the case of the JBCL ButtonBar.class). JBuilder assumes, then, that this directory is relative to the class path, allowing you to deploy your class and images in a .zip file.
    Note: Alternatively, you can type the entire path name to the image, but this complicates archiving and deployment and is not recommended.
  4. Double-click the imageNames property value, and click the ellipsis button to open the property editor.
  5. Enter a list of .GIF file names in the property editor which matches exactly the number and order that you put items in the button labels list.

Creating ButtonBar events

Unlike regular buttons, each of which has its own separate actionPerformed event handler, a ButtonBar has a single actionPerformed event for the ButtonBar as a whole. Inside its event handler, you determine which button was pressed by testing the actionCommand string property of the event. The actionCommand string will tell you the label of the button that was pressed. Each button in the ButtonBar has a label, even if labels aren't being displayed. The label strings for which you test are the same strings that are entered in the labels property of the ButtonBar.

Take a look at that now. Select your buttonBar on the Component Tree, and in the Inspector, display the labels property editor. Note the button labels, because those are what you will need to test for in your actionPerformed event handler. In our example below, there are three labels: "Open", "Save", and "About".

To create the actionPerformed event handler for the buttonBar,

  1. Select the buttonBar in the Component Tree, then change to the Events tab in the Inspector.
  2. Select, then double-click on actionPerformed to create the empty event handler and switch focus in the AppBrowser to the source code.

    Edit the code for the actionPerformed event to look something like this, substituting your ButtonBar labels for ours:

      void buttonBar_actionPerformed(java.awt.event.ActionEvent e) {
        String actionCommand = e.getActionCommand();
        if (actionCommand.equals("Open")) {
          fileOpen();
        }
        else if (actionCommand.equals("Save")) {
          saveFile();
        }
        else if (actionCommand.equals("About")) {
          helpAbout();
        }
      }

    Add more else if statements for any additional labels in your ButtonBar.

    Note that this example makes calls to three methods: fileOpen(), saveFile() and helpAbout(). Create your own methods and substitute them instead.


SplitPanel

SplitPanel is a JBCL container in which the placement and size of each component is specified relative to the components that have already been added to the container. Each component (other than the first one) splits the space already occupied by a previously added component. Therefore, the order you add the components to the SplitPanel is important. The components appear in panes separated by movable "splitter" bars that allows the user to change the pane constraints of the panel at runtime.

SplitPanel uses a Borland layout called PaneLayout. PaneLayout can be used with other containers (such as BevelPanel), but these other containers do not have a moveable splitter bar at runtime.

To create a SplitPanel in the UI Designer,

  1. Select the SplitPanel container on the JBCL Containers tab of the Component Palette. Click and drag it to the desired size in UI Designer.
  2. Select the first component on the Component Palette to be added to the SplitPanel container, and drop it into the SplitPanel. It will completely fill the SplitPanel until you add another component.

  3. Select the next component on the Palette, and draw it in the SplitPanel container, at exactly the location you want it to be.

    For example,

    The panel will now split the space between the two components, giving the second component the area you defined, and giving the first component the rest of the panel.

    Important: If the first component you added to a PaneLayout container was itself a container, the UI Designer assumes you are trying to add the second component to the outer container instead of to the PaneLayout container.

    To specify to the UI Designer that you want to add components to containers other than those at the top of the Z-order, select the target container, then hold down the Ctrl key while clicking or dragging the component in the UI Designer.

  4. To add a third component to the SplitPanel, draw it in the panel in a similar way to define its relative position.

    For example, to split the left half of SplitPanel containing two components, begin drawing the third component starting from the middle of the left edge of the panel to bottom left corner of the second component.

To modify the placement and size of a component within the SplitPanel,
  1. Select the component in the UI Designer or the Component Tree.
  2. Double-click the constraints property in the Inspector , or right-click on it in the UI Designer and choose Constraints from the pop-up menu. This opens the constraints property editor.
  3. Select one of the following positions: Top, Bottom, Left, Right or Root.
    Important: These values are relative to the component named in the "Splits" field in the property editor.
  4. Specify what proportion of the split component this component should occupy.
  5. Click OK.

Note: You can also resize the component by selecting it and dragging on the nibs. Moving a component is also allowed, however this will change the add order of the components. To change the width of the splitter bar(s) between the components,

  1. Select the SplitPanel container.
  2. Edit the number of pixels in the gap property.
See also:
PaneLayout