ADC Home > Reference Library > Reference > Carbon > User Experience > Appearance Manager Reference >

< Previous PageNext Page > Hide TOC

Deprecated Appearance Manager Functions

A function identified as deprecated has been superseded and may become unsupported in the future.

Deprecated in Mac OS X v10.5

ApplyThemeBackground

Sets the background color or pattern of the current port to be consistent with that of an embedding object. (Deprecated in Mac OS X v10.5. Use HIThemeApplyBackground instead.)

OSStatus ApplyThemeBackground (
   ThemeBackgroundKind inKind,
   const Rect *bounds,
   ThemeDrawState inState,
   SInt16 inDepth,
   Boolean inColorDev
);

Parameters
inKind

A value of type ThemeBackgroundKind. Pass a constant specifying the type of embedding object. See “Theme Backgrounds” for descriptions of possible values.

bounds

A pointer to a structure of type Rect. Before calling ApplyThemeBackground, set the rectangle to a size and position that contains the embedding object, in local coordinates.

inState

A value of type ThemeDrawState. Pass a constant specifying the current state of the embedding object. See “Theme Drawing States” 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, or false for a monochrome device.

Return Value

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

Discussion

The ApplyThemeBackground function sets the background color or pattern of the current port to match the background of an embedding object, such as a placard or tab control. Your application should call ApplyThemeBackground before erasing the background of your application’s content to ensure that the content background matches that of the object in which it is visually embedded.

ApplyThemeBackground aligns patterns based on the rectangle passed in the bounds parameter. This is in contrast to the function SetThemeBackground, which aligns patterns based on the origin of the current port.

You do not need to call ApplyThemeBackground if your content is an embedded part within a control hierarchy and is logically as well as visually embedded in its container; in this case, the Control Manager automatically requests the embedding control to set up the background before drawing the embedded control.

If you have a custom control definition function that erases its background before drawing, you should use the Control Manager function SetUpControlBackground before erasing. SetUpControlBackground calls ApplyThemeBackground if necessary.

Availability
Declared In
Appearance.h

DisposeMenuItemDrawingUPP

Disposes of the UPP to a menu item drawing function. (Deprecated in Mac OS X v10.5. There is no replacement function.)

void DisposeMenuItemDrawingUPP (
   MenuItemDrawingUPP userUPP
);

Parameters
userUPP

The UPP to dispose of.

Availability
Declared In
Appearance.h

DisposeMenuTitleDrawingUPP

Disposes of the UPP to a menu title drawing function. (Deprecated in Mac OS X v10.5. There is no replacement function.)

void DisposeMenuTitleDrawingUPP (
   MenuTitleDrawingUPP userUPP
);

Parameters
userUPP

The UPP to dispose of.

Availability
Declared In
Appearance.h

DisposeThemeButtonDrawUPP

Disposes of the UPP to a button drawing function. (Deprecated in Mac OS X v10.5. There is no replacement function.)

void DisposeThemeButtonDrawUPP (
   ThemeButtonDrawUPP userUPP
);

Parameters
userUPP

The UPP to dispose of.

Availability
Declared In
Appearance.h

DisposeThemeEraseUPP

Disposes of the UPP to a background drawing callback function. (Deprecated in Mac OS X v10.5. There is no replacement function.)

void DisposeThemeEraseUPP (
   ThemeEraseUPP userUPP
);

Parameters
userUPP

The UPP to dispose of.

Availability
Declared In
Appearance.h

DisposeThemeIteratorUPP

Disposes of the UPP to a theme iteration callback function. (Deprecated in Mac OS X v10.5. There is no replacement function.)

void DisposeThemeIteratorUPP (
   ThemeIteratorUPP userUPP
);

Parameters
userUPP

The UPP to dispose of.

Availability
Declared In
Appearance.h

DisposeThemeTabTitleDrawUPP

Disposes of the UPP to a tab title drawing function. (Deprecated in Mac OS X v10.5. There is no replacement function.)

void DisposeThemeTabTitleDrawUPP (
   ThemeTabTitleDrawUPP userUPP
);

Parameters
userUPP

The UPP to dispose of.

Availability
Declared In
Appearance.h

DisposeWindowTitleDrawingUPP

Disposes of the UPP to a window title drawing function. (Deprecated in Mac OS X v10.5. There is no replacement function.)

void DisposeWindowTitleDrawingUPP (
   WindowTitleDrawingUPP userUPP
);

Parameters
userUPP

The UPP to dispose of.

Availability
Declared In
Appearance.h

DrawThemeButton

Draws a button. (Deprecated in Mac OS X v10.5. Use HIThemeDrawButton instead.)

OSStatus DrawThemeButton (
   const Rect *inBounds,
   ThemeButtonKind inKind,
   const ThemeButtonDrawInfo *inNewInfo,
   const ThemeButtonDrawInfo *inPrevInfo,
   ThemeEraseUPP inEraseProc,
   ThemeButtonDrawUPP inLabelProc,
   URefCon inUserData
);

Parameters
inBounds

A pointer to a structure of type Rect. Pass a rectangle specifying the boundary of the button, in local coordinates.

inKind

A value of type ThemeButtonKind. Pass a constant specifying the type of button to draw. See “Theme Buttons” for descriptions of possible values.

inNewInfo

A pointer to a structure of type ThemeButtonDrawInfo. Before calling DrawThemeButton, set the structure to contain the new state, value, and adornment for the button. DrawThemeButton uses the information passed in the inNewInfo and inPrevInfo parameters to apply transitional animation or sound effects as the button state changes, if such are specified under the current theme.

inPrevInfo

A pointer to a structure of type ThemeButtonDrawInfo. If the button state is changing, set the structure to contain the previous state, value, and adornment for the button, to allow DrawThemeButton to apply any transitional effects. If the button state is not changing, you can pass NULL.

inEraseProc

A value of type ThemeEraseUPP. If you have a custom background, use this parameter to pass a universal function pointer to an application-defined function such as that described in ThemeEraseProcPtr. DrawThemeButton calls this function to erase the background before drawing the button. If you pass NULL, DrawThemeButton's default behavior is to erase the background for you.

inLabelProc

A value of type ThemeButtonDrawUPP. If you pass a universal function pointer to an application-defined function such as that described in ThemeButtonDrawProcPtr, DrawThemeButton calls that function to draw the label of the button. If you pass NULL, no label is drawn.

inUserData

An unsigned 32-bit integer. Provide any data to be passed in to the callback functions specified in the inLabelProc and inEraseProc parameters. Pass NULL if you do not wish to provide any data.

Return Value

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

Discussion

The DrawThemeButton function draws a theme-compliant button. If a ThemeEraseProcPtr is specified in the inEraseProc parameter, DrawThemeButton uses that function to erase the background of the button before drawing the button. After the button is drawn, if a ThemeButtonDrawProcPtr is specified in the inLabelProc parameter, DrawThemeButton calls that function to draw the button’s label.

Note that DrawThemeButton also draws any appearance adornments for the button and that these can extend beyond the button’s basic bounding rectangle, as specified in the inBounds parameter, and may be of variable shape. You may therefore wish to call the function GetThemeButtonBackgroundBounds to obtain the actual rectangle containing the pixels belonging to a button under the current theme.

Availability
Declared In
Appearance.h

DrawThemeChasingArrows

Draws an asynchronous arrows indicator. (Deprecated in Mac OS X v10.5. Use HIThemeDrawChasingArrows instead.)

OSStatus DrawThemeChasingArrows (
   const Rect *bounds,
   UInt32 index,
   ThemeDrawState state,
   ThemeEraseUPP eraseProc,
   URefCon eraseData
);

Parameters
bounds

A pointer to a structure of type Rect. Before calling DrawThemeChasingArrows, set the rectangle to contain the asynchronous arrows, in local coordinates.

index

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

state

A value of type ThemeDrawState. Pass a constant specifying the state in which to draw the asynchronous arrows indicator; see “Theme Drawing States.” The asynchronous arrows indicator can be drawn as active or inactive; passing kThemeStatePressed produces an error.

eraseProc

A value of type ThemeEraseUPP. If you have a custom background, pass a universal function pointer to an application-defined function such as that described in ThemeEraseProcPtr. DrawThemeChasingArrows calls that function to erase the background before drawing the asynchronous arrows. If you pass NULL, no erasing occurs.

eraseData

An unsigned 32-bit integer. Provide any data to be passed in to the eraseData parameter of the callback function specified in the eraseProc parameter.

Return Value

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

Discussion

The DrawThemeChasingArrows function draws a theme-compliant asynchronous arrows (also known as “chasing arrows”) indicator.

Availability
Declared In
Appearance.h

DrawThemeEditTextFrame

Draws an editable text frame. (Deprecated in Mac OS X v10.5. Use HIThemeDrawFrame instead.)

OSStatus DrawThemeEditTextFrame (
   const Rect *inRect,
   ThemeDrawState inState
);

Parameters
inRect

A pointer to a structure of type Rect. Before calling DrawThemeEditTextFrame, set the rectangle to the position around which to draw the editable text frame, in local coordinates.

inState

A value of type ThemeDrawState. Pass a constant specifying the state in which to draw the editable text frame; see “Theme Drawing States.” The frame can be drawn as active or inactive; passing kThemeStatePressed produces an error.

Return Value

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

Discussion

The DrawThemeEditTextFrame function draws a theme-compliant frame for an editable text field. The frame is a maximum of 2 pixels thick and is drawn outside the specified rectangle. You should not use this function to draw frames for items other than editable text fields.

To ensure that you get an appropriate focus ring for your editable text field, you should pass the same rectangle that you use with DrawThemeEditTextFrame function to the function DrawThemeFocusRect.

Availability
Declared In
Appearance.h

DrawThemeFocusRect

Draws or erases a focus ring around a specified rectangle. (Deprecated in Mac OS X v10.5. Use HIThemeDrawFocusRect instead.)

OSStatus DrawThemeFocusRect (
   const Rect *inRect,
   Boolean inHasFocus
);

Parameters
inRect

A pointer to a structure of type Rect. Before calling DrawThemeFocusRect, set the rectangle to the position around which to draw the focus ring, in local coordinates. The focus ring is drawn outside the rectangle that is passed in, and it can be outset a maximum of 3 pixels.

inHasFocus

A value of type Boolean. Pass true to draw the focus ring. Pass false to erase the focus ring.

Return Value

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

Discussion

Your application can use the DrawThemeFocusRect function to draw a theme-compliant focus ring. The presence of a focus ring indicates whether an item has keyboard focus.

If you are drawing a focus ring around an element for which you have drawn a frame using DrawThemeEditTextFrame or DrawThemeListBoxFrame, you must coordinate your drawing sequence to achieve the correct look. When drawing the element, your application should first call DrawThemeEditTextFrame or DrawThemeListBoxFrame and then call DrawThemeFocusRect, passing the same rectangle in the inRect parameter. If you use DrawThemeFocusRect to erase the focus ring around an editable text frame or list box frame, you must redraw the editable text frame or list box frame after calling DrawThemeFocusRect, because there is typically an overlap.

Availability
Declared In
Appearance.h

DrawThemeFocusRegion

Draws or erases a focus ring around a specified region. (Deprecated in Mac OS X v10.5. Use HIThemeDrawFocusRect instead.)

OSStatus DrawThemeFocusRegion (
   RgnHandle inRegion,
   Boolean inHasFocus
);

Parameters
inRegion

A value of type RgnHandle. Before calling DrawThemeFocusRegion, set the region to the position around which to draw the focus ring, in local coordinates. The focus ring is drawn outside the region that is passed in, and it can be outset a maximum of 3 pixels.

inHasFocus

A value of type Boolean. Pass true to draw the focus region. Pass false to erase the focus region.

Return Value

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

Discussion

Your application can use the DrawThemeFocusRegion function to draw a theme-compliant focus ring. The presence of a focus ring indicates whether an item has keyboard focus.

Availability
Declared In
Appearance.h

DrawThemeGenericWell

Draws an image well frame. (Deprecated in Mac OS X v10.5. Use HIThemeDrawGenericWell instead.)

OSStatus DrawThemeGenericWell (
   const Rect *inRect,
   ThemeDrawState inState,
   Boolean inFillCenter
);

Parameters
inRect

