< Previous PageNext Page >

Hide TOC

Legacy Document

Important: The Palette Manager is deprecated as of Mac OS X v10.4. There is no replacement.

Deprecated Palette Manager Reference (Not Recommended) Functions

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

Deprecated in Mac OS X v10.4

ActivatePalette

Changes the device color tables and generates window updates as needed to meet the color requirements of your window. (Deprecated in Mac OS X v10.4. There is no replacement; 8-bit graphics mode is not supported by the Mac OS X GUI.)

Not recommended.

void ActivatePalette (
   WindowRef srcWindow
);

Parameters

srcWindow: A pointer to the window for which you want status changes reported.

Discussion

The Window Manager calls ActivatePalette when your window’s status changes—for example, when your window opens, closes, moves, or becomes frontmost. You need to call the ActivatePalette function yourself if you change a palette—for example, by changing a color with the SetEntryColor function—and you want the changes to take place immediately, before the Window Manager would do it.

If the window specified in the srcWindow parameter is frontmost, ActivatePalette examines the information stored in the window’s palette and attempts to provide the color environment described therein. It determines a list of devices on which to render the palette by intersecting the port rectangle of the window with each device. If the intersection is not empty and if the device has a color table, then ActivatePalette checks to see if the color environment is sufficient. If a change is required, ActivatePalette calls QuickDraw to reserve or modify the device’s color entries as needed. The ActivatePalette function then generates update events for all windows that need color updates.

Calling ActivatePalette with an offscreen graphics world has no effect.

Special Considerations

For applications running in Mac OS X, the Palette Manager is no longer relevant because display devices always support direct color (pixel depth of 16 or 32 bits). The palette-based graphics model only works in 256-color (8-bit pseudocolor) modes of operation, which are not supported for the Mac OS X GUI.

There is some support for palettes in Quartz Services; see Quartz Display Services Reference.

Availability

Available in Mac OS X v10.0 and later.
Deprecated in Mac OS X v10.4.
Not available to 64-bit applications.

Declared In

Palettes.h

AnimateEntry

Changes the color of a window’s palette entry. (Deprecated in Mac OS X v10.4. There is no replacement; 8-bit graphics mode is not supported by the Mac OS X GUI.)

Not recommended.

void AnimateEntry (
   WindowRef dstWindow,
   short dstEntry,
   const RGBColor *srcRGB
);

Parameters

dstWindow: A pointer to the window whose palette color is to be changed.
dstEntry: The palette entry to be changed.
srcRGB: A pointer to the new RGB value.

Discussion

The AnimateEntry function changes the RGB value of an animated entry for a window’s palette. Each device for which that index has been reserved is immediately modified to contain the new value. This is not considered to be a change to the device’s color environment because no other windows should be using the animated entry.

If the palette entry is not an animated color or if the associated indexes are no longer reserved, no animation occurs.

If you have blocked color updates in a window by using SetPalette with cUpdates set to FALSE, you may observe unintentional animation. This occurs when ActivatePalette reserves for animation device indexes that are already used in the window. Redrawing the window, which normally is the result of a color update event, removes any animated colors that do not belong to the window.

Special Considerations

There is some support for palettes in Quartz Services; see Quartz Display Services Reference.

Availability

Available in Mac OS X v10.0 and later.
Deprecated in Mac OS X v10.4.
Not available to 64-bit applications.

Declared In

Palettes.h

AnimatePalette

Changes the colors of a series of palette entries; it is similar to the AnimateEntry function, but it acts upon a range of entries. (Deprecated in Mac OS X v10.4. There is no replacement; 8-bit graphics mode is not supported by the Mac OS X GUI.)

Not recommended.

void AnimatePalette (
   WindowRef dstWindow,
   CTabHandle srcCTab,
   short srcIndex,
   short dstEntry,
   short dstLength
);

Parameters

dstWindow: A pointer to the window whose palette colors are to be changed.
srcCTab: A handle to the color table containing the new colors.
srcIndex: The source color table entry at which copying starts.
dstEntry: The palette entry at which copying starts.
dstLength: The number of palette entries to be changed.

Discussion

The AnimatePalette function changes the colors of a series of palette entries. Beginning at the index specified by the srcIndex parameter (which has a minimum value of 0), the number of entries specified in dstLength are copied from the source color table to the destination window’s palette, beginning at the entry specified in the dstEntry parameter. If the source color table specified in srcCTab is not sufficiently large to accommodate the request, AnimatePalette modifies as many entries as possible and leaves the remaining entries unchanged.

