MACINTOSH C CARBON: A Hobbyist's Guide To Programming the Macintosh in C
Version 1.0
� 2001 K. J. Bricknell

CHAPTER 6

THE APPEARANCE MANAGER

History

The Appearance Manager, which was first introduced with Mac OS 8.0, had implications for the Menu Manager, the Window Manager, the Control Manager, and the Dialog Manager. The relatively minor implications in respect of the Menu Manager and Window Manager were incorporated into Chapter 3 and Chapter 4. The most profound impact of the Appearance Manager, however, has been in the area of user interface objects known as controls, which are addressed at Chapters 7 and 14. Accordingly, as a preparation for what is to come, this chapter now formally introduces the Appearance Manager, a component of the system software which, on Mac OS 8/9, represented the most significant improvement in the Macintosh user experience since the introduction of System 7.

Although introduced with Mac OS 8.0, the Appearance Manager's full impact on the Macintosh user experience was not scheduled to be realised until the release of Mac OS 8.5. Mac OS 8.5 was to be the first release to include several switchable themes, one of which (the Platinum theme) had, in fact, been included in Mac OS 8.0. The concept of switchable themes was the main driving force behind the creation of the Appearance Manager.

Essentially, a theme was intended to be an interface "look" that spanned all elements of the user interface (windows, menus, dialogs, controls, background colours, alert icons, etc), tying them together with a certain graphic design. Fig 1 shows the same window as it would have appeared in the three themes originally intended to be included in Mac OS 8.5. If one of these themes had been selected by the user, all elements of the user interface (menus, windows, controls, etc.) would have appeared in that theme.

The two additional themes (High Tech and Gizmo) shown at Fig 1 were included in pre-release versions of Mac OS 8.5; however, prior to final release, these two themes were deleted. The reasons for this decision by Apple remain tantalisingly obscure.

Themes - New Definition

Mac OS 8.5 did, in fact, introduce a theme scheme, though one of an entirely different flavour to that described above. This is reflected in the Appearance control panel introduced with Mac OS 8.5, in which the Platinum theme is now referred to as the Platinum appearance. An appearance (new definition) is now simply one component of a broader set of user preferences known as a theme (new definition). With the release of Mac OS 8.5, therefore, the term "theme" took on an entirely new meaning.

On Mac OS 8/9, in Mac OS 8.5 and later, an individual theme is a set of user preferences encompassing:

• An appearance (which unifies the look of human interface objects such as windows, dialogs, alerts, menus, controls, etc.), together with a highlight colour (for selected text) and a variation colour (for menus and controls). (As of Mac OS 9.0, Platinum remains the only appearance ever provided by Apple. It is by now certain that this situation will never change.)

• A large system font (for menus and headings), a small system font (for explanatory text and labels), a views font (for lists and icons), and an option to turn anti-aliasing of fonts on screen on or off.

• A desktop picture and desktop pattern.

• Sound preferences relating to opening menus and choosing items, dragging and resizing windows, interacting with controls, and clicking, dragging, and dropping in the Finder.

• Scrolling preference (smart scrolling on or off) and collapse-window preference (double-click title bar to collapse window on or off).

Theme-Compliance

Another significant terminological change ushered in by Mac OS 8.5 was that, whereas Apple documentation previously spoke of making applications appearance-compliant, documentation released following the release of Mac OS 8.5 spoke of making applications theme-compliant. It is assumed that the reason for this change is that, while the vast bulk of the measures required to make an application theme-compliant relate to unifying the look of the application's Mac OS 8/9 user interface elements (the province of an appearance), there are additional measures that the application may take, or may have to take:

• In response to the user changing the system and/or views fonts, using the Fonts tab of the Appearance control panel, while the application is running. (This consideration does not apply if the application uses standard human interface elements (that is, system-defined windows, controls, and menus), since the fonts used for these elements automatically change with the theme change. However, some applications may use custom human interface elements and may, for example, draw their own text in a dialog. In such cases, the application must ensure that the fonts used match the corresponding system fonts in the current theme.)

