TweetFollow Us on Twitter

September 96 - Mac OS 8 Assistants in System 7 Applications

Mac OS 8 Assistants in System 7 Applications

Jose Arcellana and Arno Gourdol

Assistants are a key part of the Mac OS 8 help system. An assistant makes an application's features easier to use and more readily accessible. In anticipation of Mac OS 8, this article will show you how to build Mac OS 8-style assistants into your System 7 applications, from design to implementation. We illustrate this with a sample assistant developed for the Internet Configuration System.

Developers are constantly pursuing two goals that seem to be at cross-purposes: making applications more powerful and making them easier to use. All too often, power brings complexity, when in fact power can be used to simplify things for the user. Assistants can make the powerful features you're building into your applications easier to access and handle.

An assistant offers the user an alternate interface. It focuses on a specific activity that the average user is likely to want to do and frames the application's functionality to support that activity. The defining aspect of an assistant is the interview, in which the user is asked to supply information about preferences and typical activities accomplished with the application.

Although assistants can be implemented under System 7, they'll be able to do more using Mac OS 8 technologies. In this article, we talk about what Mac OS 8 assistants are and give some general guidelines for designing an interview. We also provide an example of how to implement an interview in System 7. Our sample assistant helps users with the Internet Configuration System (Internet Config), a utility for setting preferences for Internet applications. Internet Config is described in detail in the article "Implementing Shared Internet Preferences With Internet Config" in develop Issue 23. The source code for the Internet Setup Assistant is included on this issue's CD.

    The final name for assistants, which have also been called experts, has not been decided at the time of this writing. Whichever the final name, the interview-based interaction that forms the basis of assistants will be an integral part of the Mac OS 8 help system.*


An assistant is a small single-purpose application that can do any or all of the following:
  • frame computer-based tasks in terms of real-world activity

  • hide details from the user by filtering out options that aren't applicable

  • pull together elements from different parts of the user interface to support a single activity

  • manage tasks so that they're executed on demand or when a specific condition becomes true

  • help the user provide the information needed by conducting interviews

  • make reasonable assumptions, based on user context and user activity, that work for the vast majority of users
For example, a resume-formatting assistant would ask the user how formal or casual the resume should be. It would then make assumptions, hiding such details as typeface selection and paragraph formatting. An assistant for maintaining a computer would use task scheduling to check for viruses when it makes sense, optimize the hard disk when it needs to, and so on.

At first glance, assistants might seem to resemble Microsoft's wizards. Currently, however, there are differences between them. Wizards don't make reasonable assumptions based on user context and user activity. Instead of filtering out options that aren't applicable, they present all options. While assistants provide an alternate interface to an application or set of applications, wizards might be the only user interface to a task, and they aren't capable of pulling together elements from other places in the interface. Wizards also can't schedule tasks for later execution.


Assistants are meant to augment and not replace the more direct ways to control your application. They shouldn't be used to cover up a flawed user interface design, such as dialog boxes or commands that are too difficult to figure out. Users should always be able to do directly in the program's primary interface whatever an assistant does for them indirectly, though it might take more steps to accomplish the task in the primary interface. How do you determine when a specific area of the user interface needs a redesign and when it could use an assistant? In general, an assistant is most effective when it supports an activity that many users want to perform with your application but that can only be accomplished if the user has a better-than-average familiarity with your application's feature set and user interface. For example, we developed an assistant for Internet Config because it takes several steps in different places of the interface to set up your Internet preferences for the first time.


An assistant conducts a brief interview, consisting of a series of simple questions, to get the information it needs from the user. The interview should be:
  • Short. Ask as few questions as possible. To minimize the number of questions, the assistant should make as many reasonable assumptions as possible.

  • Simple. Make the questions easy to answer. If a difficult question needs to be asked, the interview should provide information that helps the user answer the question.

  • Concise. No words should be wasted, even when providing information to help the user answer a question.

  • Neutral. The tone should be conversational and friendly, not too familiar or too cold.
Note that an interview isn't a dialog box, nor is it a dialog box taken apart and presented in a series of smaller dialog boxes. Adding "Assistant" to the name of a command that calls up a dialog box doesn't make the dialog box an interview or the command an assistant. Finally, the interview isn't a way to give the computer a personality.