Special Considerations

There is some support for palettes in Quartz Services; see Quartz Display Services Reference.

Availability

Available in Mac OS X v10.0 and later.
Deprecated in Mac OS X v10.4.
Not available to 64-bit applications.

Declared In

Palettes.h

CopyPalette

Copies entries from one palette to another. (Deprecated in Mac OS X v10.4. There is no replacement; 8-bit graphics mode is not supported by the Mac OS X GUI.)

Not recommended.

void CopyPalette (
   PaletteHandle srcPalette,
   PaletteHandle dstPalette,
   short srcEntry,
   short dstEntry,
   short dstLength
);

Parameters

srcPalette: A handle to the palette from which colors are copied.
dstPalette: A handle to the palette to which colors are copied.
srcEntry: The source palette entry at which copying starts.
dstEntry: The destination palette entry at which copying starts.
dstLength: The number of destination palette entries to change.

Discussion

The CopyPalette function copies entries from the source palette into the destination palette. The copy operation begins at the values specified by the srcEntry and dstEntry parameters, copying into as many entries as are specified by the dstLength parameter. CopyPalette resizes the destination palette when the number of entries after the copy operation is greater than it was before the copy operation.

CopyPalette does not call ActivatePalette, so your application is free to change the palette a number of times without causing a series of intermediate changes to the color environment. Your application should call ActivatePalette after completing all palette changes.

If either of the palette handles is NULL, CopyPalette does nothing.

Special Considerations

There is some support for palettes in Quartz Services; see Quartz Display Services Reference.

Availability

Available in Mac OS X v10.0 and later.
Deprecated in Mac OS X v10.4.
Not available to 64-bit applications.

Declared In

Palettes.h

CTab2Palette

Copies the colors of a color table into a palette. (Deprecated in Mac OS X v10.4. There is no replacement; 8-bit graphics mode is not supported by the Mac OS X GUI.)

Not recommended.

void CTab2Palette (
   CTabHandle srcCTab,
   PaletteHandle dstPalette,
   short srcUsage,
   short srcTolerance
);

Parameters

srcCTab: A handle to the color table whose colors are to be copied.
dstPalette: The palette to receive the colors.
srcUsage: A usage constant to be assigned the palette entries. Usage constants are described in “Update Constants.”
srcTolerance: A tolerance value to be assigned the palette entries.

Discussion

The CTab2Palette function copies the fields from an existing color-table structure into an existing palette structure. If the structures are not the same size, then CTab2Palette resizes the palette structure to match the number of entries in the color-table structure. If the palette in dstPalette has any entries allocated for animation on any screen device, they are relinquished before the new colors are copied. The srcUsage and srcTolerance parameters are the value that you assign to the new colors.

If you want to use color-table animation, you can use AnimateEntry and AnimatePalette to change the colors in a palette and on corresponding devices. Changes made to a palette by CTab2Palette do not take effect until the next ActivatePalette function is performed. If either the color-table handle or the palette handle is NULL, CTab2Palette does nothing.

Special Considerations

There is some support for palettes in Quartz Services; see Quartz Display Services Reference.

Availability

Available in Mac OS X v10.0 and later.
Deprecated in Mac OS X v10.4.
Not available to 64-bit applications.

Declared In

Palettes.h

DisposePalette

Disposes of a palette. (Deprecated in Mac OS X v10.4. There is no replacement; 8-bit graphics mode is not supported by the Mac OS X GUI.)

Not recommended.

void DisposePalette (
   PaletteHandle srcPalette
);

Parameters

srcPalette: A handle to the palette to be disposed of.

Discussion

If the palette has any entries allocated for animation on any screen device, then DisposePalette relinquishes these entries before the palette’s memory is released.

If a palette is attached to a window automatically—because the palette resource and the window have the same ID—you do not have to call the DisposePalette function to dispose of the function. The Palette Manager and Window Manager dispose of the palette automatically if the palette is replaced or if the window goes away.

However, if you explicitly attach a palette to a window with the SetPalette or NSetPalette function, your application owns the palette and is responsible for disposing of it. It is possible to attach a single palette to multiple windows; therefore, even when a window goes away and no longer needs a palette, other windows may still need it.

Special Considerations

There is some support for palettes in Quartz Services; see Quartz Display Services Reference.

