Next Page >

Hide TOC

Fonts Panel Reference

Framework	CommonPanels.framework
Declared in	FontPanel.h

Overview

The Fonts Panel programming interface is a collection of functions and data types that support the use of a Fonts panel in a Carbon application. The Fonts panel is the preferred user interface for fonts in Mac OS X.

Functions

FPIsFontPanelVisible

Checks whether the Fonts panel is visible.

Boolean FPIsFontPanelVisible (
   void
);

Return Value

Returns true if the Fonts panel is visible; false otherwise. See the Mac Types documentation for a description of the Boolean data type.

Availability

Not available in CarbonLib 1.x.
Available in Mac OS X version 10.2.

Declared In

FontPanel.h

FPShowHideFontPanel

Shows or hides the Fonts panel.

OSStatus FPShowHideFontPanel (
   void
);

Return Value

A result code. See “Fonts Panel Results Codes.”

Discussion

The function FPShowHideFontPanel shows the Fonts panel if the panel is not visible and hides the Fonts panel if the panel is visible.

Availability

Not available in CarbonLib 1.x.
Available in Mac OS X version 10.2.

Declared In

FontPanel.h

SetFontInfoForSelection

Sets the selections that appear in the Fonts panel.

OSStatus SetFontInfoForSelection (
   OSType iStyleType,
   UInt32 iNumStyles,
   void *iStyles,
   EventTargetRef iFPEventTarget
);

Parameters

iStyleType: The type of style data you are passing to the Fonts panel. Pass kFontSelectionQDType if you supply a FontSelectionQDStyle data structure in the iStyles parameter. Pass kFontSelectionATSUIType if you supply ATSUStyle data in the iStyles parameter.
iNumStyles: The number of styles passed in the iStyles parameter.
iStyles: A pointer to an array of data structures that correspond to the style type specified by the iStyleType parameter.
iFPEventTarget: The event target you want to receive the Carbon event kEventFontSelection that is associated with the Fonts panel. You typically specify the event target for the window that is sending the style selection to the Fonts panel.

Return Value

A result code. See “Fonts Panel Results Codes.”

Discussion

You can programmatically set a selection in the Fonts panel by calling the function SetFontInfoForSelection. You can call this function even when the Fonts panel is not open or visible. When the Fonts panel becomes visible later, the style information specified in the most recent call to SetFontInfoForSelection is selected in the panel.

Availability

Not available in CarbonLib 1.x.
Available in Mac OS X version 10.2.

Declared In

FontPanel.h

Data Types

FontSelectionQDStyle

Contains QuickDraw style font information.

struct FontSelectionQDStyle {
   UInt32 version;
   FMFontFamilyInstance instance;
   FMFontSize size;
   Boolean hasColor;
   UInt8 reserved;
   RGBColor color;
};
typedef struct FontSelectionQDStyle FontSelectionQDStyle;
typedef FontSelectionQDStyle * FontSelectionQDStylePtr;

Fields

version: Specifies the version number of the data structure.
instance: Specifies a font family instance.
size: Specifies the font size in points.
hasColor: Specifies whether the font has a color other than black.
reserved: Reserved for future use.
color: Specifies the font color.

Discussion

You should use this data structure to specify QuickDraw-style font information when you call the function SetFontInfoForSelection. When you use this data structure, you must pass the constant kFontSelectionQDType in the iStyleType parameter of the function.

Availability

Available in Mac OS X v10.2 and later.

Declared In

FontPanel.h

FontSelectionQDStylePtr

A pointer to a data structure that contains QuickDraw style font information.

typedef FontSelectionQDStyle * FontSelectionQDStylePtr;

Discussion

See FontSelectionQDStyle for more information.

Availability

Available in Mac OS X v10.2 and later.

Declared In

FontPanel.h

Constants

Font Event Class

Specifies a Carbon event related to font selection or handling.

enum {
   kEventClassFont = 'font'
};

Constants

kEventClassFont

Specifies a Carbon event related to font selection or handling.

Available in Mac OS X v10.2 and later.

Declared in FontPanel.h.

Declared In

FontPanel.h

Fonts Panel Events

Specify a Fonts panel Carbon event.

enum {
   kEventFontPanelClosed = 1,
   kEventFontSelection = 2
};

Constants

kEventFontPanelClosed

Specifies a close event in the Fonts panel. Your application should update the user interface as necessary. For example, you may need to change a Hide Fonts Panel menu command to Show Fonts Panel.

Available in Mac OS X v10.2 and later.

Declared in FontPanel.h.

kEventFontSelection

Specifies a selection event in the Fonts panel. Your application can obtain the selections from the event parameters associated with this event. Your application must check for all those parameters it handles and apply the selections to the text.

Available in Mac OS X v10.2 and later.

Declared in FontPanel.h.

Discussion

When the user closes the Fonts panel, the action generates the Carbon event kEventWindowClosed. You can then update any menu items or other controls whose state may need to change. The event kEventWindowClosed has no parameters. However, when the user selects an item in the Fonts panel, the system sends the Carbon event kEventFontSelection to the event target you specified when your application called the Fonts Panel function SetFontInfoForSelection. The event kEventFontSelection has parameters that reflect the current Fonts panel selection.

Declared In

FontPanel.h

Font Information Types

Specify the type of font information.

enum {
   kFontSelectionATSUIType = 'astl',
   kFontSelectionQDType = 'qstl'
};

Constants

kFontSelectionATSUIType

Specifies ATSUI data (ATSUStyle).

Available in Mac OS X v10.2 and later.

Declared in FontPanel.h.

kFontSelectionQDType

Specifies QuickDraw data (FontSelectionQDStyle).

