---

Interface Builder Services Reference

Overview

This reference describes the functions you use to unarchive interface objects you create using Interface Builder.

Carbon supports the Interface Builder APIs.

Functions by Task

Creating and Disposing of Nib References

• CreateNibReference
• CreateNibReferenceWithCFBundle
• DisposeNibReference

Unarchiving Menu Bars and Menus

• CreateMenuBarFromNib
• SetMenuBarFromNib
• CreateMenuFromNib

Unarchiving Windows

• CreateWindowFromNib

Functions

CreateMenuBarFromNib

Unarchives a menu bar from a nib file.

OSStatus CreateMenuBarFromNib (
   IBNibRef inNibRef,
   CFStringRef inName,
   Handle *outMenuBar
);

Parameters

inNibRef

A reference to the nib file that contains the menu bar you want to unarchive. You obtain this reference by calling the function CreateNibReference or CreateNibReferenceWithCFBundle.

inName

A CFStringRef that denotes the menu bar you want to unarchive. This is the name you supplied to the menu bar in the Instances pane of Interface Builder. See the Base Services documentation for a description of the CFStringRef data type. You can use the Core Foundation function CFSTR to convert a string to a CFString.

outMenuBar

On output, points to a handle to the menu bar.

Return Value

A result code. See Runtime Errors.

Discussion

You need to call the Menu Manager function SetMenuBarFromNib to make the unarchived menu bar available in your application.

Availability

• Available in CarbonLib 1.1 and later.
• Available in Mac OS X 10.0 and later.
• Not available to 64-bit applications.

Declared In

IBCarbonRuntime.h

CreateMenuFromNib

Unarchives a menu from a nib file.

OSStatus CreateMenuFromNib (
   IBNibRef inNibRef,
   CFStringRef inName,
   MenuRef *outMenuRef
);

Parameters

inNibRef

A reference to the nib file that contains the menu you want to unarchive. You obtain this reference by calling the function CreateNibReference or CreateNibReferenceWithCFBundle.

inName

A CFStringRef that denotes the menu you want to unarchive. This is the name you supplied to the menu in the Instance pane of Interface Builder. See the Base Services documentation for a description of the CFStringRef data type. You can use the Core Foundation function CFSTR to convert a string to a CFString.

outMenuRef

On output, points to a menu reference.

Return Value

A result code. See Runtime Errors.

Discussion

After you call the function CreateMenuFromNib you need to call the Menu Manager function InsertMenu to make the unarchived menu available in your application.

Availability

• Available in CarbonLib 1.1 and later.
• Available in Mac OS X 10.0 and later.
• Not available to 64-bit applications.

Declared In

IBCarbonRuntime.h

CreateNibReference

Creates a reference to a nib file in the current bundle.

OSStatus CreateNibReference (
   CFStringRef inNibName,
   IBNibRef *outNibRef
);

Parameters

inNibName

A CFStringRef that represents the name of a nib file you created for your application, but without the nib extension. See the Base Services documentation for a description of the CFStringRef data type. You can use the Core Foundation function CFSTR to convert a string to a CFString.

outNibRef

On output, points to a nib reference. You pass the nib reference to Interface Builder Services functions that unarchive objects from a nib file.

Return Value

A result code. See Runtime Errors.

Discussion

Use this function if the nib file is located in the current bundle. Use the function CreateNibReferenceWithCFBundle if the nib file is located in a framework or other bundle that is not the current bundle.

Availability

• Available in CarbonLib 1.1 and later.
• Available in Mac OS X 10.0 and later.
• Not available to 64-bit applications.

Declared In

IBCarbonRuntime.h

CreateNibReferenceWithCFBundle

Creates a reference to a nib file in the specified bundle.

OSStatus CreateNibReferenceWithCFBundle (
   CFBundleRef inBundle,
   CFStringRef inNibName,
   IBNibRef *outNibRef
);

Parameters

inBundle

A CFBundleRef to your application’s bundle. See the Bundle Services documentation for a description of the CFBundleRef data type. You can get this reference by calling the appropriate Core Foundation Bundle Services functions.

inNibName

A CFStringRef that represents the name of a nib file you created for your application, but without the nib extension. See the Base Services documentation for a description of the CFStringRef data type. You can use the Core Foundation function CFSTR to convert a string to a CFString.

outNibRef

On output, points to a nib reference. You pass the nib reference to Interface Builder Services functions that unarchive objects from a nib file.