Availability

Available in Mac OS X v10.0 and later.
Deprecated in Mac OS X v10.4.
Not available to 64-bit applications.

Declared In

Palettes.h

Entry2Index

Obtains the index for a specified entry in the current graphics port’s palette on the current device. (Deprecated in Mac OS X v10.4. There is no replacement; 8-bit graphics mode is not supported by the Mac OS X GUI.)

Not recommended.

SInt32 Entry2Index (
   short entry
);

Parameters

entry: The palette entry whose equivalent device index is to be returned.

Return Value

The index of the given entry.

Special Considerations

There is some support for palettes in Quartz Services; see Quartz Display Services Reference.

Availability

Available in Mac OS X v10.0 and later.
Deprecated in Mac OS X v10.4.
Not available to 64-bit applications.

Declared In

Palettes.h

GetEntryColor

Obtains the color of a palette entry. (Deprecated in Mac OS X v10.4. There is no replacement; 8-bit graphics mode is not supported by the Mac OS X GUI.)

Not recommended.

void GetEntryColor (
   PaletteHandle srcPalette,
   short srcEntry,
   RGBColor *dstRGB
);

Parameters

srcPalette: A handle to the palette to be accessed.
srcEntry: The palette entry whose color is desired.
dstRGB: A pointer to an RGB color structure to receive the palette color.

Discussion

You can modify the entry’s color using the SetEntryColor function.

Special Considerations

There is some support for palettes in Quartz Services; see Quartz Display Services Reference.

Availability

Available in Mac OS X v10.0 and later.
Deprecated in Mac OS X v10.4.
Not available to 64-bit applications.

Declared In

Palettes.h

GetEntryUsage

Obtains the usage and tolerance fields of a palette entry. (Deprecated in Mac OS X v10.4. There is no replacement; 8-bit graphics mode is not supported by the Mac OS X GUI.)

Not recommended.

void GetEntryUsage (
   PaletteHandle srcPalette,
   short srcEntry,
   short *dstUsage,
   short *dstTolerance
);

Parameters

srcPalette: A handle to the palette to be accessed.
srcEntry: The palette entry whose usage and tolerance are desired.
dstUsage: A pointer to the usage value of the palette entry.
dstTolerance: A pointer to the tolerance value of the palette entry.

Discussion

You can modify the entry’s usage and tolerance values by using the SetEntryUsage function.

Special Considerations

There is some support for palettes in Quartz Services; see Quartz Display Services Reference.

Availability

Available in Mac OS X v10.0 and later.
Deprecated in Mac OS X v10.4.
Not available to 64-bit applications.

Declared In

Palettes.h

GetGray

Determines the best intermediate color between two colors on a given graphics device. (Deprecated in Mac OS X v10.4. There is no replacement; 8-bit graphics mode is not supported by the Mac OS X GUI.)

Boolean GetGray (
   GDHandle device,
   const RGBColor *backGround,
   RGBColor *foreGround
);

Parameters

device: A handle to the graphics device for which an intermediate color or gray is needed.
backGround: The RGBColor structure for one of the two colors for which you want an intermediate color.
foreGround: On input, the RGBColor structure for the other of the two colors; upon completion, the best intermediate color between these two.

Return Value

If no gray is available (or if no distinguishable third color is available), the foreGround parameter is unchanged, and the function returns FALSE. If at least one gray or intermediate color is available, it is returned in the foreGround parameter, and the function returns TRUE.

Discussion

The GetGray function determines the midpoint values for the red, green, and blue values of the two colors you specify in the backGround and foreGround parameters.

You can also use GetGray to return the best gray. For example, when dimming an object, supply black and white as the two colors, and GetGray returns the best available gray that lies between them.

Special Considerations

There is some support for palettes in Quartz Services; see Quartz Display Services Reference.

Availability

Available in Mac OS X v10.0 and later.
Deprecated in Mac OS X v10.4.
Not available to 64-bit applications.

Declared In

Palettes.h

GetNewPalette

Creates and initializes a palette from a ‘pltt’ resource. (Deprecated in Mac OS X v10.4. There is no replacement; 8-bit graphics mode is not supported by the Mac OS X GUI.)

Not recommended.

PaletteHandle GetNewPalette (
   short PaletteID
);

Parameters

PaletteID: The resource ID of the source palette.

Return Value

A handle to the new palette.

Discussion

