Working with advanced JBCL components

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

You can find general reference information on a JBCL component in the com.borland Packages 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 AppBrowser's Doc page.


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.

TabsetPanel lets 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 displayed.

During design, you use the selectedIndex property of the TabsetPanel to determine 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.

These are the basic steps for visually designing a TabsetPanel:

  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. Click the ellipsis beside the labels property in the Inspector to display the property editor.
  5. 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 labeled One, Two, and Three on the TabsetPanel you would enter:

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

  6. Set the selectedIndex property to 0 (representing the first tab). The first tab comes to the top.
  7. Place a panel onto that page. It fills the page. Set the panel's layout to XYLayout for prototyping purposes.
  8. Repeat steps 6-7 for each of the other tabs in the TabsetPanel, using a selectedIndex of 1 for page 2, and so on.
  9. Select the TabsetPanel and set its selectedIndex property to 0 again. You can now add controls or nested panels onto the panel on the first page, creating a design for that page as needed.
  10. Repeat step 9 for each page, completing the design of all pages, using a selectedIndex of 1 for page 2, and so on.
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. Its intended use is to provide tabs for controlling something else, such as 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 it gives you more custom control over what the tabs are for.

Example

The following 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. In the Inspector, change the panel's layout property 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, and do the following:
  10. 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.
  11. 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 this:

      void tabsetControl1_selectionChanged(com.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));
        }
      }
    

  12. 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 in the Inspector:

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 com/inprise/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 Out Path is specified as JBuilder\myClasses, put your images in JBuilder\myClasses\myButtonBar\images.

  2. Select the ButtonBar on the component tree.
  3. Click the ellipsis beside 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. Click the ellipsis beside the imageNames property value, to open the property editor.
  5. Enter a list of GIF file names in the property editor that matches exactly the number and the order of the items you put in the list of button labels.

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 the following example, 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.
  3. 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();
        }
      }

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

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 in which you add the components to the SplitPanel is important. The components appear in panes separated by movable "splitter" bars that let the user change the pane constraints of the panel at runtime.

SplitPanel uses a 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. Have a container in your design that uses BorderLayout.
  2. Select the SplitPanel container on the JBCL Containers tab of the component palette, and drop it in the center of the container.
  3. 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.

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

  5. 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 the bottom left corner of the second component.

To modify the placement and size of a component within the SplitPanel (other than the first one you added, which is the root component in the SplitPanel),
  1. Select the component in the UI designer or the component tree.
  2. Click on the ellipsis beside the constraints property in the Inspector, or right-click the component 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, or Right.
    Important: The value is relative to the component named beside Splits 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