The assistant interview takes place in a fixed-size, movable window. Whether it's a regular (document) window, a modal window, or a floating window depends on the context from which you anticipate it being invoked. Assistants should be accessible from appropriate places in your user interface, such as through a menu item or a button in a dialog box. They should be accessible by name (so that the name of the menu item or button is the name of the assistant) or, if the context is clear, by the words "Assist Me." The interview window contains header, content, and navigation areas, as you can see in Figure 1.

Figure 1. A typical assistant interview window

  • If the interview window is a document window, the assistant's name appears in the title bar and the header area displays the interview phase that the user is in. If it's not a document window, the header area displays the assistant's name followed by a colon and the interview phase.

  • The content area contains text (usually a question and a brief explanation) and editable text fields and other controls that are used to answer questions and enter information.

  • The navigation area contains buttons that help the user move through the interview, such as left and right arrow buttons, which lead to the previous or next panel, and a Go Back button that takes the user back to the context from which the assistant was opened. A number between the left and right arrow buttons indicates how many panels the user has been through (see Figure 1).


To demonstrate how to add an assistant to your application, the rest of this article describes how we designed and implemented an assistant for Internet Config, a popular shareware utility program.

With Internet Config, the user can create a single file that stores preferences and settings for all Internet services. As long as an e-mail program, Web browser, or other Internet application uses the Internet Config preferences file, the user doesn't have to reenter Internet preferences for each program.

Internet Config's central location for user interaction is the window shown in Figure 2. Clicking each button in the main window brings up a window in which the user enters information and sets preferences.

Figure 2. Internet Config's main window

Internet Config enables users to store a broad range of preferences, from e-mail addresses to file conversion formats. Most users never need to set many of these preferences, but the dedicated Internet habitue probably finds them all useful. Internet Config risks being overwhelming for the sake of completeness -- a perfect opportunity for an assistant. Our assistant makes Internet Config easier to use by helping the user create a preferences file that stores only the preferences that are most commonly set.


In designing an assistant, you need to determine what most of your users will want to do. In the case of Internet Config, recent market studies show that most people use the Internet for e-mail, browsing, and downloading files. Given that information, the Internet Config assistant's functionality should be limited to setting preferences in those areas. The power-surfer minority that wants, for example, to change the default text editor can still do so directly through Internet Config's interface.

Assistants should be made available from wherever they make sense. For the Internet Setup Assistant, it would be helpful to add an Assist Me button to the main Internet Config window and an Internet Setup Assistant command to the Help menu. Application programs that use Internet Config could have a similar button in logical places in their user interfaces. In addition, the Internet Setup Assistant could be automatically displayed the first time the user launches Internet Config.


  • Our interview will elicit the information we need in order to store a simplified set of preferences for the user. As shown in Figure 3, the interview begins with an introduction that tells the user in plain language the type of questions that will be asked and describes what the assistant will do (or not do) based on the user's answers.

Figure 3. The Internet Setup Assistant introduction

The next panel, titled "Personal Information," was shown earlier in Figure 1. This panel poses two questions that are easy to answer: it asks for the user's name (filling in a default supplied by the file sharing setup) and company or organization. This starts the interview off smoothly while still obtaining necessary information.

The remaining interview panels that ask questions are listed below (in the order they appear) and are shown in Figure 4. Note that for a few of the questions, the assistant provides some information because the questions might be too difficult for some users to answer. The goal is to keep the interview self-contained, so that the user doesn't need to go to Apple Guide or a manual to figure out what to do.

Figure 4. Internet Setup Assistant interview questions

  • Geographic Location -- This panel asks a question that doesn't directly relate to what the assistant does for the user. Many users might be confused if asked to select an FTP server; instead, the interview asks for the user's location and then the assistant uses the answer to make a reasonable guess as to what the user's default FTP servers are.

  • E-mail Address and Password -- The password appears as bullets when typed and is encrypted.

  • E-mail Account and Host Computer

  • Signature -- This panel asks for a "signature" to be appended to the user's e-mail messages. A line of hyphens is supplied as the default.

  • World Wide Web Home Page -- In Internet Config, setting the Web home page preference takes place in the Other Services window, listed among less commonly used preferences such as the WAIS gateway and the Whois host. Many users might be stumped by these options and not find what they're looking for. Since we've determined that most users are interested in setting their Web site, the interview covers setting this preference. The default Web site entered is taken from the Web browser program.

  • Newsgroup Host Computer