The GetNewPalette function detaches the resource when it creates the new palette, so you do not need to call the ReleaseResource function.

If you open a new color window with GetNewCWindow, the Window Manager calls GetNewPalette automatically, with paletteID equal to the window’s resource ID. Therefore, if you have created a palette resource with the same ID as a window, the Window Manager and Palette Manager automatically create the palette for you and your application need not call GetNewPalette to create the palette.

To attach a palette to a window after creating it, use the SetPalette function. To change the entries in a palette after creating it, use the SetEntryColor and SetEntryUsage functions.

Special Considerations

There is some support for palettes in Quartz Services; see Quartz Display Services Reference.

Availability

Available in Mac OS X v10.0 and later.
Deprecated in Mac OS X v10.4.
Not available to 64-bit applications.

Declared In

Palettes.h

GetPalette

Obtains a window’s palette. (Deprecated in Mac OS X v10.4. There is no replacement; 8-bit graphics mode is not supported by the Mac OS X GUI.)

Not recommended.

PaletteHandle GetPalette (
   WindowRef srcWindow
);

Parameters

srcWindow: A pointer to the window for which you want the associated palette.

Return Value

A handle to the palette associated with the window specified in the srcWindow parameter or NULL if the window has no associated palette or is not a color window.

Discussion

Normally, the GetPalette function does not allocate memory, with one exception. When your application calls GetPalette to get a copy of the default application palette, the Palette Manager looks at the AppPalette global variable. If AppPalette is NULL, GetPalette makes a copy of the default system palette and returns a handle to this copy.

You request the default palette as follows:

myPaletteHndl = GetPalette ((WindowPtr) -1);

Special Considerations

There is some support for palettes in Quartz Services; see Quartz Display Services Reference.

Availability

Available in Mac OS X v10.0 and later.
Deprecated in Mac OS X v10.4.
Not available to 64-bit applications.

Declared In

Palettes.h

GetPaletteUpdates

Obtains the update attribute of a palette. (Deprecated in Mac OS X v10.4. There is no replacement; 8-bit graphics mode is not supported by the Mac OS X GUI.)

Not recommended.

short GetPaletteUpdates (
   PaletteHandle p
);

Parameters

p: A handle to the palette.

Return Value

One of the update attributes described in “Update Constants.”

Special Considerations

There is some support for palettes in Quartz Services; see Quartz Display Services Reference.

Availability

Available in Mac OS X v10.0 and later.
Deprecated in Mac OS X v10.4.
Not available to 64-bit applications.

Declared In

Palettes.h

HasDepth

Determines whether a video device supports a specific pixel depth. (Deprecated in Mac OS X v10.4. There is no replacement; 8-bit graphics mode is not supported by the Mac OS X GUI.)

short HasDepth (
   GDHandle gd,
   short depth,
   short whichFlags,
   short flags
);

Parameters

gd: A handle to the GDevice structure of the video device.
depth: The pixel depth for which you’re testing.
whichFlags: The gdDevType constant, which represents a bit in the gdFlags field of the GDevice structure. If this bit is set to 0 in the GDevice structure, the video device is black and white; if the bit is set to 1, the device supports color.
flags: The value 0 or 1. If you pass 0 in this parameter, the HasDepth function tests whether the video device is black and white. If you pass 1 in this parameter, HasDepth tests whether the video device supports color.

Return Value

Returns 0 if the device does not support the depth you specify in the depth parameter or the display mode you specify in the flags parameter. Any other value indicates that the device supports the specified depth and display mode. The function result contains the mode ID that QuickDraw passes to the video driver to set its pixel depth and to specify color or black and white. You can pass this mode ID in the depth parameter for the SetDepth function to set the graphics device to the pixel depth and display mode for which you tested.

Special Considerations

There is some support for palettes in Quartz Services; see Quartz Display Services Reference.

Availability

Available in Mac OS X v10.0 and later.
Deprecated in Mac OS X v10.4.
Not available to 64-bit applications.

Declared In

Palettes.h

InitPalettes

Initializes the Palette Manager. (Deprecated in Mac OS X v10.4. There is no replacement; 8-bit graphics mode is not supported by the Mac OS X GUI.)

Not recommended.

void InitPalettes (
   void
);

Discussion

The InitPalettes function searches for devices that support a device color table and initializes an internal data structure for each one. Your application does not have to call InitPalettes because the Window Manager’s InitWindows function calls it automatically.

Special Considerations

