As you recall from Chapter 2 a user can select a mode of transportation, then click a button to compute the travel time to the moon. When you created the interface, you assigned a command to the Compute Travel Time button. Your application needs to handle this command when it’s issued—a command class event kEventClassCommand.

Everything else that happens in the window—moving it, minimizing it, clicking a radio button—can be handled by the default handler for the window. (Recall you selected Standard Handler in Chapter 4.)

Now that you’ve identified the event (a command class event) in which your application is interested, you need to declare an event type specifier to indicate to the Carbon Event Manager the event for which to call the handler.

Open the Moon Travel Planner project. In the main.c file file, copy the following to the main function, after the declaration OSStatus err:

 EventTypeSpec      mainSpec = {kEventClassCommand,
                                    kEventCommandProcess};

In this section, you’ll write an event handler, MTPMainWindowEventHandler, for the main window and a function, MTPComputeCommandHandler, called by the main window event handler. Note that we’ll preface the functions and constants for the Moon Travel Planner application with MTP to distinguish them from functions and constants supplied by the Carbon programming interface.

Functions and constants from the Carbon programming interface contain either a prefix or keyword that indicates to which manager or technology they belong. For example, functions that take care of controls in the interface have the word Control somewhere in the function name, such as GetControlID. Functions from Core Foundation are prefaced by CF, such as CFStringCreateWithFormat.

We’ll point out the manager or technology associated with each function. If you want complete, technical documentation on a function or related functions, you can consult the Carbon API (application programming interface) documentation by choosing Carbon Help in the Project Builder Help menu.

// Function declarations for the window event handlers pascal OSStatus MTPMainWindowEventHandler (EventHandlerCallRef myHandler, 
                                              EventRef event,
                                              void *userData);

// Define constants for the commands, IDs, and signature used 
// in the interface. Make sure the values match those you assigned when
// you set up the interface in Interface Builder.
#define kMTPApplicationSignature        'MTPP'
#define kMTPComputeCommand              'tRav'
#define kMTPTravelTimeFieldID               129
#define kMTPModeOfTransportButtonGroupID    130

// Define constants to use in the moon travel time computation.
#define kMTPHoursPerDay 24
#define kMTPDistanceToMoon 384467  // kilometers 

// Define constants to identify the mode of transportation.
#define kMTPFootMode               1
#define kMTPCarMode                2
#define kMTPCommercialJetMode      3
#define kMTPApolloSpacecraftMode   4

// Define a window reference to the main window WindowRef           gMainWindow;

pascal OSStatus MTPMainWindowEventHandler (EventHandlerCallRef myHandler, 
                         EventRef event, void *userData)
{
    OSStatus        result  = eventNotHandledErr;                            // 1
    HICommand       command;

    GetEventParameter (event, kEventParamDirectObject, typeHICommand, NULL, 
                                    sizeof (HICommand), NULL, &command);    // 2
    switch (command.commandID)                       
              
      {
        case kMTPComputeCommand:                                             // 3
              MTPComputeCommandHandler ((WindowRef) userData);               // 4
              result = noErr;
              break;
      }
    return result;
}

pascal void MTPComputeCommandHandler (WindowRef window)
{
  ControlHandle     modeOfTransportButtonGroup,                           // 1
                    travelTimeField; 
  ControlID  modeOfTransportControlID = {kMTPApplicationSignature,        // 2
                        kMTPModeOfTransportButtonGroupID};
  ControlID  travelTimeControlID = { kMTPApplicationSignature, 
                        kMTPTravelTimeFieldID };
  CFStringRef       text;
  double            travelTime;
  SInt32            transportModeValue;
  OSErr           status;

  GetControlByID (window, &modeOfTransportControlID,                      // 3
                        &modeOfTransportButtonGroup);
  GetControlByID (window, &travelTimeControlID, &travelTimeField);
  transportModeValue = GetControl32BitValue (modeOfTransportButtonGroup); // 4
  switch (transportModeValue)                                             // 5
   {
     case kMTPFootMode:
        // Foot - good walking time is 4 miles per hour
        travelTime = (kMTPDistanceToMoon/(4.0/0.62))/kMTPHoursPerDay; 
        break;
     case kMTPCarMode:
        // Car - 70 miles per hour on the highway, no speed limit in space!
        travelTime = (kMTPDistanceToMoon/(70/0.62))/kMTPHoursPerDay; 
        break;
     case kMTPCommercialJetMode:
        // Commercial Jet - 600 miles per hour.
        travelTime = (kMTPDistanceToMoon/(600.0/0.62))/kMTPHoursPerDay;
        break;
     case kMTPApolloSpacecraftMode:
        // Apollo 11 took 4 days to get to the moon. 
        travelTime = 4; 
        break;
     default:
         travelTime = 0;
        break;
   }
  text = CFStringCreateWithFormat(NULL, NULL, CFSTR("%2.1f"),travelTime);  // 6
  status = SetControlData( travelTimeField, kControlEntireControl, 
             kControlEditTextCFStringTag,sizeof (CFStringRef), &text);     // 7
  CFRelease (text);                                                        // 8
  DrawOneControl (travelTimeField);                                        // 9
}

The event target is a window, so you can use one of the macros discussed in Section 6.1.6 to install our handler InstallWindowEventHandler.

In the main function, after the line DisposeNibReference(nibRef), add the following code:

InstallWindowEventHandler (gMainWindow,
            NewEventHandlerUPP (MTPMainWindowEventHandler), 
            1, &mainSpec, (void *) gMainWindow, NULL);

InstallWindowEventHandler tells the Carbon Event Manager to call the window’s event handler whenever a specified event type happens in the window. These are the parameters to the function InstallWindowEventHandler:

err = CreateWindowFromNib(nibRef, CFSTR("MainWindow"), &window);
ShowWindow (window );

err = CreateWindowFromNib (nibRef, CFSTR ("MainWindow"), &gMainWindow);
ShowWindow (gMainWindow);

WindowRef window;

The function RunApplicationEventLoop is already in the main function. As you recall from Chapter 3 it’s one of the lines of code provided “for free” by Project Builder. So let’s build, run, and test the application to make sure the events are handled properly.

We’ve discussed one of the most important Carbon technologies in this chapter—the Carbon Event Manager. You followed a typical event through the operating system and saw how it’s handled. Then we discussed the key concepts you need to set up event handlers for Carbon events. You had an opportunity to see how Carbon’s default handlers work, and then to actually write an event handler for the Moon Travel Planner application.

Now that the Moon Travel Planner application is more than just a pretty face and actually does something—compute travel time—you can move on. There is still a lot to do to create the application described in Chapter 2. Next you’ll take care of menus.