Apple Developer Connection
Member Login Log In | Not a Member? Contact ADC

Next Page > Hide TOC

Appearance Manager Reference

Framework
Carbon/Carbon.h
Declared in
Appearance.h

Overview

The Appearance Manager coordinates the look of human interface elements in Mac OS X. You can use the Appearance Manager to adapt any nonstandard interface elements in your program to the same coordinated look as the rest of Mac OS X. The Appearance Manager also provides many standard human interface elements, such as focus rings and group boxes, that can eliminate the need to create and maintain your own custom solutions.

In Mac OS X v10.3 and later, the Appearance Manager provides a new API called HITheme for drawing appearance primitives. Currently, this API is documented in the HITheme.h interface file. The HITheme API is similar to the legacy Appearance Manager API, but many parameters have been modified to use Quartz 2D types instead of QuickDraw types. For example, HITheme functions draw into a Quartz graphics context instead of the current QuickDraw graphics port. The legacy Appearance Manager API is implemented on top of the HITheme API, so using the new API can provide a significant performance advantage.

Functions by Task

Accessing Theme Information

Drawing Theme-Compliant Controls

Drawing Theme-Compliant Menus

Drawing Theme-Compliant Windows

Playing Theme Sounds

The theme sound functions do nothing in Mac OS X.

Registering With the Appearance Manager

Specifying Theme-Compliant Cursors

Using Theme-Compliant Colors and Patterns

Drawing Theme-Compliant Text

Creating and Disposing Universal Procedure Pointers to Appearance Manager Callbacks

Functions

BeginThemeDragSound

Continuously plays a theme-specific sound associated with the user’s movement of a given interface object.

OSStatus BeginThemeDragSound (
   ThemeDragSoundKind kind
);

Parameters
kind

A value of type ThemeDragSoundKind. Pass a constant specifying the sound to play; see “Theme Drag Sounds” for descriptions of possible values.

Return Value

A result code. See “Appearance Manager Result Codes.”

Discussion

The Appearance Manager automatically plays drag sounds for standard user interface elements and for Drag Manager drag actions. Your application may call BeginThemeDragSound, typically upon detecting a drag initiation, to play a drag sound for a custom element. BeginThemeDragSound plays the specified sound in a continuous loop until your application calls the function EndThemeDragSound, typically upon receiving a mouse-up event.

Note that the BeginThemeDragSound function automatically tracks the current mouse position and handles any panning or variations in pitch for the sound.

Special Considerations

This function is not implemented in Mac OS X.

Availability
Declared In
Appearance.h

CopyThemeIdentifier

Retrieves a string identifying the current theme variant.

OSStatus CopyThemeIdentifier (
   CFStringRef *outIdentifier
);

Parameters
outIdentifier

A pointer to a string that, on output, contains the current theme variant. When you no longer need the string, you should release it.

Return Value

A result code. See “Appearance Manager Result Codes.”

Availability
Declared In
Appearance.h

DisposeThemeDrawingState

Releases the memory associated with a reference to a graphics port’s drawing state.

OSStatus DisposeThemeDrawingState (
   ThemeDrawingState inState
);

Parameters
inState

A value of type ThemeDrawingState. Pass a value specifying the previous drawing state for the current graphics port. You may obtain this value from the outState parameter of GetThemeDrawingState.

Return Value

A result code. See “Appearance Manager Result Codes.”

Discussion

Also see the function SetThemeDrawingState.

Availability
Declared In
Appearance.h

EndThemeDragSound

Terminates the playing of a sound associated with the user’s movement of a given interface object.

OSStatus EndThemeDragSound (
   void
);

Return Value

A result code. See “Appearance Manager Result Codes.”

Discussion

The Appearance Manager automatically starts and stops drag sounds for standard user interface elements and for Drag Manager drag actions. Your application may call BeginThemeDragSound, typically upon detecting a drag initiation, to play a drag sound for a custom element. Call the EndThemeDragSound function to turn off a drag sound when the drag is completed, typically upon receipt of a mouse-up event.