There is some support for palettes in Quartz Services; see Quartz Display Services Reference.

Availability

Available in Mac OS X v10.0 and later.
Deprecated in Mac OS X v10.4.
Not available to 64-bit applications.

Declared In

Palettes.h

NewPalette

Allocates a new palette from colors in the color table. (Deprecated in Mac OS X v10.4. There is no replacement; 8-bit graphics mode is not supported by the Mac OS X GUI.)

Not recommended.

PaletteHandle NewPalette (
   short entries,
   CTabHandle srcColors,
   short srcUsage,
   short srcTolerance
);

Parameters

entries: The number of ColorInfo structures to be created in the new palette.
srcColors: A handle to the color table from which the colors are to be obtained. If no color table is provided (srcColors = NULL), then all colors in the palette are set to black (red, green, and blue equal to $0000).
srcUsage: The usage value to be assigned each ColorInfo structure in the palette.
srcTolerance: The tolerance value to be assigned each ColorInfo structure in the palette.

Return Value

A handle to the new palette.

Discussion

The NewPalette function fills the palette with as many RGB values from the color table as it has or can fit.

To attach a palette to a window after creating it, use the SetPalette function. To change the entries in a palette after creating it, use the SetEntryColor and SetEntryUsage functions.

Special Considerations

There is some support for palettes in Quartz Services; see Quartz Display Services Reference.

Availability

Available in Mac OS X v10.0 and later.
Deprecated in Mac OS X v10.4.
Not available to 64-bit applications.

Declared In

Palettes.h

NSetPalette

Associates a new palette with a window. (Deprecated in Mac OS X v10.4. There is no replacement; 8-bit graphics mode is not supported by the Mac OS X GUI.)

Not recommended.

void NSetPalette (
   WindowRef dstWindow,
   PaletteHandle srcPalette,
   short nCUpdates
);

Parameters

dstWindow: A pointer to the window to which you want to assign a new palette.
srcPalette: A handle to the palette you want to assign.
nCUpdates: An integer value in which you specify whether the window is to receive updates as a result of various changes to the color environment. See “Update Constants” for a description of the update options.

Discussion

NSetPalette changes the palette associated with the window specified in the dstWindow parameter to the palette specified by srcPalette. NSetPalette also records whether the window is to receive updates as a result of changes to its color environment. The update constants, which you pass to the nCUpdates parameter, determine when the window is updated.

This function is identical to the SetPalette function except that the nCUpdates parameter is an integer rather than a Boolean value, so that a variety of conditions can trigger an update event.

Use the SetPalette function if you do not need the flexibility that NSetPalette provides for update events.

Use the GetNewPalette function or the NewPalette function to create a new palette. To dispose of a palette, use the DisposePalette function.

Special Considerations

There is some support for palettes in Quartz Services; see Quartz Display Services Reference.

Availability

Available in Mac OS X v10.0 and later.
Deprecated in Mac OS X v10.4.
Not available to 64-bit applications.

Declared In

Palettes.h

Palette2CTab

Copies the colors of a palette into a color table. (Deprecated in Mac OS X v10.4. There is no replacement; 8-bit graphics mode is not supported by the Mac OS X GUI.)

Not recommended.

void Palette2CTab (
   PaletteHandle srcPalette,
   CTabHandle dstCTab
);

Parameters

srcPalette: A handle to the palette whose colors are to be used.
dstCTab: A handle to the color table to receive the colors.

Discussion

The Palette2CTab function copies all of the colors from an existing palette structure into an existing color-table structure. If the structures are not the same size, then Palette2CTab resizes the color-table structure to match the number of entries in the palette structure. If either the palette handle or the color-table handle is NULL, Palette2CTab does nothing.

Special Considerations

There is some support for palettes in Quartz Services; see Quartz Display Services Reference.

Availability

Available in Mac OS X v10.0 and later.
Deprecated in Mac OS X v10.4.
Not available to 64-bit applications.

Declared In

Palettes.h

PmBackColor

Sets the background color field of the current graphics port to a palette color. (Deprecated in Mac OS X v10.4. There is no replacement; 8-bit graphics mode is not supported by the Mac OS X GUI.)

Not recommended.

void PmBackColor (
   short dstEntry
);

Parameters

dstEntry: The palette entry whose color is to be used as the background color.

Discussion

