Volume Number: 13 (1997)
Issue Number: 8
Column Tag: Getting Started

Getting Started: VerySimpleText, Version 1

by Dave Mark, ©1997, All Rights Reserved

In last month's column, we built our first few applications under the OPENSTEP environment. We started off with a guided tour of OPENSTEP, including the File Viewer, dock, menuing system, and terminal emulator. The applications were all Objective-C console apps. None took advantage of the user interface elements that give our OPENSTEP apps the OPENSTEP look-and-feel.

This month's column changes that with the introduction of VerySimpleText, our first true OPENSTEP application. As its name implies, VerySimpleText is an OPENSTEP version of the Mac's classic SimpleText application. Before you read on, think about how you would go about building a SimpleText application. If you are a C programmer, you would need to deal with menu and window management, fonts, printing, embedded graphics (extremely primitive in SimpleText), and a host of other issues such as QuickTime, clipboard, TextEdit, and memory management. If you are using PowerPlant and C++, things get a bit simpler, since you can take advantage of PowerPlant's pre-built classes.

The OPENSTEP tools ProjectBuilder and InterfaceBuilder take this approach one step further by adding a RAD (stands for Rapid Application Development) front end to the development process. ProjectBuilder is somewhat like the CodeWarrior IDE, but is tightly integrated with Interface Builder. Interface Builder allows you to create and arrange the various objects/classes that make up your application and specify the relationship between them.

This month, we'll build a very basic version of the VerySimpleText application, based on a tutorial presented by the NeXT folks at Apple's World-Wide Developer's Conference. Don't be fooled, though: the pre-built objects that ship with OPENSTEP will give this version of VerySimpleText some pretty powerful capabilities. In the coming months, we'll continue to muck around with VerySimpleText, demonstrating just how easy it is to work with the OPENSTEP objects.

The version of Project Builder and Interface Builder I've got installed on my system (OPENSTEP 4.2) are a bit buggy. Nothing too awful -- mostly I find myself having to repeat a command or mouse click as Interface Builder seems to swallow (or ignore) the occasional event.

Though these bugs have been verified by some of the NeXT folks, I'm guessing that by the time this issue of MacTech hits the streets, a new version of OPENSTEP will be available and some of these bugs will no longer exist. Bottom line, if you are trying to reproduce the steps in this column and things don't go exactly as planned, patience! Try backing up and repeating the last step.

Oh yeah, thanks as usual to Michael Rutman for his excellent tech review...

