Application Manager Reference

Discussion

This function makes it possible to draw into the application Dock tile at a resolution of 128x128, which is the size of all Dock tiles prior to OS X v10.5. If the user interface scale factor is not 1.0, the drawing will be scaled to the actual size of the tile.

This function locks the application Dock tile to prevent the Dock from drawing in the tile. When you are finished using the context, you must call the function EndCGContextForApplicationDockTile to release the context and the lock. Do not use CGEndContext or CFRelease for this purpose. To ensure that drawing to the context appears onscreen, you should call CGContextFlush before releasing the context.

Discussion

The function CreateCGImageFromPixMaps uses the mask as the alpha channel for the resulting image. This allows you to have any level of transparency in the resulting image. You can pass the Quartz image as a parameter to any Quartz 2D drawing function, as well as to Dock tile functions such as the functions SetApplicationDockTileImage and OverlayApplicationDockTileImage. You can use CreateCGImageFromPixMaps to create an image for a badge, and then apply the badge to your application Dock icon.

Discussion

This function also releases the lock on the application Dock tile, signaling the Dock that you are done drawing in the tile.

Discussion

Your application needs to get the application script when it uses a function, such as UseThemeFont, that takes a script code as a parameter.

Discussion

Your application needs to use the application text encoding when it creates a CFString from text stored in Resource Manager resources. Typically the text uses a Mac encoding such as MacRoman or MacJapanese. For more information, see Programming With the Text Encoding Conversion Manager.

Discussion

This function returns information about the presentation mode of the calling application, not the presentation mode of the current login session. The login session mode may be different, since the login session mode is determined by the presentation mode of the frontmost application. If the calling application is not currently the frontmost application, then its presentation mode will not be in use. To track changes in the login session’s presentation mode, you may handle the kEventAppSystemUIModeChanged Carbon event.

Discussion

When this function is called, it displays a window called an about box that contains your application icon, name, software version, and other optional information. In a Carbon event–based application, the standard application event handler responds to the kHICommandAbout command by calling the function HIAboutBox for you. If your application menu has an About menu item, you will get this behavior for free. You don’t need to call this function unless you want to customize the contents of the about box.

In addition to the application name and version, this function is designed to display two additional strings in the about box, a copyright string and a description string. You can customize what this function displays by passing in various options in the inOptions parameter:

• You can pass NULL to display application information defined in the Info.plist file or your bundle resource (not recommended). This function looks the Info.plist file for three keys to get the name, version, and copyright strings: CFBundleName, CFBundleVersion, and CFBundleGetInfoString.

• You can pass a dictionary with replacement values for one or more strings. See “About Box Keys” for a list of valid keys in this dictionary. If a replacement string is not passed, the default behavior applies. For example, you could pass some variant of your application name in the dictionary, but not pass a replacement version string or copyright string. The function would display your replacement string, and fall back to looking in the Info.plist file for the other strings.

• You can pass a dictionary with a single entry, the name of a localized strings file that contains replacement values for one or more strings. The dictionary key is kHIAboutBoxStringFileKey, and the value is the name of the strings file without the .strings extension. This function automatically uses that file to find the strings for the about box. This example shows the key-value pairs in a typical strings file:

  HIAboutBoxName = "AboutBox";

  HIAboutBoxVersion = "v1.0";

  HIAboutBoxCopyright = "© Apple Computer, 2006";

  HIAboutBoxDescription = "An Example Application";

  Again, if a string is not found in that file, this function falls back to looking for a string in the dictionary, and then finally the Info.plist file.

Note that the description string can only be specified in an options dictionary or a strings file; this function does not check your Info.plist file for a description string.

Discussion

This function makes it possible to draw into the application Dock tile at a resolution other than 128x128, which is the size of all Dock tiles prior to OS X v10.5. In OS X v10.5 and later, dock tiles may use different sizes when the user interface scale factor is not 1.0.

Unlike BeginCGContextForApplicationDockTile, this function returns a context that has no transform applied to it; user space and device space are 1:1. Your application must use the output context size to determine the area in which you should draw in the context.

Because the Dock's tile size can change dynamically, applications that use this function should be prepared to redraw their Dock tile as necessary. A kEventAppUpdateDockTile Carbon event is sent when the application needs to redraw its Dock tile.

This function locks the application Dock tile to prevent the Dock from drawing in the tile. When you are finished using the context, you must call the function EndCGContextForApplicationDockTile to release the context and the lock. Do not use CGEndContext or CFRelease for this purpose. To ensure that drawing to the context appears onscreen, you should call CGContextFlush before releasing the context.

Discussion

In OS X v10.5 and later, you can use this function to install your own HIObject delegates on the application object.