The PmBackColor function sets the current color graphics port’s rgbBkColor field to match the color in the entry specified by the dstEntry parameter of the palette associated with the current window structure. For courteous and tolerant entries, PmBackColor calls the RGBBackColor function using the RGB color of the palette entry. For animated colors, PmBackColor selects the recorded device index previously reserved for animation (if still present) and installs it in the color graphics port. The rgbBgColor field is set to the value from the palette entry. For explicit colors, PmBackColor places the value

dstEntry modulo (maxIndex +1)

into the color graphics port, where maxIndex is the largest index available in a device’s color table. When multiple devices with different depths are present, maxIndex varies appropriately for each device.

Special Considerations

There is some support for palettes in Quartz Services; see Quartz Display Services Reference.

Availability

Available in Mac OS X v10.0 and later.
Deprecated in Mac OS X v10.4.
Not available to 64-bit applications.

Declared In

Palettes.h

PmForeColor

Sets the foreground color field of the current graphics port to a palette color. (Deprecated in Mac OS X v10.4. There is no replacement; 8-bit graphics mode is not supported by the Mac OS X GUI.)

Not recommended.

void PmForeColor (
   short dstEntry
);

Parameters

dstEntry: The palette entry whose color is to be used as the foreground color.

Discussion

The PmForeColor function sets the current color graphics port’s rgbFgColor field to match the color in the entry specified by the dstEntry parameter of the palette associated with the current window structure. For courteous and tolerant entries, PmForeColor calls the RGBForeColor function using the RGB color of the palette entry. For animated colors, PmForeColor selects the recorded device index previously reserved for animation (if still present) and installs it in the color graphics port. The RGB foreground color field is set to the value from the palette entry. For explicit colors, PmForeColor places the value

dstEntry modulo (maxIndex +1)

into the color graphics port, where maxIndex is the largest index available in a device’s color table. When multiple devices with different depths are present, the value of maxIndex varies appropriately for each device.

Special Considerations

There is some support for palettes in Quartz Services; see Quartz Display Services Reference.

Availability

Available in Mac OS X v10.0 and later.
Deprecated in Mac OS X v10.4.
Not available to 64-bit applications.

Declared In

Palettes.h

PMgrVersion

Determines which version of the Palette Manager is executing; it returns an integer specifying the version number. (Deprecated in Mac OS X v10.4. There is no replacement; 8-bit graphics mode is not supported by the Mac OS X GUI.)

short PMgrVersion (
   void
);

Return Value

PMgrVersion returns $0202 if system software version 7.0 is executing; $0201 if system software version 6.0.5 is executing; and $0200 if the original 32-Bit QuickDraw system extension is executing.

Special Considerations

There is some support for palettes in Quartz Services; see Quartz Display Services Reference.

Availability

Available in Mac OS X v10.0 and later.
Deprecated in Mac OS X v10.4.
Not available to 64-bit applications.

Declared In

Palettes.h

ResizePalette

Changes the size of a palette. (Deprecated in Mac OS X v10.4. There is no replacement; 8-bit graphics mode is not supported by the Mac OS X GUI.)

Not recommended.

void ResizePalette (
   PaletteHandle p,
   short size
);

Parameters

p: A handle to the palette to be resized.
size: The number of resulting entries in the palette.

Discussion

The ResizePalette function sets the palette specified in srcPalette to the number of entries indicated in the size parameter. If ResizePalette adds entries at the end of the palette, it sets them to pmCourteous, with the RGB values set to (0,0,0)—that is, black. If ResizePalette deletes entries from the end of the palette, it safely disposes of them.

Special Considerations

There is some support for palettes in Quartz Services; see Quartz Display Services Reference.

Availability

Available in Mac OS X v10.0 and later.
Deprecated in Mac OS X v10.4.
Not available to 64-bit applications.

Declared In

Palettes.h

RestoreBack

Sets the current background color to the color you specify. (Deprecated in Mac OS X v10.4. There is no replacement; 8-bit graphics mode is not supported by the Mac OS X GUI.)

Not recommended.

void RestoreBack (
   const ColorSpec *c
);

Parameters

c: A pointer to the ColorSpec structure containing the RGB color to be set as the background color. If you specify 0 in the value field of the ColorSpec structure, the RestoreBack function stores the RGB value in the rgbFgColor field of the current CGrafPort structure. If you specify 1 in the value field of the ColorSpec structure, the RestoreBack function stores the RGB value in the pmBkColor field of the GrafVars structure.

Special Considerations