• To cause theme-compliant sounds to accompany, for example, the opening and closing of the application's windows and the manipulation by the user of custom human interface elements.

• To support the proportional scroll boxes the user expects when Smart Scrolling is selected on in the Options tab of the Appearance control panel.

  Proportional scroll boxes are scroll boxes which vary in size according to the proportion of the document visible in the window.

The Appearance Manager

The influence of the Appearance Manager is evident to a greater or lesser extent in many chapters of this book and in all of the associated demonstration programs. Amongst other things, it ensures consistency in the appearance of the standard human interface elements on both Mac OS 8/9 and Mac OS X. It also provides the means to:

• Ensure that the appearance of your application's custom human interface elements (if any) is consistent with the Platinum and Aqua "look".

• Draw anti-aliased text on Mac OS X.

Carbon fully supports the Appearance Manager.

New Definition Functions - Mac OS 8/9

To provide a system-wide coordination of look and behaviour on Mac OS 8/9, new theme-compliant definition functions were introduced with the Appearance Manager to replace the old pre-Appearance Manager definition functions for menu bars, menus, windows, and controls. In addition, many new theme-compliant control definition functions for new types of controls (slider controls, focus rings, group boxes, etc.) were introduced to obviate the necessity for developers to provide their own.

Colours, Patterns, and Appearance Primitives

The Appearance Manager provides Appearance primitives, and the means to set the colours and patterns, needed to draw consistently in the Platininum appearance on Mac OS 8/9 and with the Aqua "look" on Mac OS X. Using these drawing primitives, colours, and patterns makes it easier to create visual entities and custom human interface elements that are consistent with the Platinum appearance and Aqua "look".

Drawing Appearance Primitives

As will become apparent at Chapters 7 and 14, most of these primitives relate to certain controls. The definition functions for these controls call these primitives when drawing the relevant control. For example, the control definition function for a primary group box calls the primitive DrawThemePrimaryGroup to draw the visual representation of that control.

Your application might use these primitives to, for example, draw an image of a placard, window header, edit text field frame, etc., when you don't want to use a control.

The following are examples of functions that draw Appearance primitives.

Fig 2 shows examples of images drawn in both the active and inactive modes using the Appearance primitives.

Draw State Constants

The following constants are passed in the inState parameter of the functions that draw Appearance primitives (except DrawThemeFocusRect and DrawThemeFocusRegion) to specify whether the primitive should be drawn in the active or deactivated mode. (DrawThemeFocusRect and DrawThemeFocusRegion either draw or erase the focus rectangle depending on whether true or false is passed in the inHasFocus parameter.)

Another draw state constant (kThemeStatePressed) is available to draw certain primitives in the pressed mode; however, the primitives listed above can only be drawn in the active and inactive modes.

Drawing in Colours and Patterns Consistent With the Platinum Appearance and Aqua "Look"

The following functions are those used to draw using colours/patterns consistent with the Platinum appearance and Aqua "look". (Patterns are explained at Chapter 11.) The reference to colours and patterns reflects the fact that either a colour or a pattern may be used for the drawing

Brush Type Constants

The following are examples of constants, of type ThemeBrush, which are of type ThemeBrush, may be passed in the inBrush parameter of calls to SetThemeWindowBackground, SetThemeBackground, and SetThemePen to specify colours/patterns for user interface elements. For reasons explained above, these constants can represent either a straight colour or a pattern.

Text Colour Constants

Constants of type ThemeTextColor may be passed in the inColor parameter of the function SetThemeTextColor to specify theme-compliant text colours for user interface elements in their active, inactive, and highlighted states. Some of these constants are as follows:

Appearance Manager Text

The Appearance Manager function UseThemeFont may be used to set the font for the current graphics port.

Text drawn on Mac OS X using QuickDraw functions such as DrawString is not entirely satisfactory. You should therefore use the Appearance Manager function DrawThemeTextBox to draw text when your application is running on Mac OS X.

You pass a value of type ThemeFontID in the inFontID parameter of UseThemeFont and DrawThemeTextBox. The principal relevant constants are as follows:

Saving and Setting the Graphics Port Drawing State