When a user types an answer that's clearly wrong (such as an e-mail address that doesn't include the @ character), we recommend that you integrate the error trapping into the flow of the interview questions, rather than presenting an alert box. For example, when the user clicks the right arrow button and there are invalid values in the current panel, the next panel should point out the error and restate the question. The goal is to preserve the question-and-answer, conversational characteristics of the interview.

Finally, when the assistant has asked all the questions, it presents the conclusion panel (Figure 5). The user can see more details by clicking the Show Details button (which then changes to Hide Details); the assistant shows the information it will use in creating the Internet preferences file (name, organization, e-mail address, and so on), summarizing the user's interview responses.

Figure 5. The Internet Setup Assistant conclusion

That's it: ten questions in seven panels, plus an introduction and a conclusion.


You can use your favorite application framework to develop an assistant, or write it from scratch as a small application. On this issue's CD, we provide sample code for developing an assistant. We don't recommend using Apple Guide to conduct the interviews. Assistants and Apple Guide are different components of the help system; they should look related but still different from each other. Also, Apple Guide is a less-than-efficient tool for implementing assistant interviews. The programming techniques used in this example are specific to System 7 but will continue to work under Mac OS 8. As long as you avoid using undocumented features or directly accessing data structures that have an accessor routine, your code should work fine under Mac OS 8. In addition, if you insulate your code from specifics of the Macintosh Toolbox, it will be easier to add Mac OS 8 features later on. For some details about Mac OS 8 compatibility, see the article "Planning for Mac OS 8 Compatibility" in develop Issue 26.

Our assistant is based on a simple framework that provides a lightweight object-oriented coating on top of the Macinosh Toolbox. For example, we have classes that provide an object-oriented layer on top of Point (CPoint), Rect (CRect), WindowPtr (CWindow), DialogPtr (CDialog), and so on. We also have a simple application shell, TApplication. Those files are grouped in the framework folder.

The classes aren't dependent on each other, so you can use them easily in your existing application. You can create an assistant dialog by using an object of a TAssistant subclass and sending it the appropriate events. Your usual framework can still be used for handling your event loop and your application's windows. To implement the appearance of assistants using your own framework, check out the TAssistant class to see how we've done it.

The interview is presented in a dialog by a TAssistant object. The class TAssistant is a subclass of CMultiDialog, which allows you to have subdialogs that can be switched in and out as needed. You could use a similar technique to switch among multiple panels in a preferences dialog. Our implementation uses the ShortenDITL and AppendDITL routines, as shown in Listing 1. For another way to change panels, see the article "Multipane Dialogs" in develop Issue 23.

