Advanced Search
Apple Developer Connection
Member Login Log In | Not a Member? Contact ADC

< Previous PageNext Page >


Using a Carbon User Interface in a Cocoa Application

This section describes how you can use a Carbon user interface in a Cocoa application. In the Jaguar and later versions of Mac OS X, the system automatically provides code that allows Cocoa and Carbon to communicate user events to each other. Communication between the two application environments is what enables a Cocoa application to use a Carbon user interface.

Using a Carbon interface in a Cocoa application requires you to perform the following major tasks:

The tasks described in the following sections are illustrated using sample code taken from a working application—CarbonInCocoa. See “About the CarbonInCocoa Application” for a description of the application. You can download the code for this application from the ADC Member Site Download Software area:

http://connect.apple.com


About the CarbonInCocoa Application

As you read the subsequent sections it may be helpful to have an idea of how the CarbonInCocoa application behaves and what the user interface looks like. When the Cocoa application is launched, the window shown in Figure 3-5 appears. This window is a Cocoa window created with Interface Builder.


Figure 3-5 The Cocoa user interface for the CarbonInCocoa application

Figure 3-5 The Cocoa user interface for the CarbonInCocoa application

When the user clicks the Show Carbon Window button, the window shown in Figure 3-6 opens and becomes the frontmost and active window. The window in Figure 3-6 is a Carbon window created with Interface Builder. When the user clicks one of the windows, that window becomes the active window. The user can type text in the text field in either window, copy the text from one window to the other, or cut the text from either window.


Figure 3-6 The Carbon user interface for the CarbonInCocoa application

Figure 3-6 The Carbon user interface for the CarbonInCocoa application

The CarbonInCocoa application is simple. Its purpose is to show how little code you need to provide to use a Carbon user interface in a Cocoa application.


Creating the Carbon User Interface

You should use Interface Builder to create the Carbon user interface. Follow these steps to create a Carbon window:

  1. Open Interface Builder.

  2. Under Carbon in the Starting Point dialog select Window and click New.

  3. When the window appears, drag items form the Carbon palette to the window to create the interface.

    See Creating a User Interface With Interface Builder for details on how to use Interface Builder, available from this website:

    http://developer.apple.com/macosx/gettingstarted/

    See Inside Mac OS X: Aqua Human Interface Guidelines for information on making an Aqua-compliant interface, available from this website:

    http://developer.apple.com/documentation/UserExperience/Conceptual/AquaHIGuidelines/index.html


  4. Save the file.

    Interface Builder saves the interface in a nib file. (The “ib” in “nib” represents Interface Builder.) A nib file contains an archive of the interface. When you want to show the interface, you need to unarchive the nib file. You’ll see how to do this in “Loading the Nib File”.



Setting Up the Cocoa Application to Use the Carbon User Interface

You must perform the following tasks to enable your Cocoa application to use the Carbon user interface:


Adding the Nib File that Specifies the Carbon Interface

To add the nib fie that specifies the Carbon interface, do the following:

  1. Open the Project Builder project for your Cocoa application.

  2. Choose Add Files from the Project menu.

  3. Locate the nib file and double-click its name.

  4. Click Add in the dialog that appears.

    If your Cocoa application has more than one target, you need to choose the appropriate target before you click Add.



Declaring the Interface for the Controller

Your controller for the CarbonInCocoa application has two instance variables: a WindowRef for the Carbon window and an NSWindow object. The NSWindow object allows management of the Carbon window using Cocoa methods. (See “Showing the Carbon Window”.)

The sample application’s controller has no other instance variables, but your application would need to declare any other instance variables that are appropriate. Listing 3-18 shows the declaration for the controller in the CarbonInCocoa application.

Listing 3-18 The declaration for the controller

@interface MyController : NSObject
{
    WindowRef   window;
    NSWindow    *cocoaFromCarbonWin;
}
@end

Loading the Nib File

