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, dialog boxes, 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

Under 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, dialog boxes, alert boxes, menus, controls, etc.), together with a highlight colour (for selected text) and a variation colour (for menus and controls). (As of Mac OS 8.6, Platinum remains the only appearance provided by Apple.)

• 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).

• 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 box. 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.

• Coordinates the look of human interface elements and provides the underlying support for themes, particularly appearances.

• Enables you to adapt your application's custom human interface elements (if any) to the coordinated system-wide look, that is, to make those elements theme-compliant.

The Appearance Manager versions delivered as extensions are Versions 1.0, 1.0.1, 1.0.2, and 1.0.3. Version 1.0.2 or, preferably, Version 1.0.3 must be used on Macintoshes and Power Macintoshes running System 7.1 through 7.6.1. Versions 1.0 and 1.0.1 were delivered with, respectively, Mac OS 8.0 and 8.1; however, it is advisable to upgrade to Version 1.0.2 or, preferably, Version 1.0.3 on such systems.

The only difference between Versions 1.0.1 and 1.0.2 is that Version 1.0.2 contains extra code (for backward compatibility) and the ".Keyboard" font. The ".Keyboard" font is used to display keyboard glyphs in menus.

The only difference between Versions 1.0.2 and 1.0.3 is that Version 1.0.3 no longer contains the ".Keyboard" font. In Version 1.0.3, this font is delivered as a separate suitcase, which should be installed into the Fonts folder in the System folder. The purpose of this latter is to avoid a font ID conflict between the ".Keyboard" font and Microsoft Internet Explorer's Arial font.

New Definition Functions

• The menu bar definition function (MBDF) with resource ID 0.

• The menu definition function (MDEF) with resource ID 0.

• The window definition function (WDEF) with resource ID 0. (Document windows).

• The window definition function (WDEF) with resource ID 124. (Utility windows).

• The control definition function (CDEF) with resource ID 0. (Buttons, checkboxes, and radio buttons).

• The control definition function (CDEF) with resource ID 1. (Scroll bars).

• The control definition function (CDEF) with resource ID 63. (Pop-up menus).

Under Mac OS 8.5 (Appearance Version 1.1), mapping on a system-wide basis is permanently on. In earlier versions of the Appearance Manager:

• Mapping on a system-wide basis only occurs when the user has selected system-wide Appearance on in the Appearance control panel.

• You can ensure that mapping on an individual application basis will occur when the user has selected system-wide Appearance off in the Appearance control panel by calling the function RegisterAppearanceClient within your application.

The RegisterAppearanceClient Function

Disadvantages of Calling a Definition Function Via a Mapper

• Since a standard pre-Appearance WDEF cannot specify the inclusion of a horizontal zoom box, when a pre-Appearance WDEF is mapped to an theme-compliant WDEF, the resulting window will not have a horizontal zoom box.

• It is never necessary to call DrawGrowIcon to have the grow icon drawn in a window's size box when an theme-compliant WDEF is called directly. However, when it is called via the mapper, DrawGrowIcon must be called once for the grow icon to be drawn.

• When the theme-compliant WDEF for modal and movable modal dialog boxes is called via the mapper, the three-pixel-wide space between the content region and the structure region created by the pre-Appearance WDEF will remain. This space created certain difficulties in the past. When the theme-compliant WDEF is called directly, the three-pixel-wide space is banished.

The Gestalt function (see Chapter 23 - Miscellany) may be used to acquire a wide range of information about the operating environment, and may be used to determine:

• Whether the Appearance Manager and its functions are present.

• Whether the Macintosh is currently in compatibility mode, that is, whether the user has switched system-wide Appearance off in the Appearance control panel. . (This applies only under Appearance Manager 1.0.3 and earlier.)

• The version of the Appearance Manager that is present.

     OSErr    osError;
     SInt32   response;
     Boolean  appearancePresent    = false;
     Boolean  appearance101present = false;
     Boolean  appearance110present = false;
     Boolean  inCompatibilityMode  = false;

     osError = Gestalt(gestaltAppearanceAttr,&response);

     // If Gestalt returns no error and the bit in response represented by the constant
     // gestaltAppearanceExists is set, proceed, otherwise exit with an error message.

     if(osError == noErr && (BitTst(&response,31 - gestaltAppearanceExists)))
     {
       // At least Version 1.0 is present.  Set a flag.

       appearancePresent = true;

       // If the bit in response represented by the constant gestaltAppearanceCompatMode
       // is set, system-wide Appearance is off.  The result of this check will be
       // relevant only where Versions 1.0 through 1.0.3 are present.

       if(BitTst(&response,31 - gestaltAppearanceCompatMode))
         inCompatibilityMode = true;

       // Call Gestalt again with the gestaltAppearanceVersion selector.

       Gestalt(gestaltAppearanceVersion,&response);

       // If the low order word in response is 0x0101, Version 1.0.1, 1.0.2, or 1.0.3 is
       // present. If the low order word in response is 0x0110, Version 1.1 is available.

       if(response == 0x00000101)
         gAppearance101present = true;
       else if(response == 0x00000110)
         gAppearance110present = true;
     }
     else
     {
       // Present nil-Appearance error alert presented here, then exit.
     }