Listing 1. Changing panels in the assistant's interview
void CMultiDialog::SetSubDialog(SInt16 subDialogID)
   if (GetWindowRef() == NULL)
   if (GetSubDialog() != subDialogID) {
      // Save parameters in current panel.
      for (int i = 0; i < kDialogParametersCount; i++) {
         if (fParameters[i].dialogItem != 0)

      // Remove items from current dialog.
      if (fSubDialogID > 0)
                     CountDITL(GetDialogRef()) - fCommonItems);
      fSubDialogID = subDialogID;

         // Add new dialog items to the dialog.
         Handle items = GetResource('DITL', GetSubDialog());
         assert(items != NULL);
         AppendDITL(GetDialogRef(), items, overlayDITL);

      // Prepare the items in the dialog.

When dialogs are displayed in assistants, you often need to capture the information the user enters so that you can put it back if the user goes back to that panel. You need to be able to do this until the user clicks the Go Ahead button in the last panel. To simplify this task, we substitute a key string, which is stored in the DITL of the dialog, for a string that can change dynamically. The substitution is done each time the dialog is displayed. Listing 2 shows how to substitute parameters in the dialog by replacing any instance of a key that appears in a static or editable text dialog item with a corresponding value. In addition, if an editable text item contains only a key, the value entered in the dialog will be associated with the key. This is an extended version of the ^0 parameter substitution done by the Dialog Manager.

Listing 2. Substituting parameter values in dialogs
void CDialog::SubstituteParameters(void)
   LazyHandle   substitutionText, itemText;

   // Reset the association between parameters and dialog items.
   for (int i = 0; i < kDialogParametersCount; i++)
      fParameters[i].dialogItem = 0;

   // Loop through all dialog items.
   for (int item = 1, itemCount = CountDITL(GetDialogRef());
        item <= itemCount; item++) {
      SInt16 itemType = GetItemType(item);

      // If it's a static or editable text item...
      if (itemType == kEditTextDialogItem || 
          itemType == kStaticTextDialogItem) {
         Boolean itemTextChanged = false;
         // Copy the text to a handle.
         Str255 itemTextString;
         GetItemText(item, itemTextString);
         itemText.Set(&itemTextString[1], itemTextString[0]);
         // Loop through the parameters.
         for (int j = 0; j < kDialogParametersCount; j++) {
            // If the parameter is used as a nonempty key...
            if (fParameters[j].key[0] != 0) {
               if (itemType == kEditTextDialogItem &&
                   ::IdenticalString (itemTextString, 
                        fParameters[j].key, NULL) == 0) {
                  // If the edit field contains only the key,
                  // associate the item index with the parameter. The
                  // parameter value is updated when the text
                  // changes.
                  fParameters[j].dialogItem = item;
                  // Replace the key with the parameter value, using
                  // the Script Manager.
                  if (::ReplaceText(itemText, substitutionText,
                          fParameters[j].key) > 0)
                     itemTextChanged = true;
         if (itemTextChanged) {
            // The item text has changed. Put the modified text back
            // in the dialog item.
            Str255 s;
            s[0] = itemText.GetSize();
            BlockMoveData(*itemText, &s[1], s[0]);
            SetItemText(item, s);

When the assistant starts up, we try to capture as much information as possible about the user's environment. For example, we use Internet Config information that the user has previously entered.

When the user has entered all the information we ask for and clicked the Go Ahead button, we again use Internet Config, this time to set the user's preferences. The CInternetConfig class provides a C++ wrapper to the Internet Config API. See the details in the source code.


As you can see, the Internet Setup Assistant doesn't try to do everything for all users. Instead, it helps complete tasks in a way that a majority of users will find useful and valuable.

This sample assistant, though a relatively unambitious demonstration, should start you thinking about how to design and develop assistants for your own applications. Nothing is quite as powerful as simplicity.


    • "Implementing Shared Internet Preferences With Internet Config" by Quinn "The Eskimo!", develop Issue 23.

    • "Multipane Dialogs" by Norman Franke, develop Issue 23.

    • "Planning for Mac OS 8 Compatibility" by Steve Falkenburg, develop Issue 26.

    • Mac OS 8 Revealed by Tony Francis (Addison-Wesley, 1996), Chapter 13, "Assistance Services."

JOSE ARCELLANA ( is a human interface designer working on Mac OS 8 assistants, Apple Guide, and related technologies. He lives a rich analog life with his wife, their four-year-old child, and a yellow Labrador retriever in an 86-year-old Craftsman bungalow in Oakland. The house has lots of books, four guitars, and no television.*

ARNO GOURDOL ( has been spotted on top of various San Francisco Bay Area chthonic protrusions with a merry group of Moof hikers in a futile attempt to cure his acrophobia. He has recently been engrossed by the Epic of Gilgamesh and would love to find someone with a good copy of the twelve tablets. In his spare time, Arno is the technical lead of the Mac OS 8 assistance and related technologies team.*

Thanks to our technical reviewers Deeje Cooley, Winston Hendrickson, Rick Mann, Jim Palmer, and Jim Rodden.*


Community Search:
MacTech Search:

Software Updates via MacUpdate

Nisus Writer Pro 2.1.2 - Multilingual wo...
Nisus Writer Pro is a powerful multilingual word processor, similar to its entry level products, but brings new features such as table of contents, indexing, bookmarks, widow and orphan control,... Read more
calibre 2.40.0 - Complete e-book library...
Calibre is a complete e-book library manager. Organize your collection, convert your books to multiple formats, and sync with all of your devices. Let Calibre be your multi-tasking digital librarian... Read more
Vivaldi - An advanced browser...
Vivaldi is a browser for our friends. In 1994, two programmers started working on a web browser. Our idea was to make a really fast browser, capable of running on limited hardware, keeping in mind... Read more
OmniPlan 3.0 - Robust project management...
With OmniPlan, you can create logical, manageable project plans with Gantt charts, schedules, summaries, milestones, and critical paths. Break down the tasks needed to make your project a success,... Read more
Yummy FTP 1.11 - FTP/SFTP/FTPS client fo...
Yummy FTP is an FTP + SFTP + FTPS file transfer client which focuses on speed, reliability and productivity. Whether you need to transfer a few files or a few thousand, schedule automatic backups, or... Read more
Tweetbot 2.1 - Popular Twitter client. (...
Tweetbot is a full-featured OS X Twitter client with a lot of personality. Whether it's the meticulously-crafted interface, sounds and animation, or features like multiple timelines and column views... Read more
MacPilot 8.0 - Enable over 1,200 hidden...
MacPilot gives you the power of UNIX and the simplicity of Macintosh, which means a phenomenal amount of untapped power in your hands! Use MacPilot to unlock over 1,200 features, and access them all... Read more
Typinator 6.7 - Speedy and reliable text...
Typinator turbo-charges your typing productivity. Type a little. Typinator does the rest. We've all faced projects that require repetitive typing tasks. With Typinator, you can store commonly used... Read more
Adobe Lightroom 6.2 - Import, develop, a...
Adobe Lightroom is available as part of Adobe Creative Cloud for as little as $9.99/month bundled with Photoshop CC as part of the photography package. Lightroom 6 is also available for purchase as a... Read more
ForeverSave 2.1.4 - Universal auto-save...
ForeverSave auto-saves all documents you're working on while simultaneously doing backup versioning in the background. Lost data can be quickly restored at any time. Losing data, caused by... Read more

Super Sharp (Games)
Super Sharp 1.1 Device: iOS Universal Category: Games Price: $1.99, Version: 1.1 (iTunes) Description: Your finger has never been so sharp! Cut with skill to complete the 120 ingenious physics levels of Super Sharp and become a cut... | Read more »
Assembly - Graphic design for everyone...
Assembly - Graphic design for everyone 1.0 Device: iOS Universal Category: Photography Price: $2.99, Version: 1.0 (iTunes) Description: Assembly is the easiest most powerful design tool on the App Store. Create anything you can... | Read more »
YAMGUN (Games)
YAMGUN 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: The invasion has begun! Protect the walls of the citadel against waves of enemies! But watch out, you will soon run out of ammo...... | Read more »
Royal Bounty HD (Games)
Royal Bounty HD 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: New World Computing Approved "Hi Guys! looks good so far! keep up the good work. I worked on HoMM 3 and 4 creating all of the... | Read more »
Swords & Crossbones: An Epic Pirate...
Swords & Crossbones: An Epic Pirate Story 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: | Read more »
Camel Up (Games)
Camel Up 1.0.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0.0 (iTunes) Description: | Read more »
The Martian: Bring Him Home (Games)
The Martian: Bring Him Home 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: Based on the best selling novel and critically acclaimed film, THE MARTIAN tells the story of Astronaut Mark... | Read more »
This Week at 148Apps: September 21-30, 2...
Leap Into Fall With 148Apps How do you know what apps are worth your time and money? Just look to the review team at 148Apps. We sort through the chaos and find the apps you're looking for. The ones we love become Editor’s Choice, standing out above... | Read more »
Tweetbot 4 for Twitter (Social Networki...
Tweetbot 4 for Twitter 4.0 Device: iOS Universal Category: Social Networking Price: $4.99, Version: 4.0 (iTunes) Description: *** 50% off for a limited time. *** | Read more »
Mori (Games)
Mori 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: Stop, rewind and unwind with Mori. Time is always running, take a moment to take control. Mori is an action puzzle game about infinitely... | Read more »

Price Scanner via

Save up to $350 with Apple refurbished iMacs
Apple has Certified Refurbished iMacs available for up to $350 off the cost of new models. Apple’s one-year warranty is standard, and shipping is free: - 27″ 3.5GHz 5K iMac – $1949 $350 off MSRP - 27... Read more
Mac Pros on sale for up to $300 off MSRP
B&H Photo has Mac Pros on sale for up to $300 off MSRP. Shipping is free, and B&H charges sales tax in NY only: - 3.7GHz 4-core Mac Pro: $2818.99, $181 off MSRP - 3.5GHz 6-core Mac Pro: $3699... Read more
5K iMacs on sale for up to $150 off MSRP, fre...
B&H Photo has the 27″ 3.3GHz 5K iMac on sale for $1899.99 including free shipping plus NY tax only. Their price is $100 off MSRP. They have the 27″ 3.5GHz 5K iMac on sale for $2149, $150 off MSRP... Read more
Twelve South Redesigns BookArc For Today’s Sm...
Twelve South has announced a redesigned version of their very first product, BookArc for MacBook. Tailored specifically for the newest generation of MacBooks, BookArc holds the new, smaller Apple... Read more
Phone 6s Tips & Tricks – Tips Book For iP...
Poole, United Kingdom based Tap Guides Ltd. has announced the release and immediate availability of iPhone 6s Tips & Tricks, an in-depth eBook available in the iBookstore that’s priced just $2.99... Read more
13-inch 2.5GHz MacBook Pro on sale for $994,...
Best Buy has the 13″ 2.5GHz MacBook Pro available for $994.99 on their online store. Choose free shipping or free instant local store pickup (if available). Their price is $105 off MSRP. Price valid... Read more
Is The iPad Pro Really A Serious Laptop Repla...
Probably not, at least for productive professionals and other power users. Steve Jobs declared that we’d entered the “post-PC Era” with the advent of the original iPad in 2010, a phrase we don’t hear... Read more
Wednesday Deal: 13-inch Retina MacBook Pros f...
Adorama has 13″ Retina MacBook Pros on sale for up to $130 off MSRP. Shipping is free, and Adorama charges sales tax for NY & NJ residents only: - 13″ 2.7GHz/128GB Retina MacBook Pro: $1199.99 $... Read more
uBar 3.0 for Mac OS X – Custom Dock Replaceme...
Brawer Software has announced the release of uBar 3.0, an important update to their popular app and window manager for Mac OS X. uBar allows users to position it whichever side of the screen they... Read more
13-inch 2.5GHz MacBook Pro (refurbished) avai...
Apple has Certified Refurbished 13″ 2.5GHz MacBook Pros available for $829, or $270 off the cost of new models. Apple’s one-year warranty is standard, and shipping is free: - 13″ 2.5GHz MacBook Pros... Read more

Jobs Board

*Apple* Retail Online, Customer Experience R...
**Job Summary** Apple Retail's Online Store sells Apple products to customers around the world. In addition to selling Apple products with unique services such Read more
Frameworks Engineer, *Apple* Watch - Apple...
**Job Summary** Join the team that is shaping the future of software development for Apple Watch! As a software engineer on the Apple Watch Frameworks team you will Read more
Senior Manager, Global Direct Marketing *App...
**Job Summary** Apple Retail is looking for an experienced Direct Marketing Leader to join its Marketing team. This position will take a leadership role in creating Read more
*Apple* Online Store Expansion - Apple (Unit...
**Job Summary** The Online Apple Store is seeking a person to lead its expansion into new countries. Based in Cupertino, CA, this person will develop and maintain an Read more
*Apple* Retail - Multiple Customer Support P...
Job Description:Customer SupportSpecialist - Retail Customer Service and SalesTransform Apple Store visitors into loyal Apple customers. When customers enter the Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.