XUL Tutorial - Tabbed Panels

It is common in preference dialogs for numerous tabs to appear. We'll find out how to create them here.

Containers

Each XUL box is a container that can contain any other element. There are a number of elements that are specialized types of boxes, such as toolbars and tabbed panels. The box tag creates the simplest box with no special properties. However, the specialized types of boxes work just like regular boxes in the way they orient the elements inside them, but they have additional features.

In fact, many components can contain other elements. We've already seen that scroll bars can contain other things besides the default. A scroll bar is just a special type of box that creates its own elements if you don't provide them. It also handles the moving of the scroll bar thumb.

In the next few sections, we'll introduce some elements that are designed for holding other elements. They are all special types of boxes and allow all of the attributes of boxes on them.

Tabbed Panels

Tabbed panels are typically used in an application in the preferences window. A series of tabs appears across the top of a window. The user can click each tab to see a different set of options. It is useful in cases when you have more options than will fit in one screen.

XUL provides a method to create such dialogs. It involves four new elements, which are described briefly here and in more detail below.

• tabcontrol
  The outer box that contains the tabs along the top and the tab pages themselves.
• tabbox
  The inner box that contains the individual tabs. In order words, this is the row of tabs.
• tab
  A specific tab. Clicking on the tab brings the tab page to the front.
• tabpanel
  The body of the tabbed panel, where the pages are. Each child element of the tabpanel becomes a tabbed page.

Tabbed panels have an unusual syntax to them. The tabcontrol is the top element. It consists of two children, a tabbox which contains the row of tabs and a tabpanel which contains the tabbed pages.

Usually, the tabs go along the top of the tabbed panel. However, the tabs can go on any of the sides of the panel. Because the tabcontrol is a type of box, you can use the orient attribute to control this.

Shown below is the typical syntax of a basic tab panel with two tabs:

<tabcontrol orient="vertical" id="tablist">
  <tabbox orient="horizontal">
    <tab value="First"/>
    <tab value="Second"/>
  </tabbox>
  <tabpanel>
    ...
    contents of tabs
    ...
  </tabpanel>
</tabcontrol>

As can be seen here, two tabs have been created, one labeled First and the other labeled Second. The two tabs have been placed inside a tabbox which is much like a regular box. It has been oriented horizontally because we want the tabs to appear next to each other in a row. The tabbox itself has been placed inside a tabcontrol. The tabcontrol also contains a tabpanel which will appear below the tabs due to the vertical orientation on the whole tab control.

An easy way to look at this is to think of all the tab elements above as regular boxes. You can see that the tabbox and the tabpanel should orient vertically (meaning that the tabs will appear along the top). Inside the tabbox, the tab elements will be oriented horizontally. There really is nothing special about the tab elements that make them different than boxes, except for two things. The tabs render slightly differently and only one tab page's contents are visible at once.

The content of the individual tab pages goes inside the tabpanel element. It does not go in the tab element as that is where the contents of the tab along the top go (which could contain any elements itself).

Each child element of the tabpanel element becomes a page on the tabbed display. The first element inside the panel corresponds to the first tab, the second element inside the panel corresponds to the second element, and so on. There is a one-to-one relationship between each tab element and the children of the tabpanel element.

When determining the size of the tabpanel, the size of the largest page is used. That means that if there are ten text fields on one tab page and only one on another, the tab page will be sized to fit the one with the ten on it as this takes up more room. The area taken up by the tab area does not change when the user switches to a new tab page.

Let's look at an example:

<tabcontrol orient="vertical">
  <tabbox orient="horizontal">
    <tab value="Mail"/>
    <tab value="News"/>
  </tabbox>
  <tabpanel>
    <box id="mailtab">
      <checkbox value="Automatically check for mail"/>
    </box>
    <box id="newstab">
      <button value="Clear News Buffer"/>
    </box>
  </tabpanel>
</tabcontrol>

Here, two tabs have been added. The first one labeled Mail and the other labeled News. When the user clicks the Mail tab, the contents of the first tab page will be displayed. In this case, the box with the check box labeled 'Automatically check for mail' will appear in the first tab. The second tab, when clicked, will display the box containing the button labeled Clear News Buffer. In the code, the two tab pages have been labeled 'mailtab' and 'newstab'.

In most cases you will put boxes inside the tabpanel because you will usually want a number of elements inside the tab page. However, you can put just a button (like the News tab above) or some other element in if you like.

The first tab is always the tab that is displayed by default. However, if you want to set a different tab as the initially displayed one, you can add an index attribute to the tabcontrol. The value should be set to the number of the tab that you want to be displayed first. The example below shows how you would set the second tab to be the default:

<tabcontrol orient="vertical" index="2">
  ...
</tabcontrol>

The currently selected tab is given an additional selected attribute on a tab element which is set to true. This is used to give the currently selected tab a different appearance so that it will look selected. Only one tab will have a true value for this attribute at a time.

Finally, you can change the position of the tabs so that they appear on any side of the tab pages. There is no special syntax to do this. You simply rearrange the position of the tabs and set the orient attribute as necessary. Remember that the tab elements are much like regular boxes in terms of layout.

For example, to put the tabs along the left side, change the orientation of the tabbox so that it is vertical. This is because you want the tabs to appear vertically stacked. Also, adjust the tabcontrol so it has horizontal orientation. This needs to be done because you want the tabs to appear beside the tab pages.

You can place the tabs on the right or bottom side by moving the tabbox so that it is after the tabpanel.

Adding Tabs to the Find Files Dialog

<box orient="vertical" flex="1">

<tabcontrol orient="vertical">
  <tabbox orient="horizontal">
    <tab value="Search" selected="true"/>
    <tab value="Options"/>
  </tabbox>

  <tabpanel>

   <box id="searchpanel" orient="vertical">

    <html>
     Enter your search criteria below and select the Find button to begin
     the search.
    </html>

    <spring style="height: 10px"/>

    <titledbox orient="horizontal">
      <title><text value="Search Criteria"/></title>

      <menulist id="searchtype">
        <menupopup>
          <menuitem value="Name"/>
          <menuitem value="Size"/>
          <menuitem value="Date Modified"/>
        </menupopup>
      </menulist>
      <spring style="width: 10px;"/>
      <menulist id="searchmode">
        <menupopup>
          <menuitem value="Is"/>
          <menuitem value="Is Not"/>
        </menupopup>
      </menulist>

      <spring style="height: 10px"/>
      <textfield id="find-text" flex="1" style="min-width: 15em;"/>

    </titledbox>
   </box>

   <box id="optionspanel" orient="vertical">
    <checkbox id="casecheck" value="Case Sensitive Search"/>
    <checkbox id="wordscheck" value="Match Entire Filename"/>
   </box>

 </tabpanel>
</tabcontrol>

(Next) Next, we'll find out how to create toolbars.

Examples: 4.5.1