Chapter 12 addresses certain measures which need to be taken consequential to the fact that both colours and patterns can be used by the Appearance functions SetThemeWindowBackground, SetThemeBackground, and SetThemePen. These measures have to do with saving, restoring, and normalising the drawing state of the graphics port. The associated functions are as follows:

Cursor Setting

The Appearance Manager introduced the following cursor-setting functions, the uses of which are addressed at Chapter 13:

Getting Menu Bar Height

The Appearance Manager introduced the function GetThemeMenuBarHeight. In most instances, the value returned by this function and GetMBarHeight are the same. However, when the menu bar is hidden, GetMBarHeight produces a value of 0, whereas GetThemeMenuBarHeight still returns the height of the (hidden) menu bar.

Appearance Manager Apple Events

On Mac OS 8/9, your application may need to respond to the user changing the system and/or views fonts using the Fonts tab in the Appearance control panel. Your application is advised of font changes via Appearance Manager Apple events. Appearance Manager Apple events are addressed at Chapter 10.

Prior to CarbonLib 1.1, it was necessary to call RegisterAppearanceClient at program launch in order for your application to receive Appearance Manager Apple events. However, in CarbonLib 1.1 and later, the CarbonLib initialisation routine calls RegisterAppearanceClient on behalf of your application, and there is thus no requirement for your application to call this function.

Main Constants, Data Types, and Functions

Constants

Theme-Compliant Brush Type Constants

kThemeBrushDialogBackgroundActive           = 1
kThemeBrushDialogBackgroundInactive         = 2
kThemeBrushAlertBackgroundActive            = 3
kThemeBrushAlertBackgroundInactive          = 4
kThemeBrushModelessDialogBackgroundActive   = 5
kThemeBrushModelessDialogBackgroundInactive = 6
kThemeBrushUtilityWindowBackgroundActive    = 7
kThemeBrushUtilityWindowBackgroundInactive  = 8
kThemeBrushListViewSortColumnBackground     = 9
kThemeBrushListViewBackground               = 10
kThemeBrushListViewSeparator                = 12
kThemeBrushDocumentWindowBackground         = 15
kThemeBrushFinderWindowBackground           = 16
kThemeBrushBlack                            = -1
kThemeBrushWhite                            = -2

Theme-Compliant Text Colour Constants

kThemeTextColorWindowHeaderActive   = 7
kThemeTextColorWindowHeaderInactive = 8
kThemeTextColorPlacardActive        = 9
kThemeTextColorPlacardInactive      = 10
kThemeTextColorPlacardPressed       = 11
kThemeTextColorListView             = 22
kThemeTextColorBlack                = -1
kThemeTextColorWhite                = -2

Theme-Compliant Draw State Constants (For Primitives)

kThemeStateInactive = 0
kThemeStateActive   = 1
kThemeStatePressed  = 2

Theme Cursor Constants

kThemeArrowCursor                 = 0
kThemeCopyArrowCursor             = 1
kThemeAliasArrowCursor            = 2
kThemeContextualMenuArrowCursor   = 3
kThemeIBeamCursor                 = 4
kThemeCrossCursor                 = 5
kThemePlusCursor                  = 6
kThemeWatchCursor                 = 7  // Can animate
kThemeClosedHandCursor            = 8
kThemeOpenHandCursor              = 9
kThemePointingHandCursor          = 10
kThemeCountingUpHandCursor        = 11  // Can animate
kThemeCountingDownHandCursor      = 12  // Can animate
kThemeCountingUpAndDownHandCursor = 13  // Can animate
kThemeSpinningCursor              = 14  // Can animate
kThemeResizeLeftCursor            = 15
kThemeResizeRightCursor           = 16
kThemeResizeLeftRightCursor       = 17

Font Costants

kThemeSystemFont                  = 0
kThemeSmallSystemFont             = 1
kThemeSmallEmphasizedSystemFont   = 2
kThemeViewsFont                   = 3
kThemeEmphasizedSystemFont        = 4
kThemeApplicationFont             = 5
kThemeLabelFont                   = 6
kThemeCurrentPortFont             = 200