Special Considerations

This function is not implemented in Mac OS X.

Availability
Declared In
Appearance.h

GetTheme

Obtains a collection containing data describing the current theme.

OSStatus GetTheme (
   Collection ioCollection
);

Parameters
ioCollection

A value of type Collection. Pass a reference to a collection object, such as that created by calling the Collection Manager function NewCollection. On return, the collection contains data describing attributes of the current theme.

Return Value

A result code. See “Appearance Manager Result Codes.”

Discussion

The GetTheme function obtains a collection containing a copy of the data for the current theme. The theme data is in the form of collection items, each corresponding to an attribute of the theme. For a given theme, the actual number of collection items may vary, depending upon how fully the theme’s attributes are specified. See “Theme Collection Tags” for descriptions of the possible theme collection items.

Your application can use theme collection tags, along with various Collection Manager functions, to access the data in the collection.

Also see the function SetTheme.

Availability
Declared In
Appearance.h

GetThemeBrushAsColor

Obtains the color that corresponds to a given theme brush type under the current theme.

OSStatus GetThemeBrushAsColor (
   ThemeBrush inBrush,
   SInt16 inDepth,
   Boolean inColorDev,
   RGBColor *outColor
);

Parameters
inBrush

A value of type ThemeBrush. Pass a constant specifying the theme brush type for which you wish to obtain a color; see “Theme Brushes” for descriptions of possible values.

inDepth

A signed 16-bit integer. Pass a value specifying the bit depth (in bits per pixel) of the current graphics port.

inColorDev

A value of type Boolean. Pass true to indicate that you are drawing on a color device. Pass false for a monochrome device.

outColor

A pointer to a structure of type RGBColor. On return, the structure contains a color corresponding to the color or pattern used by the specified theme brush under the current theme.

Return Value

A result code. See “Appearance Manager Result Codes.”

Discussion

The GetThemeBrushAsColor function obtains a color that corresponds to that which is in use for a specified theme brush. If, in the current theme, the specified brush draws with a pattern instead of a color, a theme-specified approximate color is obtained. Your application should call GetThemeBrushAsColor only when you must use an RGBColor value for a specific operation; typically, your application should call the functions SetThemeBackground and SetThemePen for greatest fidelity with the current theme.

Availability
Declared In
Appearance.h

GetThemeCheckBoxStyle

Obtains the system preference for the type of mark to use in a checkbox.

OSStatus GetThemeCheckBoxStyle (
   ThemeCheckBoxStyle *outStyle
);

Parameters
outStyle

A pointer to a value of type ThemeCheckBoxStyle. On return, the value specifies the type of mark being used. See “Theme Checkbox Styles” for descriptions of possible values.

Return Value

A result code. See “Appearance Manager Result Codes.”

Discussion

Because international systems may specify the use of one type of mark to use in checkboxes over another, your application should call GetThemeCheckBoxStyle to obtain the correct type of mark to use on the current system.

Availability
Declared In
Appearance.h

GetThemeDrawingState

Obtains the drawing state of the current graphics port.

OSStatus GetThemeDrawingState (
   ThemeDrawingState *outState
);

Parameters
outState

A pointer to a value of type ThemeDrawingState. On return, GetThemeDrawingState sets the outState parameter to point to a copy of the drawing state for the current graphics port.

Return Value

A result code. See “Appearance Manager Result Codes.”

Discussion

Your application may call the GetThemeDrawingState function before performing an operation that modifies the drawing state of a graphics port. To return the graphics port to its previous drawing state and release the memory allocated for the drawing state reference, your application should call SetThemeDrawingState, providing the reference obtained in the outState parameter of GetThemeDrawingState. You can also call DisposeThemeDrawingState to release the allocated memory.

Availability
Declared In
Appearance.h

