Adding a tab control using Interface Builder is fairly straightforward. You’ll start with a window and add a tab data view that has two tabs. You can add more if you’d like, but we’ll stick to two for the purpose of showing you how to do it:

The procedures for adding controls to a user pane are the same as those you used in Chapter 5 to add controls to a window. The only difference is that you must make sure the pane to which you want to add controls is in edit mode and is in front of the other panes.

Before you add a control, double-click the tab associated with the pane to which you want to add a control. Make sure the user pane is editable—the tab you clicked should be active and a thick line should appear around the pane. Then, you can drag controls to the pane as you would to a window.

You need to write a handler that switches the frontmost tab in response to a user click on a tab and then shows the appropriate pane while hiding the others. First, you’ll need to declare the constant that represents the IDs you assigned to the tab control and tab items when you set them up in Interface Builder. First, define constants to represent the tab ID:

#define        TAB_ID       128;

Next, set up an array—a tab list—to specify the number of tabs and the ID of each tab. The first item in the array is 2 because you set up two tab items. Recall you assigned 129 and 130 as the tab item IDs. The variable lastTabIndex is a housekeeping variable you’ll use to keep track of the last tab chosen by the user. You’ll set the starting value at 1:

int         tabList[] = {2, 129, 130}; 
int         lastTabIndex = 1;

You’ll need to declare the tab handler (MyTabEventHandler) and the function (MySwitchItemOfTabControl) that switches from one pane to another. Here are the function declarations for each:

pascal OSStatus MyTabEventHandler (EventHandlerCallRef inHandlerRef, 
                        EventRef inEvent, void *inUserData);
void MySwitchItemOfTabControl (int index, ControlRef tabControl);

In your main function, you install an event handler for the tab control. You’ll use the InstallEventHandler function we discussed in Chapter 6. As you recall, this function requires an event target as its first parameter. The event target is the tab control, but you need to pass a parameter of type EventTargetRef. The Carbon Event Manager has a function, GetControlEventTarget, that takes a control as a parameter and returns an EventTargetRef for that control. But GetControlEventTarget takes a ControlRef as a parameter. You know what the ID and signature of the tab control are, so you’ll need to use those to get the ControlRef associated with our tab control’s ID and signature. The Control Manager has a function, GetControlByID, that will get a ControlRef associated with a window reference and a ControlID data type. A ControlID is a structure that contains a signature and an ID—the two items you assigned to your tab control when you set it up in Interface Builder.

When you put it all together, the code (which should be added to your main function) looks like Example 14.6.

ControlID           controlID;
     controlID.signature  = TAB_SIGNATURE;
    controlID.id         = TAB_ID;
    GetControlByID (MyWindow, &controlID, &tabControl);
    eventTypeSpec       controlSpec = { 

    InstallEventHandler (GetControlEventTarget (tabControl),
                        NewEventHandlerUPP (MyTabEventHandler),
                        2,
                        &controlSpec,
                        0,
                        NULL);

You need to assure that when your application launches, the tab control displays properly. To do so, put the following code in your main function to select the first tab item when the application launches:

MySwitchItemOfTabControl (1,tabControl);

Now, you are ready to add the actual tab handler shown in Example 14.7. The handle switches tabs only if the tab value has changed. If the user clicks the active tab, nothing happens.

pascal OSStatus MyTabEventHandler (EventHandlerCallRef inHandlerRef, 
                                    EventRef inEvent, void *inUserData)
{
    ControlRef  tabControl;
    ControlID   controlID;   
    OSStatus    result;
    controlID.signature = TAB_SIGNATURE;
    controlID.id        = TAB_ID;

    GetControlByID (MyWindow, &controlID, &tabControl);                 // 1
    if (GetControlValue (tabControl) == lastTabIndex)                   // 2
    {
                   result = eventNotHandledErr;
    }
    else {                                                              // 3
       MySwitchItemOfTabControl (GetControlValue (tabControl), tabControl);
       result = noErr;
       }
    return result;     
}

Here is what the function does:

You’ll need to add the function called by your tab handler, as shown in Example 14.8, to switch to the pane associated with the tab.

void MySwitchItemOfTabControl (int currentTabIndex, 
                                ControlRef tabControl)
{
    ControlRef userPane;
    ControlRef selectedPane = NULL;
    ControlID controlID;
    UInt16 i;

    lastTabIndex = currentTabIndex;
    controlID.signature = TAB_SIGNATURE;

    for (i = 1; i < tabList[0] + 1; i++)
    {
        controlID.id = tabList[i];
        GetControlByID (MyWindow, &controlID, &userPane);            // 1
       
        if (i == currentTabIndex)                                    // 2
            selectedPane = userPane;
        else
            SetControlVisibility (userPane,false,true);              // 3
    }
    if (selectedPane)
        SetControlVisibility (selectedPane,true,true);               // 4

    Draw1Control (tabControl);                                       // 5
}

Here is what the function does:

Notice that none of the code you’ve added handles controls in the pane. How could you handle them? Let’s say your tabbed window has a pane identical to the Travel Time pane shown earlier, in Figure 14.6. You would use the same window event handler and compute travel time functions you wrote in Chapter 6. You let your tab handler take care of switching the view while your window event handler and compute travel time functions respond to user interaction in the actual pane.

Instead of displaying content in multiple windows, tab controls let your application display the content as a stack of panes in a single window. To use tabs, you must add tab controls to your application and then write a handler that switches from one pane to another when the user clicks a tab. As an exercise, you can modify the Moon Travel Planner application to use multiple panes instead of multiple windows.