The Cocoa nib file is loaded automatically when the Cocoa application launches. But you must explicitly load the nib file that contains the Carbon interface. For the CarbonInCocoa application, the nib file is loaded in response to the user clicking the Show Carbon Window button in the Cocoa window.

Listing 3-19 shows the code needed to load the Carbon nib file at runtime. An explanation for each numbered line of code appears following the listing.

Listing 3-19 Loading a nib file for a Carbon window

    CFBundleRef bundleRef;
    IBNibRef    nibRef;
    OSStatus    err;
    
    bundleRef = CFBundleGetMainBundle(); 
// 1
    err = CreateNibReferenceWithCFBundle (bundleRef,
                    CFSTR("SampleWindow"), 
                    &nibRef); 
// 2
    if (err!=noErr)
                NSLog(@"failed to create carbon nib reference");
    
    CFRelease(bundleRef); 
// 3
    
    err = CreateWindowFromNib (nibRef, 
                            CFSTR("CarbonWindow"), 
                            &window); 
// 4
    if (err!=noErr)
                NSLog(@"failed to create carbon window from nib");
    
    DisposeNibReference (nibRef); 
// 5

Here’s what the code does:

  1. Calls the Core Foundation Bundle Services function CFBundleGetMainBundle to obtain an instance of the application's main bundle. You need this reference for the next call.

  2. Calls the Interface Builder (IB) Services function CreateNibReferenceWithCFBundle to create a reference to the Carbon window’s nib file. The Core Foundation string you provide must be the name of the nib file, but without the .nib extension.

  3. Releases the bundle reference, as it is no longer needed.

  4. Calls the IB Services function CreateWindowFromNib to unarchive the Carbon window from the nib file. On return, window is a WindowRef to the Carbon window. Recall from “Declaring the Interface for the Controller” that window is a controller instance variable.

  5. Calls the IB Services function DisposeNibReference to dispose of the reference to the nib file. You should call this function immediately after you have finished unarchiving an object.


Creating an NSWindow Object for the Carbon Window

You do not need to create an NSWindow object for the Carbon window. However, doing so lets you manage the Carbon window using Cocoa methods rather than Carbon functions, which may be desirable in some applications and is what the CarbonInCocoa application does.

You can create an NSWindow object for a Carbon window by allocating an NSWindow object, then initializing the object using the initWithWindowRef: method, as shown in the following line of code:

cocoaFromCarbonWin = [[NSWindow alloc] initWithWindowRef:window];

Recall from “Loading the Nib File” that window is a reference to the Carbon window.

You can find more information about the NSWindow object and the initWithWindowRef: method from the NSWindow documentation.


Showing the Carbon Window

Because you created an NSWindow object for the Carbon window, you can call the makeKeyAndOrderFront: method to show the window instead of calling the Carbon function ShowWindow. You show the Carbon window with the following line of code:

 [cocoaFromCarbonWin makeKeyAndOrderFront:nil];

Summary

This section demonstrated how you can write a Cocoa application that uses a Carbon user interface, which is possible only in Jaguar and later versions of Mac OS X. The Carbon user interface (a window with a variety of controls in it) is defined in an Interface Builder nib file that is included as a resource in the Cocoa application. At runtime, the Cocoa application must load the Interface Builder file that contains the interface and then show the Carbon window. The sample code also shows how to create an NSWindow object for the Carbon window. Doing this provides the option of managing the Carbon window using Cocoa methods.

The code in this section is taken from the sample application CarbonInCocoa. Although most of the code from the CarbonInCocoa application is shown in the listings in this section, not all of the code is included. You should download the CarbonInCocoa Project Builder project for a more complete picture of how the Cocoa and Carbon pieces fit together. You can get the sample code from the ADC Member Site Download Software area:

http://connect.apple.com



< Previous PageNext Page >


Preliminary Last updated: 2003-01-01

Get information on Apple products.
Visit the Apple Store online or at retail locations.
1-800-MY-APPLE

Copyright © 2004 Apple Computer, Inc.
All rights reserved. | Terms of use | Privacy Notice