Retired Document
Important: This document may not represent best practices for current development. Links to downloads and other resources may no longer be valid.
Interface Builder Services Tasks
The primary tasks for which you’ll need to use Interface Builder Services are:
Unarchiving the menu bar and main window from your application’s main nib file
Unarchiving an object from an auxiliary nib file
Unarchiving an object from a framework or other bundle
Each of these tasks are described in the following sections.
Unarchiving Objects From the Main Nib File
When your application starts up, you need to call Interface Builder Services functions to open the main nib file and unarchive the interface objects that should be open after start-up. As the Strategies for Storing Interface Objects listed in Interface Builder Services Concepts suggest, the main nib file should contain only those items that are essential when your application starts up. In most cases, the main nib file should only contain the menu bar and perhaps a main window.
The steps below outline how to open a main nib file and unarchive the objects in it. Listing 3-1 shows how to implement the steps for a nib file that contains a menu bar and a main window. If your application needs only one of these objects at startup, you can easily modify the sample code.
Call the function
CreateNibReference
to create a reference to the main nib file.Unarchive the menu bar from the main nib file by calling the function
SetMenuBarFromNib
. This function also sets the menu bar so users can use the menu bar when your application has started up.If your application has a main window, you call the function
CreateWindowFromNib
to unarchive the main window.After you have unarchived the objects from the main nib file, you must dispose of the nib reference by calling the function
DisposeNibReference
.The function
CreateWindowFromNib
unarchives the window so it’s hidden. If you want the window to be visible, you must call the Window Manager functionShowWindow
.
It is good practice to check for errors each step of the way, as shown in <xRefNoLink>Listing 3-1. If the interface can’t be created, you should halt the start up process. Without an interface, your application is likely to be useless.
Listing 2-1 Unarchiving the menu bar and main window from the main nib file
int main (int argc, char* argv[]) |
{ |
IBNibRef nibRef; |
WindowRef window; |
OSStatus err; |
// Create a nib reference to a nib file. |
err = CreateNibReference (CFSTR ("main"), &nibRef); |
// Call the macro require_noerr to make sure no errors occurred |
require_noerr (err, CantGetNibRef); |
// Unarchive the menu bar and make it ready to use. |
err = SetMenuBarFromNib (nibRef, CFSTR("MainMenu")); |
require_noerr (err, CantSetMenuBar); |
// Unarchive the main window. |
err = CreateWindowFromNib (nibRef, CFSTR("MainWindow"), &window); |
require_noerr (err, CantCreateWindow); |
// Dispose of the nib reference as soon as you don’t need it any more. |
DisposeNibReference (nibRef); |
// Make the unarchived window visible. |
ShowWindow (window); |
// Start the event loop. RunApplicationEventLoop is a |
// Carbon Event Manager function. |
RunApplicationEventLoop (); |
// You’ll jump to one of the "Cant" statements only if there’s |
// an error. |
CantCreateWindow: |
CantSetMenuBar: |
CantGetNibRef: |
return err; |
} |
Unarchiving an Object From an Auxiliary Nib File
The Strategies for Storing Interface Objects suggest that you create several nib files to store your application’s interface objects. The main nib file should contain at the most, the menu bar and the window that opens (if any) when your application starts up. Document windows, palettes, toolbars, contextual menus, and other interface objects should be stored in separate, auxiliary nib files.
The steps for opening an auxiliary nib file and unarchiving an object from it are similar to those used to open a main nib file:
Call the function
CreateNibReference
to create a reference to the auxiliary nib file that contains the object you want to unarchive.Call the appropriate function to unarchive the object from the nib file. To unarchive a window, call the function
CreateWindowFromNib
, to unarchive a menu, call the functionCreateMenuFromNib
.After you have unarchived the object from the auxiliary nib file, you must dispose of the nib reference by calling the function
DisposeNibReference
.
One common use of an auxiliary nib file is to store an object
that’s used repeatedly in an application, such as a document window.
Another use is to store objects that are rarely needed, such as
an About window. Listing
3-2 shows how to implement a MyCreateNewDocument
function
that your application would call each time the user creates a new
document. Note that similar to Listing 3-1, the code shown in Listing 3-2 implements error
checking.
Listing 2-2 Unarchiving a document window from an auxiliary nib file
WindowRef MyCreateNewDocument (CFStringRef inName) |
{ |
IBNibRef documentNib; |
OSStatus err; |
WindowRef theWindow; |
// Create a nib reference to an auxiliary nib file with |
// the name document.nib. |
err = CreateNibReference (CFSTR ("document"), &documentNib); |
// Call the macro require_noerr to make sure no errors occurred |
require_noerr (err, CantGetNibRef); |
// Unarchive the document window. Use the name you gave to the |
// window object in the Instances pane in Interface Builder. |
err = CreateWindowFromNib (documentNib, CFSTR("MyDocument"), |
&theWindow); |
require_noerr (err, CantCreateWindow); |
// Dispose of the nib reference as soon as you don’t need it anymore. |
DisposeNibReference (documentNib); |
// Call the Window Manager function to set the title shown in the |
// window’s title bar to the name passed to MyCreateNewDocument. |
err = SetWindowTitleWithCFString (theWindow, inName); |
// In this example, the window gets returned. Remember, it’s been |
// unarchived, but it is still not visible. It won’t be visible |
// until you call the Window Manager function ShowWindow. |
return theWindow; |
// You’ll jump to one of the "Cant" statements only if there’s |
// an error. |
CantCreateWindow: |
CantGetNibRef: |
return NULL; |
} |
Unarchiving an Object From a Bundle
Your application is not limited to using interface objects contained within its own bundle. You can unarchive interface objects from another bundle or framework to which your application has access. For example, you could unarchive a tools palette or other object provided by a plug-in bundle.
The steps for unarchiving an object from a nib file in a framework
or other bundle are similar to those used to open an auxiliary nib
file. They are listed below. The main difference is that you need
to get a reference to the bundle. Then you must call the function CreateNibReferenceWithCFBundle
instead
of CreateNibReference
.
Call the Core Foundation URL Services function
CFURLCreateWithFileSystemPath
and the Core Foundation Bundle Services functionCFBundleCreate
to create a reference to the bundle that contains nib file you want to open. See the Core Foundation reference documentation for more information.Call the function
CreateNibReferenceWithCFBundle
to create a reference to the nib file that contains the object you want to unarchive.Call the appropriate function to unarchive the object from the nib file. To unarchive a window, call the function
CreateWindowFromNib
, to unarchive a menu, call the functionCreateMenuFromNib
.After you have unarchived the object from the nib file, you must dispose of the nib reference by calling the function
DisposeNibReference
.
The function MyCreateWidgetFromFramework
,
shown in Listing 3-3, shows how to unarchive a “widget window” from
a bundle whose path you pass to the function.
Listing 2-3 Unarchiving a widget window from a nib file in a bundle
WindowRef MyCreateWidgetFromBundle (CFStringRef widgetBundlePath |
CFStringRef widgetFileName, |
CFStringRef widgetWindowName) |
{ |
IBNibRef widgetNib; |
OSStatus err; |
WindowRef theWindow; |
CFBundleRef mainBundle; |
CFURLRef bundleURL; |
CFBundleRef widgetBundle; |
// Look for a resource in the bundle passed to |
// the function MyCreateWidgetFromBundle |
bundleURL = CFURLCreateWithFileSystemPath( |
kCFAllocatorDefault, |
widgetBundlePath, |
kCFURLPOSIXPathStyle, |
TRUE); |
// Make a bundle instance using the URL Reference |
widgetBundle = CFBundleCreate (kCFAllocatorDefault, bundleURL); |
// Create a nib reference to the nib file. |
err = CreateNibReferenceWithCFBundle (widgetBundle, |
widgetFileName, &widgetNib); |
// Call the macro require_noerr to make sure no errors occurred |
require_noerr (err, CantGetNibRef); |
// Unarchive the widget window. |
err = CreateWindowFromNib (widgetNib, widgetWindowName, &theWindow); |
require_noerr (err, CantCreateWindow ); |
// Dispose of the nib reference as soon as you don’t need it anymore. |
DisposeNibReference (widgetNib); |
// Release the Core Foundation objects |
CFRelease (bundleURL); |
CFRelease (widgetBundle); |
// In this example, the window gets returned. Remember, it’s been |
// unarchived, but it is still not visible. It won’t be visible |
// until you call the Window Manager function ShowWindow. |
return theWindow; |
// You’ll jump to one of the "Cant" statements only if there’s |
// an error. |
CantCreateWindow: |
CantGetNibRef: |
return NULL; |
} |
Copyright © 2002, 2004 Apple Computer, Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2004-02-17