Your application might use these primitives to, for example:

• Draw a theme-compliant image of a placard, window header, edit text field frame, etc., when you don't want to use a control.

• Assist you in making a custom list box theme-compliant by using DrawThemeListBoxFrame to draw the frame and DrawThemeFocusRect to draw the focus ring.

Fig 3 and Fig 4 show examples, in the Platinum appearance, of images drawn in both the active and inactive modes using the Appearance primitives.

Draw State Constants

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 Current Appearance

Theme-Compliant Brush Type Constants

Theme-Compliant Text Colour Constants

Saving and Setting the Colour Graphics Port Drawing State

Version 1.1 of the Appearance Manager introduced new functions which simplify this process. These functions, the uses of which are addressed at Chapter 12, are as follows:

Theme-Compliant Cursors

Appearance Manager Apple Events

Provided you have called RegisterAppearanceClient, your application is advised of font and appearance changes via Appearance Manager Apple events. Appearance Manager Apple events are addressed at Chapter 10 � Apple Events.

Theme-Compliant Applications

• Call RegisterAppearanceClient early in your application code, prior to drawing any on-screen elements or invoking any definition functions. For many applications, this will be the only action required to render the application fully theme-compliant.

• Use the system-supplied theme-compliant menu and window definition functions.

• As will be explained at Chapter 7 - Introduction to Controls and at Chapter 14 - More on Controls, use the system-supplied theme-compliant control definition functions.

• As will be explained at Chapter 8 - Dialogs and Alerts:

  • Use the new 'dlgx' and 'alrx' resources to supplement your 'DLOG' and 'ALRT' resources.

  • Enable embedding and theme-compliant backgrounds.

  In addition, and because the Appearance Manager introduces a movable modal alert and simplifies the handling of movable modal alert and dialog boxes, make all your alerts and dialogs movable. Also use the StandardAlert routine, introduced with the Appearance Manager, to create your alerts whenever possible.

• Where you absolutely cannot use the system-supplied definition functions, use Appearance Manager functions in your custom definition functions to ensure that your custom human interface elements are theme-compliant.

• Use Appearance Manager functions and constants to get any colours/patterns you need to draw consistently with the current appearance, and to draw theme-compliant visual entities such as window headers when you don't want to use a control of that type.

• Because the measurements of standard interface objects may vary from appearance to appearance, make no assumptions about the dimensions of menus, windows, or controls. (For example, if you assume an unchanging menu bar height in order to position your windows, you could end up with the menu bar overlapping your windows after an appearance change.) Use Appearance Manager functions such as GetThemeMenuBarHeight to obtain the measurements used in the current appearance.

• Use the Appearance Manager functions SetThemeCursor and SetAnimatedThemeCursor to ensure that your application's cursors are theme-compliant.

The task may be phased, however, by taking one simple initial step. That step is to simply insert a call to RegisterAppearanceClient early in your code. This will cause the mappers to invoke the new definition functions.

When converting an application under Versions 1.0 through 1.0.3 of the Appearance Manager, be sure to select system-wide Appearance off in the Appearance control panel. This puts your system back into the old System 7 look for applications that have not adopted Appearance, which makes it easy for you to tell where you have implemented the new look and where you still have work to do. (If you are running with system-wide Appearance selected on, you will not be able to distinguish the changes you've made from those performed automatically by the system.)

Memory Requirements

Main Constants, Data Types, and Functions

• Those items appearing in light blue are available only only with Appearance Version 1.0.1 through 1.0.3 and later.

• Those items appearing in dark blue are available only with Appearance Version 1.1 and later.

gestaltAppearanceAttr        = FOUR_CHAR_CODE('appr')
gestaltAppearanceExists      = 0
gestaltAppearanceCompatMode  = 1
gestaltAppearanceVersion     = FOUR_CHAR_CODE('apvr')

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

kThemeTextColorWindowHeaderActive           = 7
kThemeTextColorWindowHeaderInactive         = 8
kThemeTextColorPlacardActive                = 9
kThemeTextColorPlacardInactive              = 10
kThemeTextColorPlacardPressed               = 11
kThemeTextColorListView                     = 22

kThemeStateDisabled  = 0
kThemeStateActive    = 1
kThemeStatePressed   = 2

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

typedef UInt32 ThemeDrawState;
typedef SInt16 ThemeBrush;
typedef SInt16 ThemeTextColor;

OSStatus	RegisterAppearanceClient(void);

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);

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)
OSStatus  GetThemeAccentColors(CTabHandle *outColors);
OSStatus  IsThemeInColor(SInt16 inDepth,Boolean inIsColorDevice)

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

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