A pointer to a structure of type Rect. Before calling DrawThemeGenericWell, set the rectangle to the position around which to draw the image well frame, in local coordinates.

inState

A value of type ThemeDrawState. Pass a constant specifying the state in which to draw the image well frame; see “Theme Drawing States.” The well can be drawn as active or inactive; passing kThemeStatePressed produces an error.

inFillCenter

A value of type Boolean. Set to true to fill the image well frame with white; otherwise, false.

Return Value

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

Discussion

The DrawThemeGenericWell function draws a theme-compliant image well frame. You can specify that the center of the well be filled in with white.

Availability
Declared In
Appearance.h

DrawThemeListBoxFrame

Draws a list box frame. (Deprecated in Mac OS X v10.5. Use HIThemeDrawFrame instead.)

OSStatus DrawThemeListBoxFrame (
   const Rect *inRect,
   ThemeDrawState inState
);

Parameters
inRect

A pointer to a structure of type Rect. Before calling DrawThemeListBoxFrame, set the rectangle to the position around which to draw the list box frame, in local coordinates.

inState

A value of type ThemeDrawState. Pass a constant specifying the state in which to draw the list box frame; see “Theme Drawing States.” The frame can be drawn as active or inactive; passing kThemeStatePressed produces an error.

Return Value

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

Discussion

The DrawThemeListBoxFrame function draws a theme-compliant list box frame. The frame is a maximum of 2 pixels thick and is drawn outside the specified rectangle. To ensure that you get an appropriate focus ring for your list box, you should pass the same rectangle that you use with the DrawThemeListBoxFrame function to the function DrawThemeFocusRect.

Availability
Declared In
Appearance.h

DrawThemeMenuBackground

Draws a menu background. (Deprecated in Mac OS X v10.5. Use HIThemeDrawMenuBackground instead.)

OSStatus DrawThemeMenuBackground (
   const Rect *inMenuRect,
   ThemeMenuType inMenuType
);

Parameters
inMenuRect

A pointer to a structure of type Rect. Before calling DrawThemeMenuBackground, set the rectangle to contain the entire menu, in global coordinates.

inMenuType

A value of type ThemeMenuType. Pass a constant specifying the type of menu for which to draw a background; see “Theme Menu Types” for descriptions of possible values.

Return Value

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

Discussion

The DrawThemeMenuBackground function draws a theme-compliant menu background in the specified rectangle.

Availability
Declared In
Appearance.h

DrawThemeMenuBarBackground

Draws a menu bar background. (Deprecated in Mac OS X v10.5. Use HIThemeDrawMenuBarBackground instead.)

OSStatus DrawThemeMenuBarBackground (
   const Rect *inBounds,
   ThemeMenuBarState inState,
   UInt32 inAttributes
);

Parameters
inBounds

A pointer to a structure of type Rect. Before calling DrawThemeMenuBarBackground, set the rectangle to specify the menu bar’s initial size and location, in global coordinates.

inState

A value of type ThemeMenuBarState. Pass a constant specifying the state (active or selected) in which to draw the menu bar; see “Theme Menu Bar States.”

inAttributes

A value indicating the attributes of the menu bar. Pass 0 for a standard menu bar or kThemeMenuSquareMenuBar for a menu bar with square corners.

Return Value

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

Discussion

The DrawThemeMenuBarBackground function draws a theme-compliant menu bar background in the specified rectangle.

Availability
Declared In
Appearance.h

DrawThemeMenuItem

Draws a menu item. (Deprecated in Mac OS X v10.5. Use HIThemeDrawMenuItem instead.)

OSStatus DrawThemeMenuItem (
   const Rect *inMenuRect,
   const Rect *inItemRect,
   SInt16 inVirtualMenuTop,
   SInt16 inVirtualMenuBottom,
   ThemeMenuState inState,
   ThemeMenuItemType inItemType,
   MenuItemDrawingUPP inDrawProc,
   URefCon inUserData
);

Parameters
inMenuRect

A pointer to a structure of type Rect. Before calling DrawThemeMenuItem, set the rectangle to contain the entire menu, in global coordinates. This is the actual menu rectangle as used in your menu definition function.

inItemRect

A pointer to a structure of type Rect. Before calling DrawThemeMenuItem, set the rectangle to contain the menu item, in global coordinates. The menu item’s background is drawn in the rectangle passed in the inItemRect parameter. You should calculate the size of the menu item’s content and then call GetThemeMenuItemExtra to get the amount of padding surrounding menu items in the current theme; the width and height of the menu item rectangle are determined by adding these values together.

inVirtualMenuTop

A signed 16-bit integer. Pass a value representing the actual top of the menu. Normally this value is the top coordinate of the rectangle supplied in the inMenuRect parameter. This value could be different, however, if a menu is scrolled or bigger than can be displayed in the menu rectangle. You typically pass the value of the global variable TopMenuItem into this parameter if you are writing a custom menu definition function.

inVirtualMenuBottom

A signed 16-bit integer. Pass a value representing the actual bottom of the menu. Typically this value is the bottom coordinate of the rectangle supplied in the inMenuRect parameter. This value could be different, however, if a menu is scrolled or bigger than can be displayed in the menu rectangle. You typically pass the value of the global variable AtMenuBottom into this parameter if you are writing a custom menu definition function.

inState

A value of type ThemeMenuState. Pass a constant specifying the state (active, selected, or disabled) in which to draw the menu item; see “Theme Menu States.”

inItemType

A value of type ThemeMenuItemType. If you pass kThemeMenuItemScrollUpArrow or kThemeMenuItemScrollDownArrow, then you should pass NULL for the inDrawProc parameter, since there is no content to be drawn. If you pass kThemeMenuItemHierarchical, the hierarchical arrow is drawn for you. See “Theme Menu Item Types” for descriptions of possible values.

inDrawProc

A value of type MenuItemDrawingUPP. Pass a universal function pointer to a menu item drawing function such as MenuItemDrawingProcPtr. The value of the inDrawProc parameter can be a valid universal function pointer or NULL.

inUserData

An unsigned 32-bit integer. Provide any data to be passed in to the inUserData parameter of MenuItemDrawingProcPtr.

Return Value

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

Discussion

The DrawThemeMenuItem function draws a theme-compliant menu item.

Availability
Declared In
Appearance.h

DrawThemeMenuSeparator

Draws a menu item separator line. (Deprecated in Mac OS X v10.5. Use HIThemeDrawMenuSeparator instead.)

OSStatus DrawThemeMenuSeparator (
   const Rect *inItemRect
);

Parameters
inItemRect

A pointer to a structure of type Rect. Before calling DrawThemeMenuSeparator, set the rectangle to contain the menu item separator to be drawn, in global coordinates. The rectangle should be the same height as the height returned by the function GetThemeMenuSeparatorHeight.

Return Value

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

Discussion

The DrawThemeMenuSeparator function draws a theme-compliant menu item separator line.

Availability
Declared In
Appearance.h

DrawThemeMenuTitle

Draws a menu title. (Deprecated in Mac OS X v10.5. Use HIThemeDrawMenuTitle instead.)

OSStatus DrawThemeMenuTitle (
   const Rect *inMenuBarRect,
   const Rect *inTitleRect,
   ThemeMenuState inState,
   UInt32 inAttributes,
   MenuTitleDrawingUPP inTitleProc,
   URefCon inTitleData
);

Parameters
inMenuBarRect

A pointer to a structure of type Rect. Before calling DrawThemeMenuTitle, set the rectangle to contain the entire menu bar in which the title is to be drawn, in global coordinates. The menu bar background is drawn in the rectangle passed in the inMenuBarRect parameter. Your application can call GetThemeMenuBarHeight to get the height of the menu bar.

inTitleRect

A pointer to a structure of type Rect. Before calling DrawThemeMenuTitle, set the rectangle to contain the menu title, in global coordinates. The title background is drawn in the rectangle passed in the inTitleRect parameter. The width of this rectangle is determined by calculating the width of the menu title’s content and then calling GetThemeMenuTitleExtra to get the amount of padding between menu titles in the current theme; these two values are added together and added to the left edge of where the title should be drawn. The top and bottom coordinates of this rectangle should be the same as those of the inMenuBarRect parameter.

inState

A value of type ThemeMenuState. Pass a constant specifying the state (active, selected, or disabled) in which to draw the menu title; see “Theme Menu States.”

inAttributes

Reserved. Pass 0.

inTitleProc

A value of type MenuTitleDrawingUPP. Pass a universal function pointer to a menu title drawing function such as MenuTitleDrawingProcPtr, defining how to draw the contents of the menu title. The value of the inTitleProc parameter can be a valid universal function pointer or NULL.

inTitleData

An unsigned 32-bit integer. Provide any data to be passed in to the inUserData parameter of MenuTitleDrawingProcPtr.

Return Value

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

Discussion

The DrawThemeMenuTitle function draws a theme-compliant menu title.

Availability
Declared In
Appearance.h

DrawThemeModelessDialogFrame

Draws a beveled outline inside the content area of a modeless dialog box. (Deprecated in Mac OS X v10.5. Use HIThemeDrawWindowFrame instead.)

OSStatus DrawThemeModelessDialogFrame (
   const Rect *inRect,
   ThemeDrawState inState
);

Parameters
inRect

A pointer to a structure of type Rect. Before calling DrawThemeModelessDialogFrame, set the rectangle to the boundary of the window’s content area (that is, its port rectangle), inset by 1 pixel on each side, in local coordinates.

inState

A value of type ThemeDrawState. Pass a constant specifying the state in which to draw the modeless dialog box frame; see “Theme Drawing States” for descriptions of possible values. The frame can be drawn as active or inactive; passing kThemeStatePressed produces an error.

Return Value

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

Discussion

The DrawThemeModelessDialogFrame function draws a beveled frame, no more than 2 pixels wide, that bounds the window’s content area. You can use this function to make a custom modeless dialog box theme-compliant the Dialog Manager automatically draws the interior frame for standard dialog boxes.

If you use DrawThemeModelessDialogFrame to draw a frame for a modeless dialog box, your application must explicitly invalidate and redraw the frame area if the dialog box is resized.

Availability
Declared In
Appearance.h

DrawThemePlacard

Draws a placard. (Deprecated in Mac OS X v10.5. Use HIThemeDrawPlacard instead.)

OSStatus DrawThemePlacard (
   const Rect *inRect,
   ThemeDrawState inState
);

Parameters
inRect

A pointer to a structure of type Rect. Before calling DrawThemePlacard, set the rectangle to a size and position that contains the placard, in local coordinates.

inState

A value of type ThemeDrawState. Pass a constant specifying the state in which to draw the placard; see “Theme Drawing States.” The placard can be drawn as active, inactive, or pressed.

Return Value

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

Discussion

The DrawThemePlacard function draws a theme-compliant placard inside the specified rectangle.

Availability
Declared In
Appearance.h

DrawThemePopupArrow

Draws a pop-up arrow. (Deprecated in Mac OS X v10.5. Use HIThemeDrawPopupArrow instead.)

OSStatus DrawThemePopupArrow (
   const Rect *bounds,
   ThemeArrowOrientation orientation,
   ThemePopupArrowSize size,
   ThemeDrawState state,
   ThemeEraseUPP eraseProc,
   URefCon eraseData
);

Parameters
bounds

A pointer to a structure of type Rect. Before calling DrawThemePopupArrow, set the rectangle to contain the arrow, in local coordinates. DrawThemePopupArrow positions the arrow relative to the top left corner of the rectangle.

orientation

A value of type ThemeArrowOrientation. Pass a constant specifying the direction in which the pop-up arrow points. See “Theme Pop-Up Arrow Orientations” for descriptions of possible values.

size

A value of type ThemePopupArrowSize. Pass a constant specifying the size of the pop-up arrow to draw. See “Theme Pop-Up Arrow Sizes” for descriptions of possible values.

state

A value of type ThemeDrawState. Pass a constant specifying the current state of the button containing the pop-up arrow. See “Theme Drawing States” for descriptions of possible values.

eraseProc

A value of type ThemeEraseUPP. If you have a custom background, pass a universal function pointer to an application-defined function such as that described in ThemeEraseProcPtr. DrawThemePopupArrow calls that function to erase the background before drawing the pop-up arrow. If you pass NULL, no erasing occurs.