Data Types

typedef UInt32 ThemeDrawState;
typedef SInt16 ThemeBrush;
typedef SInt16 ThemeTextColor;
typedef UInt32 ThemeCursor;
typedef struct OpaqueThemeDrawingState* ThemeDrawingState;

Functions

Drawing Appearance Primitives

OSStatus  DrawThemeWindowHeader(const Rect *inRect,ThemeDrawState inState);
OSStatus  DrawThemeWindowListViewHeader(const Rect *inRect,ThemeDrawState inState);
OSStatus  DrawThemePlacard(const Rect *inRect,ThemeDrawState inState);
OSStatus  DrawThemeEditTextFrame(const Rect *inRect,ThemeDrawState inState);
OSStatus  DrawThemeListBoxFrame(const Rect *inRect,ThemeDrawState inState);
OSStatus  DrawThemeFocusRect(const Rect *inRect,Boolean inHasFocus);
OSStatus  DrawThemePrimaryGroup(const Rect *inRect,ThemeDrawState inState);
OSStatus  DrawThemeSecondaryGroup(const Rect *inRect,ThemeDrawState inState);
OSStatus  DrawThemeSeparator(const Rect *inRect,ThemeDrawState inState);
OSStatus  DrawThemeModelessDialogFrame(const Rect *inRect,ThemeDrawState inState);
OSStatus  DrawThemeGenericWell(const Rect *inRect,ThemeDrawState inState,
          Boolean inFillCenter);
OSStatus  DrawThemeFocusRegion(RgnHandle inRegion,Boolean inHasFocus);
OSStatus  DrawThemeTab(const Rect *inRect,ThemeTabStyle inStyle,
          ThemeTabDirection inDirection,ThemeTabTitleDrawUPP labelProc,UInt32 userData);
OSStatus  DrawThemeTabPane(const Rect *inRect,ThemeDrawState inState);

Drawing in Colours/Patterns Consistent With With Platinum/Aqua

OSStatus  SetThemeWindowBackground(WindowPtr inWindow,ThemeBrush inBrush,Boolean inUpdate);
OSStatus  SetThemeBackground(ThemeBrush inBrush,SInt16 inDepth,Boolean inIsColorDevice);
OSStatus  SetThemePen(ThemeBrush inBrush,SInt16 inDepth,Boolean inIsColorDevice);
OSStatus  SetThemeTextColor(ThemeTextColor inColor,SInt16 inDepth,Boolean inIsColorDevice);

Setting and Getting the Graphics Port Font

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

Drawing Text

OSStatus  DrawThemeTextBox(CFStringRef inString,ThemeFontID inFontID,ThemeDrawState inState,
          Boolean inWrapToWidth,const Rect *inBoundingBox,SInt16 inJust,void *inContext);
OSStatus  TruncateThemeText(CFMutableStringRef inString,ThemeFontID inFontID,
          ThemeDrawState inState,SInt16 inPixelWidthLimit,TruncCode inTruncWhere,
          Boolean *outTruncated); 
OSStatus  GetThemeTextDimensions(CFStringRef inString,ThemeFontID inFontID,
          ThemeDrawState inState,Boolean inWrapToWidth,Point *ioBounds,SInt16 *outBaseline);
OSStatus  GetThemeTextShadowOutset(ThemeFontID inFontID,ThemeDrawState inState,
          Rect * outOutset);

Saving and Setting the Graphics Port Drawing State

OSStatus  NormalizeThemeDrawingState(void);
OSStatus  GetThemeDrawingState(ThemeDrawingState *outState);
OSStatus  SetThemeDrawingState(ThemeDrawingState inState,Boolean inDisposeNow);
OSStatus  DisposeThemeDrawingState(ThemeDrawingState inState);

Setting Appearance Cursors

OSStatus  SetThemeCursor(ThemeCursor inCursor);
OSStatus  SetAnimatedThemeCursor(ThemeCursorinCursor,UInt32 inAnimationStep);

Getting Menu Bar Height

OSStatus  GetThemeMenuBarHeight(SInt16 *outHeight);