• Launch ProjectBuilder (either from the dock - it's the hammer icon - or from myhost/NextDeveloper/Apps/ProjectBuilder.app).
• Select New from ProjectBuilder's Project menu.
• When the "New Project" panel appears (a panel is a dialog box), navigate to the folder in which you want your project folder stored. ProjectBuilder will build a new folder for you using the project name you specify in the next step.
• Type VerySimpleText.01 in the Name field.
• Select Application from the Project Type popup menu.

Before you click the OK button, compare your panel to the one shown in Figure 1.

Figure 1. The New Project Panel used to create the VerySimpleText.01 project in ProjectBuilder.

• Click the OK button.

ProjectBuilder will create a new folder named VerySimpleText.01 into which it will place the files it needs for your new project. In ProjectBuilder, a new project window will appear (see Figure 2). The project window lets you browse through all the files used to build your project, including a special series of files, similar to resource files, closer still to Constructor files, known as .nib files. The .nib files are used by InterfaceBuilder to define your program's interface.

Figure 2. The project window created by ProjectBuilder.

Check out the project window shown in Figure 2. Notice that the interfaces section is highlighted showing the list of .nib files in this project. In this case, we've got one .nib file for NEXTSTEP, and another for Windows. Since I'm running the NEXTSTEP OS, I'll work with the NEXTSTEP .nib file. If you are running NEXTSTEP on top of Windows, you'll want the Windows .nib file. By the time this column hits the streets, you may have a third alternative: a Rhapsody .nib file!

• Double-click the NEXTSTEP_VerySimpleText.01.nib file in the ProjectBuilder browser, Interfaces section. This will launch InterfaceBuilder.

Note that ProjectBuilder's main menu has the title PB and InterfaceBuilder's main menu has the title IB. If you are confused as to which application you are in, just check out the menu window.

InterfaceBuilder features a number of windows you'll get to know and love. The plain window labeled "My Window" is your application's window (Figure 3). The inspector window gives you info about and lets you modify the currently selected element. At the moment, the inspector is a window inspector and lets you modify the application window (Figure 4). The palette window lets you drag various interface elements into place to become part of your application (Figure 5). Various palettes are available. Your application comes with a main menu that you can modify as you like. The main menu looks just like a regular menu (Figure 6), so you might be confused the first time you look for it. By default, the menu's title is nextstep (assuming you are using the NEXTSTEP .nib). Finally, InterfaceBuilder's main window (Figure 7) lets you work with your projects object instances, classes, sounds, and images. This window is more commonly known as the .nib window. You'll learn more about these windows as we go.

Figure 3. Your application's window.

Figure 4. The inspector window, set to inspect a window.

Figure 5. The palette window.

Figure 6. The main application menu.

Figure 7. InterfaceBuilder's main window, also known as the .nib window.

Our next step is to modify our app's main menu.

• If you don't see the main menu, click on the .nib window to bring it to the front, click on the Instances tab, then double-click on the MainMenu instance.
• In the palettes window, click on the menu icon.

A series of 12 menu items will appear (two columns of 6).

• Drag the Format menu onto your main menu, releasing it midway between the Windows and Services items. The Format submenu will appear in your main menu.

With that simple drag, you've just added a series of powerful font, text, and page manipulation features to your application. If you had your eye on the .nib window, you may have noticed the addition of a new instance, named Font Manager, that appeared in the window when you released the drag. Note that you didn't have to take any special action to add these powerful features to your application. Drag in the menu and everything the menu needs is automatically added for you. Later in the column, we'll take a few of these items for a spin. Our next step is to add a scrolling text area to our main window.

• In the palettes window, click on the DataViews icon (it looks like a window in which the word Text is partially visible).
• Drag a scrollable text view from the palette window onto the application window (the one labeled MyWindow).
• Grab one of the resize handles on the scrollable text area and resize it so it almost fills the window (leave some of the grey background showing so you can still click on it).

My application window, showing the scrollable text area is shown in Figure 8. Note the 8 pixel border around the scrolling text area. Unlike on the Mac, the NeXT interface calls for an 8-pixel border to separate interface elements. I suspect this will change under Rhapsody, but when in Rome...

Figure 8. The application window, showing the scrollable text area.

Now we'll tie the scrollable text area to the window in such a way that when you resize the window, you also resize the scrollable text area.

• Click on the scrollable text area in your application window.
• If the inspector window is not showing, bring it up by selecting Inspector... from the InterfaceBuilder's Tools menu. The inspector window should be labeled NSScrollView Inspector.
• Select Size from the popup menu at the top of the inspector window.
• Click on the square in the center of the Autosizing area so that a pair of crossed springs appear.

This will require two clicks, one for the vertical spring and one for the horizontal spring. My inspector is shown in Figure 9. The two springs specify that the scrollable area should grow along with the enclosing window in both the horizontal and vertical directions.

Figure 9. The NSScrollView inspector, showing horizontal and vertical springs.

Let's take this interface for a spin.

• Select Test Interface from the Interface Builder's Document menu. Note that you could also type the key sequence Alt-r instead.

The InterfaceBuilder windows should disappear and be replaced by your running application with its nextstep menu and application window. You can tell your application is running because the InterfaceBuilder icon in the dock will turn into a master power switch in the down position. Put the sample app through its paces. Type in some text. Modify the text by selecting various items from the Format menu. Change the font size, style, kerning, etc. Try out cut, copy, and paste. Resize the window. To exit the application, select Quit from the application's menu.

This exercise should convince you of the incredible power of the pre-built OPENSTEP classes. Think about what just happened. With absolutely no code at all, you built a working text editor. Of course, you can add as much code as you like to your applications, customizing what OPENSTEP gives you for free. It is also important to note that you did not have to compile anything to bring this application to life. Instead you linked together objects that already existed, in this case window, menu, and text objects to name a few. The ease with which you can modify and extend your "house of objects" is further proof of the power of dynamic binding and linking, and of OPENSTEP.

Our next step is to add an about box to our application, along with a method to show the about box.

• Back in InterfaceBuilder, double-click on the MainMenu instance (in the .nib window) to bring up the application's main menu.
• Click on the Info menu item to bring up the Info submenu.
• Double-click on the Info Panel... item to make it editable.
• Change the text Info Panel... to read About VerySimpleText...

In my version, the cursor disappeared as I was typing, since the new text was wider than the existing menu. To verify that I had edited the menu correctly, I clicked the Info menu item to make the submenu disappear, then clicked the Info menu item again to make the menu reappear. It was drawn correctly, resized to show the entire "About VerySimpleText..." item.

• With the "About VerySimpleText..." item selected, bring the inspector window to the front. It should be labeled as an NSMenuItem inspector.
• Select Attributes from the popup menu.
• Make sure the Disabled checkbox is unchecked. This means that the item is now enabled.

Now we'll create the About box window.

• Make sure the palette and .nib windows are both open.
• In the .nib window, select the instances tab.
• In the palette window, click on the window icon (the window title should change to "Windows"), then drag a window onto the screen. A new window instance will appear in the .nib window.
• In the .nib window, click on the new windows icon (labeled Window) and change the text below the icon to read AboutWindow.

Note that we've just changed the instances name. We have not changed the windows title. We'll do that now.

• Double-click on the instance (the icon should now be labeled AboutWindow) to bring the About window to the front.
• In the inspector window, make sure the Attributes item is selected from the popup.
• Change the window title to "About VerySimpleText..."
• Hit the Enter key to make the change take hold. The title of the window should actually change when you hit the Enter key.
• Go back to the inspector window and uncheck the "Resize bar" checkbox (in the Controls area). The About window should jump to the front and the resize part of the About window should disappear. Note that you didn't have to hit the Enter key for this change to take hold.
• Back in the palette window, select the views icon (the title of the palette window should change to Views).
• Drag some text fields onto the About window. Type in some default text and use the inspector to change the text attributes as you like.

In this next sequence of steps, we're going to create an AboutPanelController class which will handle bringing up the About window in response to the appropriate selection from the Info menu. The new class will contain a single method called show:.

• In the .nib window, click on the Classes tab.
• Click on the line labeled NSObject, being careful not to click on the little circle to the left of NSObject. That circle will collapse or expand the classes derived from NSObject.
• With NSObject selected, select Subclass from the IB menu's Classes menu. A new subclass, labeled MyNSObject, will appear.
• Double-click on the word MyNSObject if it is not already highlighted and change it to read AboutWindowController. Be sure to hit the Enter key to make your change take hold.

This next step creates an outlet and action for the new class. Think of an outlet as an instance variable or object you'd like associated with your class. When InterfaceBuilder generates the source code for this class (it will do that), the outlet object will be declared in the header file as type id.

An action, on the other hand, is a method. Objects that are derived from NSControl (like buttons, menus, etc.) have a notion of being activated by the user. For example, a button is pressed, a menu item selected. These items use their associated action as a target. Our job is to link these things together.

In our example, we'll add an outlet named abtWindow to the AboutPanelController class. We'll also add an action method named show: to the class. We'll link the "About VerySimpleText..." menu item to the AboutPanelController and specify that the target action is the show: method. Basically, this means that the AboutWindowController instance will get sent a show: message when the "About VerySimpleText..." menu item is selected.

I realize that abtWindow is not the greatest of variable names, but I wanted to be sure to distinguish between the label AboutWindow under the about windows instance in the .nib window and the outlet that ultimately will refer to that instance. Perhaps I should have gone with aboutWindowOutlet. Ah, well...

We'll also link the AboutWindowController instance (with its abtWindow instance) to the AboutWindow instance. The result: when the "About VerySimpleText..." menu item is selected, the About Window window will open.

This may seem a bit confusing at first, but once you follow the steps below, things should become clearer. Creating outlets and actions, then linking instances together is the way things are done in InterfaceBuilder. Let's try it out.

• In the .nib file, Classes tab, click on the tiny outlet icon just to the right of the word AboutWindowController.

Two new lines should appear, one labeled Outlets and one labeled Actions.

• Click on the line labeled Outlets, then select Add Outlet from the Classes menu.

An outlet named myOutlet should appear.

• Change myOutlet to abtWindow (you can double-click on the outlet name to edit it).
• Click on the line labeled Actions and select Add Action from the Classes menu.
• Change the action name to show: (be sure to include the trailing colon).

My .nib window is shown in Figure 10.

Figure 10. The .nib window, showing the AboutWindowController class with the abtWindow outlet and show: action.

• Click on the tiny outlet icon to the right of the AboutWindowController label to collapse the AboutWindowController class display in the .nib window.
• With the AboutWindowController line highlighted, select Create Files... from the Classes menu.
• Click Yes to both dialogs that appear, one asking whether to create the files and the other asking whether to add the files to the project.

At this point, you've created the .m and .h files for your new class. You can use the ProjectBuilder browser to look at the two files. One is found under Classes and the other under Headers. Note that a method named show: and a variable named abtWindow were declared. Once you are done admiring your handiwork, return to InterfaceBuilder.

• Back in InterfaceBuilder, make sure the AboutWindowController class is still highlighted, then select Instantiate from the Classes menu.

The cube labeled AboutWindowController (look for the cube shaped icon in the .nib window, instances tab) is the instance of your AboutWindowController class. If your cube is labeled AboutWindow, try clicking on it to see the full text. That's what I had to do. My guess is, this is a bug. Oh, well.

Just to avoid confusion, there are four instances you care about at this point. AboutWindowController (the cube) is your AboutWindowController. MainMenu is your menu. MyWindow is your application's main window and AboutWIndow is your application's about window.

Now let's connect all this together.

• Find your application's menu (you can double-click on the MainMenu instance) and make sure the Info menu is open.
• Hold down the Ctrl key and drag FROM the "About VerySimpleText..." menu item to the AboutWindowController instance (the cube) in the .nib window.

A line will start at the menu item and a square will appear around the cube.

• Let go of the mouse button with the square around the cube.
• When the inspector window appears, the word target should appear in the Outlets column and the word show: should appear in the Actions column.
• Click on the word show: and click the Connect button at the bottom of the inspector.

A dot will appear to the right of show:. You've just added a connection to the "About VerySimpleText..." menu item. Anytime you want to see the connections from an object (including a menu item) click on the object and select Connections from the inspector's popup menu.

• Hold down the Ctrl key and drag FROM the AboutWindowController instance (the cube) to the AboutWindow instance (the window).
• In the inspector, click on the abtWindow outlet and click the Connect button.

A dot will appear to the right of abtWindow. You've just connected this outlet (instance variable) to the instance of the about window.

• Select Save from the Document menu and quit InterfaceBuilder.

We are almost done!

• Return to ProjectBuilder and click on the Classes item in the browser window.
• In the second column, click on AboutWindowController.

You should now see the show: method in the main window of the browser. At this point, the code should read:

#import "AboutWindowController.h"

@implementation AboutWindowController

- (void)show:(id)sender
{
}

@end

Your job is to add a line to the show: method.

• Add the following line to the show: method:

[abtWindow makeKeyAndOrderFront:self];

When you are done, your code should look like this:

#import "AboutWindowController.h"

@implementation AboutWindowController

- (void)show:(id)sender
{
	[abtWindow makeKeyAndOrderFront:self];
}

@end

Now let's build and run our application.

• Click on the hammer icon in the upper-left corner of the ProjectBuilder browser window.
• When the project build window appears, click on its hammer icon.
• When prompted, click the save and build button (you won't be prompted if you already saved your changes).

A message should appear saying that your build succeeded.

• Back in the browser window, click on the run button, which looks like a computer monitor with some windows open on it. The run button is the rightmost button.
• When the launch window appears, click the run button again (if you are feeling adventurous, click on the spray can button to bring up the debugger).

Your application should appear. Take it through its paces. Be sure to select "About VerySimpleText..." from the Info menu.

This was a lot to swallow in one month. Hopefully, you've gotten a taste of the incredible power of the OPENSTEP pre-built object hierarchy. Next month, we're going to take a look at a very cool Rhapsody web site and explore OPENSTEP's documentation mechanism which, I'm told, should make its way into Rhapsody.