eraseData

An unsigned 32-bit integer. Provide any data to be passed in to the eraseData parameter of the callback function specified in the eraseProc parameter.

Return Value

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

Discussion

The DrawThemePopupArrow function draws a theme-compliant pop-up arrow. A pop-up arrow is an image drawn onto another control to indicate that when the control is clicked, you get a pop-up menu. A pop-up arrow is not a separate button itself. Typically, a pop-up arrow is used in conjunction with a button, such as a push button or bevel button. Bevel button controls automatically draw a pop-up arrow if a menu is associated with the control.

Availability
Declared In
Appearance.h

DrawThemePrimaryGroup

Draws a primary group box frame. (Deprecated in Mac OS X v10.5. Use HIThemeDrawGroupBox instead.)

OSStatus DrawThemePrimaryGroup (
   const Rect *inRect,
   ThemeDrawState inState
);

Parameters
inRect

A pointer to a structure of type Rect. Before calling DrawThemePrimaryGroup, set the rectangle to the bounds of the primary group box frame, in local coordinates.

inState

A value of type ThemeDrawState. Pass a constant specifying the state in which to draw the primary group box frame; see “Theme Drawing States.” The frame can be drawn as active or inactive; passing kThemeStatePressed produces an error.

Return Value

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

Discussion

The DrawThemePrimaryGroup function draws a theme-compliant primary group box frame. The primary group box frame is drawn inside the specified rectangle and is a maximum of 2 pixels thick.

Availability
Declared In
Appearance.h

DrawThemeScrollBarArrows

Draws scroll bar arrows consistent with the current system preferences. (Deprecated in Mac OS X v10.5. Use HIThemeDrawTrack, which draws the entire scrollbar including both the track and arrows.)

OSStatus DrawThemeScrollBarArrows (
   const Rect *bounds,
   ThemeTrackEnableState enableState,
   ThemeTrackPressState pressState,
   Boolean isHoriz,
   Rect *trackBounds
);

Parameters
bounds

A pointer to a structure of type Rect. Before calling DrawThemeScrollBarArrows, set the rectangle to contain the scroll bar for which to draw arrows, in local coordinates. Typically, the rectangle you specify is the entire base control rectangle—that is, the value contained in the contrlRect field of the scroll bar’s ControlRecord structure.

enableState

A value of type ThemeTrackEnableState. Pass a constant specifying the current state of the scroll bar; see “Theme Track States” for descriptions of possible values.

pressState

A value of type ThemeTrackPressState. Pass a constant specifying what is pressed in an active scroll bar or 0 if nothing is pressed. The press state is ignored if the scroll bar is not active. See “Theme Track Press States” for descriptions of possible values.

isHoriz

A value of type Boolean. Pass true if the scroll bar is horizontal; pass false if it is vertical.

trackBounds

A pointer to a structure of type Rect. On return, the rectangle is set to the bounds of the track portion of the scroll bar; this rectangle excludes the area containing the scroll bar arrows. Pass NULL if you do not wish to obtain this information.

Return Value

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

Discussion

The DrawThemeScrollBarArrows function draws a set of theme-compliant scroll bar arrows for the scroll bar whose position and dimensions are specified in the bounds parameter. Depending upon the current system preferences, DrawThemeScrollBarArrows draws the arrows in one of the following configurations:

Availability
Declared In
Appearance.h

DrawThemeScrollBarDelimiters

Outlines a window’s scroll bars. (Deprecated in Mac OS X v10.5. Use HIThemeDrawScrollBarDelimiters instead.)

OSStatus DrawThemeScrollBarDelimiters (
   ThemeWindowType flavor,
   const Rect *inContRect,
   ThemeDrawState state,
   ThemeWindowAttributes attributes
);

Parameters
flavor

A value of type ThemeWindowType. Pass a constant specifying the type of window for which to draw scroll bar delimiters. See “Theme Window Types” for descriptions of possible values.

inContRect

A pointer to a structure of type Rect. Before calling DrawThemeScrollBarDelimiters, set the rectangle to the boundary of the content rectangle of the window, in local coordinates.

state

A value of type ThemeDrawState. Pass a constant—either kThemeStateActive or kThemeStateInactive—appropriate to the current state of the window. The scroll bar delimiters can be drawn as active or inactive passing kThemeStatePressed produces an error. See “Theme Drawing States” for descriptions of these values.

attributes

A value of type ThemeWindowAttributes. Pass one or more constants corresponding to the window’s current visual attributes. See “Theme Window Attributes” for descriptions of possible values. Pass 0 if the window has none of the enumerated attributes.

Return Value

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

Discussion

The DrawThemeScrollBarDelimiters function draws theme-compliant outlines for both the horizontal and vertical scroll bars in a given window. The scroll bars are each assumed to cover the full length of their respective sides of the window’s content region if the scroll bars for which you wish delimiters to be drawn are not full length, or if only one scroll bar exists for a given window, DrawThemeScrollBarDelimiters should not be used.

Availability
Declared In
Appearance.h

DrawThemeSecondaryGroup

Draws a secondary group box frame. (Deprecated in Mac OS X v10.5. Use HIThemeDrawGroupBox instead.)

OSStatus DrawThemeSecondaryGroup (
   const Rect *inRect,
   ThemeDrawState inState
);

Parameters
inRect

A pointer to a structure of type Rect. Before calling DrawThemeSecondaryGroup, set the rectangle to the bounds of the secondary group box frame to be drawn, in local coordinates.

inState

A value of type ThemeDrawState. Pass a constant specifying the state in which to draw the secondary group box frame; see “Theme Drawing States.” The frame can be drawn as active or inactive; passing kThemeStatePressed produces an error.

Return Value

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

Discussion

The DrawThemeSecondaryGroup function draws a theme-compliant secondary group box frame. The secondary group box frame is drawn inside the specified rectangle and is a maximum of 2 pixels thick. Note that a secondary group box frame is typically nested within a primary group box frame.

Availability
Declared In
Appearance.h

DrawThemeSeparator

Draws a separator line. (Deprecated in Mac OS X v10.5. Use HIThemeDrawSeparator instead.)

OSStatus DrawThemeSeparator (
   const Rect *inRect,
   ThemeDrawState inState
);

Parameters
inRect

A pointer to a structure of type Rect. Before calling DrawThemeSeparator, set the rectangle to contain the separator line, in local coordinates. The orientation of the rectangle determines where the separator line is drawn. If the rectangle is wider than it is tall, the separator line is horizontal; otherwise it is vertical.

inState

A value of type ThemeDrawState. Pass a constant specifying the state in which to draw the separator line; see “Theme Drawing States.” The separator line can be drawn as active or inactive; passing kThemeStatePressed produces an error.

Return Value

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

Discussion

The DrawThemeSeparator function draws a theme-compliant separator line. The separator line is a maximum of 2 pixels thick and is drawn inside the specified rectangle.

Availability
Declared In
Appearance.h

DrawThemeStandaloneGrowBox

Draws a size box. (Deprecated in Mac OS X v10.5. Use HIThemeDrawGrowBox instead.)

OSStatus DrawThemeStandaloneGrowBox (
   Point origin,
   ThemeGrowDirection growDirection,
   Boolean isSmall,
   ThemeDrawState state
);

Parameters
origin

A structure of type Point. Pass the origin point of the size box rectangle. For example, the origin point of the size box for an object that can grow downward and to the right is the size box’s upper-left corner. Typically, you use the coordinates of the corner of whatever object owns the size box for the origin value. For example, if you are drawing a scrolling list that can grow downward and to the right, the origin value would be the coordinates of the bottom-right corner of the list.

growDirection

A value of type ThemeGrowDirection. Pass a constant specifying the direction(s) in which the resizeable object can grow. See “Theme Size Box Directions” for descriptions of possible values. The Appearance Manager uses the growDirection parameter to establish which corner of the size box is the origin.

isSmall

A value of type Boolean. Pass a value of true to specify a small size box (typically for use with small scroll bars) or false to specify a standard size box.

state

A value of type ThemeDrawState. Pass a constant—either kThemeStateActive or kThemeStateInactive—appropriate to the current state of the size box the size box cannot be drawn as pressed. See “Theme Drawing States” for descriptions of these values.

Return Value

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

Discussion

The DrawThemeStandaloneGrowBox function draws a theme-compliant size box that is suitable for use inside the content area of a window. The image is designed to fit between scroll bars and does not have to be abutted with the window frame.

Also see the function DrawThemeStandaloneNoGrowBox.

Availability
Declared In
Appearance.h

DrawThemeStandaloneNoGrowBox

Draws a fill image for use in the corner space between scroll bars. (Deprecated in Mac OS X v10.5. Use HIThemeDrawGrowBox instead.)

OSStatus DrawThemeStandaloneNoGrowBox (
   Point origin,
   ThemeGrowDirection growDirection,
   Boolean isSmall,
   ThemeDrawState state
);

Parameters
origin

A structure of type Point. Pass the origin point of the rectangle in which to draw the image. Typically, you use the coordinates of the corner of whatever object owns the image for the origin value. For example, if you are drawing the image in the bottom-right corner of a window between the scroll bars of a non-resizeable scrolling list, the origin value would be the coordinates of the bottom-right corner of the list.

growDirection

A value of type ThemeGrowDirection. See “Theme Size Box Directions” for descriptions of possible values. The Appearance Manager uses the growDirection parameter to establish which corner of the rectangle that contains the image is the origin.

isSmall

A value of type Boolean. Pass a value of true to specify a small image (for use with small scroll bars) or false to specify a large image (for use with standard scroll bars).

state

A value of type ThemeDrawState. Pass a constant—either kThemeStateActive or kThemeStateInactive—appropriate to the current state of the window containing the fill image the image cannot be drawn as pressed. See “Theme Drawing States” for descriptions of these values.

Return Value

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

Discussion

The DrawThemeStandaloneNoGrowBox function draws a theme-compliant image for use as filler in the corner space between scroll bars that

Also see the function DrawThemeStandaloneGrowBox.

Availability
Declared In
Appearance.h

DrawThemeTab

Draws a tab. (Deprecated in Mac OS X v10.5. Use HIThemeDrawTab instead.)

OSStatus DrawThemeTab (
   const Rect *inRect,
   ThemeTabStyle inStyle,
   ThemeTabDirection inDirection,
   ThemeTabTitleDrawUPP labelProc,
   URefCon userData
);

Parameters
inRect

A pointer to a structure of type Rect. Before calling DrawThemeTab, set the rectangle to the bounds of the tab, in local coordinates. There are two standard sizes (or heights) for tabs that should be used in your calculation of the tab rectangle—these are measured by the distance the tabs protrude from the pane. Small tabs have a height of 16 pixels large tabs have a height of 21 pixels. (The widths of tabs are variable.) Additionally, the distance that the tab overlaps the pane must be included in the tab rectangle this overlap distance is always 3 pixels, although the 3-pixel overlap is only drawn for the front tab. The tab rectangle should reflect the orientation of the tab that is specified in the inDirection parameter.

inStyle

A value of type ThemeTabStyle. Pass a constant specifying the relative position (front or non-front) and state of the tab. See “Theme Tab Styles” for descriptions of possible values.

inDirection

A value of type ThemeTabDirection. Pass a constant specifying the direction in which to orient the tab. See “Theme Tab Directions” for descriptions of possible values.

labelProc

A value of type ThemeTabTitleDrawUPP. Pass a universal function pointer to an application-defined function such as that described in ThemeTabTitleDrawProcPtr. DrawThemeTab calls your function to draw the title of the tab. If you pass NULL, no drawing occurs.

userData

An unsigned 32-bit integer. Provide any data to be passed in to the userData parameter of the callback function specified in the labelProc parameter.

Return Value

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

Discussion

The DrawThemeTab function draws a theme-compliant tab. A tab control consists of two basic components: multiple tabs that label the various content pages that can be displayed and a single pane upon which the content for each tab is drawn. Use the function DrawThemeTabPane to draw the tab pane. The Appearance Manager coordinates the appearance of the pane and frontmost tab automatically.

Availability
Declared In
Appearance.h

DrawThemeTabPane

Draws a tab pane. (Deprecated in Mac OS X v10.5. Use HIThemeDrawTabPane instead.)