Return Value

A result code. See Runtime Errors.

Discussion

Use this function if the nib file is located in a framework or other bundle that is not the current bundle. Use the function CreateNibReference if the nib file is located in the current bundle.

Availability

• Available in CarbonLib 1.1 and later.
• Available in Mac OS X 10.0 and later.
• Not available to 64-bit applications.

Declared In

IBCarbonRuntime.h

CreateWindowFromNib

Unarchives a window from a nib file.

OSStatus CreateWindowFromNib (
   IBNibRef inNibRef,
   CFStringRef inName,
   WindowRef *outWindow
);

Parameters

inNibRef

A reference to the nib file that contains the window you want to unarchive. You obtain this reference by calling the function CreateNibReference or CreateNibReferenceWithCFBundle.

inName

A CFStringRef that denotes the window you want to unarchive. This is the name you supplied to the window in the Instances pane of Interface Builder. See the Base Services documentation for a description of the CFStringRef data type. You can use the Core Foundation function CFSTR to convert a string to a CFString.

outWindow

On output, points to the window unarchived from the nib file.

Return Value

A result code. See Runtime Errors.

Discussion

You need to call the Window Manager function ShowWindow to make the unarchived window visible.

Availability

• Available in CarbonLib 1.1 and later.
• Available in Mac OS X 10.0 and later.
• Not available to 64-bit applications.

Declared In

IBCarbonRuntime.h

DisposeNibReference

Disposes of a nib reference.

void DisposeNibReference (
   IBNibRef inNibRef
);

Parameters

inNibRef

A nib reference you created by calling the function CreateNibReference or CreateNibReferenceWithCFBundle.

Return Value

Discussion

You should call the function DisposeNibReference immediately after you have finished unarchiving objects (windows, menus, menu bar, and so forth) from the nib file associated with the nib reference.

Availability

• Available in CarbonLib 1.1 and later.
• Available in Mac OS X 10.0 and later.
• Not available to 64-bit applications.

Declared In

IBCarbonRuntime.h

SetMenuBarFromNib

Unarchives a menu bar from a nib file, then makes the menu bar available in your application.

OSStatus SetMenuBarFromNib (
   IBNibRef inNibRef,
   CFStringRef inName
);

Parameters

inNibRef

A reference to the nib file that contains the menu bar you want to unarchive. You obtain this reference by calling the function CreateNibReference or CreateNibReferenceWithCFBundle.

inName

A CFStringRef that denotes the menu bar you want to unarchive. This is the name you supplied to the menu bar in the Instances pane of Interface Builder. (The default name is “MainMenu”.) See the Base Services documentation for a description of the CFStringRef data type. You can use the Core Foundation function CFSTR to convert a string to a CFString.

Return Value

A result code. See Runtime Errors.

Discussion

The function SetMenuBarFromNib makes the menu bar visible and selectable by the user when your application opens. If you don’t want the menu bar to be visible and selectable when it is unarchived, use the function CreateMenuBarFromNib.

Availability

• Available in CarbonLib 1.1 and later.
• Available in Mac OS X 10.0 and later.
• Not available to 64-bit applications.

Declared In

IBCarbonRuntime.h

Data Types

IBNibRef

A reference to a nib file.

typedef struct OpaqueIBNibRef * IBNibRef;

Availability

• Available in Mac OS X v10.0 and later.

Declared In

IBCarbonRuntime.h

Constants

Runtime Errors

Specify a problem that occurs when Interface Builder Services tries to load nib files or objects.

enum {
   kIBCarbonRuntimeCantFindNibFile = -10960,
   kIBCarbonRuntimeObjectNotOfRequestedType = -10961,
   kIBCarbonRuntimeCantFindObject = -10962
};

Constants

kIBCarbonRuntimeCantFindNibFile

Indicates the CFStringRef supplied for a nib file does not match the name of a nib file.

Available in Mac OS X v10.0 and later.

Declared in IBCarbonRuntime.h

kIBCarbonRuntimeObjectNotOfRequestedType

Indicates the window, menu, or menu bar you want to unarchive isn’t what you specified.

Available in Mac OS X v10.0 and later.

Declared in IBCarbonRuntime.h

kIBCarbonRuntimeCantFindObject

Indicates the window, menu, or menu bar wasn’t found.

Available in Mac OS X v10.0 and later.

Declared in IBCarbonRuntime.h

---