Kiosk Mode Technical Note

Kiosk mode is a system-software and user-interface feature that is ideal for computer games and kiosk-style applications. It is useful when you want the user interface elements of the system to behave in custom ways when your application is active—that is, when you want a different user experience from the one that the system user interface normally offers. These customizable features include the dock, menu bar, and task switcher. In addition, with kiosk mode your customized application can observe changes in UI behavior that are made by other active applications

In Mac OS X v10.6 and later, the NSApplication class supports this customization. It also serves as a replacement for the Carbon SystemUIMode API available in Mac OS X v10.5 and earlier.

The main goal of kiosk mode is to lock the user into a particular application, either to allow a game to take over the entire screen (in computer game applications) or to prevent uusers at a computer from opening applications that should not be accessible to them (in a kiosk-style application).

This technical note covers several useful techniques that can be used by kiosk developers, outlines the numerous options for kiosk mode, and provides advice on how and when to successfully implement its many features.

Features of the API

Kiosk mode lets you control the user experience by manipulating numerous system user interface elements from within your application. For example:

• You can decide whether you want users to the see the Dock and menu bar and whether the Apple menu is active.

• You can disable activities that take users out of your application, such as process switching, the Force Quit window, hiding the application, and Exposé

• You can prevent users from restarting or powering down the computer

Choosing the Features

A set of options exists for customizing the user experience through the NSApplication class by using a new bitmask, NSApplicationPresentationOptions (this set of options serves as a replacement for the Carbon interface SystemUIMode that is available in Mac OS X v10.5 and earlier).

The flags that comprise an application’s presentation options are as follows:

Getting and Setting the Features

There are a few main methods that are used for getting or setting the presentation options. The setPresentationOptions: method sets the application’s presentation options to the specified value. When using this method, it is important to note that only certain combinations of NSApplicationPresentationOptions flags are allowed, as detailed in the following section, and that when given an invalid combination of option flags, this method raises an exception.

For example, in the main controller file of a simple window based application, the following code snippet in the awakeFromNib method hides the dock and menu bar upon your application’s launch:

-(void) awakeFromNib {

     @try {

          NSApplicationPresentationOptions options = NSApplicationPresentationHideDock + NSApplicationPresentationHideMenuBar;

          [NSApp setPresentationOptions:options];

     }

     @catch(NSException * exception) {

          NSLog(@"Error.  Make sure you have a valid combination of options.");

     }

}

The presentationOptions method returns the set of application presentation options for that current application. The currentSystemPresentationOptions method returns the set of application presentation options that are currently in effect for the system. These are the presentations options that have been put into effect by the currently active application.

For most applications, the initial value of presentationOptions is NSApplicationPresentationDefault. If an application’s Info.plist file specifies a value for the LSUIElement key, as described in Guide to Creating Kiosks on Mac OS X, the application’s presentationOptions is initialized to an equivalent combination of NSApplicationPresentationOptions flags instead.

Valid Combinations of Settings

When you combine settings, or option flags, to pass to the setPresentationOptions: method, you must do so in a way that satisfies the following requirements:

• NSApplicationPresentationAutoHideDock and NSApplicationPresentationHideDock are mutually exclusive: You may specify one or the other, but not both.

• NSApplicationPresentationAutoHideMenuBar and NSApplicationPresentationHideMenuBar are mutually exclusive: You may specify one or the other, but not both.

• If you specify NSApplicationPresentationHideMenuBar, it must be accompanied by NSApplicationPresentationHideDock. If you specify NSApplicationPresentationAutoHideMenuBar, it must be accompanied by either NSApplicationPresentationHideDock or NSApplicationPresentationAutoHideDock.

• If you specify any of NSApplicationPresentationDisableProcessSwitching, NSApplicationPresentationDisableForceQuit, NSApplicationPresentationDisableSessionTermination, or NSApplicationPresentationDisableMenuBarTransparency, it must be accompanied by either NSApplicationPresentationHideDock or NSApplicationPresentationAutoHideDock.

When the setPresentationOptions: method receives a newOptions parameter that does not conform to these requirements, it raises an exception (NSInvalidArgumentException).

Key-Value Observing Compliance

Both presentationOptions and currentSystemPresentationOptions are key-value observing (KVO) compliant. A client that observes currentSystemPresentationOptions receives notifications if the following events occur:

1. The client is the active application and makes a change itself using the setPresentationOptions: method.

2. Another application is active and makes its own changes.

3. Making a different application active causes the active set of presentation options to change.

For more information about KVO compliance, see Key-Value Observing Programming Guide.

Full-Screen Mode Compatibility

In Mac OS X v10.6 and later, you can use an instance of the NSView class in full-screen mode and retain the kiosk mode functionality. The enterFullScreenMode:withOptions: method accepts a new option, whose key-value pair specifies the kiosk mode options to use while the view is operating in full-screen mode. The new key is the string NSFullScreenModeApplicationPresentationOptions. It’s value must be of type NSApplicationPresentationOptions.

When the options dictionary you pass to enterFullScreenMode:withOptions: does not contain a value for NSFullScreenModeApplicationPresentationOptions, AppKit does not alter the presentation options that were previously in effect before taking the view full-screen. AppKit also captures either the destination screen, or, if you specify YES for NSFullScreenModeAllScreens, all attached screens.

In Mac OS X v10.6 and later, you can put a windowless view in full-screen mode. This means that the enterFullScreenMode:withOptions: method can be sent to a view for which [view window] == nil.

When the options dictionary you pass to enterFullScreenMode:withOptions: does contain a value for NSFullScreenModeApplicationPresentationOptions, AppKit does not capture any displays, because doing so would prevent the showing of presentationOptions-controlled UI elements such as the menu bar and Dock. AppKit puts the requested NSApplicationPresentationOptions value into effect when switching the view into full-screen mode, and restores the previously active NSApplication presentationOptions setting when the view exits from full-screen mode via the exitFullScreenModeWithOptions: method.