OSStatus DrawThemeTabPane (
   const Rect *inRect,
   ThemeDrawState inState
);

Parameters
inRect

A pointer to a structure of type Rect. Before calling DrawThemeTabPane, set the rectangle to the bounds of the tab pane, in local coordinates.

inState

A value of type ThemeDrawState. Pass a constant specifying the state in which to draw the tab pane; see “Theme Drawing States.” The tab pane can be drawn as active or inactive; passing kThemeStatePressed produces an error.

Return Value

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

Discussion

The DrawThemeTabPane function draws a theme-compliant tab pane. A tab control consists of two basic components: multiple tabs that label the various content pages that can be displayed and a single pane upon which the content for each tab is drawn. Use the function DrawThemeTab to draw the tab. The Appearance Manager coordinates the appearance of the pane and frontmost tab automatically.

Availability
Declared In
Appearance.h

DrawThemeTextBox

Draws text into the area you specify. (Deprecated in Mac OS X v10.5. Use HIThemeDrawTextBox instead.)

OSStatus DrawThemeTextBox (
   CFStringRef inString,
   ThemeFontID inFontID,
   ThemeDrawState inState,
   Boolean inWrapToWidth,
   const Rect *inBoundingBox,
   SInt16 inJust,
   CGContextRef inContext
);

Parameters
inString

A CFStringRef containing the unicode characters you wish to render. You must not pass in a CFStringRef that was allocated with any of the "NoCopy" CFString creation functions; a string created with a "NoCopy" function has transient storage which is incompatible with DrawThemeTextBox's caches.

inFontID

The ThemeFontID describing the font you'd like to render the text with. See “Theme Font IDs” for the values you can use here.

inState

The ThemeDrawState describing the state of the interface element you are drawing the text for. If, for example, you are drawing text for an inactive window, you would pass kThemeStateInactive. The ThemeDrawState is generally only used to determine the shadow characteristics for the text on Mac OS X.

See “Theme Drawing States” for the values you can use here.

Note that the ThemeDrawState does not imply a color. It is not used as a mechanism for graying the text. If you wish to draw grayed text, you must set up the desired gray color and apply it to either the current QuickDraw port or the CGContextRef, as appropriate.

inWrapToWidth

A Boolean value indicating whether you want to draw multiple lines of text wrapped to a bounding box. False indicates that only one line of text should be drawn without any sort of wrapping.

inBoundingBox

The rectangle, in coordinates relative to the current QuickDraw port, describing the area to draw the text within. The first line of text will be top-justified to this rectangle. Wrapping, if desired, will happen at the horizontal extent of this rectangle. Regardless of the amount of text in your CFStringRef, all drawn text will be clipped to this rectangle.

inJust

The horizontal alignment you would like for your text. You can use one of the standard alignment constants from TextEdit.h.

inContext

The CGContextRef into which you would like to draw the text. On Mac OS X, all text drawing happens in CGContextRefs; if you pass NULL, a transient CGContextRef will be allocated and deallocated for use within the single function call. Relying on the system behavior if transiently creating CGContextRefs may result in performance problems. On Mac OS 9, this parameter is ignored.

Return Value

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

Discussion

DrawThemeTextBox allows you to draw theme-savvy —that is, Aqua-savvy on Mac OS X— text. It is unicode savvy, although only partially so under CarbonLib, and allows you to customize certain text rendering characteristics such as the font, wrapping behavior, and justification. The text is drawn into the CGContextRef you provide, or into the current QuickDraw port if no CGContextRef is provided. None of DrawThemeTextBox's parameters imply a color, so you must set up the desired text color separately before calling DrawThemeTextBox. If you provide a CGContextRef, its fill color will be used to draw the text. If you do not provide a CGContextRef, a color based on the current QuickDraw port's foreground color and the grayishTextOr mode, if set, will be used to draw the text.

Availability
Declared In
Appearance.h

DrawThemeTickMark

Draws a tick mark. (Deprecated in Mac OS X v10.5. Use HIThemeDrawTickMark instead.)

OSStatus DrawThemeTickMark (
   const Rect *bounds,
   ThemeDrawState state
);

Parameters
bounds

A pointer to a structure of type Rect. Before calling DrawThemeTickMark, set the rectangle to the position that contains the tick mark, in local coordinates. Note that tick marks are of a fixed—3 pixel by 8 pixel—size.

state

A value of type ThemeDrawState. Pass a constant specifying the state in which to draw the tick mark; see “Theme Drawing States.” The tick mark can be drawn as active or inactive; passing kThemeStatePressed produces an error.

Return Value

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

Discussion

The DrawThemeTickMark function draws a single theme-compliant tick mark. To draw a complete set of tick marks for a track, call the function DrawThemeTrackTickMarks.

Availability
Declared In
Appearance.h

DrawThemeTitleBarWidget

Draws a close box, zoom box, or collapse box. (Deprecated in Mac OS X v10.5. Use HIThemeDrawTitleBarWidget instead.)

OSStatus DrawThemeTitleBarWidget (
   ThemeWindowType flavor,
   const Rect *contRect,
   ThemeDrawState state,
   const ThemeWindowMetrics *metrics,
   ThemeWindowAttributes attributes,
   ThemeTitleBarWidget widget
);

Parameters
flavor

A value of type ThemeWindowType. Pass a constant specifying the type of window for which to draw a title bar item. See “Theme Window Types” for descriptions of possible values.

contRect

A pointer to a structure of type Rect. Before calling DrawThemeTitleBarWidget, specify the rectangle for which you wish to draw a title bar item, in coordinates local to the current port. This rectangle is typically the content rectangle of a window.

state

A value of type ThemeDrawState. Pass a constant— kThemeStateActive, kThemeStateInactive, or kThemeStatePressed—appropriate to the current state of the title bar item. See “Theme Drawing States” for descriptions of these values.

metrics

A pointer to a structure of type ThemeWindowMetrics. Before calling DrawThemeTitleBarWidget, set the structure to contain information describing the window for which you wish to draw a title bar item.

attributes

A value of type ThemeWindowAttributes. Pass one or more constants corresponding to the window’s current visual attributes. See “Theme Window Attributes” for descriptions of possible values. Pass 0 if the window has none of the enumerated attributes.

widget

A value of type ThemeTitleBarWidget. Pass a constant—kThemeWidgetCloseBox, kThemeWidgetZoomBox, or kThemeWidgetCollapseBox—appropriate to the type of title bar item you wish to draw. See “Theme Title Bar Items” for descriptions of these values.

Return Value

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

Discussion

The DrawThemeTitleBarWidget function draws theme-compliant title bar items. Your application should not typically need to call this function; DrawThemeTitleBarWidget is typically of use only for applications that need to draw title bar items of simulated windows. Note that while the DrawThemeWindowFrame function automatically draws all title bar items, your application must call the DrawThemeTitleBarWidget function during tracking, to ensure that the title bar items’ states are drawn correctly.

Availability
Declared In
Appearance.h

DrawThemeTrack

Draws a track. (Deprecated in Mac OS X v10.5. Use HIThemeDrawTrack instead.)

OSStatus DrawThemeTrack (
   const ThemeTrackDrawInfo *drawInfo,
   RgnHandle rgnGhost,
   ThemeEraseUPP eraseProc,
   URefCon eraseData
);

Parameters
drawInfo

A pointer to a structure of type ThemeTrackDrawInfo. Before calling DrawThemeTrack, set the structure to contain the current visual characteristics of the track.

rgnGhost

A value of type RgnHandle. If the track is of a type that contains an indicator, such as a scroll bar or slider, you may pass a handle to the region where DrawThemeTrack is to draw a ghost image of the track indicator. Your application should only use a ghost image with the indicator when a track does not support live feedback. Pass NULL if you do not want to draw a ghost image.

eraseProc

A value of type ThemeEraseUPP. If you have a custom background, pass a universal function pointer to an application-defined function such as that described in ThemeEraseProcPtr. DrawThemeTrack calls that function to erase the background before drawing the track. If you pass NULL, no erasing occurs.

eraseData

An unsigned 32-bit integer. Provide any data to be passed in to the callback function specified in the eraseProc parameter.

Return Value

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

Discussion

Your application may use the DrawThemeTrack function to draw a theme-compliant slider, progress bar, or scroll bar. If you use DrawThemeTrack to draw a scroll bar, use the function DrawThemeScrollBarArrows to draw the scroll bar’s arrows. If you use DrawThemeTrack to draw a slider, use DrawThemeTrackTickMarks to draw any tick marks for the slider.

Availability
Declared In
Appearance.h

DrawThemeTrackTickMarks

Draws tick marks for a track. (Deprecated in Mac OS X v10.5. Use HIThemeDrawTrackTickMarks instead.)

OSStatus DrawThemeTrackTickMarks (
   const ThemeTrackDrawInfo *drawInfo,
   ItemCount numTicks,
   ThemeEraseUPP eraseProc,
   URefCon eraseData
);

Parameters
drawInfo

A pointer to a structure of type ThemeTrackDrawInfo. Before calling DrawThemeTrackTickMarks, set the structure to describe the current visual characteristics of the track. Because, under Appearance Manager 1.1, sliders are the only track type to support tick marks, you should set the kind field of the ThemeTrackDrawInfo structure to kThemeSlider and fill out the remainder of the structure appropriately for a slider track. You should set the bounds field of the ThemeTrackDrawInfo structure to the boundary of the track itself, not including the area that contains the tick marks; you can obtain the actual bounding rectangle of the track by calling the function GetThemeTrackBounds. DrawThemeTrackTickMarks draws the tick marks outside the track’s bounding rectangle, above or below the track depending on the thumb direction indicated by the drawInfo.trackInfo.slider.thumbDir field.

numTicks

A value of type ItemCount. Pass an unsigned 32-bit value specifying the number of tick marks to be drawn.

eraseProc

A value of type ThemeEraseUPP. If you have a custom background, pass a universal function pointer to an application-defined function such as that described in ThemeEraseProcPtr. DrawThemeTrackTickMarks calls that function to erase the background before drawing tick marks. If you pass NULL, no erasing occurs.

eraseData

An unsigned 32-bit integer. Provide any data to be passed in to the callback function specified in the eraseProc parameter.

Return Value

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

Discussion

Your application can call the DrawThemeTrackTickMarks function to draw theme-compliant tick marks for a slider control. (Under Appearance Manager 1.1, sliders are the only track type that supports tick marks.) To draw a track control, call the function DrawThemeTrack. To draw a single tick mark, call the function DrawThemeTickMark.

Availability
Declared In
Appearance.h

DrawThemeWindowFrame

Draws a window frame. (Deprecated in Mac OS X v10.5. Use HIThemeDrawWindowFrame instead.)

OSStatus DrawThemeWindowFrame (
   ThemeWindowType flavor,
   const Rect *contRect,
   ThemeDrawState state,
   const ThemeWindowMetrics *metrics,
   ThemeWindowAttributes attributes,
   WindowTitleDrawingUPP titleProc,
   URefCon titleData
);

Parameters
flavor

A value of type ThemeWindowType. Pass a constant specifying the type of window for which to draw a frame. See “Theme Window Types” for descriptions of possible values.

contRect

A pointer to a structure of type Rect. Before calling DrawThemeWindowFrame, specify the rectangle for which you wish to draw a window frame, in coordinates local to the current port. This rectangle is typically the content rectangle of a window.

state

A value of type ThemeDrawState. Pass a constant—either kThemeStateActive or kThemeStateInactive—appropriate to the current state of the window. See “Theme Drawing States” for descriptions of these values.

metrics

A pointer to a structure of type ThemeWindowMetrics. Before calling DrawThemeWindowFrame, set the structure to describe the window for which to draw a frame.

attributes

A value of type ThemeWindowAttributes. Pass one or more constants corresponding to the window’s current visual attributes. See “Theme Window Attributes” for descriptions of possible values. Pass 0 if the window has none of the enumerated attributes.

titleProc

A value of type WindowTitleDrawingUPP. If you pass the value kThemeWindowHasTitleText in the attributes parameter, you should pass a universal function pointer to an application-defined function such as that described in WindowTitleDrawingProcPtr in the titleProc parameter. DrawThemeWindowFrame calls that function to draw the window’s title. Pass NULL if there is no title to be drawn.

titleData

