Opening User Documents That You Plan to Display in a New Window

When you want to ask the user to select a document to display in a new window, display the standard Open panel modally. Document-based apps normally provide this behavior for you automatically, providing the infrastructure needed to respond to the Open command in the menu. To display this panel in other situations, you can implement your own method to display the panel. The steps for creating and presenting an Open panel yourself are as follows:

1. Use the openPanel class method of NSOpenPanel to retrieve an Open panel object.

2. Present the panel using the beginWithCompletionHandler: method.

3. Use your completion handler to process the results.

Listing 5-1 shows a custom method that presents the standard Open panel to the user. This panel uses the default configuration options, which support the selection of a single file from all available file types. The beginWithCompletionHandler: method displays the panel in a detached window and returns immediately. The panel runs modally relative to the app and calls the supplied completion handler on the app’s main thread when an item is selected. Upon the successful selection of a document, you need to provide the code to open the document and present its window.

Listing 5-1  Presenting the Open panel to the user

- (IBAction)openExistingDocument:(id)sender {

   NSOpenPanel* panel = [NSOpenPanel openPanel];

   // This method displays the panel and returns immediately.

   // The completion handler is called when the user selects an

   // item or cancels the panel.

   [panel beginWithCompletionHandler:^(NSInteger result){

      if (result == NSFileHandlingPanelOKButton) {

         NSURL*  theDoc = [[panel URLs] objectAtIndex:0];

         // Open  the document.

      }

   }];

}

In a document-based app, requests to display the Open panel are handled by the openDocument: method of the app’s document controller object, which is part of the app’s default responder chain. Instead of implementing your own Open panel code, you might consider calling the openDocument: method instead. Doing so ensures that your custom code and the default app infrastructure always display the same Open panel. Customizing the panel at a later time also becomes easier because you have to make changes in only one place.

For more information about implementing a document-based app, see Mac App Programming Guide.

Choosing Files and Directories for an Already Open Window

To choose files or directories that relate to the current window, configure the standard Open panel as a Choose panel and use it to retrieve the user’s selection. The main difference between the standard Open panel and a Choose panel is how you present it. Whereas you present the standard Open panel as a standalone modal panel, you almost always attach a Choose panel to one of your existing windows. Attaching the panel to a window makes it modal to the window but not to your whole app. Other differences relate to the configuration of the panel itself. A Choose panel can be configured to allow the selection of directories, multiple items, or hidden items among other options.

The NSOpenPanel object returned by the openPanel method is configured with the following default options:

• File selection: enabled

• Directory selection: disabled

• Resolve aliases: enabled

• Multiple selection: disabled

• Show hidden files: disabled

• File packages treated as directories: disabled

• Can create directories: disabled

Listing 5-2 shows a method you might implement in one of your NSDocument subclasses to import some files and associate them with the document. After configuring the panel, this method uses the beginSheetModalForWindow:completionHandler: method to present the panel as a sheet attached to the document’s main window. If the user selects some files, the URLs method contains the corresponding file and directory references to incorporate.

Listing 5-2  Associating an Open panel with a window

- (IBAction)importFilesAndDirectories:(id)sender {

   // Get the main window for the document.

   NSWindow* window = [[[self windowControllers] objectAtIndex:0] window];

   // Create and configure the panel.

   NSOpenPanel* panel = [NSOpenPanel openPanel];

   [panel setCanChooseDirectories:YES];

   [panel setAllowsMultipleSelection:YES];

   [panel setMessage:@"Import one or more files or directories."];

   // Display the panel attached to the document's window.

   [panel beginSheetModalForWindow:window completionHandler:^(NSInteger result){

      if (result == NSFileHandlingPanelOKButton) {

         NSArray* urls = [panel URLs];

         // Use the URLs to build a list of items to import.

      }

    }];

}

For single-window apps, associate the open panel with your app’s main window. For document-based apps, associate it with the main window of the current document.