GetThemeMenuBarHeight

Obtains the height of a menu bar.

OSStatus GetThemeMenuBarHeight (
   SInt16 *outHeight
);

Parameters
outHeight

A pointer to a signed 16-bit integer. On return, the integer value represents the height (in pixels) of the menu bar.

Return Value

A result code. See “Appearance Manager Result Codes.”

Discussion

The GetThemeMenuBarHeight function obtains the specified height of a menu bar in the current theme. This is in contrast to the Menu Manager function GetMBarHeight, which obtains the actual space that the menu bar is currently occupying on the screen. In most instances, the values produced by these two functions are the same. But, when the menu bar is hidden, GetMBarHeight produces a value of 0, and GetThemeMenuBarHeight still provides the “ideal” menu bar height.

Special Considerations

Because menu bar heights may vary among appearances by one or more pixels, you should check the current menu bar height after a theme switch. Specifically, your application should respond to the theme-switch Apple event, kAEAppearanceChanged, by checking the current menu bar height. See “Appearance Manager Apple Events” for more details on kAEAppearanceChanged.

It is important to check the menu bar height before positioning any windows. Failure to do so may result in the menu bar overlapping your application’s windows.

Availability
Declared In
Appearance.h

GetThemeMenuItemExtra

Obtains a measurement of the space surrounding a menu item.

OSStatus GetThemeMenuItemExtra (
   ThemeMenuItemType inItemType,
   SInt16 *outHeight,
   SInt16 *outWidth
);

Parameters
inItemType

A value of type ThemeMenuItemType. Pass a constant identifying the type of menu item for which you are interested in getting a measurement. See “Theme Menu Item Types.”

outHeight

A pointer to a signed 16-bit integer. On return, the integer value represents the total amount of padding between the content of the menu item and the top and bottom of its frame (in pixels). Your content’s height plus the measurement provided by the outHeight parameter equals the total item height.

outWidth

A pointer to a signed 16-bit integer. On return, the integer value represents the total amount of padding between the content of the menu item and the left and right limits of the menu (in pixels). Your content’s width plus the measurement provided by the outWidth parameter equals the total item width.

Return Value

A result code. See “Appearance Manager Result Codes.”

Discussion

Your application should call the GetThemeMenuItemExtra function when you are writing your own menu definition function and wish to be theme-compliant. Once you have determined the height and width of the content of a menu item, call GetThemeMenuItemExtra to get a measurement in pixels of the space surrounding a menu item, including any necessary inter-item spacing, in the current theme. By combining the values for your menu item’s content and the extra padding needed by the theme, you can derive the size of the rectangle needed to encompass both the content and the theme element together.

Availability
Declared In
Appearance.h

GetThemeMenuSeparatorHeight

Obtains the height of a menu separator line.

OSStatus GetThemeMenuSeparatorHeight (
   SInt16 *outHeight
);

Parameters
outHeight

A pointer to a signed 16-bit integer. On return, the integer value represents the height (in pixels) of the menu separator line.

Return Value

A result code. See “Appearance Manager Result Codes.”

Discussion

The GetThemeMenuSeparatorHeight function obtains the height of a menu separator line under the current theme. Your application should call the GetThemeMenuSeparatorHeight function when you are writing your own menu definition function and wish to calculate a menu rectangle for a separator to match the current theme.

Availability
Declared In
Appearance.h

GetThemeMenuTitleExtra

Obtains a measurement of the space to either side of a menu title.

OSStatus GetThemeMenuTitleExtra (
   SInt16 *outWidth,
   Boolean inIsSquished
);

Parameters
outWidth

A pointer to a signed 16-bit integer. On return, the integer value represents the horizontal distance (in pixels) between the menu title and the bounds of its containing rectangle.

inIsSquished

A value of type Boolean. If all the titles do not fit in the menu bar and you wish to condense the menu title’s spacing to fit, pass true. If you pass false, the menu title is not condensed.

