Creating Your Inspector Class

The IBInspector class provides the default controller interface for implementing your custom inspector objects. Custom inspectors are needed only for classes that have custom design-time attributes that you want to be configurable in Interface Builder. If your classes do not expose any public attributes, you do not need to create an inspector class.

Every inspector class has the following responsibilities:

• Provide an interface for viewing and setting attributes.

• Synchronize the controls in its view with the attributes of the current selection.

The viewNibName method of IBInspector is the preferred way to provide the interface for your inspector class. This method returns the name of the nib file containing your inspector’s interface. You can also create your user interface programmatically if you prefer. The steps for creating your user interface are discussed in Creating Your Inspector’s User Interface.

For information on how to synchronize your inspector’s interface with the current selection, see Synchronizing Your Inspector’s Interface.

Creating Your Inspector’s User Interface

There are two ways to create your inspector’s user interface: programmatically or using a nib file. Using a nib file is by far the simplest way to create your inspector’s interface. In fact, if you use Cocoa bindings, it is possible to create your inspector with little or no code at all. Whereas, creating your inspector interface programmatically is complicated and requires much more effort and testing to ensure the correct positioning and layout of any controls.

All new plug-in projects in Xcode come with an inspector nib file for you to customize. To create additional inspector nib files, you use Interface Builder. Interface Builder’s new document dialog includes an IB Kit tab that contains plug-in related template nib files. From this tab, selecting the Inspector template creates a nib file with the default content view shown in Figure 5-2. This view includes several guides to help you line up your custom controls with the controls found in other inspectors. The view also includes some default controls that you can use for your inspector (or delete if they are not needed). Although you should not change the width of your inspector view, you can (and should) change its height to match the space used by your controls.

To configure the nib file containing your inspector’s user interface, do the following:

1. Open your plug-in project in Xcode. (This ensures that your class header files are accessible in Interface Builder.)

2. Open your project’s existing inspector nib file (or create a new one).

3. Add or remove any needed controls in your inspector view.

   Typically, you would provide a single control for each design-time attribute of your object you want to expose. The type of the control would be determined by the type of data represented by the underlying attribute.

   • String values are typically represented by text fields.

   • Numerical values may be displayed in a text field but might also have an optional stepper control to increment or decrement the value.

   • Boolean values are typically represented using check boxes.

   • Enumerated type lists may be represented by radio buttons or pop-up menus.

4. Select the Files Owner placeholder object and open the identity pane of the inspector window.

5. Set the class name of File’s Owner to your IBInspector subclass. (You set this information in the identity pane of the inspector window.)

6. If it is not already connected, connect the inspectorView outlet of Files Owner to your inspector view. (This outlet is provided for you by the IBInspector class and should be connected already.)

7. Create any other connections or bindings required by your code. (For example, you might want to connect any outlets or actions to their targets.)

8. Save your nib file and add it to your Xcode project (if it has not yet been added).

Nearly all inspector nib files require some additional connections beyond the inspectorView outlet of File’s Owner. You use these connections to make it possible to synchronize changes as the user changes the current selection and modifies controls in your inspector. Cocoa bindings provide the simplest type of connection by automatically synchronizing the current selection with your inspector’s controls. You can also use outlets and actions if you prefer, however. For more information on using both of these techniques, see Synchronizing Your Inspector’s Interface.

If you want to create your inspector view programmatically, you can do so by implementing a custom view method in your IBInspector subclass. In your implementation of this method, you would create the view object you want your inspector to display and configure it as required by your custom object. In addition to overriding this method, you must override the viewNibName method and have it return nil to prevent Interface Builder from automatically looking for a nib file.

Synchronizing Your Inspector’s Interface

Interface Builder relies on your inspector object to coordinate the synchronization of the currently selected objects to your inspector’s user interface. Cocoa bindings are the preferred (and simplest) way to synchronize data but you can also use outlets and actions if you prefer. Which technique you choose may also depend on the complexity of your objects and how much logic is required to synchronize them with the inspector controls. Synchronization is required in the following situations:

• The user changes the current selection.

• The user changes the value of one of your inspector’s controls.

When multiple objects are selected, the inspector window displays only those inspector sections that are common to all of the selected objects. Your inspector objects must be prepared to handle this situation gracefully by displaying appropriate values in the controls of their user interfaces. Although there are options for situations where handling multiple selected objects is difficult or impossible, you are highly encouraged to design your inspector interface in a way that allows it to display at least some information when multiple objects are selected.

The following sections guide you through the steps to implement the synchronization code for your inspectors. Remember that you can choose to use bindings, outlets and actions, or a combination of both.

- (void)refresh

{

    NSArray*        objects = [self inspectedObjects];

    NSString*       newTitle;

    NSInteger       numObjects = [objects count];

    if (numObjects == 1)

    {

        newTitle = [[objects objectAtIndex:0] title];

        [titleField setStringValue:newTitle];

    }

    else if (numObjects > 1)

    {

        NSString*    tempString;

        NSInteger    i;

        BOOL        allMatch = YES;

        // See if the titles are all the same.

        newTitle = [[objects objectAtIndex:0] title];

        for (i = 1; i < numObjects; i++)

        {

            tempString = [[objects objectAtIndex:i] title];

            if (![newTitle isEqualToString:tempString])

            {

                allMatch = NO;

                break;

            }

        }

        // Set the value of the text field.

        if (allMatch)

            [titleField setStringValue:newTitle];

        else

        {

            [titleField setStringValue:@""];

            [(NSTextFieldCell*)[titleField cell] setPlaceholderString:@"<multiple>"];

        }

    }

    [super refresh];

}

Registering Your Inspector Objects

Before it can display your inspector interface, Interface Builder needs to know which objects use it. You provide this information by implementing the ibPopulateAttributeInspectorClasses: and ibPopulateSizeInspectorClasses: methods on your custom object. In your implementation of these methods, you add the list of inspector classes that can be used to edit your object to the provided array. Interface Builder then creates inspector objects based on the set of classes you return.

When implementing these methods, be sure to call super before adding any custom classes to the classes array. The order in which you add classes to the array defines the resulting order of the inspector sections in the inspector window. The first class in the array appears at the bottom of the inspector window, while the last class appears at the top. This means that you should generally add any inherited inspectors first and add your custom inspectors after that.

Listing 5-2 shows a sample implementation of the ibPopulateAttributeInspectorClasses: method for a custom view. This view has a single custom inspector, called MyInspector, that it adds to the inherited inspector list.

Listing 5-2  Returning the attribute inspectors for an object

@implementation MyCustomView (InspectorIntegration)

- (void)ibPopulateAttributeInspectorClasses:(NSMutableArray *)classes

{

    [super ibPopulateAttributeInspectorClasses:classes];

    [classes addObject:[MyInspector class]];

}

@end

A sample implementation of the ibPopulateSizeInspectorClasses: method is similar. For more information about these two methods, see NSObject Interface Builder Kit Additions Reference.