The function GetApplicationEventTarget returns the event target associated with the application object.

Discussion

With the introduction of the modal focus stack in OS X v10.5, an application may have two different focused windows: the modeless focus (the window most recently passed to the function SetUserFocusWindow), and the effective focus (either the modeless focus or, if there is a non-empty modal focus stack, the topmost window in the focus stack). This function returns either window.

Applications can use this function to determine if the modeless focus and effective focus are different windows. An application with a custom HIView can also use this function to determine if the application should show an insertion point. The insertion point should only be visible if the view is inside the effective focus.

Note that the function GetUserFocusWindow returns the modeless focus—the same window returned when you pass false to HIApplicationGetFocus.

Discussion

This function displays a window with the standard Spotlight search interface. For more information, see File Metadata Search Programming Guide.

Discussion

You can overlay an image, such as a badge, to indicate the application’s status to the user.

Discussion

If you’ve called the functions SetApplicationDockTileImage or OverlayApplicationDockTileImage, you can use the function RestoreApplicationDockTileImage to restore the Dock icon to the original application icon.

Discussion

When an application starts up, by default the application icon is always used as the application Dock tile. You can use the function SetApplicationDockTileImage to replace the application icon with another image. This can be useful to indicate the state of the application to the user. If you set the image, it will not revert back to its original image when your application terminates. You need to manually restore it before quitting using the function RestoreApplicationDockTileImage.

Discussion

When you position the cursor over an application Dock tile and hold down the mouse button, a contextual menu automatically displays a list of the application’s document windows and standard application Dock menu items such as Open at Login and Show in Finder. You can use the function SetApplicationDockTileMenu to add menu items to the contextual menu displayed for your application Dock tile. The items in the menu you pass to this function are inserted into your application Dock tile menu, between the list of document windows and the standard items.

This function increments the reference count of the menu you pass to it. Before the menu is displayed, it receives the Carbon events kEventMenuPopulate, kEventMenuOpening, and kEventMenuEnableItems, so any event handlers for these events can update the menu appropriately. You can receive notifications of and handle selections from the menu using kEventCommandProcess Carbon event handlers installed in the application event target. You must make sure each menu item has a command ID, as the kEventCommandProcess event sent to your application provides the menu item’s command ID.

When you use this function to pass a menu to the Dock, the following state of each menu item is preserved:

• Information about whether the item is a text item or a separator

• The item text (if the item is not a separator)

• The item command ID

• The item command key modifiers (but not the command key itself)

• The item mark

• The item indent

• The item style

• The item icon, if the icon was specified with kMenuSystemIconSelectorType or kMenuIconResourceType

• The item’s submenu

• These menu item attributes:

  • kMenuItemAttrNotPreviousAlternate

  • kMenuItemAttrSectionHeader

  • kMenuItemAttrDisabled

  • kMenuItemAttrIconDisabled

  • kMenuItemAttrSubmenuParentChoosable

  • kMenuItemAttrDynamic

No other menu or menu item state is preserved when the menu is displayed by the Dock. For example, you can set a custom font for the menu or a menu item, but the menu as displayed by the Dock will not use that font.

Discussion

The purpose of this function is to make it easier to implement a dedicated kiosk system, in which the user is not permitted access to certain elements and features in the system user interface. This function gives your application control over the visibility of the Dock and the menu bar, and over various other system-provided user interface features such as process switching, logout, restart, and shutdown.

If your application is frontmost and you call this function to request a new presentation mode, your presentation mode will take effect immediately. If another application becomes frontmost, the presentation mode you requested will no longer be in effect. If your application becomes frontmost again, the presentation mode you previously established will come back into effect.

When the frontmost application uses this function to change its presentation mode, a kEventAppSystemUIModeChanged Carbon event is sent to all applications that have registered for the event. This event is also sent when an application is activated; it contains the newly active application's presentation mode.

In addition to using this function, an application may also specify an initial presentation mode when it is launched by using the LSUIPresentationMode key in its Info.plist file. This key should be of type Number and should have the value of one of the presentation mode constants listed in “Presentation Modes.”

Discussion

The values associated with the keys in an options dictionary are all strings.

Discussion

You can use this constant to check for the presence of bug fixes documented in HIToolbox release notes. For example, to test for the HIToolbox included in OS X v10.4.2, check that kHIToolboxVersionNumber is at least 220. See the header file MacApplication.h for a list of the version numbers for specific releases.

Discussion

The presentation mode of an application determines which system-provided user interface elements are visible on the screen. Your application can specify its presentation mode using the function SetSystemUIMode.

Discussion

Presentation mode options are used to inhibit or allow certain user interface elements and commands. Your application can specify these options using the function SetSystemUIMode.