tab-control

Class

The class of tab-control controls.

Control

An instance of the tab-control class. This control allows you to create a set of pages of controls and group them in related sub-groups on each tab. The Options dialog dialog is an example of a tab-control.

The individual tabs are instances of the tab-info class. The range property contains a list of tab-info objects, and the value property contains the name of the selected tab-info. Setting the value property to a different name will select a different tab. A tab can be added to an existing tab-control by calling add-tab, or removed by calling remove-tab. A widget can be added to an existing tab by calling add-component-to-tab, or removed by calling remove-component-from-tab.

Other properties that are unique to the tab-control include tab-height, tab-width, fixed-width, single-line, focus-on-click, ragged-right, tab-side, button-style, and tabs-are-draggable.

When creating tab-controls interactively on form windows, tab-controls allow overlap on their borders even when the allow-component-overlap option is turned off. Objects overlapping a tab may or may not appear in the range and tab-info(s) for the tabs they overlap, so use this feature with care.

In Windows, the tab-order of the controls on a parent window is always the same as the front-to-back occlusion order of the controls. This means that a tab-control must be positioned in the tab order after all of the widgets that are on it, or else it will cover those widgets. This is handled automatically when designing a form window interactively, but it must be handled by the application when creating a dialog programmatically. See tab-position.

The generic functions select-adjacent-tab and select-recent-tab are useful for keyboard shortcuts that select nearby or recently-selected tabs of a tab-control.

Adding a tab-control to your form

Click the tab-control tool on of the Component toolbar. Move the mouse cursor to the part of the form where you want to place the control, and click again. The control will appear with colored resizing handles.

Adding widgets to tabs programmatically

If you are creating a dialog programmatically rather than laying it out interactively as a form, then there are two ways to add widgets to tab-control tabs. One way is to associate the widgets with each other when creating all of them together. The other way is to call add-component-to-tab to add a widget to a pre-existing tab-control.

First we have is an example of the first approach. This code will create a window that contains a tab-control that has a button widget on its first tab. To make the button appear only when its tab is selected, the tab-control and the button must be associated with each other. So the button points to its tab by specifying a :tab-control initarg of (:my-tab-control :one), which is a list of the name of the tab-control followed by the name of the tab. Conversely, the first tab points to the button by specifying a :widgets initarg of (:first-button), which is a list of all of the widgets that are on that tab.

(setq my-window
      (make-window :my-window
        :class 'dialog :width 300 :height 300
        :dialog-items
        (list (make-instance 'button
                :left 80 :top 100 :width 100 :height 30
                :name :first-button :title "~First"
                :tab-control '(:my-tab-control :first-tab))
              (make-instance 'tab-control
                :left 50 :top 50 :width 200 :height 150
                :name :my-tab-control :value :first-tab
                :range
                (list (make-instance 'tab-info
                        :name :first-tab :label "One"
                        :widgets '(:first-button))
                      (make-instance 'tab-info
                        :name :second-tab :label "Two")
                      (make-instance 'tab-info
                        :name :third-tab :label "Three"))))))

The other way to add a widget to a tab programmatically is to call add-component-to-tab. This is useful if you want to create a tab-control and then add widgets to it later. (Similarly, remove-component-from-tab will remove a widget from a tab.)

This example would add another button widget to the tab-control that was created above, this time to the second tab.

(add-component-to-tab
  (find-component :my-tab-control my-window)
  :second-tab
  (make-instance 'button
    :left 100 :top 100 :width 100 :height 30
    :name :second-button :title "~Second"))

Resizing and moving the control

Controls can only be resized and moved on forms during the design stage; the size and location of everything is fixed on a running form.

Resize the control by clicking the mouse cursor and dragging one of the handles to the new size-point. Release the mouse key when you are satisfied with the new size.

Resizing the tab-control won't mean proportional changes in the size of the characters of the labels of the tabs. Change the font property if you want to change the size of the actual characters displayed.

Move the control by clicking anywhere on it except a resizing handle and dragging it to a new location on the form. Release the mouse key when you are ready to place the control.

Moving a tab-control means dragging all of the contained objects along with it.

Adding controls to the tab-control tabs

When designing a dialog using a form, drag controls onto the individual tabs and position them. After you have added controls to each tab, you will be able to see their names in the expanded portions of the Inspector. To see the names of the controls placed on each tab in the Inspector:

1. Click on the tab-control to give it focus in the Inspector. (If no inspector is visible, double-click the widget to ensure that an Inspector window is created if needed and brought to the front.)
2. Click on the range, making sure to click on the name of the range property (the left column) rather than the value (the right column). You will see a display of tab-info entries, one per line. There will be one tab-info for each tab in your tab-control. They will be numbered from 0 to n for (n+1) tabs.
3. Double-click on the value (the right hand column) for one of the tab-infos. A dialog will appear displaying the contents of the tab-info. All of the controls on that tab will appear in the value expression displayed by the dialog.
4. Click the OK button when you are done inspecting the expression to close the dialog.

You can also inspect the tab-infos programmatically by searching your code for calls to make-instance with tab-info for the particular tab-control you are working on.

Adding more tabs to the tab-control in the IDE

1. Click on the tab-control to give it focus in the Inspector.
2. Click on the extended editor button (the one with 3 dots) for the value of the range of the tab-control.
3. The Edit Expression dialog will appear. You can either copy a make-info from one of the existing tabs in the dialog and paste it in another location and modify it, or just begin typing your own make-infos directly into the window.
4. Click the OK button when you are satisfied with your new expression. The new tab-control will appear on your form with the changes you coded in the Edit Expression dialog.

Highlighting one or more specific tabs

The generic funcion highlight-tab allows you to highlight one or more tabs on a tab-control.

See About how to get sample code for creating controls in cgide.htm, which explains how to use the IDE to create such code.

A diagram of window and widget classes is shown in Widget and window classes in cgide.htm.

GTK Note

The GTK tab-control always uses a single row of tabs, and specifying the single-line property will have no effect. You can scroll a tab-control quickly by holding the mouse button down on the scroll arrow, but only if the widget's focus-on-click property is true, since otherwise Common Graphics will move the keyboard focus to a widget on a tab. If it is tedious to scroll to all of the tabs, you might consider using a multi-picture-button instead, as we did for the IDE's Class Browser.

Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page has had moderate revisions compared to the 8.1 page.
Created 2016.6.21.