Return Value

A result code. See “Appearance Manager Result Codes.”

Discussion

Once you have determined the height and width of the content of a menu title, call GetThemeMenuTitleExtra to get the space surrounding the menu title in the current theme.

Availability
Declared In
Appearance.h

GetThemeMetric

Retrieves the value of a metric property of a user interface element.

OSStatus GetThemeMetric (
   ThemeMetric inMetric,
   SInt32 *outMetric
);

Parameters
inMetric

The user interface metric to retrieve. See “Theme Metrics” for a list of possible metrics.

outMetric

A pointer to an integer value. On output, contains the value of the specified metric property, generally in points.

Return Value

A result code. See “Appearance Manager Result Codes.”

Availability
Declared In
Appearance.h

GetThemeScrollBarArrowStyle

Obtains the system preference for the type of scroll bar arrows to be used.

OSStatus GetThemeScrollBarArrowStyle (
   ThemeScrollBarArrowStyle *outStyle
);

Parameters
outStyle

A pointer to a value of type ThemeScrollBarArrowStyle. On return, the value specifies the type of scroll bar arrows being used. See “Theme Scroll Bar Arrow Styles” for descriptions of possible values.

Return Value

A result code. See “Appearance Manager Result Codes.”

Discussion

Because the user can specify varying types of scroll bar arrows on a theme-specific basis, your application should call GetThemeScrollBarArrowStyle to obtain the preferred style under the current theme.

Availability
Declared In
Appearance.h

GetThemeScrollBarThumbStyle

Obtains the system preference for the type of scroll box to be used.

OSStatus GetThemeScrollBarThumbStyle (
   ThemeScrollBarThumbStyle *outStyle
);

Parameters
outStyle

A pointer to a value of type ThemeScrollBarThumbStyle. On return, the value specifies the type of scroll box being used. See “Theme Scroll Box Styles” for descriptions of possible values.

Return Value

A result code. See “Appearance Manager Result Codes.”

Discussion

Because the user can specify either proportional or fixed-size scroll boxes (also known as “scroll indicators” or “thumbs”) on a theme-specific basis, your application should call GetThemeScrollBarThumbStyle to obtain the preferred style under the current theme.

Availability
Declared In
Appearance.h

GetThemeTextColor

Obtains the text color used for a specified element under the current theme.

OSStatus GetThemeTextColor (
   ThemeTextColor inColor,
   SInt16 inDepth,
   Boolean inColorDev,
   RGBColor *outColor
);

Parameters
inColor

A value of type ThemeTextColor. Pass a constant specifying the element for which you wish to obtain the current text color; see “Theme Text Colors” for descriptions of possible values.

inDepth

A signed 16-bit integer. Pass a value specifying the bit depth (in bits per pixel) of the current graphics port.

inColorDev

A value of type Boolean. Pass true to indicate that you are drawing on a color device. Pass false for a monochrome device.

outColor

A pointer to a structure of type RGBColor. On return, the structure contains the text color used for the specified element under the current theme.

Return Value

A result code. See “Appearance Manager Result Codes.”

Discussion

Also see the function SetThemeTextColor.

Availability
Declared In
Appearance.h

GetThemeTextShadowOutset

Tells you the amount of space taken up by the shadow for a given font and drawing state combination.

OSStatus GetThemeTextShadowOutset (
   ThemeFontID inFontID,
   ThemeDrawState inState,
   Rect *outOutset
);

Parameters
inFontID

The ThemeFontID describing the font you'd like the shadow characteristics of. Font and drawing state both determine the amount of shadow that will be used on rendered text. See “Theme Font IDs” for the values you can use here.

inState

The ThemeDrawState which matches the drawing state you'd like the shadow characteristics of. Font and state both determine the amount of shadow that will be used on rendered text. See “Theme Drawing States” for the values you can use here.

outOutset