Available in Mac OS X v10.2 and later.

Declared in FontPanel.h.

Discussion

These constants specify the type of font information passed to the function SetFontInfoForSelection.

Declared In

FontPanel.h

Font Information Versions

Specify the supported versions of the FontSelectionQDStyle data structure.

enum {
   kFontSelectionQDStyleVersionZero = 0
};

Constants

kFontSelectionQDStyleVersionZero

Specifies version 0 of a QuickDraw font selection.

Available in Mac OS X v10.2 and later.

Declared in FontPanel.h.

Discussion

You should always set the version field in the FontSelectionQDStyle data structure to this constant

Declared In

FontPanel.h

Fonts Panel Command

Specifies the four-character code for the show/hide Fonts panel command.

enum {
   kHICommandShowHideFontPanel = 'shfp'
};

Constants

kHICommandShowHideFontPanel

Specifies the four-character code for the show/hide Fonts panel command.

Available in Mac OS X v10.2 and later.

Declared in FontPanel.h.

Discussion

If the user closes the Fonts panel directly, your application receives a kEventFontPanelClosed Carbon event. You can then call the Carbon Event Manager function GetEventParameter to extract the HI command from the event.

Declared In

FontPanel.h

Font Parameters and Data Types

Specify font event parameters and their associated data types.

enum {
   typeATSUFontID = typeUInt32,
   typeATSUSize = typeFixed,
   typeFMFontFamily = typeSInt16,
   typeFMFontStyle = typeSInt16,
   typeFMFontSize = typeSInt16,
   typeFontColor = typeRGBColor,
   kEventParamATSUFontID = 'auid',
   kEventParamATSUFontSize = 'ausz',
   kEventParamFMFontFamily = 'fmfm',
   kEventParamFMFontStyle = 'fmst',
   kEventParamFMFontSize = 'fmsz',
   kEventParamFontColor = 'fclr'
};

Constants

typeATSUFontID

Specifies that an ATSUFontID is of type UInt32.

Available in Mac OS X v10.2 and later.

Declared in FontPanel.h.

typeATSUSize

Specifies that an ATSUSize is of type Fixed.

Available in Mac OS X v10.2 and later.

Declared in FontPanel.h.

typeFMFontFamily

Specifies that an FMFontFamily is of type SInt16.

Available in Mac OS X v10.2 and later.

Declared in FontPanel.h.

typeFMFontStyle

Specifies that an FMFontStyle is of type SInt16.

Available in Mac OS X v10.2 and later.

Declared in FontPanel.h.

typeFMFontSize

Specifies that an FMFontSize is of type SInt16.

Available in Mac OS X v10.2 and later.

Declared in FontPanel.h.

typeFontColor

Specifies that a font color is of type RGBColor.

Available in Mac OS X v10.2 and later.

Declared in FontPanel.h.

kEventParamATSUFontID

Specifies the four-character code associated with an ATSUFontID selection in the Fonts panel.

Available in Mac OS X v10.2 and later.

Declared in FontPanel.h.

kEventParamATSUFontSize

Specifies the four-character code associated with an ATSUFontSize selection in the Fonts panel.

Available in Mac OS X v10.2 and later.

Declared in FontPanel.h.

kEventParamFMFontFamily

Specifies the four-character code associated with an FMFontFamily selection in the Fonts panel.

Available in Mac OS X v10.2 and later.

Declared in FontPanel.h.

kEventParamFMFontStyle

Specifies the four-character code associated with an FMFontStyle selection in the Fonts panel.

Available in Mac OS X v10.2 and later.

Declared in FontPanel.h.

kEventParamFMFontSize

Specifies the four-character code associated with an FMFontSize selection in the Fonts panel.

Available in Mac OS X v10.2 and later.

Declared in FontPanel.h.

kEventParamFontColor

Specifies the four-character code associated with a font color selection in the Fonts panel.

Available in Mac OS X v10.2 and later.

Declared in FontPanel.h.

Discussion

Table 1 lists the parameters and data types associated with the Carbon event kEventFontSelection.

**Table 1** Parameters and parameter data types for a font selection event.
Parameter	Data type
`kEventParamATSUFontID`	`typeATSUFontID`
`kEventParamATSUFontSize`	`typeATSUFontSize`
`kEventParamFMFontFamily`	`typeFMFontFamily`
`kEventParamFMFontStyle`	`typeFMFontStyle`
`kEventParamFMFontSize`	`typeFMFontSize`
`kEventParamFontColor`	`typeFontColor`

Declared In

FontPanel.h

Result Codes

The most common result codes returned by the Fonts Panel programming interface are listed below.

Result Code Value Description

Result Code	Value	Description
`fontPanelShowErr`	-8880	The Fonts panel could not be opened. Available in Mac OS X v10.2 and later.
`fontPanelSelectionStyleErr`	-8881	Your application specified an invalid style type in the `iStyleType` parameter of the `SetFontInfoForSelection` function. Available in Mac OS X v10.2 and later.
`fontPanelFontSelectionQDStyleVersionErr`	-8882	Your application specified an invalid version in the `version` field of the `FontSelectionQDStyle` data structure. Available in Mac OS X v10.2 and later.

fontPanelShowErr

-8880

The Fonts panel could not be opened.

Available in Mac OS X v10.2 and later.

fontPanelSelectionStyleErr

-8881

Your application specified an invalid style type in the iStyleType parameter of the SetFontInfoForSelection function.

Available in Mac OS X v10.2 and later.

fontPanelFontSelectionQDStyleVersionErr

-8882

Your application specified an invalid version in the version field of the FontSelectionQDStyle data structure.

Available in Mac OS X v10.2 and later.

Next 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.