Working with advanced components

This section shows you how to work with some of the more complex JBuilder components.

General reference information on the JBuilder Components can be found in the Component Library Reference or by placing the component in your design, drilling down to see its source code by double clicking on it in the Structure pane of the browser, then examining its source or clicking the Doc tab and reading the online reference docs for that specific component.

The following components are discussed:

TabsetPanel
TabsetControl
ButtonBar
SplitPanel


TabsetPanel and TabsetControl

TabsetPanel is a composite control, consisting of a set of tabs and a blank "page" area. If you are just looking for a set of tabs, without a multipage client area, consider using the TabsetControl instead.

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.

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.

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.

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 designing a TabsetPanel are:

  1. Open or create a project with a UI 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 Containers tab of the Component Palette, and add it to your UI.
  4. Edit its labels property in the Inspector to enter the labels you want for the tabs. Enter one label per line, with no blank lines.

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

  5. Set its selectedIndex property to 0 (representing the first tab). Note that the first tab comes to the top.
  6. Place a Panel or BevelPanel 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

Example

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

  1. Use the Application Wizard. On Step 2 of 2 of the Application Wizard, only check "Center frame on screen".
  2. Select Frame1.java in the Navigation Pane and click on the Design tab.
  3. Select the TabsetControl from the Controls tab of the Component Palette, and draw it across the top part of your Frame.
  4. In the Inspector, edit theTabsetControl's labels property to enter two labels for the tabs called "Normal" and "Inverted". Enter one label per line, with no blank lines, and don't press Enter after the last label. You will notice that two tabs appear on the TabsetControl in the UI Designer.
  5. Select the TextArea from the AWT tab of the Component Palette, and draw it to fill the rest of the Frame.
  6. To generate the code for setting the TextArea's foreground (text) and background colors to black and white, respectively, set the foreground and background properties of the text control to those colors explicitly using the Inspector. This sets the code correctly for the initial colors of the box. You can also copy and paste this code into the tab selection event handler and use it to set the colors for tab selection.
  7. 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.
  8. 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) {
          textArea1.setForeground(Color.black);
          textArea1.setBackground(new Color(254, 254, 254));
        }
        else {
          textArea1.setBackground(Color.black);
          textArea1.setForeground(new Color(254, 254, 254));
        }
      }
    

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

Deleting tabs from a TabsetPanel or TabsetControl

The procedure for deleting tabbed pages from a TabsetPanel or tabs from a TabsetControl is the same.
  1. Select the TabsetPanel or TabsetControl component on the Component Tree.
  2. In the Inspector, select the labels property and click the ellipsis button to open the property editor.
  3. Highlight the label associated with the tab you want to delete.
  4. Press Delete once to remove the label, then again to remove the blank space. Be sure there are no blank spaces between labels, and no blank lines after the last label.
  5. Press OK.


Using a ButtonBar

A ButtonBar is a simple toolbar containing just 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 of a ButtonBar, you can choose the appearance and number of buttons, as well as optional labels or images.

Creating the buttons on a ButtonBar component:

  1. Add a ButtonBar component to your UI Design from the Controls tab on the Component Palette.
  2. First, decide whether you want buttons that show text labels only, GIF images only, or both. Select the buttonType property to set a value.
  3. Next, select the labels property and click the ellipsis button to open the labels property editor.
  4. Enter a list of strings that will be used to label and identify the buttons, even if you aren't planning to show the labels on the buttons. Enter one label per line in the editor. You can enter a blank line to create a gap in the buttons. Be sure to press Enter at the end of the last label. The number of labels you have determines the number of buttons in the ButtonBar.
  5. Next, if you are using GIF images, you should enter a list of GIF file names into the imageBase property, matching exactly the number and order that you put items in the labels list.
  6. Finally, you need to indicate, as an absolute path, or a path relative to the class location, the directory where the GIF image files are located. Select the imageBase property and type the path to your image directory.

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 in this example we are making 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.

Creating a SplitPanel in the UI Designer,

  1. On the Containers tab of the Component Palette, click the SplitPanel container and draw it the desired size in your UI.
  2. Select the first component to be added to the SplitPanel container, and drop it into the SplitPanel. It will completely fill up the SplitPanel until you add another component.

  3. Select the next component on the Palette, and draw it in the SplitPanel 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 in the SplitPanel,
  1. Click on the component in the UI Designer.
  2. Select the constraints property in the Inspector, then click the ellipsis button to open the constraints property editor.
  3. Select one of the following positions: Top, Bottom, Left, Right or Root. These values are relative to the component named in the Splits field in the property editor.
  4. Specify the proportion of the split component this component should occupy.
  5. Press 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