Configuring the Library Nib Files

The main job of the plug-in object is to provide Interface Builder with information about the custom objects it supports. It does this by returning a set of nib file names from its libraryNibNames method. These “library nib files” are so named because they contain the objects to be integrated into Interface Builder’s library window. Inside the nib file are one or more library object templates, which are special containers that hold the visual representation of the objects. Because not all objects have a direct visual representation, library template objects have accommodations for specifying both the real object and a visual placeholder for that object.

The best way to understand how the library object templates inside of a library nib file work is to look at an example. Figure 4-1 shows the default nib file that is created whenever you create a plug-in project using the Xcode template. This nib file contains two library object templates. The first of these objects contains a generic NSView object. The second contains an NSButton object that acts as a placeholder for an NSButtonCell object. If you were to build and install the plug-in without modifying this nib file, Interface Builder would add two objects to the library window: a generic NSView object and a button cell (represented visually by an NSButton object). Dragging one of these objects out of the library window would instantiate the corresponding real object (either the NSView or NSButtonCell) in the user’s document. Because they are existing Cocoa objects, the user could then select and configure those objects before saving them with the document.

There is no magic to how library object templates work. They are simply views used to identify entries for the library window. The library object template itself is just a container into which you place a single child view. This child view provides the visual appearance of your library entry at runtime. In most cases, this child view is your custom view object. If your object does not descend from NSView, or if it is a view but is too large or complex to recognize when scaled to fit the library window, you can instead place an image view in the library object template and use that view to display an iconic representation of your object. You can then use the representedObject and draggedView outlets of the library object template to associate the real objects to be added to the user’s nib file.

The representedObject outlet of a library object template points to the object that should be added to a user’s nib file in place of the visual representation displayed in the library window. For custom objects that do not descend from NSView, you would connect this outlet to an instance of your object that you added to the nib file. Similarly, if you use an image view to draw an iconic version of a view, you would connect this outlet to the actual view that should be added to the user’s nib file. If you do not configure this outlet, Interface Builder assumes the view embedded in your library object template is the object that should be added to the user’s nib file.

The draggedView outlet points to the view that should be used during drag operations from the library window. Dragged views are commonly used to show the user the actual size of views as they are dragged out of the library window. If your plug-in contains a custom object that might be difficult to represent in the limited space available in the library window, you could use a custom icon for the library window and assign the actual view to the draggedView outlet. In such a situation, your dragged view would also be the represented object of the entry, unless you specified a different object in the representedObject outlet. For more information about setting up dragged views, see Using a Custom Dragged VIew.

- (NSArray *)libraryNibNames

{

    return [NSArray arrayWithObjects:@"myLibraryNibFile1", @"myLibraryNibFile2", nil];

}

Registering Your Plug-in’s Object Frameworks

When you build your plug-in, you link it against the framework containing the code for your custom objects. Thus, when Interface Builder loads your plug-in at design time, it automatically loads your custom object frameworks as well. This is fine for manipulating your objects at design time but causes a problem during simulation. When the user simulates a window, Interface Builder launches an entirely separate process—one that does not load your plug-in code and therefore does not know about your object frameworks. In order to ensure that your objects work properly in the simulator environment, you should override the requiredFrameworks method and return the list of frameworks containing your custom objects. Interface Builder passes this list to the simulator environment, which loads the corresponding frameworks as needed to run the simulation.

Listing 4-2 shows a sample implementation of the requiredFrameworks method that searches for the desired framework using its bundle identifier string.

Listing 4-2  Returning the required frameworks of a plug-in

- (NSArray*)requiredFrameworks

{

    NSBundle*    frameworkBundle = [NSBundle bundleWithIdentifier:@"com.mycompany.MyFramework"];

    return [NSArray arrayWithObject:frameworkBundle];

}

Handling Load and Unload Notifications

Most plug-ins should not require any special initialization, but if yours does, the IBPlugin class provides notification methods to let you know when your plug-in is loaded into (or removed from) the Interface Builder environment:

• didLoad

• willUnload

Most plug-ins should have little need to use either of these methods. If you do use them, do not assume that calls to the didLoad method will be balanced by calls to the willUnoad method. Although Interface Builder calls the didLoad method whenever your plug-in is loaded, it calls the willUnload method only when the user explicitly removes your plug-in from the list of plug-ins in the preferences window. Therefore, you should not use your didLoad method to acquire resources and the willLoad method to release them. You may end up leaking those resources if you do. Instead, release any resources in the dealloc or finalize method of your plug-in object.

Implementing Plug-in Preferences

When the user selects your plug-in in the preferences window, Interface Builder displays additional information about the plug-in to the right of the plug-in list. By default, Interface Builder shows the list of library nib files and frameworks found in your plug-in but you can use this space to display custom preferences. Doing so is not required, however.

To display a custom preferences view, you must do the following:

1. Create a nib file with an NSView object as a top-level object.

2. Set the File’s Owner of the nib file to your IBPlugin subclass. Your plug-in object should be configured to act as the controller for your preferences view.

3. Add your custom content to the view object and connect any outlets and actions to Files Owner.

4. Override the preferencesView method in your IBPlugin subclass. In your implementation, load your nib file and return the view object you created.

Your plug-in object should contain all of the outlets, actions, or binding points needed to manage your preferences view. Other objects in your plug-in can access the information in your plug-in object by obtaining the shared plug-in object (using the sharedInstance class method of IBPlugin) and calling its methods.

Changing your Plug-in Bundle’s Principal Class

Your custom IBPlugin subclass must be the principal class of your plug-in bundle. If you created your project using the Interface Builder 3.x Plugin project template, this information should be configured for you automatically. If you created your project without using the template or renamed your plug-in subclass, you must configure this information manually by doing the following:

1. Open an inspector window for your plug-in target.

2. Select the Properties tab.

3. In the Principal Class field, enter the name of your custom IBPlugin subclass.