On output, this parameter contains the amount of space the shadow will take up beyond each edge of the text bounding rectangle returned by GetThemeTextDimensions. The fields of this parameter will either be positive values or zero.

Return Value

A result code. See “Appearance Manager Result Codes.”

Discussion

GetThemeTextShadowOutset passes back the maximum amount of space the shadow will take up for text drawn in the specified font and state. While GetThemeTextDimensions tells you how much space is taken up by the character glyphs themselves, it does not incorporate the font or state shadow into its calculations. If you need to know how much total space including the shadow will be taken up, call GetThemeTextDimensions followed by GetThemeTextShadowOutset.

Availability
Declared In
Appearance.h

NormalizeThemeDrawingState

Sets the current graphics port to a default drawing state.

OSStatus NormalizeThemeDrawingState (
   void
);

Return Value

A result code. See “Appearance Manager Result Codes.”

Discussion

The NormalizeThemeDrawingState function sets the background of a graphics port to white; the pen of the port to a size of 1 pixel by 1 pixel, a pattern mode of patCopy, and a pattern of black; and the text mode of the port to srcOr. NormalizeThemeDrawingState also flushes from memory any color foreground or background patterns saved in the port’s GrafPort.pnPat or GrafPort.bkPat fields, respectively.

Availability
Declared In
Appearance.h

PlayThemeSound

Plays an asynchronous sound associated with the specified state change.

OSStatus PlayThemeSound (
   ThemeSoundKind kind
);

Parameters
kind

A value of type ThemeSoundKind. Pass a constant specifying the sound to play; see “Theme Sounds” for descriptions of possible values.

Return Value

A result code. See “Appearance Manager Result Codes.”

Discussion

The Appearance Manager automatically plays theme sounds for standard user interface elements. Your application can call the PlayThemeSound function to play a theme sound for a custom element. The sound plays asynchronously until complete, stopping automatically.

Special Considerations

This function is not implemented in Mac OS X.

Availability
Declared In
Appearance.h

SetAnimatedThemeCursor

Animates a version of the specified cursor type that is consistent with the current theme.

OSStatus SetAnimatedThemeCursor (
   ThemeCursor inCursor,
   UInt32 inAnimationStep
);

Parameters
inCursor

A value of type ThemeCursor. Pass a constant specifying the type of cursor to set; see “Theme Cursors” for a description of the possible values. Note that only cursors designated as able to be animated should be used for this function. If you specify an unanimatable cursor type, SetAnimatedThemeCursor returns the error themeBadCursorIndexErr (–30565).

inAnimationStep

An unsigned 32-bit value. Pass a value specifying the current animation step of the cursor. To animate the cursor, increment the value by 1 with each call to SetAnimatedThemeCursor.

Return Value

A result code. See “Appearance Manager Result Codes.”

Discussion

Appearance Manager 1.1 introduces cursors that can change appearance with a theme change. In order to be theme-compliant, your program should use these theme-specific cursors whenever possible, instead of the classic black-and-white cursors.

Your application should call the SetAnimatedThemeCursor function to ensure that its animated cursors are theme-compliant, rather than using any QuickDraw cursor utilities functions such as SetCursor, SetCCursor, SpinCursor, or RotateCursor. If you wish a non-animated cursor to be theme-compliant, call the function SetThemeCursor.

Because these are color cursors, they currently cannot be set from interrupt time. Therefore, if you support animated cursors that are changed at interrupt time you should continue to use your own cursors for now.

Special Considerations

Do not call SetAnimatedThemeCursor at interrupt time.

Availability
Declared In
Appearance.h

SetThemeCursor

Sets the cursor to a version of the specified cursor type that is consistent with the current theme.

OSStatus SetThemeCursor (
   ThemeCursor inCursor
);

Parameters
inCursor

A value of type ThemeCursor. Pass a constant specifying the type of cursor to set; see “Theme Cursors” for a description of possible values.