An unsigned 32-bit integer. Provide any data to be passed in to the userData parameter of the callback function specified in the titleProc parameter.

Return Value

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

Discussion

The DrawThemeWindowFrame function draws a window frame appropriate to the specified window type. You may use DrawThemeWindowFrame to make a custom window theme-compliant.

Availability
Declared In
Appearance.h

DrawThemeWindowHeader

Draws a window header. (Deprecated in Mac OS X v10.5. Use HIThemeDrawHeader instead.)

OSStatus DrawThemeWindowHeader (
   const Rect *inRect,
   ThemeDrawState inState
);

Parameters
inRect

A pointer to a structure of type Rect. Before calling DrawThemeWindowHeader, specify the rectangle containing the window header, in local coordinates.

inState

A value of type ThemeDrawState. Pass a constant specifying the state in which to draw the window header; see “Theme Drawing States.” The header can be drawn as active or inactive; passing kThemeStatePressed produces an error.

Return Value

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

Discussion

The DrawThemeWindowHeader function draws a theme-compliant window header, such as that used by the Finder.

Availability
Declared In
Appearance.h

DrawThemeWindowListViewHeader

Draws a window list view header. (Deprecated in Mac OS X v10.5. Use HIThemeDrawHeader instead.)

OSStatus DrawThemeWindowListViewHeader (
   const Rect *inRect,
   ThemeDrawState inState
);

Parameters
inRect

A pointer to a structure of type Rect. Before calling DrawThemeWindowListViewHeader, specify the rectangle in which to draw the window list view header, in local coordinates.

inState

A value of type ThemeDrawState. Pass a constant specifying the state in which to draw the window list view header; see “Theme Drawing States.” The header can be drawn as active or inactive; passing kThemeStatePressed produces an error.

Return Value

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

Discussion

The DrawThemeWindowListViewHeader function draws a theme-compliant window list view header, such as that used by the Finder. A window list view header is drawn without a line on its bottom edge, so that bevel buttons can be placed against it without overlapping.

Availability
Declared In
Appearance.h

GetThemeAccentColors

Obtains a copy of a theme’s accent colors. (Deprecated in Mac OS X v10.5. There is no replacement function.)

OSStatus GetThemeAccentColors (
   CTabHandle *outColors
);

Parameters
outColors

A pointer to a value of type CTabHandle. On return, the handle refers to a ColorTable structure containing the current accent colors.

Return Value

A result code. GetThemeAccentColors returns the result appearanceThemeHasNoAccents if the current theme has no accent colors.

Discussion

Note that the Appearance Manager does not currently define semantics for any indexes into the color table produced by the GetThemeAccentColors function.

Special Considerations

In Mac OS X, theme accent colors are not supported.

Availability
Declared In
Appearance.h

GetThemeButtonBackgroundBounds

Obtains the rectangle that contains a button. (Deprecated in Mac OS X v10.5. Use HIThemeGetButtonBackgroundBounds instead.)

OSStatus GetThemeButtonBackgroundBounds (
   const Rect *inBounds,
   ThemeButtonKind inKind,
   const ThemeButtonDrawInfo *inDrawInfo,
   Rect *outBounds
);

Parameters
inBounds

A pointer to a structure of type Rect. Before calling GetThemeButtonBackgroundBounds, set the rectangle to the boundary of the button without any adornments, in local coordinates.

inKind

A value of type ThemeButtonKind. Pass a constant specifying the type of button being examined. See “Theme Buttons” for descriptions of possible values.

inDrawInfo

A pointer to a structure of type ThemeButtonDrawInfo. Before calling GetThemeButtonBackgroundBounds, set the structure to contain the state, value, and adornment for the button.

outBounds

A pointer to a structure of type Rect. On return, the rectangle contains the actual boundary of the button, including any adornments, in local coordinates.

Return Value

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

Discussion

Appearance adornments can extend beyond the basic bounding rectangle of a button and may be of variable shape. Your application may call the GetThemeButtonBackgroundBounds function to obtain the actual rectangle containing the pixels belonging to a button under the current theme.

Availability
Declared In
Appearance.h

GetThemeButtonContentBounds

Obtains the rectangle where content can be drawn for a button. (Deprecated in Mac OS X v10.5. Use HIThemeGetButtonContentBounds instead.)

OSStatus GetThemeButtonContentBounds (
   const Rect *inBounds,
   ThemeButtonKind inKind,
   const ThemeButtonDrawInfo *inDrawInfo,
   Rect *outBounds
);

Parameters
inBounds

A pointer to a structure of type Rect. Before calling GetThemeButtonContentBounds, set the rectangle to contain the boundary of the button, in local coordinates.

inKind

A value of type ThemeButtonKind. Pass a constant specifying the type of button being examined. See “Theme Buttons” for descriptions of possible values.

inDrawInfo

A pointer to a structure of type ThemeButtonDrawInfo. Before calling GetThemeButtonContentBounds, set the structure to contain the state, value, and adornment for the button.

outBounds

A pointer to a structure of type Rect. On return, the rectangle contains the actual boundary, in local coordinates, of the area of the button’s face in which content can be drawn.

Return Value

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

Discussion

The GetThemeButtonContentBounds function obtains the rectangle where content can be drawn for a button under the current theme.

Availability
Declared In
Appearance.h

GetThemeButtonRegion

Obtains the region occupied by a button. (Deprecated in Mac OS X v10.5. Use HIThemeGetButtonShape instead.)

OSStatus GetThemeButtonRegion (
   const Rect *inBounds,
   ThemeButtonKind inKind,
   const ThemeButtonDrawInfo *inNewInfo,
   RgnHandle outRegion
);

Parameters
inBounds

A pointer to a structure of type Rect. Before calling GetThemeButtonRegion, set the rectangle to the boundary of the button without any adornments, in local coordinates.

inKind

A value of type ThemeButtonKind. Pass a constant specifying the type of button being examined. See “Theme Buttons” for descriptions of possible values.

inNewInfo

A pointer to a structure of type ThemeButtonDrawInfo. Before calling GetThemeButtonRegion, set the structure to contain the state, value, and adornment for the button.

outRegion

A value of type RgnHandle. On return, the region contains the actual dimensions and position of the button and any adornments, in local coordinates.

Return Value

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

Discussion

Appearance adornments can extend beyond the basic bounding rectangle of a button and may be of variable shape. Your application may call the GetThemeButtonRegion function to obtain the exact area covered by pixels belonging to a specific button under the current theme.

Special Considerations

This function is available with Appearance Manager 1.1 and later.

Availability
Declared In
Appearance.h

GetThemeFont

Obtains information about a system font in the current theme. (Deprecated in Mac OS X v10.5. Some theme fonts cannot be drawn using QuickDraw; use HIThemeDrawTextBox instead.)

OSStatus GetThemeFont (
   ThemeFontID inFontID,
   ScriptCode inScript,
   Str255 outFontName,
   SInt16 *outFontSize,
   Style *outStyle
);

Parameters
inFontID

A value of type ThemeFontID. Pass a constant specifying the kind of font (that is, the current large, small, or small emphasized system fonts or the views font) for which you wish to retrieve the current font name, size, and style in use.

inScript

A value of type ScriptCode. Pass a script code identifying the script system for which you wish obtain font information. You may pass the metascript code smSystemScript to specify the system script.

outFontName

A value of type StringPtr. Pass a pointer to a Pascal string. On return, the string contains the name of the font in use. Pass NULL if you do not wish to obtain this information.

outFontSize

A pointer to a signed 16-bit integer. On return, the integer value specifies the size of the font in use. Pass NULL if you do not wish to obtain this information.

outStyle

A pointer to a value of type Style. On return, the value specifies the style of the font in use. Pass NULL if you do not wish to obtain this information.

Return Value

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

Discussion

Your application can call the GetThemeFont function to obtain the precise font settings (font name, size, and style) used by a system font under the current theme.

Also see the function UseThemeFont.

Availability
Declared In
Appearance.h

GetThemeMenuBackgroundRegion

Obtains the background region for a menu. (Deprecated in Mac OS X v10.5. Use HIThemeGetMenuBackgroundShape instead.)

OSStatus GetThemeMenuBackgroundRegion (
   const Rect *inMenuRect,
   ThemeMenuType menuType,
   RgnHandle region
);

Parameters
inMenuRect

A pointer to a structure of type Rect. Before calling GetThemeMenuBackgroundRegion, set the rectangle to contain the entire menu, in global coordinates.

menuType

A value of type ThemeMenuType. Pass a constant specifying the type of menu (pull-down, pop-up, or hierarchical) whose background you wish to obtain; see “Theme Menu Types” for descriptions of possible values.

region

A value of type RgnHandle. Pass a region handle created by your application. On return, the region is set to that of the rectangle specified in the inMenuRect parameter, that is, the menu’s background region.

Return Value

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

Discussion

The GetThemeMenuBackgroundRegion function obtains the background region that a menu occupies under the current theme.

Availability
Declared In
Appearance.h

GetThemeScrollBarTrackRect

Obtains the area containing the track portion of a scroll bar. (Deprecated in Mac OS X v10.5. Use HIThemeGetScrollBarTrackRect instead.)

OSStatus GetThemeScrollBarTrackRect (
   const Rect *bounds,
   ThemeTrackEnableState enableState,
   ThemeTrackPressState pressState,
   Boolean isHoriz,
   Rect *trackBounds
);

Parameters
bounds

A pointer to a structure of type Rect. Before calling GetThemeScrollBarTrackRect, set the rectangle to the boundary of the scroll bar, in local coordinates. Typically, the rectangle you specify is the entire base control rectangle—that is, the value contained in the contrlRect field of the track’s ControlRecord structure.

enableState

A value of type ThemeTrackEnableState. Pass a constant specifying the current state of the scroll bar; see “Theme Track States” for descriptions of possible values.

pressState

A value of type ThemeTrackPressState. Pass a constant specifying what is pressed in an active scroll bar or 0 if nothing is pressed; the press state is ignored if the scroll bar is not active. See “Theme Track Press States” for descriptions of possible values.

isHoriz

A value of type Boolean. Pass true if the scroll bar is horizontal; pass false if it is vertical.

trackBounds

A pointer to a structure of type Rect. On return, the structure contains the rectangle that bounds the track portion of the scroll bar. Note that the rectangle produced does not include in its bounds any tick marks that a track (such as a slider) might have; tick marks are drawn outside the track rectangle. Similarly, for a scroll bar, the rectangle produced does not contain the scroll bar arrows, just the track itself.

Return Value

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

Discussion

Your application may call the GetThemeScrollBarTrackRect function to obtain the actual rectangle containing the track portion of a scroll bar under the current theme.

Availability
Declared In
Appearance.h

GetThemeStandaloneGrowBoxBounds

Obtains the bounds of a size box. (Deprecated in Mac OS X v10.5. Use HIThemeGetGrowBoxBounds instead.)

OSStatus GetThemeStandaloneGrowBoxBounds (
   Point origin,
   ThemeGrowDirection growDirection,
   Boolean isSmall,
   Rect *bounds
);

Parameters
origin

A structure of type Point. Pass the origin point of the size box rectangle. For example, the origin point of the size box for an object that can grow downward and to the right is the size box’s upper-left corner. Typically, you use the coordinates of the corner of whatever object owns the size box for the origin value; for instance, if you are drawing a scrolling list that can grow downward and to the right, the origin value would be the coordinates of the bottom-right corner of the list.

growDirection

A value of type ThemeGrowDirection. For a size box, pass a constant specifying the direction(s) in which the window can grow. See “Theme Size Box Directions” for descriptions of possible values. The Appearance Manager uses the growDirection parameter to establish which corner of the size box is the origin.

isSmall

A value of type Boolean. Pass a value of true to specify a small size box or fill image. Pass false to specify a large size box or fill image.

bounds

A pointer to a structure of type Rect. On return, the rectangle contains the boundary of the size box or fill image.

Return Value

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

Discussion

The GetThemeStandaloneGrowBoxBounds function obtains the bounds of a size box under the current theme. Note that you can also use GetThemeStandaloneGrowBoxBounds to obtain the bounds of the fill image drawn by the function DrawThemeStandaloneNoGrowBox.

Availability
Declared In
Appearance.h

GetThemeTabRegion