There is some support for palettes in Quartz Services; see Quartz Display Services Reference.

Availability

Available in Mac OS X v10.0 and later.
Deprecated in Mac OS X v10.4.
Not available to 64-bit applications.

Declared In

Palettes.h

RestoreDeviceClut

Sets the color table of a graphics device to its default state. (Deprecated in Mac OS X v10.4. There is no replacement; 8-bit graphics mode is not supported by the Mac OS X GUI.)

Not recommended.

void RestoreDeviceClut (
   GDHandle gd
);

Parameters

gd: A handle to the GDevice structure. Pass NULL in the gdh parameter to restore all screens.

Discussion

The RestoreDeviceClut function changes the color table of the device specified by the gdh parameter to its default state. If this process changes any entries, the Palette Manager posts color updates to windows intersecting the device.

You do not need to use this function to restore the Finder’s desktop colors, because its colors are automatically restored upon switching from applications that use the Palette Manager. Likewise, you need not worry when switching to another application that uses the Palette Manager. Although colors are not automatically restored in this case, if that application needs a certain set of colors, the Palette Manager provides them the moment that application comes to the front.

The reason to use RestoreDeviceClut is that you may be switching to an application that does not use the Palette Manager, in which case that application inherits your palette unless you restore the default color lookup tables for all the available display devices.

Special Considerations

There is some support for palettes in Quartz Services; see Quartz Display Services Reference.

Availability

Available in Mac OS X v10.0 and later.
Deprecated in Mac OS X v10.4.
Not available to 64-bit applications.

Declared In

Palettes.h

RestoreFore

Sets the current foreground color to the color you supply. (Deprecated in Mac OS X v10.4. There is no replacement; 8-bit graphics mode is not supported by the Mac OS X GUI.)

Not recommended.

void RestoreFore (
   const ColorSpec *c
);

Parameters

c: A pointer to the ColorSpec structure containing the RGB color to be set as the foreground color. If you specify 0 in the value field of the ColorSpec structure, the RestoreFore function stores the RGB value in the rgbFgColor field of the current CGrafPort structure. If you specify 1 in the value field of the ColorSpec structure, the RestoreFore function stores the RGB value in the pmFgColor field of the GrafVars structure.

Special Considerations

There is some support for palettes in Quartz Services; see Quartz Display Services Reference.

Availability

Available in Mac OS X v10.0 and later.
Deprecated in Mac OS X v10.4.
Not available to 64-bit applications.

Declared In

Palettes.h

SaveBack

Saves the current background color. (Deprecated in Mac OS X v10.4. There is no replacement; 8-bit graphics mode is not supported by the Mac OS X GUI.)

Not recommended.

void SaveBack (
   ColorSpec *c
);

Parameters

c: A pointer to the ColorSpec structure to receive the current background color. A value of 0 in the value field of the ColorSpec structure specifies retrieving the RGB color from the rgbBkColor field of the CGrafPort structure; a value of 1 in the value field specifies retrieving the palette entry from the pmBkColor field of the GrafVars structure.

Special Considerations

There is some support for palettes in Quartz Services; see Quartz Display Services Reference.

Availability

Available in Mac OS X v10.0 and later.
Deprecated in Mac OS X v10.4.
Not available to 64-bit applications.

Declared In

Palettes.h

SaveFore

Saves the current foreground color. (Deprecated in Mac OS X v10.4. There is no replacement; 8-bit graphics mode is not supported by the Mac OS X GUI.)

Not recommended.

void SaveFore (
   ColorSpec *c
);

Parameters

c: A pointer to the ColorSpec structure to hold the current foreground color. A value of 0 in the value field of the ColorSpec structure specifies retrieving the RGB color from the rgbFgColor field of the CGrafPort structure; a value of 1 in the value field specifies retrieving the palette entry from the pmFgColor field of the GrafVars structure.On return, ColorSpec structure holds the current foreground color. You can save either QuickDraw’s foreground color from the CGrafPort structure or the Palette Manager’s foreground color from the GrafVars structure.

Special Considerations

There is some support for palettes in Quartz Services; see Quartz Display Services Reference.

Availability

Available in Mac OS X v10.0 and later.
Deprecated in Mac OS X v10.4.
Not available to 64-bit applications.

Declared In

Palettes.h

SetEntryColor

Changes the color of a palette entry. (Deprecated in Mac OS X v10.4. There is no replacement; 8-bit graphics mode is not supported by the Mac OS X GUI.)

