ADVERTISEMENT

Volume Number: 19
Issue Number: 12
Column Tag: Programming

Mac OS X Programming Secrets

Checking Out Kiosk Mode Features

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.  

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.

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.