Obtains the region occupied by a tab. (Deprecated in Mac OS X v10.5. Use HIThemeGetTabDrawShape instead.)

OSStatus GetThemeTabRegion (
   const Rect *inRect,
   ThemeTabStyle inStyle,
   ThemeTabDirection inDirection,
   RgnHandle ioRgn
);

Parameters
inRect

A pointer to a structure of type Rect. Before calling GetThemeTabRegion, set the rectangle to the boundary of the tab, in local coordinates.

inStyle

A value of type ThemeTabStyle. Pass a constant specifying the relative position (front or non-front) and state of the tab to be examined. See “Theme Tab Styles” for descriptions of possible values.

inDirection

A value of type ThemeTabDirection. Pass a constant specifying the direction in which the tab is oriented. See “Theme Tab Directions” for descriptions of possible values.

ioRgn

A value of type RgnHandle. On return, the region contains the actual dimensions and position of the tab, in local coordinates.

Return Value

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

Discussion

Because a tab can have a non-rectangular shape, your application should call GetThemeTabRegion to get the actual region containing the tab under the current theme, in order to perform accurate hit testing.

Availability
Declared In
Appearance.h

GetThemeTextDimensions

Tells you the height, width, and baseline for a string. (Deprecated in Mac OS X v10.5. Use HIThemeGetTextDimensions instead.)

OSStatus GetThemeTextDimensions (
   CFStringRef inString,
   ThemeFontID inFontID,
   ThemeDrawState inState,
   Boolean inWrapToWidth,
   Point *ioBounds,
   SInt16 *outBaseline
);

Parameters
inString

A CFStringRef containing the unicode characters you wish to measure. You must not pass in a CFStringRef that was allocated with any of the "NoCopy" CFString creation functions, as mentioned in the description of the DrawThemeTextBox function.

inFontID

The ThemeFontID describing the font you'd like to measure the text with. See “Theme Font IDs” for the values you can use here.

inState

The ThemeDrawState which matches the state you will ultimately render the string with. Drawing state may affect text measurement, so you should be sure the value you pass to GetThemeTextDimensions matches the value you will eventually use for drawing. See “Theme Drawing States” for the values you can use here.

inWrapToWidth

A Boolean indicating whether you want the measurements based on wrapping the text to a specific width. If you pass true, you must specify the desired width in ioBounds->h.

ioBounds

On output, ioBounds->v contains the height of the text. If you pass false in the inWrapToWidth parameter, ioBounds->h will contain the width of the text on output. If you pass true in inWrapToWidth, ioBounds->h must (on input) contain the desired width for wrapping; on output, ioBounds->h contains the same value you specified on input.

outBaseline

On output, outBaseline contains the offset (in QuickDraw space) from the bottom edge of the last line of text to the baseline of the first line of text. outBaseline will generally be a negative value.

Return Value

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

Discussion

GetThemeTextDimensions measures the given string using the font and drawing state you specify. It always reports the actual height and baseline. It sometimes reports the actual width. It can measure a string that wraps. It is unicode savvy, although only partially so under CarbonLib.

Availability
Declared In
Appearance.h

GetThemeTrackBounds

Obtains the bounding rectangle of a track. (Deprecated in Mac OS X v10.5. Use HIThemeGetTrackBounds instead.)

OSStatus GetThemeTrackBounds (
   const ThemeTrackDrawInfo *drawInfo,
   Rect *bounds
);

Parameters
drawInfo

A pointer to a structure of type ThemeTrackDrawInfo. Before calling GetThemeTrackBounds, set the structure to describe the current visual characteristics of the track. Typically, the rectangle you specify in ThemeTrackDrawInfo.bounds is the proposed bounding rectangle for the track. GetThemeTrackBounds examines this rectangle to determine the actual bounds that the track would occupy. Depending on the track type, the actual bounding rectangle for a track might contain an absolute or fixed value (as for the height of a progress bar, which is always 14 pixels). Or, the track bounds might scale (as for a scroll bar) to fit the proposed bounds.

bounds

A pointer to a structure of type Rect. On return, the rectangle contains the actual boundary of the track, in local coordinates. Note that the rectangle produced does not include in its bounds any tick marks that a track (such as a slider) might have; tick marks are drawn outside the track rectangle. Similarly, for a scroll bar, the rectangle produced does not contain the scroll bar arrows, just the track itself.

Return Value

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

Discussion

Your application may call the GetThemeTrackBounds function to obtain the actual rectangle containing a track under the current theme.

Availability
Declared In
Appearance.h

GetThemeTrackDragRect

Obtains the area in which the user may drag a track’s indicator. (Deprecated in Mac OS X v10.5. Use HIThemeGetTrackDragRect instead.)

OSStatus GetThemeTrackDragRect (
   const ThemeTrackDrawInfo *drawInfo,
   Rect *dragRect
);

Parameters
drawInfo

A pointer to a structure of type ThemeTrackDrawInfo. Before calling GetThemeTrackDragRect, set the structure to contain the current visual characteristics of the track.

dragRect

A pointer to a structure of type Rect. On return, the rectangle contains the actual boundary of the indicator’s drag rectangle, in local coordinates.

Return Value

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

Discussion

Because of varying indicator geometries and theme designs, the draggable area for an indicator is not typically exactly the same as the track rectangle. Your application should call GetThemeTrackDragRect to obtain the actual area within a track where an indicator can be dragged under the current theme.

Availability
Declared In
Appearance.h

GetThemeTrackLiveValue

Obtains the current value of a track’s indicator, given its relative position. (Deprecated in Mac OS X v10.5. Use HIThemeGetTrackLiveValue instead.)

OSStatus GetThemeTrackLiveValue (
   const ThemeTrackDrawInfo *drawInfo,
   SInt32 relativePosition,
   SInt32 *value
);

Parameters
drawInfo

A pointer to a structure of type ThemeTrackDrawInfo. Before calling GetThemeTrackLiveValue, set the structure to contain the current visual characteristics of the track.

relativePosition

A signed 32-bit value. Pass the distance, in pixels, between the minimum end of the track and the near side of the indicator. You may obtain this value by calling either of the functions GetThemeTrackThumbPositionFromOffset or GetThemeTrackThumbPositionFromRegion.

value

A pointer to a signed 32-bit value. On return, this value contains the new value of the indicator.

Return Value

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

Discussion

Your application can use the GetThemeTrackLiveValue function to respond to the posCntl and kControlMsgCalcValueFromPos control definition message.

Availability
Declared In
Appearance.h

GetThemeTrackThumbPositionFromOffset

Obtains the relative position of a track’s indicator, given an offset from its prior position. (Deprecated in Mac OS X v10.5. Use HIThemeGetTrackThumbPositionFromOffset instead.)

OSStatus GetThemeTrackThumbPositionFromOffset (
   const ThemeTrackDrawInfo *drawInfo,
   Point thumbOffset,
   SInt32 *relativePosition
);

Parameters
drawInfo

A pointer to a structure of type ThemeTrackDrawInfo. Before calling GetThemeTrackThumbPositionFromOffset, set the structure to contain the current visual characteristics of the track.

thumbOffset

A structure of type Point. Pass the point (in coordinates local to the control’s window) that specifies the vertical and horizontal offset, in pixels, by which the indicator has moved from its current position. Typically, this is the offset between the locations where the cursor was when the user pressed and released the mouse button while dragging the indicator.

relativePosition

A pointer to a signed 32-bit value. On return, this value contains the new distance, in pixels, between the minimum end of the track and the near side of the indicator.

Return Value

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

Discussion

Your application can use the GetThemeTrackThumbPositionFromOffset function to respond to the posCntl control definition message.

Availability
Declared In
Appearance.h

GetThemeTrackThumbPositionFromRegion

Obtains the relative position of a track’s indicator, given its current position. (Deprecated in Mac OS X v10.5. use HIThemeGetTrackThumbPositionFromBounds instead.)

OSStatus GetThemeTrackThumbPositionFromRegion (
   const ThemeTrackDrawInfo *drawInfo,
   RgnHandle thumbRgn,
   SInt32 *relativePosition
);

Parameters
drawInfo

A pointer to a structure of type ThemeTrackDrawInfo. Before calling GetThemeTrackThumbPositionFromRegion, set the structure to contain the current visual characteristics of the track.

thumbRgn

A value of type RgnHandle. Before calling GetThemeTrackThumbPositionFromRegion set the region to contain the actual dimensions and position of the indicator, in local coordinates.

relativePosition

A pointer to a signed 32-bit value. On return, this value contains the new distance, in pixels, between the minimum end of the track and the near side of the indicator.

Return Value

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

Discussion

Your application can use the GetThemeTrackThumbPositionFromRegion function to respond to the kControlMsgCalcValueFromPos control definition message.

Availability
Declared In
Appearance.h

GetThemeTrackThumbRgn

Obtains the region containing a track’s indicator. (Deprecated in Mac OS X v10.5. Use HIThemeGetTrackThumbShape instead.)

OSStatus GetThemeTrackThumbRgn (
   const ThemeTrackDrawInfo *drawInfo,
   RgnHandle thumbRgn
);

Parameters
drawInfo

A pointer to a structure of type ThemeTrackDrawInfo. Before calling GetThemeTrackThumbRgn, set the structure to contain the current visual characteristics of the track.

thumbRgn

A value of type RgnHandle. On return, the region contains the actual dimensions and position of the indicator, in local coordinates.

Return Value

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

Discussion

Your application can use the GetThemeTrackThumbRgn function to obtain the indicator region for tracks that have indicators, such as sliders and scroll bars.

Availability
Declared In
Appearance.h

GetThemeWindowRegion

Obtains the specified window region. (Deprecated in Mac OS X v10.5. Use HIThemeGetWindowShape instead.)

OSStatus GetThemeWindowRegion (
   ThemeWindowType flavor,
   const Rect *contRect,
   ThemeDrawState state,
   const ThemeWindowMetrics *metrics,
   ThemeWindowAttributes attributes,
   AppearanceRegionCode winRegion,
   RgnHandle rgn
);

Parameters
flavor

A value of type ThemeWindowType. Pass a constant specifying the type of window to be examined. See “Theme Window Types” for descriptions of possible values.

contRect

A pointer to a structure of type Rect. Before calling GetThemeWindowRegion, set the rectangle to the content area of the window, specified in coordinates local to the current port.

state

A value of type ThemeDrawState. Pass a constant—either kThemeStateActive or kThemeStateInactive—appropriate to the current state of the window. See “Theme Drawing States” for descriptions of these values.

metrics

A pointer to a structure of type ThemeWindowMetrics. Before calling GetThemeWindowRegion, set the structure to contain information describing the window.

attributes

A value of type ThemeWindowAttributes. Pass one or more constants corresponding to the window’s current visual attributes. See “Theme Window Attributes” for descriptions of possible values. Pass 0 if the window has none of the enumerated attributes.

winRegion

A value of type WindowRegionCode. Pass a constant specifying the region of the window whose dimensions you wish to obtain.

rgn

A value of type RgnHandle. Pass a handle to a valid region. On return, the region represents the actual region requested.

Return Value

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

Discussion

The GetThemeWindowRegion function obtains the dimensions of the specified window region under the current theme.

Availability
Declared In
Appearance.h

GetThemeWindowRegionHit

Obtains the part of the window that the user clicked upon. (Deprecated in Mac OS X v10.5. Use HIThemeGetWindowRegionHit instead.)

Boolean GetThemeWindowRegionHit (
   ThemeWindowType flavor,
   const Rect *inContRect,
   ThemeDrawState state,
   const ThemeWindowMetrics *metrics,
   ThemeWindowAttributes inAttributes,
   Point inPoint,
   AppearanceRegionCode *outRegionHit
);

Parameters
flavor

A value of type ThemeWindowType. Pass a constant specifying the type of window to be examined. See “Theme Window Types” for descriptions of possible values.

inContRect

A pointer to a structure of type Rect. Before calling GetThemeWindowRegionHit, set rectangle to the content area of the window, specified in coordinates local to the current port.

state

A value of type ThemeDrawState. Pass a constant—either kThemeStateActive or kThemeStateInactive—appropriate to the current state of the window. See “Theme Drawing States” for descriptions of these values.

metrics

A pointer to a structure of type ThemeWindowMetrics. Before calling GetThemeWindowRegionHit, set the structure to contain information describing the window.