Return Value

A result code. See “Appearance Manager Result Codes.”

Discussion

Appearance Manager 1.1 introduces cursors that can change appearance with a theme change. In order to be theme-compliant, your program should use these theme-specific cursors whenever possible, instead of the classic black-and-white cursors. Because these are color cursors, they currently cannot be set from interrupt time.

Your application should call the SetThemeCursor function to ensure that its cursors are theme-compliant, rather than the QuickDraw cursor utilities functions SetCursor or SetCCursor. If you wish an animatable cursor to be theme-compliant, call the function SetAnimatedThemeCursor.

Special Considerations

Do not call SetThemeCursor at interrupt time.

Availability
Declared In
Appearance.h

SetThemeDrawingState

Sets the drawing state of the current graphics port.

OSStatus SetThemeDrawingState (
   ThemeDrawingState inState,
   Boolean inDisposeNow
);

Parameters
inState

A value of type ThemeDrawingState. Pass a ThemeDrawingState value such as that produced in the outState parameter of GetThemeDrawingState.

inDisposeNow

A value of type Boolean. Pass a value of true to release the memory allocated for the drawing state reference. Pass false if you wish to continue using the drawing state and do not want to dispose of the memory at this time; you must call DisposeThemeDrawingState to dispose of the memory any time before your application terminates.

Return Value

A result code. See “Appearance Manager Result Codes.”

Discussion

Your application can save the port state by calling the function GetThemeDrawingState and restore the port state by calling the function SetThemeDrawingState, supplying the value obtained in the outState parameter of GetThemeDrawingState, after you have completed all of your drawing.

Availability
Declared In
Appearance.h

Callbacks

MenuItemDrawingProcPtr

Draws a menu item.

typedef void ( *MenuItemDrawingProcPtr)
(
   const Rect * inBounds,
   SInt16 inDepth,
   Boolean inIsColorDevice,
   SInt32 inUserData
);

If you name your function MyMenuItemDrawingCallback, you would declare it like this:

void MyMenuItemDrawingCallback (
   const Rect * inBounds,
   SInt16 inDepth,
   Boolean inIsColorDevice,
   SInt32 inUserData
);

Parameters
inBounds

A pointer to a structure of type Rect. You are passed a rectangle specifying the dimensions and position in which you should draw your menu item content. Your menu item drawing function is called clipped to the rectangle in which you are allowed to draw your content; do not draw outside this region.

inDepth

A signed 16-bit integer. You are passed the bit depth (in bits per pixel) of the current graphics port.

inIsColorDevice

A value of type Boolean. You are passed true to indicate that you are drawing on a color device; inIsColorDevice is false for a monochrome device.

inUserData

You are passed data specifying how to draw the menu item content from the inUserData parameter of DrawThemeMenuItem.

Discussion

At the time your menu item drawing function is called, the foreground text color and mode is already set to draw in the correct state (enabled, selected, disabled) and correct color for the theme. You do not need to set the color unless you have special drawing needs. If you do have special drawing needs, you should supply the inDepth value and the value of the inIsColorDevice parameter to the function IsThemeInColor to determine whether or not you should draw the menu item content in color.

Note that the Appearance Manager calls your MyMenuItemDrawingCallback function for every device that the inBounds rectangle intersects.

You should refer to your MyMenuItemDrawingCallback function using a MenuItemDrawingUPP, which you can create with NewMenuItemDrawingUPP.

You typically use the NewMenuItemDrawingUPP function like this:

MenuItemDrawingUPP myMenuItemDrawingUPP;
myMenuItemDrawingUPP = NewMenuItemDrawingUPP(MyMenuItemDrawingCallback);
Special Considerations

The Appearance Manager draws the background of the menu item prior to calling your menu item drawing function, so you should not erase the item’s background from this function.

Version Notes

This function is available with Appearance Manager 1.0.1 and later.

Availability
Declared In
Appearance.h