Not recommended.

void SetEntryColor (
   PaletteHandle dstPalette,
   short dstEntry,
   const RGBColor *srcRGB
);

Parameters

dstPalette: The palette whose entry color is to be changed.
dstEntry: The palette entry to be changed.
srcRGB: A pointer to the new RGB color value.

Discussion

SetEntryColor marks the entry as having changed, but it does not change the color environment. That change occurs upon the next call to ActivatePalette. SetEntryColor marks modified entries such that the palette is updated, even though no update is required by a change in the color environment.

Special Considerations

There is some support for palettes in Quartz Services; see Quartz Display Services Reference.

Availability

Available in Mac OS X v10.0 and later.
Deprecated in Mac OS X v10.4.
Not available to 64-bit applications.

Declared In

Palettes.h

SetEntryUsage

Modifies the usage category and tolerance values of a palette entry. (Deprecated in Mac OS X v10.4. There is no replacement; 8-bit graphics mode is not supported by the Mac OS X GUI.)

Not recommended.

void SetEntryUsage (
   PaletteHandle dstPalette,
   short dstEntry,
   short srcUsage,
   short srcTolerance
);

Parameters

dstPalette: A handle to the palette to be modified.
dstEntry: The palette entry.
srcUsage: The new usage value; one or more usage constants.
srcTolerance: The new tolerance value.

Discussion

SetEntryUsage marks the entry as having changed, but it does not change the color environment. That change occurs upon the next call to ActivatePalette. Modified entries are marked such that the palette is updated even though no update is required by a change in the color environment. If either srcUsage or srcTolerance is set to $FFFF (–1), the entries are not changed.

This function allows you to easily modify a palette created with NewPalette or modified by CTab2Palette. For such palettes the ciUsage and ciTolerance fields of the ColorInfo structure are the same because you can designate only one value for each. You typically call SetEntryUsage after NewPalette or CTab2Palette to adjust and customize your palette.

Special Considerations

There is some support for palettes in Quartz Services; see Quartz Display Services Reference.

Availability

Available in Mac OS X v10.0 and later.
Deprecated in Mac OS X v10.4.
Not available to 64-bit applications.

Declared In

Palettes.h

SetPalette

Associates a palette with a window. (Deprecated in Mac OS X v10.4. There is no replacement; 8-bit graphics mode is not supported by the Mac OS X GUI.)

Not recommended.

void SetPalette (
   WindowRef dstWindow,
   PaletteHandle srcPalette,
   Boolean cUpdates
);

Parameters

dstWindow: A pointer to the window to which you want to assign a new palette.
srcPalette: A handle to the palette you want to assign.
cUpdates: A Boolean value in which your application specifies whether the window is to receive updates as a result of changes to the color environment. Specify TRUE if you want the window to be updated, even if the window is not the frontmost window. When a window is the frontmost window, changes to its palette cause it to get an update event regardless of how the cUpdates parameter is set.

Discussion

You can use the NSetPalette function, which does the same thing as SetPalette, when you need greater flexibility in setting criteria for updates. The nCUpdates parameter for the NSetPalette function includes the option of turning off updates when the window is the frontmost window.

Use the NSetPalette function to associate a palette with a window but with additional options as to when an update event is triggered by changes to the color environment.

Use the GetNewPalette function or the NewPalette function to create a new palette. To dispose of a palette, use the DisposePalette function.

Special Considerations

There is some support for palettes in Quartz Services; see Quartz Display Services Reference.

Availability

Available in Mac OS X v10.0 and later.
Deprecated in Mac OS X v10.4.
Not available to 64-bit applications.

Declared In

Palettes.h

SetPaletteUpdates

Sets the update attribute of a palette. (Deprecated in Mac OS X v10.4. There is no replacement; 8-bit graphics mode is not supported by the Mac OS X GUI.)

Not recommended.

void SetPaletteUpdates (
   PaletteHandle p,
   short updates
);

Parameters

p: A handle to the palette.
updates: One of the update attributes for the NSetPalette function. See “Update Constants” for a description of the update attributes.

Special Considerations

There is some support for palettes in Quartz Services; see Quartz Display Services Reference.

Availability

Available in Mac OS X v10.0 and later.
Deprecated in Mac OS X v10.4.
Not available to 64-bit applications.

Declared In

Palettes.h

< Previous PageNext Page >

Hide TOC

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.