Defining the Contents of Your Accessory View

Because an accessory view is just another view, you define it the way you define other views in your app. An accessory view always consists of a single main view that may itself contain any number of subviews. The most common configuration for an accessory view is as a host for one or more controls. When the user interacts with the controls in your accessory view, those controls use the target-action design pattern to call your app’s custom code. You can then use that code to store configuration options or take any relevant actions.

A nib file is the simplest way to define an accessory view. Before setting up the nib file, you need to know which object in your app is going to present the panel. For example, in a document-based app, your NSDocument subclass is usually responsible for displaying any Open and Save panels. In general, the object that presents the panel should also own the contents of the accessory view. With that in mind, the configuration of your nib file would be as follows:

1. Create a new nib file whose contents are a single view.

2. Set the File’s Owner of the nib file to the object that presents the panel.

3. Configure the contents of the nib file’s top-level view object.

   • Add any subviews, such as checkboxes, that you want to include in the accessory view.

   • You can change the class of the top-level view object if you want, but doing so is not required. If you use a generic view as the main view, the underlying panel provides the appropriate background appearance for the rest of your content.

4. Connect actions (as appropriate) to your views to facilitate interactions with your custom code. You should implement the action methods themselves in the object you assigned as File’s Owner.

5. Connect outlets (as appropriate) for any controls you use to gather data passively from the user. The completion handler for the panel can then use the outlets to access the data in the controls.

6. Size your accessory view to be as small as possible while still showing all subviews in their entirety.

7. Save the nib file.

When displaying an accessory view, the Open and Save panels show your entire accessory view. If your accessory view is larger than the panel itself, the panel grows to accommodate your view. If the panel grows too large, it could look strange or could cause problems on smaller screens. Most accessory views should have only a few controls anyway. So if you find yourself adding more than ten controls, you might want to consider whether an accessory view is appropriate or if there is a better way to gather the information.

For more detail on the process of building a user interface and creating and configuring interface builder files, see Xcode Help.

Loading and Configuring Your Accessory View at Runtime

Immediately before displaying an Open or Save panel, load (or create) your accessory view and attach it to the panel using the setAccessoryView: method. If you create your accessory view programmatically, you normally create it right before presenting the panel itself. If you store your accessory view in a nib file, you load that nib file first.

Loading the nib file for an accessory view is relatively simple as long as the nib file itself is configured properly. The easiest way to configure the nib file is to assign the object that presents the panel as the File’s Owner of the nib file itself. That way, any outlets and actions defined on the object are connected automatically and ready to use as soon as the nib file is loaded into memory. Listing 5-5 shows an example of how this works. The method in this example is implemented on an NSDocument object. When called, the method presents an Open panel with an accessory view attached to the document’s main window. The accessory view itself contains a single checkbox that is connected to a custom optionCheckbox outlet that the document object defines. (The outlet itself is implemented using a property. ) The handler block uses the value of the checkbox to determine how to open the file.

Listing 5-5  Loading a nib file with an accessory view

- (IBAction)openFileWithOptions:(id)sender {

   NSOpenPanel*    panel = [NSOpenPanel openPanel];

   NSWindow*       window = [[[self windowControllers] objectAtIndex:0] window];

   // Load the nib file with the accessory view and attach it to the panel.

   if ([NSBundle loadNibNamed:@"MyAccessoryView" owner:self])

      [panel setAccessoryView:self.accessoryView];

   // Show the open panel and process the results.

   [panel beginSheetModalForWindow:window completionHandler:^(NSInteger result){

      if (result == NSFileHandlingPanelOKButton) {

         BOOL option1 = ([self.optionCheckbox state] == NSOnState);

         // Open the selected file using the specified option...

      }

   }];

}

If you create your accessory view programmatically, replace the if statement containing the call to the loadNibNamed:owner: method with your custom view-creation code.

For more information on how to load objects from nib files, see Resource Programming Guide.