inAttributes

A value of type ThemeWindowAttributes. Pass one or more constants corresponding to the window’s current visual attributes. See “Theme Window Attributes” for descriptions of possible values. Pass 0 if the window has none of the enumerated attributes.

inPoint

A structure of type Point. Pass the point, specified in specified in coordinates local to the current port, where the mouse-down event occurred. Your application may retrieve this value from the where field of the event structure.

outRegionHit

A pointer to a value of type WindowRegionCode. On return, the value is set to the region code of the window part in which the point passed in the inPoint parameter is located.

Return Value

A value of type Boolean. If true, the mouse-down event occurred inside the window; otherwise, false.

Discussion

Your window definition function should call the GetThemeWindowRegionHit function to determine where a specified mouse-down event occurred.

Availability
Declared In
Appearance.h

HitTestThemeScrollBarArrows

Returns whether the user clicked upon the specified scroll bar’s arrows. (Deprecated in Mac OS X v10.5. Use HIThemeHitTestScrollBarArrows instead.)

Boolean HitTestThemeScrollBarArrows (
   const Rect *scrollBarBounds,
   ThemeTrackEnableState enableState,
   ThemeTrackPressState pressState,
   Boolean isHoriz,
   Point ptHit,
   Rect *trackBounds,
   AppearancePartCode *partcode
);

Parameters
scrollBarBounds

A pointer to a structure of type Rect. Before calling HitTestThemeScrollBarArrows, set the rectangle to the boundary of the scroll bar, in local coordinates. Typically, the rectangle you specify is the entire base control rectangle—that is, the value contained in the contrlRect field of the scroll bar’s ControlRecord structure.

enableState

A value of type ThemeTrackEnableState. Pass a constant specifying the current state of the scroll bar; see “Theme Track States” for descriptions of possible values.

pressState

A value of type ThemeTrackPressState. Pass a constant specifying what is pressed in an active scroll bar or 0 if nothing is pressed; the press state is ignored if the scroll bar is not active. See “Theme Track Press States” for descriptions of possible values.

isHoriz

A value of type Boolean. Pass true if the scroll bar is horizontal; pass false if it is vertical.

ptHit

A structure of type Point. Pass the point, specified in local coordinates, where the mouse-down event occurred. Your application may retrieve this value from the where field of the event structure.

trackBounds

A pointer to a structure of type Rect. On return, the rectangle contains the bounds of the track portion of the scroll bar; this rectangle excludes the area containing the scroll bar arrows. Pass NULL if you do not wish to obtain this information.

partcode

A pointer to a value of type ControlPartCode. On return, this value specifies the arrow in which the mouse-down event occurred.

Return Value

A value of type Boolean. If true, the mouse-down event occurred inside the scroll bar arrows; otherwise, false.

Discussion

Your application may use the HitTestThemeScrollBarArrow function to test whether a given mouse-down event occurred on a scroll bar’s arrows. If not, you may then use the rectangle produced in the trackBounds parameter of HitTestThemeScrollBarArrows as the bounds of the track for the function HitTestThemeTrack, in order to determine whether the mouse-down event occurred in the track part of the scroll bar.

Availability
Declared In
Appearance.h

HitTestThemeTrack

Returns whether the user clicked upon the specified track. (Deprecated in Mac OS X v10.5. Use HIThemeHitTestTrack instead.)

Boolean HitTestThemeTrack (
   const ThemeTrackDrawInfo *drawInfo,
   Point mousePoint,
   AppearancePartCode *partHit
);

Parameters
drawInfo

A pointer to a structure of type ThemeTrackDrawInfo. Before calling HitTestThemeTrack, set the structure to contain the current visual characteristics of the track.

mousePoint

A structure of type Point. Pass the point, specified in local coordinates, where the mouse-down event occurred. Your application may retrieve this value from the where field of the event structure.

partHit

A pointer to a value of type ControlPartCode. On return, this value specifies the part of the track in which the mouse-down event occurred.

Return Value

A value of type Boolean. If true, the mouse-down event occurred inside the track; otherwise, false.

Discussion

The HitTestThemeTrack function checks to see whether a given track contains the specified point at which a mouse-down event occurred.

For a scroll bar–type track, your application should also check to see whether the mouse-down event occurred in the scroll bar’s arrows, which are not considered part of the track and are not tested by this function. To do this, your application should first use the function HitTestThemeScrollBarArrows to test whether a given mouse-down event occurred on a scroll bar’s arrows. If not, you may then use the rectangle produced in the rTrack parameter of HitTestThemeScrollBarArrows as the bounds of the track for HitTestThemeTrack, in order to determine whether the mouse-down event occurred in the track part of the scroll bar.

Availability
Declared In
Appearance.h

InvokeMenuItemDrawingUPP

Invokes your menu item drawing function. (Deprecated in Mac OS X v10.5. There is no replacement function.)

void InvokeMenuItemDrawingUPP (
   const Rect *inBounds,
   SInt16 inDepth,
   Boolean inIsColorDevice,
   SRefCon inUserData,
   MenuItemDrawingUPP userUPP
);

Discussion

You should not need to use the function InvokeMenuItemDrawingUPP, as the system calls your menu item drawing function for you.

Availability
Declared In
Appearance.h

InvokeMenuTitleDrawingUPP

Invokes your menu title drawing function. (Deprecated in Mac OS X v10.5. There is no replacement function.)

void InvokeMenuTitleDrawingUPP (
   const Rect *inBounds,
   SInt16 inDepth,
   Boolean inIsColorDevice,
   SRefCon inUserData,
   MenuTitleDrawingUPP userUPP
);

Discussion

You should not need to use the function InvokeMenuTitleDrawingUPP, as the system calls your menu title drawing function for you.

Availability
Declared In
Appearance.h

InvokeThemeButtonDrawUPP

Invokes your button drawing function. (Deprecated in Mac OS X v10.5. There is no replacement function.)

void InvokeThemeButtonDrawUPP (
   const Rect *bounds,
   ThemeButtonKind kind,
   const ThemeButtonDrawInfo *info,
   URefCon userData,
   SInt16 depth,
   Boolean isColorDev,
   ThemeButtonDrawUPP userUPP
);

Discussion

You should not need to use the function InvokeThemeButtonDrawUPP, as the system calls your button drawing function for you.

Availability
Declared In
Appearance.h

InvokeThemeEraseUPP

Invokes your background drawing callback function. (Deprecated in Mac OS X v10.5. There is no replacement function.)

void InvokeThemeEraseUPP (
   const Rect *bounds,
   URefCon eraseData,
   SInt16 depth,
   Boolean isColorDev,
   ThemeEraseUPP userUPP
);

Discussion

You should not need to use the function InvokeThemeEraseUPP, as the system calls your ThemeEraseProcPtr callback function for you.

Availability
Declared In
Appearance.h

InvokeThemeIteratorUPP

Invokes your theme iteration callback function. (Deprecated in Mac OS X v10.5. There is no replacement function.)

Boolean InvokeThemeIteratorUPP (
   ConstStr255Param inFileName,
   SInt16 resID,
   Collection inThemeSettings,
   PRefCon inUserData,
   ThemeIteratorUPP userUPP
);

Discussion

You should not need to use the function InvokeThemeIteratorUPP, as the system calls your ThemeIteratorProcPtr callback function for you.

Availability
Declared In
Appearance.h

InvokeThemeTabTitleDrawUPP

Invokes your tab title drawing function. (Deprecated in Mac OS X v10.5. There is no replacement function.)

void InvokeThemeTabTitleDrawUPP (
   const Rect *bounds,
   ThemeTabStyle style,
   ThemeTabDirection direction,
   SInt16 depth,
   Boolean isColorDev,
   URefCon userData,
   ThemeTabTitleDrawUPP userUPP
);

Discussion

You should not need to use the function InvokeThemeTabTitleDrawUPP, as the system calls your tab title drawing function for you.

Availability
Declared In
Appearance.h

InvokeWindowTitleDrawingUPP

Invokes your window title drawing function. (Deprecated in Mac OS X v10.5. There is no replacement function.)

void InvokeWindowTitleDrawingUPP (
   const Rect *bounds,
   SInt16 depth,
   Boolean colorDevice,
   URefCon userData,
   WindowTitleDrawingUPP userUPP
);

Discussion

You should not need to use the function InvokeWindowTitleDrawingUPP, as the system calls your window title drawing function for you.

Availability
Declared In
Appearance.h

IsAppearanceClient

Returns whether a given process is currently registered as a client of the Appearance Manager. (Deprecated in Mac OS X v10.5. There is no replacement function.)

Boolean IsAppearanceClient (
   const ProcessSerialNumber *process
);

Parameters
process

A pointer to a value of type ProcessSerialNumber. Pass the serial number of the process to examine.

Return Value

A value of type Boolean. If true, the specified process is currently registered as a client of the Appearance Manager; otherwise, false.

Discussion

Applications typically do not need to call the IsAppearanceClient function. A plug-in could call IsAppearanceClient to determine whether the process in which it is running is a registered Appearance Manager client. To register with the Appearance Manager, call the function RegisterAppearanceClient.

Special Considerations

This function always returns true in Mac OS X.

Availability
Declared In
Appearance.h

IsThemeInColor

Returns whether the current theme would draw in color in the given environment. (Deprecated in Mac OS X v10.5. There is no replacement function.)

Boolean IsThemeInColor (
   SInt16 inDepth,
   Boolean inIsColorDevice
);

Parameters
inDepth

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

inIsColorDevice

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

Return Value

A value of type Boolean. IsThemeInColor returns true if, given the depth and color device information, the theme would draw in color; otherwise, false.

Discussion

To be consistent with the current theme, your application can call the IsThemeInColor function to determine whether or not the Appearance Manager is drawing the theme in color or black and white. If the function returns true, you should draw in color; if it returns false, you should draw in black and white. Note that the Appearance Manager may draw a theme in black and white not only because of the current bit depth or device type, but also because the theme may have defined black-and-white elements, such as the “Black & White” accent color in the platinum appearance.

Special Considerations

In Mac OS X, this function always returns true because the Aqua theme is always drawn in color.

Availability
Declared In
Appearance.h

IsValidAppearanceFileType

Returns whether the system can interpret files of a given file type as appearance files. (Deprecated in Mac OS X v10.5. There is no replacement function.)

Boolean IsValidAppearanceFileType (
   OSType fileType
);

Parameters
fileType

A four-character code. Pass the file type to be examined.

Return Value

A value of type Boolean. If true, files of the specified file type can be used as appearance files; otherwise, false.

Discussion

Under Appearance Manager 1.1, only the 'thme' and 'pltn' file types, described in “Appearance Manager File Types,” are valid appearance file types. Your application typically does not need to call this function.

Special Considerations

This function always returns false in Mac OS X.

Availability
Declared In
Appearance.h

IterateThemes

Iterates over all themes installed on a system. (Deprecated in Mac OS X v10.5. There is no replacement function.)

OSStatus IterateThemes (
   ThemeIteratorUPP inProc,
   PRefCon inUserData
);

Parameters
inProc

A universal function pointer to an application-defined function such as that described in ThemeIteratorProcPtr. IterateThemes calls the specified function for each theme found installed in the system.

inUserData

A pointer to data of any type. Provide any data to be passed in to the inUserData parameter of the callback function specified in the inProc parameter. Pass NULL, if you do not wish to provide any data.

Return Value

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

Discussion

The IterateThemes function continues to iterate until the function specified in the inProc parameter returns false or until there are no more themes.

Special Considerations

This function does nothing in Mac OS X; it does not call the theme iterator callback function.

Availability
Declared In
Appearance.h

NewMenuItemDrawingUPP

Creates a new universal procedure pointer (UPP) to a menu item drawing function. (Deprecated in Mac OS X v10.5. There is no replacement function.)

MenuItemDrawingUPP NewMenuItemDrawingUPP (
   MenuItemDrawingProcPtr userRoutine
);

Return Value

A UPP. See MenuItemDrawingProcPtr for information on the menu item drawing function. See the description of the MenuItemDrawingUPP data type.

Availability
Declared In
Appearance.h

NewMenuTitleDrawingUPP

Creates a new universal procedure pointer (UPP) to a menu title drawing function. (Deprecated in Mac OS X v10.5. There is no replacement function.)

