Core Controls in Mac OS X: Part 1/2

The Value Combo – NSComboBox

A combo box is interesting — and quite handy — as it allows the user to choose one value from an array of options, as well as enter their own text.

It looks similar to a text field in which the user can type freely, but it also contains a button that allows the user to display a list of selectable items. You can find a solid example of this in OS X’s Date & Time preferences panel:

Here, the user can select from a predefined list, or enter their own server name, if they wish.

The control responsible for this in OS X is NSComboBox.

NSComboBox has two distinct components: the text field where the user can type, and the list of options which appear when the embedded button is clicked. You’re able to control the data in both parts separately.

To get or set the value in the text field, simply use the stringValue and setStringValue methods covered earlier. Hooray for keeping things simple and consistent! :]

Providing options for the list is a little more involved, but still relatively straightforward. You can call methods directly on the control to add elements in a manner similar to NSMutableArray, or you can use a data source — anyone familiar with iOS programming and UITableViewDataSource will feel right at home!

Method 1 – Calling Methods Directly On The Control

NSComboBox contains an internal list of items, and exposes several methods that allow you to manipulate this list, as follows:

// Add an object to the list
[myComboBox addItemWithObjectValue:anObject];

// Add an array of objects to the list
[myComboBox addItemsWithObjectValues:@[objectOne, objectTwo, objectThree]];

// Remove all objects from the list
[myComboBox removeAllItems];

// Remove an object from the list at a specific index
[myComboBox removeItemAtIndex:3];

// Get the index of the currently selected object
NSInteger selectedIndex = [myComboBox indexOfSelectedItem];

// Select an object at a specific index
[myComboBox selectItemAtIndex:1];

That’s relatively straightforward, but what if you don’t want your options hardcoded in the app — such as a dynamic list that is stored outside of the app? That’s when using a datasource comes in really handy! :]

Method 2 – Using A Data Source

When using a data source to populate the combo box, the control will query the data source for the items it needs to display as well, as any necessary metadata, such as the number of items in the list.

To use a data source, you’ll need to implement the NSComboBoxDataSource protocol in your class. From there, it’s a two-step process to configure the combo box to use the data source.

First, call the control’s setDataSource method, passing an instance of the class implementing the protocol; usually “self”. Then call the control’s setUsesDataSource method, passing YES as the parameter.

In order to conform to the protocol, you’ll need to implement the following two methods:

// Returns the number of items that the data source manages for the combo box
- (NSInteger)numberOfItemsInComboBox:(NSComboBox *)aComboBox
{
    // anArray is an NSArray variable containing the objects
    return [anArray count];
}

// Returns the object that corresponds to the item at the specified index in the combo box
- (id)comboBox:(NSComboBox *)aComboBox objectValueForItemAtIndex:(NSInteger)index
{
    return [anArray objectAtIndex:index];
}

Finally, whenever you need to reload the data in a combo box which is using a data source, simply call reloadData().

Which Method To Use?

If your list of items is relatively small and you don’t expect it to change that often, adding items once to the internal list is probably the best choice. But if your list of items is large or dynamic, it can often be more efficient to handle it yourself using a data source.

Now that you’ve covered the fundamentals of the combo box, move on to implement one in your app! :]

The Singles Bar — A Singular Noun

In this section you’ll add a combo box to your Mad Libs application, to allow the user to choose from a list of singular nouns (or allow them to enter their own).

To do this, first add a Label to the app so that the user knows what the control is for. Select the MainMenu.xib in the project explorer to open it in Interface Builder, and then select the Main Window.

In the Object Library palette, locate the Label control and drag it onto the window. Double-click it to edit it’s default text, changing it to Singular Noun:.

Next, add the combo box that will provide the users with the list of choices. Locate the Combo Box control and drag it onto the window, placing it to the right of the label.

Your window should now look like this:

Now you need to add an NSComboBox property to the view controller so you can populate the default items, and later access it via code to read the user’s selection.

To do this, use the same technique you used for the text field: select the assistant editor (making sure RootViewController.m is selected) and Ctrl-Drag the combo box to the RootViewController.m to create a new property, just like in the screenshot below:

In the popup window that appears, name the property singularNounCombo.

Now the NSComboBox property is connected to the combo box control! Now, if you only had some data to populate the list! :] Time to add some.

Open RootViewController.m in the code editor and add the following property declaration directly below the singularNounCombo property:

@property (nonatomic,strong) NSArray *singularNouns;

Inside awakeFromNib, add this to the bottom:

// Setup the combo box with singular nouns
self.singularNouns = @[@"dog", @"muppet", @"ninja", @"fat dude"];
[self.singularNounCombo addItemsWithObjectValues:self.singularNouns];
[self.singularNounCombo selectItemAtIndex:2];

The first line initializes an array with four strings. The second line adds those items to the combo box using one of the methods covered earlier. Finally, the combo box is asked to select the item at index 2.

Build and run the application to see your combo box in action!

Great — it looks as though everything is working just right. Once the app has launched, the combo box selects the second item as the default. If you click on the combo box, you can then view and select any of the other items.

But what if you want to present the user with a list of choices, but not allow them to enter their own text? Read on — there’s a control for that as well! :]