OS X Technology Usage Guidelines
OS X provides a wealth of highly developed technologies that users appreciate. Taking advantage of these fully integrated technologies enhances the way your app interacts with the system and with other apps on the platform.
Mission Control gives users an easy way to see all their desktops and full-screen windows, in addition to Dashboard and the Dock, at one time. In Mission Control, users can create a new desktop, switch between desktops and full-screen windows, or choose a specific window on the current desktop.
In System Preferences, users can set how they want to enter Mission Control, such as with a couple of keystrokes, a gesture, a hot corner, or all three.
Apps don’t influence the way Mission Control displays the user’s desktops and full-screen windows, but apps need to ensure that users can enter Mission Control whenever they want.
Respect the “enter Mission Control” gesture. No matter which gesture users choose for this action, you need to ensure that it works all the time, regardless of what your app is doing.
The Dock provides a convenient place for users to keep the apps they use most often. In addition, users can use the Dock to store webpage bookmarks, documents, folders, and stacks (which are collections of documents or other content). Users expect the Dock to be always available and to behave according to their preferences.
If appropriate, customize your app’s Dock menu. Users can click and hold (or Control-click) an app’s Dock icon to reveal the Dock menu. A Dock menu can contain app commands such as Open, Quit, and Hide, in addition to high-level options such as Show in Finder, Open at Login, and Assign to this Desktop. When your app is running, users can see a customized version of the Dock menu that can contain items such as:
Commands that initiate actions in your app when it is not frontmost, such as New Window
Commands that are applicable when there is no open document window, such as New Document
Status and informational text
For example, the customized Mail Dock menu includes the Get New Mail and Compose New Message commands.
To learn how to customize your Dock menu in code, see Dock Tile Programming Guide.
Take Dock position into account when you create new windows or resize existing windows. If window boundaries are behind the Dock, or too near the edge of the screen that hides the Dock, users have difficulty dragging or resizing the window without inadvertently interacting with the Dock. In particular, you should not create new windows that overlap the boundaries of the Dock. Similarly, you should prevent users from moving or resizing windows so that they are behind the Dock.
Respond appropriately when the user clicks your Dock icon. Generally, a window should become active when the user clicks on an app’s Dock icon. The precise behavior depends on whether the app is currently running and on whether the user has minimized any windows.
If the app is not running, a new window should open. In a document-based app, a new untitled window should open. In an app that is not document-based, the main app window should open.
If the app is running when the user clicks its Dock icon, the app becomes active and all open unminimized windows are brought to the front; minimized document windows remain in the Dock. If there are no unminimized windows, the last minimized window should be expanded and made active. If no windows are open, the app should open a new window—a new untitled window for document-based apps, otherwise the main app window.
Use badging to give users noncritical status information in an unobtrusive way. A badge is a small red oval that appears over the upper-right corner of an app’s Dock icon. For example, Calendar displays the number of new events in a badge; when there are no new events, the badge disappears (it doesn’t display 0).
Use bouncing to notify users of serious information that requires their attention. A bouncing Dock icon is very noticeable, so you should use this method only when the user really needs to know about something. Also, make sure you disable bouncing as soon as the user has addressed the problem.
The Finder gives users access to the file system. Although it’s best to minimize users’ interaction with the Finder while they’re in your app, you need to make sure your app integrates well with it.
Make sure your app bundle has the correct extension. The Finder looks for the
.app extension and treats your app appropriately when it finds it. The Finder also shows or hides this extension, depending on the state of the "Show all filename extensions" preference in the Advanced pane of Finder preferences.
Use an information property list to supply information to the Finder. The information property list (that is, an
Info.plist file) is the standard place to store information about your app and document types. For information on what to put in this file, see Runtime Configuration Guidelines.
Add the appropriate filename extension to documents users can create in your app. Accurate extensions help ensure platform interoperability. You can also set a file type and optionally a creator type for a file, although this is not strictly necessary. For more information about filename extensions, file types, and creator types, see File System Overview.
Avoid changing the creator type of existing documents. The creator type implies a distinct sense of ownership over a file. Your app can assign a creator type for files it creates, but it should not change creator types for documents that are created by other apps unless the user gives explicit consent. Note that the user can still associate files with a specific app by using the Info window.
Include a Quick Look generator if your app creates documents in an uncommon or custom format. A Quick Look generator converts an uncommon format into a format that the Finder can display in Cover Flow view and in a Quick Look preview. Specifically, if your app produces documents in content types other than HTML, RTF, plain text, TIFF, PNG, JPEG, PDF, and QuickTime movies, it’s a good idea to provide a Quick Look generator so that users can view your documents they way they expect. To learn how to create a Quick Look generator, see Quick Look Programming Guide.
If necessary, report disk size or usage information appropriately. If your app needs to display this type of information, it’s important to provide values that are consistent with values reported by the Finder and other system apps, such as Activity Monitor. Otherwise, users can become confused if your app and the system report different values for the same quantity.
To ensure consistent values, be sure to calculate all disk size statistics using GB, not GiB. A GB is defined as 1,000,000,000 bytes, whereas a GiB is defined as 1,073,741,824 bytes (which is the value of 230).
Dashboard gives users a way to get information and perform simple tasks quickly and easily. Appearing and disappearing with a single keystroke or gesture, Dashboard presents a default or user-defined set of widgets in a format reminiscent of a heads-up display, as shown below.
Each Dashboard component, called a widget, is small, visually appealing, and narrowly focused on the task it enables. You can develop a standalone widget that performs a lightweight task or a widget whose task is actually performed by your larger, more functional app. In-depth instructions for how to implement a Dashboard widget, including plentiful code examples and UI guidance, are available in Dashboard Programming Topics.
Gatekeeper helps protect users from malware. In OS X v10.8, users can choose between three settings. Users can set Gatekeeper to download and install:
Only apps from the Mac App Store
Apps from the Mac App Store and apps signed with a Developer ID (this is the default setting)
With the default setting, if an app is unsigned, Gatekeeper blocks the app from installing and warns users that the app did not come from an identified developer. Users can choose to override Gatekeeper or change the settings.
To ensure the best possible experience for your users, you should:
Vend your app from the Mac App Store. By offering your app in the Mac App Store, users automatically know that your app has been reviewed by Apple and has not been tampered with.
Sign your app with a valid Developer ID. If you choose to distribute your app outside of the Mac App Store, sign your app with a Developer ID. This identifies you as an Apple developer and ensures that your app launches on Macs with Gatekeeper enabled. See “Distributing Outside the Mac App Store” for more information.
iCloud storage helps people access the content they care about regardless of which device they’re currently using. When you support iCloud storage in your app, users can use different instances of your app on different devices to view and edit their content without performing explicit synchronization. To enable this user experience, it’s likely that you’ll need to reexamine the ways in which you store, access, and present information (especially user-created content) in your app.
All iCloud-enabled document-based apps have a modified open dialog, as shown below with TextEdit. New documents are stored in iCloud by default, but users can choose to store a document on their computer only. You can’t change the behavior or appearance of the dialog.
A fundamental aspect of the iCloud storage user experience is transparency: Ideally, users don’t need to know where their content is located, and they should seldom have to think about which version of the content they’re currently viewing. The following guidelines can help you provide this user experience in your app.
Respect the user’s iCloud account. It’s important to remember that iCloud storage is a finite resource that users pay for. You should use iCloud storage to store information that users create, and avoid using it to store app resources or content that you can regenerate.
Determine which types of information to store in iCloud storage. In addition to storing documents and other user content, you can also store small amounts of key-value data in iCloud storage. For example, if users choose to sync iCloud Contacts, Mail stores their VIPs and Previous Recipients lists. These preferences are available to them on all Mac computers with OS X v10.8 installed.
If you store preferences in iCloud key-value storage, be sure that the preferences are ones that users are likely to want to have applied to all their devices. For example, Mail doesn’t sync users’ Downloads folder because it probably contains large files and users can still access these files through Mail on their other computers as needed. Additionally, it may makes sense for your app to keep track of which files are open, but not the exact window positions of those files. Note that in some cases, it can make sense to store preferences on your app’s server, instead of in the user’s iCloud account, so that the preferences are available regardless of whether iCloud is available.
Make sure that your app behaves reasonably when iCloud storage is unavailable. For example, if users sign out of their iCloud account or aren’t connected to the Internet, iCloud storage becomes unavailable. For document-based apps, the Open dialog shows that a document is Waiting if there are unsaved changes that haven’t yet been stored in iCloud. Your app doesn’t need to inform users that iCloud storage is unavailable. For non-document-based apps, it can be appropriate to show users that the changes they make won’t be visible on other devices until they restore access to iCloud storage.
If appropriate, make it easy for users to enable iCloud storage for your app. On their Mac computers, users sign in to their iCloud account in iCloud Settings, and for the most part, they expect their apps to work with iCloud storage automatically. If you think users might want to choose whether to use iCloud storage with your app, you can provide an option that they set when your app opens. In most cases, a simple choice between using iCloud Storage or not for all user content should be sufficient.
Allow users to choose which documents to store in iCloud. When users have iCloud enabled, their documents are stored in iCloud by default. However, because iCloud storage is finite, users may choose to store content in iCloud on a file-by-file basis. To provide the appropriate user experience, users should be able to save a document on their Mac only, but iCloud should still be the default location.
Warn users about the consequences of deleting a document. When a user deletes a document in an app that uses iCloud storage, the document is removed from the user’s iCloud account and all other devices. It’s appropriate to display an alert that describes this result and to get confirmation before you perform the deletion.
Tell users about conflicts as soon as possible, but only when necessary. For document-based apps, OS X handles conflict resolution for you; you don’t need to do additional work to warn users about conflicts. For other apps, first determine if you can use iCloud storage APIs to resolve the conflict without involving the user. When this isn’t possible, make sure that you detect conflicts as soon as possible so that you can help users avoid wasting time on the wrong version of their content. You need to design an unobtrusive way to show users that a conflict exists; then, make it easy for users to distinguish between versions and make a decision.
Be sure to include the user’s iCloud content in searches. Users with iCloud accounts tend to think of their content as being universally available, and they expect search results to reflect this perception. If your app helps people to search their content, make sure you use the appropriate APIs to extend search to their iCloud accounts. See “Searching iCloud and the Desktop” to learn more.
Notification Center gives users a single, convenient place in which to view notifications from their apps. Users appreciate the unobtrusive interface of Notification Center, and they value the ability to customize the way each app can present its notifications.
Notification Center uses a sectioned list to display recent notification items from the apps that users are interested in.
Mac apps can use local or push notifications to let people know when interesting things happen, such as:
A message has arrived.
An event is about to occur.
New data is available for download.
The status of something has changed.
A local notification is scheduled by an app and delivered by OS X on the same device, regardless of whether the app is currently running in the foreground. For example, a calendar or to-do app can schedule a local notification to alert people of an upcoming meeting or due date.
A push notification is sent by an app’s remote server to the Apple Push Notification Service, which pushes the notification to all devices that have the app installed. For example, a game that a user can play against remote opponents can update all players with the latest move.
You can still receive local and push notifications when your app is running in the foreground, but you pass the information to your users in an app-specific way.
Mac apps that support local or push notifications can participate in Notification Center in various ways, depending on the user’s preferences. To ensure that users can customize their notification experience, you should support as many as possible of the following notification styles:
A banner is a small view that appears in the upper-right corner and then disappears after a few seconds. In addition to displaying your notification message, OS X displays the small version of your app icon in a banner, so that people can see at a glance which app is notifying them (to learn more about app icons, see “About App Icon Genres and Families”).
An alert is a standard alert view that appears onscreen and requires user interaction to dismiss. An alert contains the alert message, informative text, action buttons, and your app icon. You have no control over the background appearance of the alert or the buttons. See “Alerts” for more information about using alerts.
A badge is a small red oval that displays the number of pending notification items (a badge appears over the upper‐right corner of an app’s icon in the Dock, similar to the unread messages badge in Mail shown here).
A badge contains only numbers, not letters or punctuation. You have no control over the size or color of a badge.
A custom or system-provided sound can accompany any of the other three notification delivery styles.
As you design the content that your notifications can deliver, be sure to observe the following guidelines.
Respect users’ Notification Center preferences. In System Preferences, users can choose their preferred notification style for your app from the available formats. If your app uses all styles, users can choose whether to receive notifications as alerts, banners, or neither. They can choose whether to show badges and play sounds for your app. Additionally, users can choose to turn off all notifications. Respect users’ notification preferences to ensure that your app provides information unobtrusively.
Don’t use Notification Center to display error messages. Although users can launch your app from Notification Center, notifications don't provide a way for users to resolve a problem. If you need to display an error message or a message requiring some action, use an application-driven alert dialog. For example, if users need to be connected to the Internet in order to complete a task, you could inform users through an alert dialog with an action button labeled Turn WiFi On.
Keep badge contents up to date. It’s especially important to update a badge as soon as users have attended to the new information, so that they don’t think additional notifications have arrived. Note that setting the badge contents to zero also removes the related notification items from Notification Center.
Don’t use a badge to indicate information other than a pending notification. Users can choose to turn off badges for your app. If your app uses a badge to provide critical information, these users will miss out.
Don’t try to copy the appearance of a badge. If you mimic the appearance of a badge, users who have turned off badges may be frustrated that they appear to be receiving badge notifications anyway.
Don’t send multiple notifications for the same event. Users can attend to notification items when they choose; the items don’t disappear until users handle them in some way. If you send multiple notifications for the same event, you fill up the Notification Center list and users are likely to turn off notifications from your app.
Choose an appropriate default style for your notifications. Use an alert when you need to deliver information that users need to know about right now. Because banners disappear after a few seconds, don't use banners for information that is critical for users to see. And because alerts interrupt the user’s workflow, it’s best to use them only when users would rather be interrupted than miss your notification. If users become annoyed with alerts, they may turn off notifications for your app.
Provide a custom message that does not include your app name. Your custom message is displayed in alerts and banners, and in Notification Center list items. You should not include your app’s name in your custom message, because OS X automatically displays the name with your message.
To be useful, a local or push notification message should:
Not rely on alert buttons for users to understand the notification message. Because users can decide whether to receive your app’s notifications as banners or alerts, make sure your message is clear in either style.
Focus on the information, not on user actions. Avoid telling people which alert button to click or how to open your app.
Be short enough to display in one or two lines. Long messages are difficult for users to read quickly, and they can force alerts to scroll.
Use sentence-style capitalization and appropriate ending punctuation. When possible, use a complete sentence.
Label alert buttons with actions that clearly describe what the buttons do. Provide custom titles for buttons in a notification alert if you provide custom behavior. For example, Reminders uses Snooze to allow you to repeat the alert at a later time. Remember that OS X may truncate the label to fit.
Provide a sound that users can choose to hear when a notification arrives. A sound can get people’s attention when they’re not looking at the device screen. Users might want to enable sounds when they’re expecting a notification that they consider important. For example, a calendar app might play a sound with an alert that reminds people about an imminent event. Or a collaborative task management app might play a sound with a badge update to signal that a remote colleague has completed an assignment.
You can supply a custom sound, or you can use a built-in alert sound. If you create a custom sound, be sure it is short, distinctive, and professionally produced.
Sharing allows users to share content directly from your app. The Share menu automatically includes some built-in services like AirDrop and Mail, but it only displays the services that make sense to share with that specific service. For example, Flickr (a photo-sharing service) appears in the Share menu only if you are viewing a photo. You can also customize the menu to allow users to share to other services. In Safari, users can add a webpage to their reading list, bookmark it, or share it via Mail, Message, or Twitter, as shown here.
As you implement and customize the Share menu in your app, consider the following guidelines.
In general, use the Share button for content users want to share with other people. When deciding whether to add a Share button in your app, consider whether users want to share their content with other people. This includes sending content directly via AirDrop, Mail, and Message, or posting it to a social sharing service such as Facebook, YouTube, or Flickr.
In particular, don't use the Share menu to edit content or to pass content between apps. For example, QuickTime Player uses a separate Export menu to send files to iTunes and iMovie or to reformat a file. Use an Action Menu for other actions that users may want to perform with their content, such as Duplicate, Move to Trash, or Get Info. The Share menu should not replace the Action menu. See “Action Menu” for more information.
Add a Share item to the File menu. Users should be able to share their content from the File menu as well as with the Share button. Make sure to provide the same menu items in both places. It’s also best to use the same wording so that users readily recognize the available options.
List built-in OS X services first in the Share menu. If you add other services to the Share menu, make sure to list them after OS X apps (such as Mail, Message, and AirDrop). This order ensures a consistent user experience across all apps.
Use a verb to label actions in the share menu (and a verb phrase for the first action). For example, you might label your actions: Email this Page (not Mail), followed by Message, AirDrop, and so forth.
Use title-style capitalization to label services. As with all menu-item names, use title-style capitalization for the service title and, in general, avoid including definite or indefinite articles. (For more information about capitalization in the UI, see “Capitalizing Labels and Text.”)
With Sharing Service on OS X, you can also integrate features of a specific social networking service directly into your app. For example, users can view the Facebook profile and photos of their contacts from a menu item in the Contacts app (as shown here). You can also generate HTTP requests to get and push content from available social services. Users appreciate when they can share content they care about and can view relevant social information from within your app.
Use the AppKit and Social frameworks to make sharing easier for your users. See the Social Framework Reference for more information.
Game Center allows user to track scores on a leaderboard, compare in-game achievements, invite friends to play a game, and start a multiplayer game through automatic matching.
Game Center functionality is provided in two parts:
The Game Center app, where users sign in to their account, discover new games, add new friends, and browse leaderboards and achievements
Game Center features that your app provides, such as multiplayer or turn-based games, in-game voice chat, and leaderboards
In your game, use the Game Kit APIs to post scores and achievements to the Game Center service and to display leaderboards in your user interface. You can also use Game Kit APIs to help users find others to play with in a multiplayer game. Note that to support Game Center in your Mac app, you must sign the app with a provisioning profile that enables Game Center. To learn more about adding Game Center support to your app, see Game Center Programming Guide.
For most games, it’s best to use the standard Game Center UI. Although it may make sense for some games with a distinct aesthetic to customize the Game Center user interface, in general, it’s appropriate to use the standard UI. This creates a consistent experience for users, because they recognize the look of Game Center features. Creating a custom Game Center UI to match your game’s aesthetic is not necessarily a better experience for users.
Use a consistent user interface for all versions of your game. If you have an iOS version of your game, make sure that achievements and any other custom Game Center features have a similar appearance for all versions.
Keep in mind that your Mac app should still be designed specifically for the platform and should not be simply a copy of your iOS app. For example, your app icon, which appears in Game Center, should not be the same rounded rectangle icon from iOS. For more information about designing a great app icon, see “Icon Design Guidelines.”
Don’t add custom UI to prompt users to sign in to Game Center. When users first launch your Game Center–enabled app, they’re prompted to log in to Game Center, if they aren’t already logged in. Game Center takes care of presenting UI to the users and authenticating their account for you (you should not write your own code to do this).
Allow users to turn off voice chat. It’s a good idea to disable voice chat by default so that users aren’t overheard without their knowledge. When users turn on voice chat, make sure there’s an obvious way for them to turn it off.
Indicate when voice chat is on. When a player’s microphone is turned on, a game should make this clear to the user.
In-App Purchase allows users to purchase digital products within your app. For example, users could:
Upgrade a basic version of an app to include premium features
Renew a subscription for new monthly content
Purchase virtual property, such as a new weapon in a fighting game
Buy and download new books
With In-App Purchase, users can complete transactions in only a few clicks because their payment information is tracked and stored by the App Store. Your app can implement In-App Purchase to take advantage of the App Store’s searcher payment processing. Use the Store Kit framework to embed a store directly in your app.
Store Kit prompts users to authorize a purchase and then notifies your app so that you can provide the purchased items to the users. Store Kit does not provide functionality for presenting your store to the users, you must design this yourself. Note that all products you sell via In-App Purchase must be registered in the App Store. See the In-App Purchase Programming Guide for more information.
As you design the purchasing experience, follow these guidelines.
Elegantly integrate the purchasing interface with your app. When presenting products for users to purchase and handling their transactions, create a seamless experience for your users. When you make In-App Purchase a thoughtfully designed aspect of your app, and not a clumsy addition, you may entice users to purchase more.
Don’t alter the default confirmation dialog. When users choose a product to purchase, Store Kit presents a confirmation dialog that helps them avoid accidental purchases.
Calendar helps people manage their schedules and create and respond to events. You can integrate Calendar information into your app so that users don’t need to look up or reenter information. With the Event Kit framework, you can access users’ events and create, edit, or delete new events. See Calendar and Reminders Programming Guide for more information.
Don’t modify a user’s Calendar data without permission. Before creating, editing, or deleting a user’s event, make sure you get permission from the user. Additionally, when you perform operations on a group of events that result in significant changes to the user’s Calendar, make sure the user is fully informed of the action your app is about to perform.
Using Reminders, people keep track of tasks, to-do items, and events. Users specify the time and location of a reminder, set an alarm, and mark it completed when it’s finished. Using the Event Kit framework, you can access users’ reminders, and create, edit, or delete new reminders. Reminders and Calendars use the same framework and access the same Calendar database. See Calendar and Reminders Programming Guide for more information.
Don’t modify a user’s Reminder data without permission. Before creating, editing, or deleting a user’s reminder, make sure you get permission from the user. Additionally, when you perform operations on a group of reminders that result in significant changes to the user’s data, make sure the user is fully informed of the action your app is about to perform.
Contacts helps users keep track of their contacts, storing information such as names, phone numbers, fax numbers, and email addresses. Users appreciate apps that access this information automatically so that they don’t have to look it up or reenter it more than necessary.
When you use the Address Book framework, you can access contact information from the user’s database or display it in a customizable window within your app. You can also customize the user’s Contacts experience by supplying a plug-in that performs an action when users Control-click a labeled item, such as a name or phone number.
One way to customize a contact-information window is to display only the data relevant to your app. For example, Mail customizes this window to focus on the email addresses of the contacts, as shown below.
The following guidelines help you provide a good user experience as you integrate Contacts information in your app and develop action plug-ins.
Don’t use developer terms in your UI. In particular, don’t use the terms people picker or picker. Although the Address Book framework uses these terms, they are not suitable user terms. Additionally, you should name a custom contact-information window in a way that describes its contents as they relate to your app, such as Addresses or Contacts. (To learn about additional terms that you should avoid in your UI, see “Use User-Centric Terminology.”)
Limit to a single window new UI that’s displayed by an action plug-in. For example, the Large Type action uses a very large font to display the selected phone number in a single window. If you develop an action that needs to do more than display information in a single window, it should launch a separate app.
Don’t add UI to the Contacts app itself. In particular, there is no reason to add a pane to Contacts preferences. Instead, use the Contacts programming interfaces to make sure that your action plug-in name appears in the contextual menu users see when they Control-click an item.
To learn more about working with the Address Book framework, see Address Book Programming Guide for Mac.
OS X integrates many accessibility features that help people with disabilities or special needs customize their Mac experience.
As you incorporate accessibility into your app, keep the following guidelines in mind.
Focus first on ease of use. An easy-to-use app provides the best experience for all users. To make sure that users who use assistive technologies (such as VoiceOver or a braille display) can benefit fully from your app, you might need to supply some descriptive information about the UI. To learn about the programmatic steps you need to take to supply accessibility information, see Accessibility Overview for OS X.
Don’t override the built-in OS X accessibility features. Users expect to be able to use accessibility features, such as the ability to perform all UI functions using the keyboard, regardless of the app they’re currently using. Users can access these features in the Universal Access and Keyboard panes of System Preferences.
Avoid relying solely on one type of cue to convey important information in your app. For example, although the judicious use of color can enhance the UI, color coding should always be redundant to other types of cues, such as text, position, or highlighting. Allowing users to select from a variety of colors to convey information enables them to choose colors appropriate for their needs. Similarly, it’s best when sound cues are available visually as well. Because OS X allows users to specify a visual cue in addition to the standard audible system alert, be sure to use the standard system alert when you need to get the user’s attention.
Don’t override keyboard navigation settings. In addition, don’t override the keyboard shortcuts used by assistive technologies. When an assistive technology is enabled, keyboard shortcuts used by that technology take precedence over the ones defined in your app. To learn more about system-defined keyboard shortcuts, see “Keyboard Shortcuts.”
As early as possible in the design process, build in support for internationalization and localization so that as many people as possible can use your app. Internationalization and localization can take a significant amount of time to do well; follow the guidelines in this section to help streamline the process. To get more details about internationalization and localization, read Internationalization Programming Topics.
Plan to localize visible UI elements. That is, make sure the UI elements in your app can be translated into other languages and otherwise adapted for use in other countries. Note that when you use the Auto Layout, you can specify how text and other UI elements are related so that localizers don’t have to redesign your layout to accommodate different lengths of text. To learn more about the advantages of Auto Layout, see “Cocoa Auto Layout” in Mac Technology Overview.
In addition to translating text, be prepared to adjust your use of color, graphics, and representations of time and money. Examine your use of specific objects or symbols (such as electrical outlets and the currency symbol) as they may have a different appearance, or not be understood, in other countries.
Pay attention to the possible meanings of the graphics and symbols in your app. Make sure your graphics and symbols are unambiguous and inoffensive to all, or prepare to localize them. For example, if you use images of American holidays to represent seasons—such as Christmas trees, pumpkins, or fireworks—be sure to localize them for cultures that are not familiar with those holidays.
Be aware of the user’s locale preferences. In the Formats pane of Language & Text preferences, OS X allows users to customize the way dates, times, and number-based data (such as monetary values or measurements) are displayed. Most APIs take these preferences into account when getting or formatting this type of information, so you should not have to perform custom formatting or conversion tasks.
Support different address formats. Don’t assume that all of the user’s contacts have addresses that are in the same format as the user’s address. Contacts helps users keep track of contacts all over the world by supporting different regions and allowing customization of any format. If you support or display Contacts data, be prepared to handle different address formats and postal code information.
Make your text easy to translate. Translating text is a sophisticated, delicate task. Avoid using colloquial phrases or nonstandard usage and syntax that can be difficult to translate. Carefully choose words for menu commands, dialogs, and help text. Be aware that text in U.S. English can grow up to 50 percent longer when translated to other languages.
Use complete sentences in string resources whenever possible. Grammar problems may arise when you concatenate multiple strings to create sentences; the word order may become completely different in another language, rendering the message nonsensical when translated. For example, word order in German sometimes places the verb at the end of a sentence. For more information on handling text in other languages, see “Guidelines for Internationalization”.
As much as possible, identify the logical flow of content and use that to determine the layout of your UI. For example, the more important or higher level objects are usually placed near the upper left of a window that is designed for regions associated with left-to-right languages. In a version of the window that targets users who read right-to-left languages, it makes sense to reverse this layout. The more you can characterize user interface objects according to their logical, not visual, position, the more easily you can extend your app to other markets.
The Colors Window
OS X provides a standard panel for picking colors. The Colors window (shown below) lets users enter color data using any of five different color models.
If your app deals with color, you may need a way for the user to enter color information. Be sure to use the Colors window rather than create a custom interface for color selection. For information on how to use this window in your app, see Color Programming Topics.
The Fonts Window
OS X provides a standard panel for picking fonts. As shown below, the standard Fonts window also includes several controls for adjusting a font’s characteristics. (The minimal version of the Fonts window allows users to choose a font, typeface, and size.)
If your app supports typography and text layout using user-selectable fonts, you should use the Fonts window to obtain the user’s font selection rather than create a custom font-picker window.
The standard Fonts window also provides advanced typography controls for fonts that support those options. The user can open a Typography inspector by choosing Typography from the action menu (shown above). For example, the Typography inspector shows the typography controls for the Zapfino font.
Automator helps users automate common procedures and build workflows by arranging processes from different apps into a desired order. Familiar Apple apps, such as Mail, iPhoto, and Safari make their tasks available to users to organize into a workflow. These tasks (called actions) are simple and narrowly defined, such as opening a file or applying a filter, so a user can include them in different workflows.
As an app developer, you can define Automator actions that represent discrete tasks that your app can perform. You make an action available to users by creating an action plug-in, which contains a nib file and code that manages the action’s user interface and implements its behavior. You might consider creating a set of basic actions to ship with your app so that users have a starting point for using your app's tasks with Automator. For more information on developing Automator actions, see Automator Programming Guide.
As you design the UI of an action, keep the following guidelines in mind.
Minimize the height of an action. Users stack actions on top of each other in Automator. Because display screens are wider than they are tall, you should minimize an action’s use of vertical space. One way to do this is to use a pop-up menu instead of radio buttons, even if there are only two choices.
Don’t use group boxes. An action does not need to separate or group controls with a group box.
Avoid tab views. Instead, use hidden tab views to alternate between different sets of controls.
Avoid using labels to repeat the action’s title or description. Labels that repeat information available elsewhere take up space without providing value.
Conserve space by using the appropriate controls and layout. For example, you can use a disclosure triangle to hide and display optional settings. (For more information on disclosure triangles, see “Disclosure Triangle.”) Overall, you should use the small size of Aqua controls and 10-point margins to make the best use of space.
Provide feedback. Use the appropriate progress indicator when an action needs time to complete (for more information about different types of progress indicators, see “Progress Indicators”).
OS X includes an advanced printing system. Users appreciate the extensive printing options that are available and they expect to be able to access them regardless of the app they’re using. Fortunately, when you use the OS X printing system in your app, the printing features are easy to make available to users.
Use the standard printing dialog instead of creating a custom dialog. Because of all the options the OS X printing system provides, it is important to use the standard printing dialog with which users are familiar.
For information about the standard printing dialog, see “The Print and Page Setup Dialogs”; to learn how to extend the Print dialog to include additional options, see Extending Printing Dialogs. For general information about the printing system, see Printing Programming Guide for Mac.
Users appreciate the security of the OS X environment and they expect their apps to be equally secure. When you take advantage of OS X security technologies, you can store secret information locally, authorize a user for specific operations, or transport information securely across a network.
Keep the following guidelines in mind when your app needs to work with sensitive information or perform tasks in a secure environment.
Factor out code that requires privileged access into a separate process. Factoring isolates the secure code from the nonsecure code and makes it easier to verify that no rogue operations are occurring that could do damage, whether intentionally or unintentionally.
Avoid storing passwords and secrets in plain-text files. Even if you restrict access to the file using file permissions, sensitive information is much safer in a keychain.
Avoid inventing your own authentication schemes. If you want a client-server operation to be secure, use the authorization APIs to guarantee the identity of the client.
Be wary of the code you load or call from privileged code. For example, you should avoid loading plug-ins from privileged code, because plug-ins receive the same privileges as the parent process. You should also avoid calling potentially dangerous functions, such as
popen, from privileged code.
Avoid making inappropriate assumptions. For example, you should not assume that only one user is logged in. Because of fast user switching, multiple users may be active on the same system (for more information, see Multiple User Environment Programming Topics). Also, you should not assume that keychains are always stored as files.
When feasible, avoid relying solely on passwords for authentication. Be prepared to take advantage of other technologies, such as smart cards or biometric devices.
Use Keychain Services to store sensitive information, such as credit card numbers and passwords. The keychain mechanism in OS X provides the following benefits:
It provides a secure, predictable, consistent experience for users when dealing with their private information.
Users can modify settings for all of their passwords as a group or create separate keychains for different activities, with each keychain having its own activation settings. (By default, passwords are modified as a group.)
The Keychain Access app provides a simple UI for managing keychains and their settings, relieving you of this task.
To get started learning about security in OS X, see Security Overview.
Preferences are user-defined settings that your app remembers from session to session. Users expect to be able to customize the appearance and behavior of your app in preferences. For example, in Finder preferences, users can customize the contents of Finder windows and the behavior of File > New Finder Window, among other things.
Be picky about which app features should have preferences. Avoid implementing all the preferences you can think of. Instead, be decisive and focus your preferences on the features users might really want to modify.
Don’t provide preferences that affect systemwide settings. For example, if users want to change the size of sidebar icons or change the visibility of the running-app indicator in the Dock, they can do so in System Preferences. In particular, your app should not encourage users to change the way your app handles automatic saving of their content; this is a system feature that users expect to rely on in all the apps they use.
As much as possible, ensure that users rarely need to reset preferences. Ideally, preferences include settings that users might want to change only once. If there are settings users might want to change every time they open your app, or every time they perform a certain task, don’t put these settings in preferences. Instead, you could use a menu item or a control in a panel to gives user modeless access to these settings.
Don’t provide a preferences toolbar item. Because the toolbar should contain only frequently used items, it does not make sense to include a preferences item in it. Instead, make app-level preferences available in the app menu (for more information, see “The App Menu”); and make document-specific preferences available in the File menu (for more information, see “The File Menu”).
To learn more about implementing preferences using Cocoa, see Preferences and Settings Programming Guide. For information on implementing preferences using Core Foundation, see Preferences Programming Topics for Core Foundation.
Bonjour enables automatic discovery of computers, devices, and services on IP networks, and makes file and media sharing easy. If your app needs to communicate with other computers and processes on the Internet or a local area network, you should avoid making assumptions about the user’s network settings. In particular, you should not save settings based on the user’s IP address, because it might change many times during a single session.
Use Bonjour to support user mobility and free users from the app-management task of having to enter an IP address. For more information about Bonjour, see Bonjour Overview.
OS X services are features that apps can make available to each other. Using services, you can share your app’s resources and capabilities with other apps and, in turn, allow your users to take advantage of resources and capabilities that other apps provide.
By default, the app menu contains a Services submenu that lists services that are appropriate for the currently selected or targeted content in your app. This submenu automatically includes a command that opens Services preferences in Keyboard Shortcuts preferences. The services listed in the submenu can be provided by apps installed anywhere on the system. For example, the Services that are available when an image file is selected in a Finder window can include options for using it as the desktop picture and opening with a specific app.
To vend services to other apps, your app provides information about each service, such as:
The data types on which it operates
The command that can appear in the Services menu
The keyboard shortcut for invoking the command, if appropriate. Note that if the keyboard shortcut you choose conflicts with a keyboard shortcut used by the current “host” app, the host app’s shortcut is always used.
To learn the programmatic steps you need to take both to provide services and to take advantage of them, read Services Implementation Guide.
To ensure a good user experience, follow these guidelines when defining the services that your app can provide.
Give each service a short, focused title that describes exactly what it does. Strive to create a unique service title. If there are two or more services with identical names, the app name is automatically displayed after each service to distinguish them.
Use proper capitalization in your service title. As with all menu-item names, use title-style capitalization for the service title and, in general, avoid including definite or indefinite articles. Good examples are “Look Up in Dictionary” and “Make New Sticky Note.” (For more information about capitalization in the UI, see “Capitalizing Labels and Text.”)
Avoid providing an “Open in My App” service. Instead, users can view the apps that can open a selected file in the Open With menu item of the Finder.
Don’t use services for sharing user content. For sharing user content with other apps and social services, use a “Sharing Service.”
OS X provides speech technologies that allow software to recognize and speak U.S. English.
Speech recognition is the ability for the computer to recognize and respond to a person’s speech. OS X users can choose to control their computer by voice; consequently, speech-recognition technology is very important for both people with special needs and general users.
Using speech recognition, users can accomplish tasks comprising multiple steps—for example, “Schedule a meeting next Friday at 3 p.m. with John, Paul, and George” or “Create a 3-by-3 table”—with one spoken command. Developers can take advantage of the speech engine and API included with OS X, as well as the built-in user interface. (The system-provided speech feedback window is shown here.)
Speech synthesis, also called text-to-speech (TTS), converts text into audible speech. You might want to use speech synthesis to deliver information to users without forcing them to shift attention from their current task. For example, an app could, in the background, deliver messages such as “Your download is complete; one of the files has been corrupted” or “You have email from your boss; would you like to read it now?”
TTS is also crucial for users with vision or attention disabilities. As with speech recognition, OS X TTS provides both an API and several UI features.
For information about implementing speech synthesis and recognition, see Speech Synthesis Programming Guide and Speech Recognition Manager Reference.
Consider how you would want a text label in your app to adapt when users resize a window, adjust the font size, or switch to a different language. With Cocoa Auto Layout, you create user interface constraints to ensure that your app adjusts gracefully to changes. Constraints allow you to design elements of your user interface in relation to each other.
You specify constraints in Interface Builder with Xcode or create them programmatically using ASCII-art inspired format strings. See Auto Layout Guide for more information about how to design your app with Auto Layout.
Drag and Drop
Drag and drop is a fundamental direct-manipulation technology that makes it easy for users to interact with their content. Users expect to be able to drag any selectable item—such as a section of text, a file, an image, or an icon—and drop it in a new location.
In addition to handling users’ data without loss, supporting drag and drop is largely a matter of providing appropriate feedback. Specifically, users need to know:
Whether drag and drop is possible for an item (indicated by drag feedback)
What the results of a drag-and-drop operation will be (indicated by destination feedback)
Whether a drag-and-drop operation was successful (indicated by drop feedback)
The following guidelines help you provide a drag-and-drop experience that users appreciate.
As much as possible, provide alternative methods for accomplishing drag-and-drop tasks. For some users, especially those who use assistive technologies to interact with your app, drag and drop is difficult or impossible to perform. Except in cases where drag and drop is so intrinsic to an app that no suitable alternative methods exist—dragging icons in the Finder, for example—there should always be another method for accomplishing a drag-and-drop task.
Determine whether a drag-and-drop operation should result in a move or a copy. In general, if the source and destination are in the same container, such as the same window or volume, a drag-and-drop operation is interpreted as a move (that is, cut and paste). If the source and destination are in different containers, a drag-and-drop operation is interpreted as a copy (that is, copy and paste).
As much as possible, you should also consider the underlying data structure of the contents in the destination container. For example, if your app allows two windows to display the same document (multiple views of the same data), a drag-and-drop operation between these two windows should result in a move.
Check for the Option key at drop time. This behavior gives the user the flexibility of making the move-or-copy decision at a later point in the drag-and-drop sequence. Pressing the Option key during the drag-and-drop sequence should not “latch” for the remainder of the sequence.
Support single-gesture selection and dragging, when appropriate. Using a mouse or a trackpad, users can drag an item by selecting it and immediately beginning to drag, instead of by selecting the item, pausing, and then dragging. (The automatic selection of the item that can occur in this situation is called implicit selection.) Note that single-gesture selection and dragging is not possible when the user selects multiple items by dragging or by clicking individual items while holding the Command key, because multiple selection can't be implicit.
Allow users to drag a selection from an inactive window. Users expect to be able to drag items they selected previously into the currently active window. To support this action, your app should maintain the user’s selection when the containing window becomes inactive. A persistent selection in an inactive window is called a background selection and it has a different appearance from a selection in an active window.
In particular, support background selection for items that users must select by range, such as text or a group of icons. If you don’t support background selection for range-selected items, the user must reactivate the window and reselect the items before dragging them. Support for background selection is not required if the item the user wants to drag is discrete—for example, an icon or graphical object—because implicit selection can occur when a discrete item is dragged. Note that when an inactive window is made key, the appearance of a background selection changes to the appearance of a standard selection. To learn more about the different states a window can have, see “Main, Key, and Inactive Windows.”
Provide drag feedback as soon as users drag an item at least three points. Display a translucent image of the item at the beginning of the drag so that users can confirm the item that they’re dragging. After the user begins a drag, the item should stay draggable, and the drag image should stay visible, until the user drops the item. For example, as soon as the user begins to drag a PDF document, an image of the document appears to lift up under the pointer.
Display a drag image composed of multiple items, if appropriate. If the user selects multiple items to drag, you should display a drag image composed of images that represent each item. In addition, you should badge the aggregate drag image with the number of items being dragged so that users can confirm how many items they’re dragging. For example, dragging five files into a Mail message might look like this:
Change the drag image to show the dropped form of the item, if appropriate. If it helps users understand how your app can handle an item, you can change its drag image when it enters a destination region in your app. For example, when the user drags a picture file from the desktop into a TextEdit document, the picture expands to show how it will look after the user drops it in the document.
Although changing the drag image can provide valuable feedback, you want to avoid creating a distracting drag-and-drop experience in which drag images are constantly (and radically) changing form.
Use the appropriate pointer to indicate what will happen when the user drops an item. For example, when users drag an icon into a toolbar, the copy pointer appears to indicate that if they let go of it there, the item will be added to the toolbar. Other pointers that provide useful destination feedback include the alias, poof, and not allowed pointers. (For more information about system-provided pointers, see “Use the Right Pointer for the Job.”)
Update the badge of a multi-item drag when appropriate. If the destination can accept only a subset of a multi-item drag, change the number in the badge to indicate how many of the items will be accepted.
Highlight the destination region as soon as the pointer enters it and stop highlighting when the pointer leaves the region. If there are multiple destination regions within a window, highlight one destination region at a time.
Don’t highlight the destination region if the drag-and-drop operation takes place entirely within it. For example, moving a document icon to a different location in the same folder window does not highlight the folder window because this would be confusing to the user. Do highlight the destination region if the user drags an item completely out of the region and then drags the same item back into the same region again.
In text, use a vertical insertion indicator to show where the dragged item will be inserted. Note that an insertion indicator is separate from the pointer. The pointer indicates to users whether the drag is valid and whether it is interpreted as a copy.
In a list, use a horizontal insertion indicator to show where the item will be inserted. For example, when a user drags a file into the Xcode navigator, a horizontal insertion indicator appears.
In a table, consider highlighting specific cells to show where the item will end up. When you provide highly targeted destination feedback such as this, you help users avoid having to rearrange their content later.
Highlight dropped text at its destination. If the destination supports styled text, the dropped text should maintain its font, typeface, and size attributes. If the destination does not support styled text, the dropped text should assume the font, typeface, and size attributes specified by the destination insertion point.
Provide additional feedback if the drop initiates a process. For example, if the user drops an item onto an icon that represents a task (such as printing), show that the task has begun and keep the user informed of the task’s progress.
Make sure users know when a dropped item can't be accepted. When the user drops an item on a destination that does not accept it, the item zooms from the pointer location back to its source location (this behavior is called a zoomback). A zoomback should also occur when a drop inside a valid destination does not result in a successful operation.
At the destination, accept the portion of the dragged item that makes sense. In your app, a destination should be able to extract the relevant data from the item the user drops. For example, if a user drags an Contacts entry to the “To” text field in Mail, only the email address is accepted, not the rest of the contact’s address information.
Display the appropriate post-drag selection state. After a successful drag-and-drop operation involving a single window, the selection state is maintained at the new location. This behavior shows the location of the dropped item and allows the user to reposition the item without having to select it again. Also:
If the user drags an item from an active window to an inactive window, the dragged item becomes a background selection at the destination. The active window should maintain the item’s selected state.
When content is dropped into a window in which something is already selected, you should deselect everything in the destination before the drop rather than replace the selection with the dragged item. Deselecting everything in the destination helps the user avoid accidental data loss.
Automatically scroll a destination window when appropriate. When an item is being dragged, your app must determine whether to scroll the contents or allow the item to “escape” the window. If your app allows items to be dragged outside of windows, you should define an automatic scrolling region. Automatically scroll a destination window only if it is also the source window and is frontmost. Don’t automatically scroll inactive windows.
Display a confirmation dialog when a drag-and-drop operation is not undoable. Although it’s best to support undo for the drag-and-drop operations in your app, it’s not always possible. For example, if the user attempts to drop an icon into a write-only drop box on a shared volume, the action is not undoable because the user doesn’t have privileges to open the drop box and reverse the drag. In such cases, it’s important to use a confirmation dialog to tell the user that their drag-and-drop operation can't be reversed.
Create a clipping or other item to contain content that users drag from your app to the Trash. A clipping is an intermediate form of content that has been dragged from a source location but has not yet been dragged to its final destination. For example, OS X allows users to drag content to a Finder window (or to the desktop) and then, in a later step, drag the content to another destination. (Note that a clipping has no relation to the Clipboard: Copying to the Clipboard and creating drag-and-drop clippings don't interfere with each other.)
Auto Save and Versions
Document-based apps can free users from having to save their work explicitly or worry about losing unsaved changes. When document-based apps enable Auto Save, the system automatically writes document data to disk as needed, without necessarily creating additional copies.
Versions displays an immersive interface in which users can browse earlier versions of their document and replace their working document with a previous version. Auto Save and Versions work together to reduce file-management tasks and help users focus on creating content.
If your app is document-based, you can enable Auto Save with comparatively little effort. (When you adopt Auto Save, version browsing is enabled automatically.) To learn the programmatic steps you need to take to opt in to Auto Save, see “Documents Are Automatically Saved” in Mac App Programming Guide.
Beginning in OS X v.10.8, if your document-based app is iCloud-enabled, untitled documents are automatically saved in iCloud as soon as the users begins editing. (If your app is not iCloud-enabled, these documents are saved in the user’s Documents folder.) See “iCloud Storage” to learn more about iCloud.
To help users enjoy the full benefits of Auto Save and Versions in your app, follow these guidelines:
Avoid implying that users will lose their work unless they choose File > Save. You want to help users understand that your app will always save their work unless they explicitly choose to discard it. In particular, you want to help users learn that the primary use for the Save command is to give them the opportunity to specify the name and location of a document, not to save their content. A good way to emphasize this point is to automatically save content in an untitled document unless the user closes the window and declines to name the document.
As much as possible, avoid displaying a dot in the document window’s close button. In earlier versions of OS X, a document with unsaved changes always displayed a dot in the close button, which indicated the “dirty state.” To encourage users to embrace the Auto Save experience, you want them to get out of the habit of checking the close button to see if they need to save their work. In general, only apps that are not document-based should regularly display a dot to indicate unsaved changes.
When possible, you should also avoid displaying a dot next to a document’s name in the Window menu. To learn more about the contents of the Window menu, see “The Window Menu.”
Don’t ask users to save when they log out, restart, or quit your app. Users should not be presented with a Save dialog unless they explicitly close a document window that contains content that has never been named. When a document window closes as the result of another action (such as when the user logs out) the content should be automatically saved even if the user has never titled it. In this way, the user’s work is automatically saved in all circumstances, unless the user explicitly chooses to throw it away.
Spotlight is a powerful OS X search technology that makes searching for files on the computer as easy as searching the web. Using Spotlight, users can search for things using attributes that have meaning for them, such as the intended audience for a document, the orientation of an image, or the key signature of the music in an audio file. Information like this (called metadata) is embedded in a file by the app that created it.
Spotlight is also available to developers to help them find files to display, plug-ins to load, and data to use in their apps. The guidelines in this section help you extend Spotlight capabilities to your users and take advantage of its benefits in your app.
Use Spotlight to give advanced file-search capabilities to users within the context of your app. For example, you might choose to replicate the Spotlight contextual-menu item, using a button that initiates a Spotlight search for the user’s selected text. You might then display a custom window that contains all the search results or a filtered subset of them.
Consider providing Spotlight-powered search instead of a Finder-based Open dialog. Users often need to work on a file that was saved in an atypical place or given an unexpected or forgotten name. If you offer only a Finder-based Open dialog, it might force the user to waste time navigating the file system, trying to remember what the file was named and where it was saved. Instead, provide a Spotlight-powered search that allows users to search the entire file system, using attributes that are meaningful to them.
Consider using Spotlight behind the scenes to find needed files or plug-ins. For example, an app that provides a back-up service might allow users to choose a broad category of file type to back up, such as images. Instead of asking users to identify all the folders that contain their images or only backing up a Pictures folder, the app could perform a Spotlight search to find every image file in the file system, regardless of its location.
Use Search Kit (not Spotlight) to do fine-grained textual searching within a document. Spotlight is tuned to search for files; it’s not intended to do extensive text-based searching within a document. An app that stores data in database records, for example, should not base its database search on Spotlight because the data are not stored in separate files. For more information on using Search Kit in your app, see Search Kit Programming Guide.
Include a Quick Look generator if your app creates documents in an uncommon or custom format. Spotlight uses Quick Look technology to display thumbnails and full-size previews of the documents returned in a search. If your app produces documents in common content types, such as HTML, RTF, plain text, TIFF, PNG, JPEG, PDF, and QuickTime movies, Spotlight can display the thumbnails and previews automatically. Otherwise, you should include a Quick Look generator to convert your native document format into a format Spotlight can display. To learn how to create a Quick Look generator, see Quick Look Programming Guide.
Be sure to supply a plug-in that describes the types of metadata your file format contains. Supplying this plug-in (called a Spotlight importer) ensures that users can search for the files your app creates using the attributes described by the metadata your files contain. For comprehensive information on how to create a Spotlight importer, see Spotlight Importer Programming Guide.
OS X supports two user help features: Help tags and Apple Help. Help tags allow you to provide temporary context-sensitive help whereas Apple Help allows you to provide a more thorough discussion of a topic or task.
For the best user experience, don’t create a custom help feature. When users refer to help, it’s usually because they are having difficulty accomplishing a task, which means they might be frustrated. This isn’t a good time to make them learn yet another task, such as figuring out a help viewing mechanism that differs from the one they use in all the other apps on their computer.
Using Apple Help, you can display HTML files in Help Viewer, a browser-like app designed for displaying and searching help documents. Help Viewer can also display documents containing QuickTime content, open AppleScript-based automations, retrieve updated help content from the Internet, and provide context-sensitive assistance.
Although users can access Apple Help by launching the Help Viewer app, they will more commonly access it from your app, in one of the following three ways:
The Help menu. The Help menu is the last app menu item in the menu bar (in left-to-right systems, the Help menu is on the right). When you register your help book with Help Viewer, the first item in the Help menu is the system-provided Spotlight For Help search field. The second item in the menu should be AppName Help, which opens Help Viewer to the first page of your help content. For more information on the Help menu, see “The Help Menu.”
Help buttons. A Help button provides easy access to specific sections of your help book. When a user clicks a Help button in your UI, you send to Help Viewer either a search term or an anchor lookup.
From a contextual menu item. If contextually appropriate help content is available for the object the user has Control-clicked, the first item in the contextual menu is Help. As with Help buttons, this menu item can send either a search term or an anchor lookup to Help Viewer.
Only display a Help button in a window when there is contextually relevant help available. It’s not necessary for every dialog and window in your app to include a Help button. Because the Help menu is available, users always have another way to access your help content. To learn how to write Apple Help content and provide it with your app, see Apple Help Programming Guide.
Help tags allow you to provide basic help information for interface elements in your app without requiring users to shift their focus away from the primary interface.
Help tags are short messages that appear when the user allows the pointer to rest on a UI element for a few seconds. When the pointer leaves the object, the tag vanishes. If the pointer isn’t moved, the system hides the help tag after about 10 seconds. For example, the Finder displays a help tag that describes the behavior of the Quick Look toolbar control.
Note that help tags look similar to expansion tooltips, but they aren’t the same. An expansion tooltip can appear when users position the pointer over truncated text in a table, outline, or browser view’s cell. For example, when a filename is too long to display without truncation in a Finder column, an expansion tooltip displays the complete text. (To learn more about enabling expansion tooltips in your app, see
The text of a help tag should briefly describe what an interface element does. If you find that you need more than a few words to describe the function of a control, you might want to reconsider the design of your app’s user interface.
You can define help tags in Interface Builder, where they are called tooltips. Here are some guidelines to help you create effective help tag messages.
In general, don’t name the interface element in the tag. Because a help tag is specific to a UI element, it shouldn’t be necessary to refer to it by name, unless the name helps the user and isn’t available onscreen. If you do need to refer to an element by name, make sure you use the same name throughout all of your documentation.
Describe only the element that the pointer is resting on. Users expect a help tag to describe what they can do with the control; they don’t expect to read about other controls or about how to perform a larger task.
Describe controls that are unique to your app. Don’t provide help tags that describe window resize controls, scrollers, or other standard Aqua controls.
Focus on the action users can perform using the control. A good way to stay focused on the action is to begin the tag with a verb, for example, “Restores default settings” or “Add or remove a language from the list”.
Use the fewest words possible. Help tags are always on, so it’s important to keep your tag text unobtrusive—that is, short—and useful. As much as possible, keep tag text to a maximum of 60 to 75 characters. A tag should present only one concept and that concept should be directly related to the interface element. You can also omit articles to limit the length of the tag. Note that localization can lengthen the text by 20 to 30 percent, which is another good reason to keep the tag short.
Use sentence-style capitalization. Sentence-style capitalization tends to appear more friendly and less formal to users (to learn more about this capitalization style, see “Capitalizing Labels and Text”).
In general, use a sentence fragment. A sentence fragment emphasizes the brevity of the help tag’s message. If the tag text must form a complete sentence, end it with the appropriate punctuation.
Consider creating contextually sensitive help tags. You can provide different text for different states a control can have, or you can provide the same text for all states. When you describe what the interface element accomplishes, you help the user understand the current state of the control even if the tag isn’t applicable to all situations.