Volume Number: 19 (2003)
Issue Number: 12
Column Tag: Programming
by Scott Knaster
For about 20 years now, Apple has been telling us that modes in software are bad. It's hard to remember, especially if you're a youngster, but we used to drive software around by getting into and out of modes, restricted places that provided their own definitions for the way commands worked and actions were interpreted (kind of the way a lot of venerable UNIX text editors and command line tools work in OS X today, except this was for everybody, not just us geeks). For example, when you typed a slash into a little old spreadsheet program called VisiCalc, you went into command mode, signaling that the next character was an instruction rather than something that should appear in a cell.
But Apple in its wisdom says modes are OK in certain situations. For example, modes that emulate the real world are permitted, such as picking a type of brush in a painting program. Another kind of mode is useful when you intentionally want to limit what your users can do. This rare situation becomes reality when you consider the kiosk, a public computer that has to fend for itself when accosted by clueless newbies, hostile geeks, and keyboard-pounding toddlers.
If you're developing an application that has to run at a kiosk, Apple helps you out by providing a set of features for kiosk mode in Mac OS X. In this column, we'll take a look at how to take advantage of what OS X can do for you in kiosk mode.
Apple put the cool new kiosk mode features into OS X 10.2, adding a little more in 10.3. You get to the features through two function calls: SetSystemUIMode and GetSystemUIMode. These calls let you effectively lock the user inside your application, preventing the hostile, curious, or ignorant from wreaking havoc. The SetSystemUIMode call is defined like this:
OSStatus SetSystemUIMode (SystemUIMode inMode,
SystemUIOptions inOptions);
The inMode parameter specifies the UI mode you want, and inOptions lets you choose settings for that mode. There are five modes you can pick for your application, as shown in the following table:
System UI mode setting Details
kUIModeNormal The usual mode for all applications, and the mode you get if you don't
make any calls to this API.
kUIModeContentSuppressed This mode prevents the system from drawing anything into the content
area of the screen below the menu bar unless the user performs an action
that triggers an auto-show behavior. In practice, this mode simply turns
dock hiding on, which makes the dock vanish until the mouse pointer
moves over it, whereupon it slides onto the screen. Note: this was
broken in 10.2 and is fixed in 10.3.
kUIModeContentHidden This mode hides the dock - technically, all system UI elements other
than the menu bar - and does not show it even if the user mouses into
the dock region. Note: this was also broken in 10.2 and fixed in 10.3.
kUIModeAllHidden Use this mode to hide the menu bar along with the dock, with no
auto-showing feature.
kUIModeAllSuppressed This mode was added in 10.3. Use it for hiding the dock and menu bar,
but in this mode they will both auto-show if the user mouses over their
content areas.
When you call SetSystemUIMode, you also get to pass a set of options in addition to the mode you want to use. These options provide even more lock-in features for your kiosk and help you further refine the imprisonment of your rowdy user. Here's a list of the options you can choose:
System UI option Details
kUIOptionDisableAppleMenu Use this option to disable all items in the Apple menu,
although despite the option's name, the appearance of the
Apple itself isn't disabled (must be a corporate logo thing).
kUIOptionDisableProcessSwitch This option turns off the user's ability to switch apps using
Command-Tab and Command-Shift-Tab.
kUIOptionDisableForceQuit If you select this option, the Force Quit item in the Apple
menu is disabled, and Command-Option-Escape doesn't do
anything. Powerful!
kUIOptionDisableSessionTerminate This option helps prevent the user from shutting down or
logging out. When you use it, the Restart, Shut Down, and
Log Out menu items are disabled. Also, if the user presses
the power button, the Restart/Sleep/Cancel/Shut Down alert
won't appear.
kUIOptionAutoShowMenuBar This option is only valid when used with kUIModeAllHidden.
Pass it to make the menu bar show itself if the user rolls
the mouse into its content region.
kUIOptionDisableHide This option was added in 10.3. Set it to disable the Hide item
in the application menu.
Figure 1. You can use SetSystemUIMode to prevent users from getting access to the Force Quit and Power windows.
One of the cautions to note in using SetSystemUIMode is that the mode you set is only respected when your application is frontmost. If through magical incantation or other method the user somehow manages to bring another application to the front, the UI mode for your application is switched out along with the rest of the app.
There is a corresponding call to find out the current UI mode:
GetSystemUIMode(SystemUIMode *outMode,
SystemUIOptions *outOptions);
As you can guess, calling GetSystemUIMode gets the current mode and options, in case you need to know what they are.
Depending on what your kiosk does, you might want to make the Finder go away. One good reason for this is that it prevents users from clicking on the desktop to switch out of your application. You can get rid of the Finder by sending it a kAEQuitApplication Apple event. Apple has an example to show you how to do that - it's at http://developer.apple.com/technotes/tn2002/downloads/tn2062_2.hqx .
If you just want your application to start up in one of the modified system UI modes and stay there, and you don't need to set any options, you can specify your desire in the application's property list. Just add a key named LSUIPresentationMode with type number and a value of 0, 1, 2, 3, or 4. Use 0 for normal mode, 1 for content suppressed, 2 for content hidden, 3 for all hidden, and 4 for all suppressed.
To help you view the power of the kiosk mode APIs in all their majesty, Apple provides a cool sample app, called UsingSystemUIMode, that demonstrates the various available features and tweaks. See Figure 2 for a shot of the app's screen.
Figure 2. Apple's sample application for testing kiosk mode APIs.
To get the sample app and to learn more about implementing kiosk mode in your application, see Technical Note TN2062, Guide to Creating Kiosks on Mac OS X, available at http://developer.apple.com/technotes/tn2002/tn2062.html.
Although the kiosk mode API is a good start toward locking up your kiosk machine, there are some things you'll want to do that you can't do yet. And just when you thought everything was perfect. Here's more information about some of those limitations:
You can't disable the eject key. If your kiosk has to run with a CD or DVD inserted, you can design the kiosk so that it's physically impossible to eject the disk.
To disable various wacky scenarios, such as taking control of the machine by booting off an external disk or booting into single-user mode by holding down Command-S, you can enable the Mac's Open Firmware password. When the Open Firmware password is enabled, the Mac will only boot from the startup disk you select in System Preferences.
You can't prevent the user from messing with the brightness keys and darkening the screen, nor can you intercept the volume keys.
Needless to say, locking your users in and preventing them from having basic features is not a standard design principle. In a kiosk, many of these features are necessary. In a typical app, they're practically criminal. Please use them with care, or at least a sense of humor.
Scott Knaster has been writing about Macs for as long as there have been Macs. Scott's books How To Write Macintosh Software and Macintosh Programming Secrets were required reading for Mac programmers for more than a decade. Scott wrote developer books for General Magic and worked on Mac software for Microsoft. Scott's books have been translated into Japanese and Pascal. Scott has every issue of Mad magazine, which explains a lot.