MenuTitleDrawingUPP NewMenuTitleDrawingUPP (
   MenuTitleDrawingProcPtr userRoutine
);

Return Value

A UPP. See MenuTitleDrawingProcPtr for information on the menu title drawing function. See the description of the MenuTitleDrawingUPP data type.

Availability
Declared In
Appearance.h

NewThemeButtonDrawUPP

Creates a new universal procedure pointer (UPP) to a button drawing function. (Deprecated in Mac OS X v10.5. There is no replacement function.)

ThemeButtonDrawUPP NewThemeButtonDrawUPP (
   ThemeButtonDrawProcPtr userRoutine
);

Return Value

A UPP. See ThemeButtonDrawProcPtr for information on the button drawing function. See the description of the ThemeButtonDrawUPP data type.

Availability
Declared In
Appearance.h

NewThemeEraseUPP

Creates a new universal procedure pointer (UPP) to a background drawing callback function. (Deprecated in Mac OS X v10.5. There is no replacement function.)

ThemeEraseUPP NewThemeEraseUPP (
   ThemeEraseProcPtr userRoutine
);

Return Value

A UPP. See the description of the ThemeEraseUPP data type.

Availability
Declared In
Appearance.h

NewThemeIteratorUPP

Creates a new universal procedure pointer (UPP) to a theme iteration callback function. (Deprecated in Mac OS X v10.5. There is no replacement function.)

ThemeIteratorUPP NewThemeIteratorUPP (
   ThemeIteratorProcPtr userRoutine
);

Return Value

A UPP. See the description of the ThemeIteratorUPP data type.

Availability
Declared In
Appearance.h

NewThemeTabTitleDrawUPP

Creates a new universal procedure pointer (UPP) to a tab title drawing function. (Deprecated in Mac OS X v10.5. There is no replacement function.)

ThemeTabTitleDrawUPP NewThemeTabTitleDrawUPP (
   ThemeTabTitleDrawProcPtr userRoutine
);

Return Value

A UPP. See ThemeTabTitleDrawProcPtr for information on the tab title drawing function. See the description of the ThemeTabTitleDrawUPP data type.

Availability
Declared In
Appearance.h

NewWindowTitleDrawingUPP

Creates a new universal procedure pointer (UPP) to a window title drawing function. (Deprecated in Mac OS X v10.5. There is no replacement function.)

WindowTitleDrawingUPP NewWindowTitleDrawingUPP (
   WindowTitleDrawingProcPtr userRoutine
);

Return Value

A UPP. See WindowTitleDrawingProcPtr for information on the window title drawing function. See the description of the WindowTitleDrawingUPP data type.

Availability
Declared In
Appearance.h

RegisterAppearanceClient

Registers your program with the Appearance Manager. (Deprecated in Mac OS X v10.5. There is no replacement function.)

OSStatus RegisterAppearanceClient (
   void
);

Return Value

A result code. The result code appearanceProcessRegisteredErr indicates that your program was already registered when you called the RegisterAppearanceClient function.

Discussion

The RegisterAppearanceClient function must be called at the beginning of your program, prior to initializing or drawing any onscreen elements or invoking any definition functions, such as the menu bar.

You should call RegisterAppearanceClient in order to receive Appearance Manager Apple events. Under Appearance Manager 1.1 and later, when the user changes the current appearance (that is, when a theme switch occurs), the Appearance Manager sends Apple events to all running applications that are registered as clients of the Appearance Manager and which are high-level event aware. Because typical results of a theme switch might include a change in menu bar height or window structure dimensions, as well as changes to the system fonts, colors, and patterns currently in use, you should listen for and respond to the Appearance Manager Apple events under most circumstances. See “Appearance Manager Apple Events” for more details.

When your program calls RegisterAppearanceClient, the Appearance Manager also automatically maps standard pre–Appearance Manager definition functions to their theme-compliant equivalents for your program, whether or not systemwide appearance is active.

See also the function UnregisterAppearanceClient.

Special Considerations

This function does nothing in Mac OS X.

Availability
Declared In
Appearance.h

SetTheme

Sets a specified collection as the current theme. (Deprecated in Mac OS X v10.5. There is no replacement function.)

OSStatus SetTheme (
   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. Before calling SetTheme, set the collection to contain theme data that you wish to use 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. Your application can use theme collection tags, along with various Collection Manager functions, to access the data in the collection. See “Theme Collection Tags” for descriptions of the possible theme collection items.

Return Value

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

Discussion

The SetTheme function sets the attributes of the current theme. You may use SetTheme to set up a custom theme environment for your application, to be used only when your application is active. You may also use SetTheme to create a theme environment that you want to be user-selectable and to have systemwide effect.

Your application can use the GetTheme function to obtain a collection containing a copy of the data for the current theme.

Special Considerations

This function does not modify the current theme in Mac OS X.

Availability
Declared In
Appearance.h

SetThemeBackground

Applies a theme-compliant color or pattern to the background of the current port. (Deprecated in Mac OS X v10.5. Use HIThemeSetFill and draw using Quartz 2D.)

OSStatus SetThemeBackground (
   ThemeBrush inBrush,
   SInt16 inDepth,
   Boolean inIsColorDevice
);

Parameters
inBrush

A value of type ThemeBrush. Pass a constant specifying the theme brush to which to set the background; 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.

inIsColorDevice

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

Return Value

A result code. The result code appearanceBadBrushIndexErr indicates that the brush constant passed was not valid.

Discussion

Your application should call the SetThemeBackground function each time you wish to draw in a specified brush type. Note that the SetThemeBackground function aligns patterns with 0,0 in the current port. To align a pattern independently of the port origin, use the function ApplyThemeBackground.

Because the constant in the inBrush parameter can specify a color or pattern, depending on the current theme, your application must save and restore the current drawing state of the graphics port around calls to SetThemeBackground. Under Appearance Manager 1.1 and later, you can use the functions GetThemeDrawingState and SetThemeDrawingState to do this.

Prior to Appearance Manager 1.1, you must save and restore the pnPixPat and bkPixPat fields of your graphics port when saving the text and background colors. Because patterns in the bkPixPat field override the background color of the window, call the QuickDraw function BackPat to set your background pattern to a normal white pattern. This ensures that you can use RGBBackColor to set your background color to white, call the QuickDraw function EraseRect, and get the expected results.

Availability
Declared In
Appearance.h

SetThemePen

Applies a theme-compliant color or pattern to the foreground of the current port. (Deprecated in Mac OS X v10.5. Use HIThemeSetStroke and draw using Quartz 2D.)

OSStatus SetThemePen (
   ThemeBrush inBrush,
   SInt16 inDepth,
   Boolean inIsColorDevice
);

Parameters
inBrush

A value of type ThemeBrush. Pass a constant specifying the theme brush type to which to set the pen; 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.

inIsColorDevice

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

Return Value

A result code. The result code appearanceBadBrushIndexErr indicates that the brush constant passed in was not valid.

Discussion

Your application should call the SetThemePen function each time you wish to draw an element in a specified brush constant.

Because the constant in the inBrush parameter can represent a color or pattern, depending on the current theme, your application must save and restore the current drawing state of the graphics port around calls to SetThemePen. Under Appearance Manager 1.1 and later, you can use the functions GetThemeDrawingState and SetThemeDrawingState to do this. Prior to Appearance Manager 1.1, you must save and restore the pnPixPat and bkPixPat fields of your graphics port when saving the text and background colors. Because patterns in the pnPixPat field override the foreground color of the window, call the QuickDraw function PenPat to set your foreground pattern to a normal white pattern. This ensures that you can use RGBForeColor to set your foreground color to white, call the QuickDraw function PaintRect, and get the expected results.

Availability
Declared In
Appearance.h

SetThemeTextColor

Sets the current text color to be consistent with that of a specified element. (Deprecated in Mac OS X v10.5. Use HIThemeSetTextFill and draw with Quartz 2D, ATSUI, or HIThemeDrawTextBox.)

OSStatus SetThemeTextColor (
   ThemeTextColor inColor,
   SInt16 inDepth,
   Boolean inIsColorDevice
);

Parameters
inColor

A value of type ThemeTextColor. Pass a constant specifying an interface element. SetThemeTextColor sets the current text color to be the same as the color of that element’s text. 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.

inIsColorDevice

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

Return Value

A result code. The result code appearanceBadTextColorIndexErr indicates that the text color index passed was not valid.

Discussion

Your application typically uses the SetThemeTextColor function inside a DeviceLoop drawing function to set the foreground color to a theme-compliant value.

Also see the function GetThemeTextColor.

Availability
Declared In
Appearance.h

TruncateThemeText

Truncates text to fit within the width you specify. (Deprecated in Mac OS X v10.5. There is no replacement function; use HIThemeGetTextDimensions or HIThemeDrawTextBox instead.)

OSStatus TruncateThemeText (
   CFMutableStringRef inString,
   ThemeFontID inFontID,
   ThemeDrawState inState,
   SInt16 inPixelWidthLimit,
   TruncCode inTruncWhere,
   Boolean *outTruncated
);

Parameters
inString

A CFMutableStringRef containing the unicode characters you wish to truncate. On output, this string may have been altered to fit within the specified width.

You must not pass in a CFString that was allocated with any of the "NoCopy" CFString creation functions, as mentioned in the description of the DrawThemeTextBox function.

inFontID

The ThemeFontID to use for text measurements. See “Theme Font IDs” for the values you can use here.

inState

The ThemeDrawState which matches the state you will ultimately render the string with. This may affect text measurement during truncation, so you should be sure the value you pass to TruncateThemeText matches the value you will eventually use for drawing. See “Theme Drawing States” for the values you can use here.

inPixelWidthLimit

The maximum width, in pixels, that the resulting truncated string may have.

inTruncWhere

A TruncCode indicating where you would like truncation to occur.

outTruncated

On output, this Boolean value indicates whether the string was truncated. True means the string was truncated. False means the string was not—and did not need to be—truncated.

Return Value

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

Discussion

TruncateThemeText alters a unicode string to fit within a width that you specify. It is unicode savvy, although only partially so under CarbonLib, and makes its calculations—and any subsequent string alteration—based on the font and drawing state you specify. If the string needs to be truncated, it will be reduced to the maximum number of characters which, with the addition of an ellipsis character, fits within the specified width.

Availability
Declared In
Appearance.h

UnregisterAppearanceClient

Informs the Appearance Manager that your program is no longer its client. (Deprecated in Mac OS X v10.5. There is no replacement function.)

OSStatus UnregisterAppearanceClient (
   void
);

Return Value

A result code. The result code appearanceProcessNotRegisteredErr indicates that your program was not registered when you called the UnregisterAppearanceClient function.

Discussion

The UnregisterAppearanceClient function is automatically called for you when your program terminates. While you do not typically need to call this function, you might want to call UnregisterAppearanceClient if you are running a plug-in architecture, and you know that a given plug-in is not theme-compliant. In this case you would bracket your use of the plug-in with calls to UnregisterAppearanceClient (before the plug-in is used) and RegisterAppearanceClient (after the plug-in is used), so that the Appearance Manager is turned off for the duration of the plug-in’s usage.

See also the function RegisterAppearanceClient.

Special Considerations

This function does nothing in Mac OS X.

Availability
Declared In
Appearance.h

UseThemeFont

Sets the font of the current graphics port to one of the current theme’s system fonts. (Deprecated in Mac OS X v10.5. Use HIThemeDrawTextBox instead.)

OSStatus UseThemeFont (
   ThemeFontID inFontID,
   ScriptCode inScript
);

Parameters
inFontID

A value of type ThemeFontID. Pass a constant specifying the kind of font (that is, the current large, small, or small emphasized system fonts or the views font) to be applied to the current port. See “Theme Font IDs” for descriptions of possible values.

inScript

A value of type ScriptCode. Pass a script code specifying the script system for which you wish to set the current font; you may pass the metascript code smSystemScript to specify the system script.

Return Value

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

Discussion

Your application can call the UseThemeFont function to draw text in one of the current theme’s system fonts.

Also see the function GetThemeFont.

Availability
Declared In
Appearance.h

< Previous PageNext Page > Hide TOC

© 2007 Apple Inc. All Rights Reserved. (Last updated: 2007-01-23)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.