#ifndef CONTROLS_H
#define CONTROLS_H

#ifndef APPLICATIONSERVICES_H
#include <ApplicationServices/ApplicationServices.h>
#endif

#ifndef ICONS_H
#include <HIServices/Icons.h>
#endif

#ifndef APPEARANCE_H
#include <HIToolbox/Appearance.h>
#endif

#ifndef HIOBJECT_H
#include <HIToolbox/HIObject.h>
#endif

#ifndef MENUS_H
#include <HIToolbox/Menus.h>
#endif

#ifndef TEXTEDIT_H
#include <HIToolbox/TextEdit.h>
#endif

#ifndef DRAG_H
#include <HIToolbox/Drag.h>
#endif

#ifndef CONTROLDEFINITIONS_H
//#include <HIToolbox/ControlDefinitions.h> //hys
#endif

#include <HYS/HIToolbox/Controls.h>
#include <AvailabilityMacros.h>

#if PRAGMA_ONCE
#pragma once
#endif

#ifdef __cplusplus
extern "C" {
#endif

/*Control Use Theme Font ID Mask Constant

enum {
   kControlUseThemeFontIDMask = 0x0080
};*/

enum {
   kControlUseThemeFontIDMask = 0x0080
};


/*ControlBackgroundRec

struct ControlBackgroundRec {
   SInt16 depth;
   Boolean colorDevice;
};
typedef struct ControlBackgroundRec ControlBackgroundRec;
typedef ControlBackgroundRec * ControlBackgroundPtr;
Fields
depth

A signed 16-bit integer indicating the bit depth (in pixels) of the current graphics port. 
colorDevice

A Boolean value. If true, you are drawing on a color device. If false, you are drawing on a monochrome device. 
Availability
Available in Mac OS X v10.0 and later.*/
struct ControlBackgroundRec {
   SInt16 depth;
   Boolean colorDevice;
};
typedef struct ControlBackgroundRec ControlBackgroundRec;
typedef ControlBackgroundRec * ControlBackgroundPtr;



/*Mac OS 8.5 Control Font Style Flag Constant

enum {
   kControlAddToMetaFontMask = 0x0200
};
Constants
kControlAddToMetaFontMask

If the bit specified by this mask is set, the control may use a meta-font while also adding other attributes to the font. If the bit specified by this mask is not set, but a meta-font is specified for the control, any additional attributes set for the font are ignored.

Available in Mac OS X v10.0 and later.
Discussion

With the Mac OS 8.5 Control Manager, you can pass this new control font style flag constant in the flags field of the ControlFontStyleRec structure to specify the fields of the structure that should be applied to the control. For more on control font style flag constants, see “Control Font Style Flag Constants” and the “ControlFontStyleRec” structure.*/

enum {
   kControlAddToMetaFontMask = 0x0200
};


/*Meta Font Constants

enum {
   kControlFontBigSystemFont = -1,
   kControlFontSmallSystemFont = -2,
   kControlFontSmallBoldSystemFont = -3,
   kControlFontViewSystemFont = -4
};
Constants
kControlFontBigSystemFont

Use the system font.

Available in Mac OS X v10.0 and later.
kControlFontSmallSystemFont

Use the small system font.

Available in Mac OS X v10.0 and later.
kControlFontSmallBoldSystemFont

Use the small emphasized system font (emphasis applied correctly for locale).

Available in Mac OS X v10.0 and later.
Discussion

You can use the meta font constants in the font field of the structure ControlFontStyleRec and the Font ID field of a dialog font table resource to specify the style, size, and font family of the control font. You should use these meta font constants whenever possible because the system font can change, depending upon the current theme. If none of these constants are specified, the control uses the system font unless directed to use a window font by a control variant.
Version Notes

The meta font constants are available with Appearance Manager 1.0 and later.*/
enum {
   kControlFontBigSystemFont = -1,
   kControlFontSmallSystemFont = -2,
   kControlFontSmallBoldSystemFont = -3,
   kControlFontViewSystemFont = -4
};


/*Control Meta Part Code Constants

enum {
   kControlStructureMetaPart = -1,
   kControlContentMetaPart = -2
};
Constants
kControlStructureMetaPart

Identifies the entire region occupied by a control. The kControlStructureMetaPart constant is for use only with GetControlRegion.

Available in Mac OS X v10.0 and later.
kControlContentMetaPart

Identifies the area of a control in which other controls may be embedded; this region is only defined for controls that can be embedders. The kControlContentMetaPart constant is for use only with GetControlRegion.

Available in Mac OS X v10.0 and later.
Discussion

The Mac OS 8.5 Control Manager defines these new “meta” part code constants for controls. You can use control part codes with various functions to identify control parts. For details on other control part code constants, see “Control Part Code Constants” and “Control State Part Code Constants”.*/
enum {
   kControlStructureMetaPart = -1,
   kControlContentMetaPart = -2
};



/*Control Focus Part Code Constants

enum {
   kControlFocusNoPart = 0,
   kControlFocusNextPart = -1,
   kControlFocusPrevPart = -2
};
Constants
kControlFocusNoPart

Your control definition function should relinquish its focus and return kControlFocusNoPart. It might respond by deactivating its text edit handle and erasing its focus ring. If the control is at the end of its subparts, it should return kControlFocusNoPart. This tells the focusing mechanism to jump to the next control that supports focus.

Available in Mac OS X v10.0 and later.
kControlFocusNextPart

Your control definition function should change keyboard focus to its next part, the entire control, or remove keyboard focus from the control, depending upon the circumstances.

For multiple part controls that already had keyboard focus, the next part of the control would receive keyboard focus when kControlFocusNextPart was passed in the param parameter. For example, a clock control with keyboard focus would change its focus to the left-most element of the control (the month field).

For single-part controls that did not have keyboard focus and are now receiving it, the entire control would receive keyboard focus when kControlFocusNextPart was passed in the param parameter.

For single-part controls that already had keyboard focus and are now losing it, the entire control would lose keyboard focus.

If you are passed kControlFocusNextPart and have run out of parts, return kControlFocusNoPart to indicate that the user tabbed past the control.

Available in Mac OS X v10.0 and later.
kControlFocusPrevPart

Your control definition function should change keyboard focus to its previous part, the entire control, or remove keyboard focus from the control, depending upon the circumstances.

For multiple part controls that already had keyboard focus, the previous part of the control would receive keyboard focus when kControlFocusPrevPart was passed in the param parameter. For example, a clock control with keyboard focus would change its focus to the right-most element of the control (the year field).

For single-part controls that did not have keyboard focus and are now receiving it, the entire control would receive keyboard focus when kControlFocusNextPart was passed in the param parameter.

For single-part controls that already had keyboard focus and are now losing it, the entire control would lose keyboard focus.

If you are passed kControlFocusPrevPart and have run out of parts, return kControlFocusNoPart to indicate that the user tabbed past the control.

Available in Mac OS X v10.0 and later.*/
enum {
   kControlFocusNoPart = 0,
   kControlFocusNextPart = -1,
   kControlFocusPrevPart = -2
};



/*Key Filter Result Codes

enum {
   kControlKeyFilterBlockKey = 0,
   kControlKeyFilterPassKey = 1
};
Constants
kControlKeyFilterBlockKey

The keystroke is blocked and not received by the control.

Available in Mac OS X v10.0 and later.
kControlKeyFilterPassKey

The keystroke is filtered and received by the control.

Available in Mac OS X v10.0 and later.
Discussion

Your key filter function returns these constants to specify whether or not a keystroke is filtered or blocked.*/
enum {
   kControlKeyFilterBlockKey = 0,
   kControlKeyFilterPassKey = 1
};


/*ControlKeyFilterResult

typedef SInt16 ControlKeyFilterResult;
Availability
Available in Mac OS X v10.0 and later.*/
typedef SInt16 ControlKeyFilterResult;


/*ControlFocusPart

typedef SInt16 ControlFocusPart;
Availability
Available in Mac OS X v10.0 and later.*/
typedef SInt16 ControlFocusPart;

/*Control State Part Code Constants

enum {
   kControlNoPart = 0,
   kControlIndicatorPart = 129,
   kControlDisabledPart = 254,
   kControlInactivePart = 255
};
Constants
kControlNoPart

Identifies no specific control part. This value unhighlights any highlighted part of the control when passed to the HiliteControl function. For events in bevel buttons with an attached menu, this part code indicates that either the mouse was released outside the bevel button and menu or that the button was disabled.

Available in Mac OS X v10.0 and later.
kControlIndicatorPart

Identifies the scroll box of a scroll bar control.

Available in Mac OS X v10.0 and later.
kControlDisabledPart

Used with HiliteControlto disable the control.

Available in Mac OS X v10.0 and later.
kControlInactivePart

Used with HiliteControl to make the control inactive.

Available in Mac OS X v10.0 and later.
Discussion

Constants of type ControlPartCode identify specific parts of controls.

Part codes are meaningful only within the scope of a single control definition function. For example, the standard tab control uses part codes 1...N, where N is the number of tabs, even though those numbers do collide with part codes defined for use with other control definition functions. Therefore, when you wish to specify part codes for the tab control for use with the function SetControlData, for example, you should use a part code corresponding to a 1-based index of the tab whose data you wish to set. In other words, the first tab is part code 1, the second tab is part code 2, and so on.

Note that if you wish to create part codes for a custom control definition function, you may assign values anywhere within the ranges 1–128 and 130–253. Note also that the function FindControl does not typically return the kControlDisabledPart or kControlInactivePart part codes and never returns them with standard controls.*/
enum {
   kControlNoPart = 0,
   kControlIndicatorPart = 129,
   kControlDisabledPart = 254,
   kControlInactivePart = 255
};


/*Control Font Style and Key Filter Data Tag Constants

enum {
   kControlFontStyleTag = 'font',
   kControlKeyFilterTag = 'fltr',
   kControlKindTag = 'kind',
   kControlSizeTag = 'size'
};
Constants
kControlFontStyleTag

Sent with a pointer to a ControlKind record to be filled in. Only valid for GetControlData.

Available in Mac OS X v10.0 and later.
kControlKeyFilterTag

Gets or sets the key filter function for controls that handle filtered input (includes editable text and list box).

Data type returned or set: ControlKeyFilterUPP

Available in Mac OS X v10.0 and later.
Discussion

You can use the control data tag constants to set or obtain data that is associated with a control. The control data tag constants are passed in the inTagName parameters of SetControlData and GetControlData to specify the piece of data in a control that you wish to set or get. You can also pass these constants in the inTagName parameter of GetControlDataSize if you wish to determine the size of variable-length control data (e.g., text in an editable text control). These constants can also be used by custom control definition functions that return the feature bit kControlSupportsDataAccess in response to a kControlMsgGetFeatures message.

The data that your application sets or obtains can be of various types, dependent upon the control. Therefore, the descriptions of the control data tag constants list the data types for the information that you can set in the inData parameter to the SetControlData function and that you can get in the inBuffer parameter to the GetControlData function. 
Version Notes

The control data tag constants are available with Appearance Manager 1.0 and later.*/
enum {
   kControlFontStyleTag = 'font',
   kControlKeyFilterTag = 'fltr',
   kControlKindTag = 'kind',
   kControlSizeTag = 'size'
};

/*ControlRef

typedef struct OpaqueControlRef * ControlRef;
Availability
Available in Mac OS X v10.0 and later.*/
typedef struct OpaqueControlRef * ControlRef;

/*Control Entire Control Constant

enum {
   kControlEntireControl = 0
};*/
enum {
   kControlEntireControl = 0
};

/*Control Font Style Flag Constants

enum {
   kControlUseFontMask = 0x0001,
   kControlUseFaceMask = 0x0002,
   kControlUseSizeMask = 0x0004,
   kControlUseForeColorMask = 0x0008,
   kControlUseBackColorMask = 0x0010,
   kControlUseModeMask = 0x0020,
   kControlUseJustMask = 0x0040,
   kControlUseAllMask = 0x00FF,
   kControlAddFontSizeMask = 0x0100
};
Constants
kControlUseFontMask

If the kControlUseFontMask flag is set (bit 0), the font field of the control font style structure is applied to the control.

Available in Mac OS X v10.0 and later.
kControlUseFaceMask

If the kControlUseFaceMask flag is set (bit 1), the style field of the control font style structure is applied to the control. This flag is ignored if you specify a meta font value; see “Meta Font Constants”. 

Available in Mac OS X v10.0 and later.
kControlUseSizeMask

If the kControlUseSizeMask flag is set (bit 2), the size field of the control font style structure is applied to the control. This flag is ignored if you specify a meta font value; see “Meta Font Constants”.

Available in Mac OS X v10.0 and later.
kControlUseForeColorMask

If the kControlUseForeColorMask flag is set (bit 3), the foreColor field of the control font style structure is applied to the control. This flag only applies to static text controls.

Available in Mac OS X v10.0 and later.
kControlUseBackColorMask

If the kControlUseBackColorMask flag is set (bit 4), the backColor field of the control font style structure is applied to the control. This flag only applies to static text controls.

Available in Mac OS X v10.0 and later.
kControlUseModeMask

If the kControlUseModeMask flag is set (bit 5), the text mode specified in the mode field of the control font style structure is applied to the control.

Available in Mac OS X v10.0 and later.
kControlUseJustMask

If the kControlUseJustMask flag is set (bit 6), the just field of the control font style structure is applied to the control.

Available in Mac OS X v10.0 and later.
kControlUseAllMask

If kControlUseAllMask is used, all flags in this mask will be set except kControlUseAddFontSizeMask.

Available in Mac OS X v10.0 and later.
kControlAddFontSizeMask

If the kControlUseAddFontSizeMask flag is set (bit 8), the Dialog Manager will add a specified font size to the size field of the control font style structure. This flag is ignored if you specify a meta font value; see “Meta Font Constants”.

Available in Mac OS X v10.0 and later.
Discussion

You can pass one or more control font style flag constants in the flags field of the control font style structure to specify the field(s) of the structure that should be applied to the control; see “ControlFontStyleRec”. If none of the flags are set, the control uses the system font unless a control variant specifies use of a window font.
Version Notes

These control font style flag constants are available with Appearance Manager 1.0 and later.*/
enum {
   kControlUseFontMask = 0x0001,
   kControlUseFaceMask = 0x0002,
   kControlUseSizeMask = 0x0004,
   kControlUseForeColorMask = 0x0008,
   kControlUseBackColorMask = 0x0010,
   kControlUseModeMask = 0x0020,
   kControlUseJustMask = 0x0040,
   kControlUseAllMask = 0x00FF,
   kControlAddFontSizeMask = 0x0100
};

/*ControlRef

typedef struct OpaqueControlRef * ControlRef;
Availability
Available in Mac OS X v10.0 and later.*/
typedef struct OpaqueControlRef * ControlRef;

/*Control Features Constants

enum {
   kControlSupportsGhosting = 1 << 0,
   kControlSupportsEmbedding = 1 << 1,
   kControlSupportsFocus = 1 << 2,
   kControlWantsIdle = 1 << 3,
   kControlWantsActivate = 1 << 4,
   kControlHandlesTracking = 1 << 5,
   kControlSupportsDataAccess = 1 << 6,
   kControlHasSpecialBackground = 1 << 7,
   kControlGetsFocusOnClick = 1 << 8,
   kControlSupportsCalcBestRect = 1 << 9,
   kControlSupportsLiveFeedback = 1 << 10,
   kControlHasRadioBehavior = 1 << 11,
   kControlSupportsDragAndDrop = 1 << 12,
   kControlAutoToggles = 1 << 14,
   kControlSupportsGetRegion = 1 << 17,
   kControlSupportsFlattening = 1 << 19,
   kControlSupportsSetCursor = 1 << 20,
   kControlSupportsContextualMenus = 1 << 21,
   kControlSupportsClickActivation = 1 << 22,
   kControlIdlesWithTimer = 1 << 23
};
Constants
kControlSupportsGhosting

If this bit (bit 0) is set, the control definition function supports the kControlMsgDrawGhost message.

Available in Mac OS X v10.0 and later.
kControlSupportsEmbedding

If this bit (bit 1) is set, the control definition function supports the kControlMsgSubControlAdded and kControlMsgSubControlRemovedmessages.

Available in Mac OS X v10.0 and later.
kControlSupportsFocus

If this bit (bit 2) is set, the control definition function supports the kControlMsgKeyDown message. If this bit and the kControlGetsFocusOnClick bit are set, the control definition function supports the kControlMsgFocus message.

Available in Mac OS X v10.0 and later.
kControlWantsIdle

If this bit (bit 3) is set, the control definition function supports the kControlMsgIdle message.

Available in Mac OS X v10.0 and later.
kControlWantsActivate

If this bit (bit 4) is set, the control definition function supports the kControlMsgActivate message.

Available in Mac OS X v10.0 and later.
kControlHandlesTracking

If this bit (bit 5) is set, the control definition function supports the kControlMsgHandleTracking message. 

Available in Mac OS X v10.0 and later.
kControlSupportsDataAccess

If this bit (bit 6) is set, the control definition function supports the kControlMsgGetData and kControlMsgSetData messages.

Available in Mac OS X v10.0 and later.
kControlHasSpecialBackground

If this bit (bit 7) is set, the control definition function supports the kControlMsgSetUpBackground message. 

Available in Mac OS X v10.0 and later.
kControlGetsFocusOnClick

If this bit (bit 8) and the kControlSupportsFocus bit are set, the control definition function supports the kControlMsgFocus message.

Available in Mac OS X v10.0 and later.
kControlSupportsCalcBestRect

If this bit (bit 9) is set, the control definition function supports the kControlMsgCalcBestRect message. 

Available in Mac OS X v10.0 and later.
kControlSupportsLiveFeedback

If this bit (bit 10) is set, the control definition function supports the kControlMsgCalcValueFromPos message. 

Available in Mac OS X v10.0 and later.
kControlHasRadioBehavior

If this bit (bit 11) is set, the control definition function supports radio button behavior and can be embedded in a radio group control. This constant is available with Appearance 1.0.1 and later. 

Available in Mac OS X v10.0 and later.
kControlAutoToggles

If the bit specified by this mask is set, the control definition function supports automatically changing among various states (on, off, mixed) in response to user actions.

Available in Mac OS X v10.0 and later.
kControlSupportsGetRegion

If the bit specified by this mask is set, the control definition function supports the kControlMsgGetRegion message, described in “Control Definition Message Constants”.

Available in Mac OS X v10.0 and later.
Discussion

If your control definition function supports Appearance-compliant messages, it should return a bit field of the features it supports, composed of one or more of these bits.*/
enum {
   kControlSupportsGhosting = 1 << 0,
   kControlSupportsEmbedding = 1 << 1,
   kControlSupportsFocus = 1 << 2,
   kControlWantsIdle = 1 << 3,
   kControlWantsActivate = 1 << 4,
   kControlHandlesTracking = 1 << 5,
   kControlSupportsDataAccess = 1 << 6,
   kControlHasSpecialBackground = 1 << 7,
   kControlGetsFocusOnClick = 1 << 8,
   kControlSupportsCalcBestRect = 1 << 9,
   kControlSupportsLiveFeedback = 1 << 10,
   kControlHasRadioBehavior = 1 << 11,
   kControlSupportsDragAndDrop = 1 << 12,
   kControlAutoToggles = 1 << 14,
   kControlSupportsGetRegion = 1 << 17,
   kControlSupportsFlattening = 1 << 19,
   kControlSupportsSetCursor = 1 << 20,
   kControlSupportsContextualMenus = 1 << 21,
   kControlSupportsClickActivation = 1 << 22,
   kControlIdlesWithTimer = 1 << 23
};

/*Control Content Type Constants

enum {
   kControlContentTextOnly = 0,
   kControlNoContent = 0,
   kControlContentIconSuiteRes = 1,
   kControlContentCIconRes = 2,
   kControlContentPictRes = 3,
   kControlContentICONRes = 4,
   kControlContentIconSuiteHandle = 129,
   kControlContentCIconHandle = 130,
   kControlContentPictHandle = 131,
   kControlContentIconRef = 132,
   kControlContentICON = 133
};
Constants
kControlContentTextOnly

Content type is text. This constant is passed in the contentType field of the ControlButtonContentInfo structure if the content is text only. The variation code kControlUsesOwningWindowsFontVariant applies when text content is used. 

Available in Mac OS X v10.0 and later.
kControlContentIconSuiteRes

Content type uses an icon suite resource ID. The resource ID of the icon suite resource you wish to display should be in the resID field of the ControlButtonContentInfo structure. 

Available in Mac OS X v10.0 and later.
kControlContentCIconRes

Content type is a color icon resource ID. The resource ID of the color icon resource you wish to display should be in the resID field of the ControlButtonContentInfo structure.

Available in Mac OS X v10.0 and later.
kControlContentPictRes

Content type is a picture resource ID. The resource ID of the picture resource you wish to display should be in the resID field of the ControlButtonContentInfo structure.

Available in Mac OS X v10.0 and later.
kControlContentIconSuiteHandle

Content type is an icon suite handle. The handle of the icon suite you wish to display should be in the iconSuite field of the ControlButtonContentInfo structure.

Available in Mac OS X v10.0 and later.
kControlContentCIconHandle

Content type uses a color icon handle. The handle of the color icon you wish to display should be in the cIconHandle field of the ControlButtonContentInfo structure.

Available in Mac OS X v10.0 and later.
kControlContentPictHandle

Content type uses a picture handle. The handle of the picture you wish to display should be in the picture field of the ControlButtonContentInfo structure.

Available in Mac OS X v10.0 and later.
kControlContentIconRef

Content type is IconRef. An IconRef value for the icon you wish to display should be provided in the iconRef field of the ControlButtonContentInfo structure. Note that the kControlBevelButtonGraphicOffsetTag control data tag constant should not be used with IconRef based bevel button content, because IconRef based icons may change with a theme switch; see “Bevel Button Control Data Tag Constants”. Supported with Mac OS 8.5 and later.

Available in Mac OS X v10.0 and later.*/
enum {
   kControlContentTextOnly = 0,
   kControlNoContent = 0,
   kControlContentIconSuiteRes = 1,
   kControlContentCIconRes = 2,
   kControlContentPictRes = 3,
   kControlContentICONRes = 4,
   kControlContentIconSuiteHandle = 129,
   kControlContentCIconHandle = 130,
   kControlContentPictHandle = 131,
   kControlContentIconRef = 132,
   kControlContentICON = 133
};


/*ControlFontStyleRec

struct ControlFontStyleRec {
   SInt16 flags;
   SInt16 font;
   SInt16 size;
   SInt16 style;
   SInt16 mode;
   SInt16 just;
   RGBColor foreColor;
   RGBColor backColor;
};
typedef struct ControlFontStyleRec ControlFontStyleRec;
typedef ControlFontStyleRec * ControlFontStylePtr;
Fields
flags

A value specifying which fields of the structure should be applied to the control; see “Mac OS 8.5 Control Font Style Flag Constant” and “Control Font Style Flag Constants”. If none of the flags in the flags field of the structure are set, the control uses the system font unless the control variant kControlUsesOwningWindowsFontVariant has been specified, in which case the control uses the window font. 
font

If the kControlUseFontMask bit is set, then this field contains a value specifying the ID of the font family to use. If this bit is not set, then the system default font is used. A meta font constant can be specified instead; see “Meta Font Constants”.
size

If the kControlUseSizeMask bit is set, then this field contains a value specifying the point size of the text. If the kControlAddSizeMask bit is set, this value will represent the size to add to the current point size of the text. A meta font constant can be specified instead; see “Meta Font Constants”.
style

If the kControlUseFaceMask bit is set, then this field contains a value specifying which styles to apply to the text. If all bits are clear, the plain font style is used. The bit numbers and the styles they represent are bold (0), italic (1), underline (2), outline (3), shadow (4), condensed (5), and extended (6).
mode

If the kControlUseModeMask bit is set, then this field contains a value specifying how characters are drawn in the bit image. See Inside Macintosh: Imaging With QuickDraw for a discussion of transfer modes.
just

If the kControlUseJustMask bit is set, then this field contains a value specifying text justification. Possible values are teFlushDefault (0), teCenter (1), teFlushRight (-1), and teFlushLeft (-2).
foreColor

If the kControlUseForeColorMask bit is set, then this field contains an RGB color value to use when drawing the text. 
backColor

If the kControlUseBackColorMask bit is set, then this field contains an RGB color value to use when drawing the background behind the text. In certain text modes, background color is ignored.
Discussion

You can use the ControlFontStyleRec type to specify a control’s font. You pass a pointer to the control font style structure in the inStyle parameter of SetControlFontStyle to specify a control’s font. If none of the flags in the flags field of the structure are set, the control uses the system font unless the control variant kControlUsesOwningWindowsFontVariant has been specified, in which case the control uses the window font. The ControlFontStyleRec type is available with Appearance Manager 1.0 and later.

Note that if you wish to specify the font for controls in a dialog box, you should use a dialog font table resource, which is automatically read in by the Dialog Manager. 
Availability
Available in Mac OS X v10.0 and later.*/
struct ControlFontStyleRec {
   SInt16 flags;
   SInt16 font;
   SInt16 size;
   SInt16 style;
   SInt16 mode;
   SInt16 just;
   RGBColor foreColor;
   RGBColor backColor;
};
typedef struct ControlFontStyleRec ControlFontStyleRec;
typedef ControlFontStyleRec * ControlFontStylePtr;

/*ControlContentType

typedef SInt16 ControlContentType;
Availability
Available in Mac OS X v10.0 and later.*/
typedef SInt16 ControlContentType;

/*ControlButtonContentInfo

struct ControlButtonContentInfo {
   ControlContentType contentType
   union {
      SInt16 resID;
      CIconHandle cIconHandle;
      Handle iconSuite;
      IconRef iconRef;
      PicHandle picture;
      Handle ICONHandle;
      CGImageRef imageRef;
   } u;
};
typedef struct ControlButtonContentInfo ControlButtonContentInfo;
typedef ControlButtonContentInfo ControlImageContentInfo;
Fields
contentType

Specifies the bevel button or image well content type and whether the content is text-only, resource-based, or handle-based; see “Control Content Type Constants” for possible values. The value specified in the contentType field determines which of the other fields in the structure are used. For a description of this data type, see “ControlContentType”.
u

If the content type specified in the contentType field is kControlContentIconSuiteRes, kControlContentCIconRes, or kControlContentPictRes, this field contains the resource ID of a picture, color icon, or icon suite resource. If the contentType field is kControlContentCGImageRef, this field contains a CGImageRef.
Discussion

You can use the ControlButtonContentInfo structure to specify the content for a bevel button or image well. Values of type ControlButtonContentInfo are set via SetControlData and obtained from GetControlData, in conjunction with the kControlBevelButtonContentTag and kControlImageWellContentTag constants; see “Bevel Button Control Data Tag Constants” and “Image Well Control Data Tag Constants”. 
Version Notes

The ControlButtonContentInfo type is available with Appearance Manager 1.0 and later.
Availability
Available in Mac OS X v10.0 and later.*/
struct ControlButtonContentInfo {
   ControlContentType contentType;
   union {
      SInt16 resID;
      CIconHandle cIconHandle;
      Handle iconSuite;
      IconRef iconRef;
      PicHandle picture;
      Handle ICONHandle;
      CGImageRef imageRef;
   } u;
};
typedef struct ControlButtonContentInfo ControlButtonContentInfo;
typedef ControlButtonContentInfo ControlImageContentInfo;


/*Control Size Constants

enum {
   kControlSizeNormal = 0,
   kControlSizeSmall = 1,
   kControlSizeLarge = 2,
   kControlSizeAuto = 0xFFFF
};*/
enum {
   kControlSizeNormal = 0,
   kControlSizeSmall = 1,
   kControlSizeLarge = 2,
   kControlSizeAuto = 0xFFFF
};

/*ControlPartCode

typedef SInt16 ControlPartCode;
Availability
Available in Mac OS X v10.0 and later.*/
typedef SInt16 ControlPartCode;

/*ControlID

struct ControlID {
   OSType signature;
   SInt32 id;
};
typedef struct ControlID ControlID;
typedef ControlID HIViewID;
Availability
Available in Mac OS X v10.0 and later.*/
struct ControlID {
   OSType signature;
   SInt32 id;
};
typedef struct ControlID ControlID;

/*ControlRef

typedef struct OpaqueControlRef * ControlRef;
Availability
Available in Mac OS X v10.0 and later.*/
typedef struct OpaqueControlRef * ControlRef;


/*ControlActionProcPtr

Defines actions to be performed repeatedly in response to a mouse-down event in a control part.

typedef void (*ControlActionProcPtr) (
   ControlRef theControl,
   ControlPartCode partCode
);

If you name your function MyControlActionProc, you would declare it like this:

void MyControlActionProc (
   ControlRef theControl,
   ControlPartCode partCode
);
Parameters
theControl

A handle to the control in which the mouse-down event occurred. For a description of this data type, see “ControlRef”.
partCode

A control part code; see “Control Part Code Constants”, “Control Part Code Constants”, and “Control State Part Code Constants”. When the cursor is still in the control part where the mouse-down event first occurred, this parameter contains that control’s part code. When the user drags the cursor outside the original control part, this parameter contains 0.
Discussion

The Control Manager defines the data type ControlActionUPP to identify the universal procedure pointer for this application-defined function:

typedef UniversalProcPtr ControlActionUPP; 

You typically use the NewControlActionProc macro like this:

ControlActionUPP myActionUPP; 

myActionUPP = NewControlActionProc(MyControlActionCallback); 

You typically use the CallControlActionProc macro like this:

CallControlActionProc(MyActionUPP, theControl, partCode); 

When a mouse-down event occurs in a control, HandleControlClick and TrackControl respond as is appropriate, typically by highlighting the control or dragging the indicator as long as the user holds down the mouse button. You can define other actions to be performed repeatedly during this interval. To do so, define your own action function and point to it in the actionProc parameter of the TrackControl function or the inAction parameter of HandleControlClick. This is the only way to specify actions in response to all mouse-down events in a control or indicator.

When your action function is called for a control part, the action function is passed a handle to the control and the control’s part code. The action function should then respond as is appropriate. MyActionProc is an example of such an action function. The only exception to this is for indicators that don’t support live feedback.

If the mouse-down event occurs in an indicator of a control that does not support live feedback, your action function should take no parameters, because the user may move the cursor outside the indicator while dragging it. 

As an alternative to passing a pointer to your action function in a parameter to TrackControl, you can use the function SetControlAction to store a pointer to the action function in the contrlAction field in the control structure. When you pass Pointer(–1) instead of a function pointer to TrackControl, TrackControl uses the action function pointed to in the control structure.*/
typedef void (*ControlActionProcPtr) (
   ControlRef theControl,
   ControlPartCode partCode
);

/*ControlKeyFilterProcPtr

The key filter function allows for the interception and possible changing of keystrokes destined for a control.

typedef ControlKeyFilterResult (*ControlKeyFilterProcPtr) (
   ControlRef theControl,
   SInt16 * keyCode,
   SInt16 * charCode,
   EventModifiers * modifiers
);

If you name your function MyControlKeyFilterProc, you would declare it like this:

ControlKeyFilterResult MyControlKeyFilterProc (
   ControlRef theControl,
   SInt16 * keyCode,
   SInt16 * charCode,
   EventModifiers * modifiers
);
Parameters
theControl

A handle to the control in which the key-down event occurred. 
keyCode

The virtual key code derived from the event structure. This value represents the key pressed or released by the user. It is always the same for a specific physical key on a particular keyboard regardless of which modifier keys were also pressed. 
charCode

A particular character derived from the event structure. This value depends on the virtual key code, the state of the modifier keys, and the current 'KCHR' resource. Because this filter provides WorldScript-encoded text in its parameters, it provides no meaningful information for key events generated when a Unicode keyboard layout or input method is active; these layouts and input methods generate Unicode text that often cannot be translated into any WorldScript encoding.
modifiers

The constant in the modifiers field of the event structure specifying the state of the modifier keys and the mouse button at the time the event was posted. 
Return Value

Returns a value indicating whether or not it allowed or blocked keystrokes; see “Key Filter Result Codes”. For a description of this data type, see “ControlKeyFilterResult”.
Discussion

Controls that support text input (such as editable text and list box controls) can attach a key filter function to filter key strokes and modify them on return. 

Important:  On Mac OS X, you should avoid using this filter, or at most, use the filter as an indication that the text is changing but do not depend on the charCode parameter to the filter. Use a kEventTextInputUnicodeForKeyEvent Carbon event handler as a replacement for the ControlKeyFilter callback; on Mac OS X v10.4 and later, you can also use a kEventTextShouldChangeInRange or kEventTextDidChange event handler. 


The Control Manager defines the data type ControlKeyFilterUPP to identify the universal procedure pointer for this application-defined function:

typedef UniversalProcPtr ControlKeyFilterUPP; 

You typically use the NewControlKeyFilterProc macro like this:

ControlKeyFilterUPP myControlKeyFilterUPP; 

myControlKeyFilterUPP = NewControlKeyFilterProc(MyControlKeyFilterCallback); 

You typically use the CallControlKeyFilterProc macro like this:

CallControlKeyFilterProc(myControlKeyFilterUPP, theControl, keyCode, charCode, modifiers); 

Your key filter function can intercept and change keystrokes destined for a control. Your key filter function can change the keystroke, leave it alone, or block your control definition function from receiving it. For example, an editable text control can use a key filter function to allow only numeric values to be input in its field. 
Availability
This callback is available with Appearance Manager 1.0 and later.*/

typedef ControlKeyFilterResult (*ControlKeyFilterProcPtr) (
   ControlRef theControl,
   SInt16 * keyCode,
   SInt16 * charCode,
   EventModifiers * modifiers
);


//function



/*GetControl32BitValue

Obtains the current setting of a control.

SInt32 GetControl32BitValue (
   ControlRef theControl
);
Parameters
theControl

A handle to the control whose current setting you wish to obtain. 
Return Value

The current setting of the control. 
Discussion

Your application may use the GetControl32BitValue function to obtain a 32-bit value previously set with the function SetControl32BitValue.

If your application uses a 32-bit control value, it should not attempt to obtain this value by calling the pre–Mac OS 8.5 function GetControlValue because the 16-bit value that is returned does not accurately reflect the current 32-bit control value.
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/
SInt32 GetControl32BitValue (
   ControlRef theControl
);

/*GetControlPopupMenuHandle

Gets the menu handle for a pop-up control.

MenuRef GetControlPopupMenuHandle (
   ControlRef control
);
Parameters
control

The pop-up control to query.
Return Value

See the Menu Manager documentation for a description of the MenuRef data type.
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/
MenuRef GetControlPopupMenuHandle (
   ControlRef control
);

/*SetControl32BitMaximum

Changes the maximum setting of a control and, if appropriate, redraws it accordingly.

void SetControl32BitMaximum (
   ControlRef theControl,
   SInt32 newMaximum
);
Parameters
theControl

A handle to the control whose maximum setting you wish to change. For a description of this data type, see “ControlRef”.
newMaximum

The new maximum setting of the control. In general, to avoid unpredictable behavior, do not set the maximum control value lower than the current minimum value. 
Discussion

Your application may use the SetControl32BitMaximum function to set a 32-bit value as the maximum setting for a control.

If your application uses a 32-bit control maximum value, it should not attempt to obtain this value by calling the pre–Mac OS 8.5 function GetControlMaximum because the 16-bit value that is returned does not accurately reflect the current 32-bit control value. Instead, use the function GetControl32BitMaximum.
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/
void SetControl32BitMaximum (
   ControlRef theControl,
   SInt32 newMaximum
);

/*GetControlByID

Finds a control in a window by its unique ID.

OSStatus GetControlByID (
   WindowRef inWindow,
   const ControlID * inID,
   ControlRef * outControl
);
Parameters
inWindow

The window to query.
inID

The control ID.
outControl

A pointer to a value of type ControlRef that, on output, is filled in with the control reference for the control specified by inID. For a description of this data type, see “ControlRef”.
Return Value

A result code. See “Control Manager Result Codes”.
Discussion

As of Mac OS X v10.3, this function is superseded by the HIViewFindByID function, which is preferred over the GetControlByID function. The first parameter to the HIViewFindByID function is a view and not a window, so you can start the search at any point in the hierarchy.
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/
OSStatus GetControlByID (
   WindowRef inWindow,
   const ControlID * inID,
   ControlRef * outControl
);

/*SetControlData

Sets control-specific data.

OSErr SetControlData (
   ControlRef inControl,
   ControlPartCode inPart,
   ResType inTagName,
   Size inSize,
   const void * inData
);
Parameters
inControl

A handle to the control for which data is to be set. 
inPart

The part code of the control part for which data is to be set; see “Control Meta Part Code Constants”, “Control Part Code Constants”, and “Control State Part Code Constants”. Passing kControlEntireControl indicates that either the control has no parts or the data is not tied to any specific part of the control. 
inTagName

A constant representing the control-specific data you wish to set see the data tag constants in the “Control Manager Constants” section. 
inSize

The size (in bytes) of the data pointed to by the inData parameter. For variable-length control data, pass the value returned in the outMaxSize parameter of GetControlDataSize in the inSize parameter. The number of bytes must match the actual data size. 
inData

A pointer to a buffer allocated by your application. This buffer contains the data that you are sending to the control. After calling SetControlData, your application is responsible for disposing of this buffer, if necessary, as information is copied by control.
Return Value

A result code. See “Control Manager Result Codes”. The result code errDataNotSupported indicates that the inTagName parameter is not valid.
Discussion

The SetControlData function sets control-specific data represented by the value in the inTagName parameter to the data pointed to by the inData parameter. SetControlData could be used, for example, to switch a progress indicator from a determinate to indeterminate state. For a list of the control attributes that can be set, see the data tag constants in the “Control Manager Constants” section. 
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/
OSErr SetControlData (
   ControlRef inControl,
   ControlPartCode inPart,
   ResType inTagName,
   Size inSize,
   const void * inData
);

/*SetControlCommandID

Sets the command ID for a control. 

OSStatus SetControlCommandID (
   ControlRef inControl,
   UInt32 inCommandID
);
Parameters
inControl

. For a description of this data type, see 
inCommandID

The command ID that is to be set.
Return Value

A result code. See “Control Manager Result Codes”.
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/
OSStatus SetControlCommandID (
   ControlRef inControl,
   UInt32 inCommandID
);

/*SetControlID

Sets a control’s ID. 

OSStatus SetControlID (
   ControlRef inControl,
   const ControlID * inID
);
Return Value

A result code. See “Control Manager Result Codes”.
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/

OSStatus SetControlID (
   ControlRef inControl,
   const ControlID * inID
);

/*GetControl32BitMinimum

Obtains the minimum setting of a control.

SInt32 GetControl32BitMinimum (
   ControlRef theControl
);
Parameters
theControl

A handle to the control whose minimum setting you wish to obtain. For a description of this data type, see “ControlRef”.
Return Value

The minimum setting of the control. 
Discussion

Your application may use the GetControl32BitMinimum function to obtain a 32-bit value previously set with the function SetControl32BitMinimum.

If your application uses a 32-bit control minimum value, it should not attempt to obtain this value by calling the pre–Mac OS 8.5 function GetControlMinimum because the 16-bit value that is returned does not accurately reflect the current 32-bit control value. 
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/
SInt32 GetControl32BitMinimum (
   ControlRef theControl
);


/*GetControlOwner

Returns the window to which a control is bound.

WindowRef GetControlOwner (
   ControlRef control
);
Parameters
control

The control to query. For a description of this data type, see “ControlRef”.
Return Value

The window reference to which the control is bound, or NULL if the control is not bound to a window.
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/
WindowRef GetControlOwner (
   ControlRef control
);

/*SetControlAction

Sets the action function for a control.

void SetControlAction (
   ControlRef theControl,
   ControlActionUPP actionProc
);
Parameters
theControl

A handle to the control whose action function is to be changed. For a description of this data type, see 
actionProc

A universal procedure pointer to an action function defining what action your application takes while the user holds down the mouse button. See ControlActionProcPtr for a description of an action function. 
Discussion

The SetControlAction function associates the action function specified by actionProc with the control specified by theControl. If the cursor is in the specified control, the HandleControlClick and TrackControl functions call the specified action function when the user holds down the mouse button. You must provide the action function, and it must define some action to perform repeatedly as long as the user holds down the mouse button. HandleControlUnderClick and TrackControl always highlight and drag the control as appropriate.

SetControlAction should be used to set the application-defined action function for providing live feedback for standard system scroll bar controls.

Note that the action function associated with a control is used by TrackControl only if you set the action function to TrackControl to Pointer(–1). Also, an action function can be specified in the actionProc parameter to TrackControl, so you don’t have to call SetControlAction to change it.
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/

void SetControlAction (
   ControlRef theControl,
   ControlActionUPP actionProc
);

/*GetControlData

Obtains control-specific data.

OSErr GetControlData (
   ControlRef inControl,
   ControlPartCode inPart,
   ResType inTagName,
   Size inBufferSize,
   void * inBuffer,
   Size * outActualSize
);
Parameters
inControl

A handle to the control to be examined. 
inPart

The part code of the control part from which data is to be obtained; see “Control Meta Part Code Constants”, “Control Part Code Constants”, and “Control State Part Code Constants”. Passing kControlEntireControl indicates that either the control has no parts or the data is not tied to any specific part of the control. For a description of this data type, see “ControlPartCode”. 
inTagName

A constant representing the control-specific data you wish to obtain see the data tag constants in the “Control Manager Constants” section. 
inBufferSize

The size (in bytes) of the data pointed to by the inBuffer parameter. For variable-length control data, pass the value returned in the outMaxSize parameter of GetControlDataSize in the inBufferSize parameter. The number of bytes must match the actual data size. 
inBuffer

On input, a pointer to a buffer allocated by your application. On return, the buffer contains a copy of the control-specific data. If you pass NULL on input, it is equivalent to calling GetControlDataSize. The actual size of the control-specific data will be returned in the outActualSize parameter. For variable-length data, the number of bytes must match the actual data size.
outActualSize

On input, a pointer to a Size value. On return, the value is set to the actual size of the data. You can pass NULL if you don’t care about this value. 
Return Value

A result code. See “Control Manager Result Codes”. The result code errDataNotSupported indicates that the inTagName parameter is not valid.
Discussion

The GetControlData function will only copy the amount of data specified in the inBufferSize parameter, but will tell you the actual size of the buffer so you will know if the data was truncated. 
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/
OSErr GetControlData (
   ControlRef inControl,
   ControlPartCode inPart,
   ResType inTagName,
   Size inBufferSize,
   void * inBuffer,
   Size * outActualSize
);

/*SetControl32BitValue

Changes the current setting of a control and redraws it accordingly.

void SetControl32BitValue (
   ControlRef theControl,
   SInt32 newValue
);
Parameters
theControl

A handle to the control whose current setting you wish to change. For a description of this data type, see “ControlRef”.
newValue

A value specifying the new setting of the control. If the specified value is less than the minimum setting for the control, SetControl32BitValue sets the current setting of the control to its minimum setting. If the specified value is greater than the maximum setting, SetControl32BitValue sets the control to its maximum.
Discussion

Your application may use the SetControl32BitValue function to set a 32-bit value as the current setting for a control.

If your application uses a 32-bit control value, it should not attempt to obtain this value by calling the pre–Mac OS 8.5 function GetControlValue because the 16-bit value that is returned does not accurately reflect the current 32-bit control value. Instead, use the function GetControl32BitValue. 
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/

void SetControl32BitValue (
   ControlRef theControl,
   SInt32 newValue
);

/*Draw1Control

Draws a control and any embedded controls that are currently visible in the specified window. 

void Draw1Control (
   ControlRef theControl
);
Parameters
theControl

A handle to the control to draw. For a description of this data type, see “ControlRef”.
Discussion

Although you should generally use the functionUpdateControls to update controls, you can use the DrawOneControl function to update a single control. If an embedding hierarchy exists and the control passed in has embedded controls, DrawOneControl draws the control and embedded controls. If the root control for a window is passed in, the result is the same as if DrawControls was called.

If you are using compositing mode, you generally do not need to call Draw1Control. If you call Draw1Control in compositing mode, keep in mind that it draws the specified control as well as all other controls that intersect the control.
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/
void Draw1Control (
   ControlRef theControl
);

/*GetControlValue

Obtains a control’s current setting. (Deprecated. Use GetControl32BitValue instead.)

Not recommended

SInt16 GetControlValue (
   ControlRef theControl
);
Parameters
theControl

On input, a handle to a control. 
Return Value

The current setting of the control. 
Discussion

When you create a control, you specify an initial setting either in the control resource or in the value parameter of the function NewControl. You can change the setting by calling SetControlValue.
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/

SInt16 GetControlValue (
   ControlRef theControl
);

/*SetControlMaximum

Changes the maximum setting of a control and redraws its indicator or scroll box accordingly. (Deprecated. Use SetControl32BitMaximum instead.)

Not recommended

void SetControlMaximum (
   ControlRef theControl,
   SInt16 newMaximum
);
Parameters
theControl

A handle to the control whose maximum setting you wish to change. 
newMaximum

The new maximum setting. 
Discussion

The SetControlMaximum function changes the maximum value of a control to the value specified by the newMaximum parameter and redraws its indicator or scroll box to reflect its new range.

When you set the maximum setting of a scroll bar equal to its minimum setting, the control definition function makes the scroll bar inactive. When you make the maximum setting exceed the minimum, the control definition function makes the scroll bar active again.

When you create a control, you specify an initial maximum setting either in the control resource or in the max parameter of the function NewControl. To determine a control’s current maximum setting, use the function GetControlMaximum. 
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/
void SetControlMaximum (
   ControlRef theControl,
   SInt16 newMaximum
);

/*SetControlMinimum

Changes the minimum setting of a control and redraws its indicator or scroll box accordingly. (Deprecated. Use SetControl32BitMinimum instead.)

Not recommended

void SetControlMinimum (
   ControlRef theControl,
   SInt16 newMinimum
);
Parameters
theControl

A handle to the control whose minimum setting you wish to change. For a description of this data type, see “ControlRef”.
newMinimum

The new minimum setting.
Discussion

The SetControlMinimum function changes the control’s minimum value to the value specified by the newMinimum parameter and redraws its indicator or scroll box to reflect its new range.

When you create a control, you specify an initial minimum setting either in the control resource or in the min parameter of the NewControl function. To obtain a control’s current minimum setting, use the function GetControlMinimum. 
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/
void SetControlMinimum (
   ControlRef theControl,
   SInt16 newMinimum
);

/*GetControlReference

Obtains a control’s current reference value. 

SInt32 GetControlReference (
   ControlRef theControl
);
Parameters
theControl

A handle to the control whose current reference value you wish to determine. 
Return Value

The current reference value for the specified control. 
Discussion

When you create a control, you specify an initial reference value, either in the control resource or in the refCon parameter of the function NewControl. The reference value is stored in the contrlRfCon field of the control structure. You can use this field for any purpose, and you can use the function SetControlReference to change this value. 
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/
SInt32 GetControlReference (
   ControlRef theControl
);

/*SetControlReference

Changes a control’s current reference value. 

void SetControlReference (
   ControlRef theControl,
   SInt32 data
);
Parameters
theControl

A handle to the control whose reference value you want to change. For a description of this data type, see “ControlRef”.
data

The new reference value for the control.
Discussion

The SetControlReference function sets the control’s reference value to the value you specify in the data parameter.

When you create a control, you specify an initial reference value, either in the control resource or in the refCon parameter of the function NewControl. Call GetControlReference to obtain the current value. You can use this value for any purpose.
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/
void SetControlReference (
   ControlRef theControl,
   SInt32 data
);

/*EnableControl

Enables a control.

OSStatus EnableControl (
   ControlRef inControl
);
Parameters
theControl

The control that is to be enabled. For a description of this data type, see 
Return Value

A result code. See “Control Manager Result Codes”.
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/
OSStatus EnableControl (
   ControlRef inControl
);

/*DeactivateControl

Deactivates a control and any latent embedded controls.

OSErr DeactivateControl (
   ControlRef inControl
);
Parameters
inControl

A handle to the control to deactivate. If you pass a window’s root control, DeactivateControl deactivates all controls in that window. For a description of this data type, see 
Return Value

A result code. See “Control Manager Result Codes”.
Discussion

The DeactivateControl function should be called instead of HiliteControl to deactivate a specified control and its latent embedded controls. 

An embedded control is considered latent when it is deactivated or hidden due to its embedder control being deactivated or hidden. If you activate a latent embedded control whose embedder is deactivated, the embedded control becomes latent until the embedder is activated. However, if you deactivate a latent embedded control, it will not be activated when its embedder is activated.

If a control definition function supports activate events, it will receive a kControlMsgActivate message before redrawing itself in its inactive state. 
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/
OSErr DeactivateControl (
   ControlRef inControl
);

/*GetControlProperty

Obtains a piece of data that has been previously associated with a control.

OSStatus GetControlProperty (
   ControlRef control,
   OSType propertyCreator,
   OSType propertyTag,
   UInt32 bufferSize,
   UInt32 * actualSize,
   void * propertyBuffer
);
Parameters
control

A handle to the control whose associated data you wish to obtain. 
propertyCreator

Your program’s signature, as registered through Apple Developer Technical Support. If your program is of a type that would not normally have a signature (for example, a plug-in), you should still register and use a signature in this case, even though your program’s file may not have the same creator code as the signature that you register. The ‘macs' property signature is reserved for the system and should not be used. 
propertyTag

The application-defined code identifying the data.
bufferSize

A value specifying the size of the data to be obtained. If the size of the data is unknown, use the function GetControlPropertySize to get the data’s size. If the size specified in the bufferSize parameter does not match the actual size of the property, GetControlProperty only retrieves data up to the size specified or up to the actual size of the property, whichever is smaller, and an error is returned. 
actualSize

On input, a pointer to an unsigned 32-bit integer. On return, this value is set to the actual size of the associated data. You may pass NULL for the actualSize parameter if you are not interested in this information.
propertyBuffer

On input, a pointer to a buffer. On return, this buffer contains a copy of the data that is associated with the specified control.
Return Value

A result code. See “Control Manager Result Codes”.
Discussion

You may use the function GetControlProperty to obtain a copy of data previously set by your application with the function SetControlProperty. 
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/
OSStatus GetControlProperty (
   ControlRef control,
   OSType propertyCreator,
   OSType propertyTag,
   UInt32 bufferSize,
   UInt32 * actualSize,
   void * propertyBuffer
);


/*SetControlProperty

Associates data with a control.

OSStatus SetControlProperty (
   ControlRef control,
   OSType propertyCreator,
   OSType propertyTag,
   UInt32 propertySize,
   const void * propertyData
);
Parameters
control

A handle to the control with which you wish to associate data. For a description of this data type, see “ControlRef”.
propertyCreator

Your program’s signature, as registered through Apple Developer Technical Support. If your program is of a type that would not normally have a signature (for example, a plug-in), you should still register and use a signature in this case, even though your program’s file may not have the same creator code as the signature that you register. The 'macs' property signature is reserved for the system and should not be used. 
propertyTag

A value identifying the data. You define the tag your application uses to identify the data.
propertySize

A value specifying the size of the data. 
propertyData

On input, a pointer to data of any type. Pass a pointer to a buffer containing the data to be associated; this buffer should be at least as large as the value specified in the propertySize parameter.
Return Value

A result code. See “Control Manager Result Codes”.
Discussion

Your application may use the SetControlProperty function to associate any type of data with a control. 
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/
OSStatus SetControlProperty (
   ControlRef control,
   OSType propertyCreator,
   OSType propertyTag,
   UInt32 propertySize,
   const void * propertyData
);

/*SetControlDragTrackingEnabled

Sets the drag tracking state for a control. 

OSStatus SetControlDragTrackingEnabled (
   ControlRef inControl,
   Boolean inTracks
);
Parameters
inControl

The control for which the drag tracking state is to be set. 
inTracks

A Boolean whose value is true if you want the control to track and receive drags or false if want to disable support for drag and drop.
Return Value

A result code. See “Control Manager Result Codes”.
Discussion

Call this function to enable a control’s support for drag and drop. If you don’t enable drag and drop support, the control won’t track drags.

Some controls don’t support drag and drop; these controls won’t track or receive drags even if you call this function with the inTracks parameter set to true.
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/
OSStatus SetControlDragTrackingEnabled (
   ControlRef inControl,
   Boolean inTracks
);

/*SetControlTitleWithCFString

Sets the title for a control to the specified Core Foundation string. 

OSStatus SetControlTitleWithCFString (
   ControlRef inControl,
   CFStringRef inString
);
Return Value

A result code. See “Control Manager Result Codes”.
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/
OSStatus SetControlTitleWithCFString (
   ControlRef inControl,
   CFStringRef inString
);

/*SetAutomaticControlDragTrackingEnabledForWindow

Enables or disables automatic drag tracking for a window. 

OSStatus SetAutomaticControlDragTrackingEnabledForWindow (
   WindowRef inWindow,
   Boolean inTracks
);
Parameters
inWindow
inTracks

A Boolean whose value is true to enable the Control Manager’s automatic drag tracking support or false to disable automatic drag tracking support.
Return Value

A result code. See “Control Manager Result Codes”.
Discussion

By default, your application is responsible for installing drag tracking and receive handlers on a given window. The Control Manager, however, has support for automatically tracking and receiving drags over controls that you can enable by calling this function with the inTracks parameter set to true.

The Control Manager automatic drag tracking detects the control the drag is over and calls HandleControlDragTracking and HandleControlDragReceive appropriately. By default, the Control Manager’s automatic drag tracking is disabled.

Earlier versions of system software enabled automatic drag tracking by default, but as of Mac OS X v10.1.3, Mac OS 9.2, and CarbonLib 1.4, you must call this function to enable automatic drag tracking.
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/
OSStatus SetAutomaticControlDragTrackingEnabledForWindow (
   WindowRef inWindow,
   Boolean inTracks
);
/*SetControlValue

Changes the current setting of a control and redraws it accordingly. (Deprecated. Use SetControl32BitValue instead.)

Not recommended

void SetControlValue (
   ControlRef theControl,
   SInt16 newValue
);
Parameters
theControl

A handle to the control whose current setting you wish to change. For a description of this data type, see “ControlRef”.
newValue

The new setting for the control. 
Discussion

For controls whose values the user can set, you can use the SetControlValue function to change the value to the specified value and redraw the control to reflect the new setting. For checkboxes and radio buttons, the value 1 fills the control with the appropriate mark, and 0 removes the mark. For Mac OS 8 checkboxes and radio buttons, 2 represents a mixed state; see “Checkbox Value Constants” and “Radio Button Value Constants”. For scroll bars, SetControlValue redraws the scroll box where appropriate. 

If the specified value is less than the minimum setting for the control, SetControlValue sets the control to its minimum setting; if the value is greater than the maximum setting, SetControlValue sets the control to its maximum.

When you create a control, you specify an initial setting either in the control resource or in the value parameter of the function NewControl. To determine a control’s current setting before changing it in response to a user’s click in that control, use the function GetControlValue. 
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/
void SetControlValue (
   ControlRef theControl,
   SInt16 newValue
);

/*NewControlActionUPP

Creates a UPP for a control action callback function. 

ControlActionUPP NewControlActionUPP (
   ControlActionProcPtr userRoutine
);
Parameters
userRoutine

A pointer to your control action callback function. See ControlActionProcPtr for information about defining this function. 
Return Value

A UPP to your control action callback function. 
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/
ControlActionUPP NewControlActionUPP (
   ControlActionProcPtr userRoutine
);

/*SetKeyboardFocus

Sets the current keyboard focus to a specified control part for a window.

OSErr SetKeyboardFocus (
   WindowRef inWindow,
   ControlRef inControl,
   ControlFocusPart inPart
);
Parameters
inWindow

A pointer to the window containing the control that is to receive keyboard focus.
inControl

A handle to the control that is to receive keyboard focus. For a description of this data type, see 
inPart

A part code specifying the part of a control to receive keyboard focus. To clear a control’s keyboard focus, pass kControlFocusNoPart. For a description of this data type, see “ControlFocusPart”
Return Value

A result code. See “Control Manager Result Codes”.
Discussion

A control with keyboard focus receives keyboard events. The Dialog Manager tests to see which control has keyboard focus when a keyboard event is processed and sends the event to that control. If no control has keyboard focus, the keyboard event is discarded. A control retains keyboard focus if it is hidden or deactivated.

Keyboard focus is only available if an embedding hierarchy has been established in the focusable control’s window. The default focusing order is based on the order in which controls are added to the window. For more details on embedding hierarchies, see EmbedControl.

The SetKeyboardFocus function sets the keyboard focus to a specified control part. The control to receive keyboard focus can be deactivated or invisible. This permits you to set the focus for an item in a dialog box before the dialog box is displayed. 
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/
OSErr SetKeyboardFocus (
   WindowRef inWindow,
   ControlRef inControl,
   ControlFocusPart inPart
);

/*DisableControl

Disables a control.

OSStatus DisableControl (
   ControlRef inControl
);
Parameters
inControl

The control to disable. For a description of this data type, see “ControlRef”.
Return Value

A result code. See “Control Manager Result Codes”.
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/
#ifndef GryphalVOId
OSStatus DisableControl (
   ControlRef inControl
);
#endif

/*GetControlBounds

Gets the bounds of a control.

Rect * GetControlBounds (
   ControlRef control,
   Rect * bounds
);
Parameters
control

The control to query. For a description of this data type, see “ControlRef”.
bounds

On input, a pointer to a QuickDraw rectangle. On output, the rectangle contains the bounds of the control in local coordinates.
Return Value

A pointer to the rectangle passed in the bounds parameter.
Discussion

When called in a composited window, this function returns the view’s frame, which is equivalent to calling HIViewGetFrame.
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/
Rect * GetControlBounds (
   ControlRef control,
   Rect * bounds
);

/*IsControlActive

Returns whether a control is active.

Boolean IsControlActive (
   ControlRef inControl
);
Parameters
inControl

A handle to the control to be examined. 
Return Value

A Boolean whose value is true if the control is active; otherwise, false.
Discussion

If you wish to determine whether a control is active, you should call IsControlActive instead of testing the contrlHilite field of the control structure. 
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/
Boolean IsControlActive (
   ControlRef inControl
);

/*HideControl

Makes a control, and any latent embedded controls, invisible.

void HideControl (
   ControlRef theControl
);
Parameters
theControl

A handle to the control to hide. For a description of this data type, see 
Discussion

The HideControl function makes the specified control invisible. This can be useful, for example, before adjusting a control’s size and location. It also adds the control’s rectangle to the window’s update region, so that anything else that was previously obscured by the control will reappear on the screen. If the control is already invisible, HideControl has no effect.

When hiding groups of controls, the state of an embedded control that is hidden or deactivated is preserved so that when the embedder control is shown or activated, the embedded control appears in the same state as the embedder. If the specified control has embedded controls, HideControl makes the embedded controls invisible as well.

An embedded control is considered latent when it is deactivated or hidden due to its embedder control being deactivated or hidden. If you call HideControl on a latent embedded control, it would not be displayed the next time ShowControl was called on its embedder control.

To make the control visible again, call ShowControl.

You can also call SetControlVisibility to hide or show a control without causing it to redraw.
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/
void HideControl (
   ControlRef theControl
);

/*ShowControl

Makes an invisible control, and any latent embedded controls, visible.

void ShowControl (
   ControlRef theControl
);
Parameters
theControl

A handle to the control to make visible. For a description of this data type, see “ControlRef”.
Discussion

If the specified control is invisible, the ShowControl function makes it visible and immediately draws the control within its window without using your window’s standard updating mechanism. Note that the ShowControl function draws the control in its window, but the control can still be completely or partially obscured by overlapping windows or other objects. If the control is already visible, ShowControl has no effect.

When showing groups of controls, the state of an embedded control that is hidden or deactivated is preserved, so that when the embedder control is shown or activated, the embedded control appears in the same state as the embedder. If the specified control has embedded controls, ShowControl makes the embedded controls visible as well.

An embedded control is considered latent when it is deactivated or hidden due to its embedder control being deactivated or hidden. If you call ShowControl on a latent embedded control whose embedder is disabled, the embedded control will remain invisible until its embedder control is enabled.

You can make a control invisible in several ways:
Specifying its invisibility in the control resource. 
Passing a value of false in the visible parameter of NewControl. 
Calling HideControl. 
Calling SetControlVisibility.
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/
void ShowControl (
   ControlRef theControl
);

/*AutoEmbedControl

Automatically embeds a control in the smallest appropriate embedder control.

OSErr AutoEmbedControl (
   ControlRef inControl,
   WindowRef inWindow
);
Parameters
inControl

A handle to the control to be embedded. 
inWindow

A pointer to the window in which to embed the control.
Return Value

A result code. See “Control Manager Result Codes”.
Discussion

The Dialog Manager uses AutoEmbedControl to position dialog items in an embedding hierarchy based on both visual containment and the item list resource order. As items are added to a dialog box during creation, controls that already exist in the window will be containers for new controls if they both visually contain the control and have set the kControlSupportsEmbedding feature bit. For this reason, you should place the largest embedder controls at the beginning of the item list resource. As an example, the Dialog Manager would embed radio buttons in a tab control if they visually “fit” inside the tab control, as long as the tab control was already created in a'DITL' resource and established as an embedder control. For more information on embedding hierarchies in dialog and alert boxes, see the function EmbedControl. 
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/
OSErr AutoEmbedControl (
   ControlRef inControl,
   WindowRef inWindow
);

/*GetControlTitle

Obtains the title of a control. (Deprecated. Use CopyControlTitleAsCFString instead.)

Not recommended

void GetControlTitle (
   ControlRef theControl,
   Str255 title
);
Parameters
theControl

A handle to the control whose title you want to determine. 
title

On input, a pascal string. On output, the title of the control. 
Discussion

The GetControlTitle function produces the title of the specified control, which is stored in the contrlTitle field of the control structure.

When you create a control, you specify an initial title either in the control resource or in the title parameter of the function NewControl. You can change the title by using SetControlTitle. 
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/

void GetControlTitle (
   ControlRef theControl,
   Str255 title
);
/*ActivateControl

Activates a control and any latent embedded controls.

OSErr ActivateControl (
   ControlRef inControl
);
Parameters
inControl

A handle to the control to activate. If you pass a window’s root control, ActivateControl activates all controls in that window. For a description of this data type, see “ControlRef”.
Return Value

A result code. See “Control Manager Result Codes”.
Discussion

The ActivateControl function should be called instead of HiliteControl to activate a specified control and its latent embedded controls.

An embedded control is considered latent when it is deactivated or hidden due to its embedder control being deactivated or hidden. If you activate a latent embedded control whose embedder is deactivated, the embedded control becomes latent until the embedder is activated. However, if you deactivate a latent embedded control, it will not be activated when its embedder is activated.

If a control definition function supports activate events, it will receive a kControlMsgActivate message before redrawing itself in its active state. 
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/

OSErr ActivateControl (
   ControlRef inControl
);

/*AdvanceKeyboardFocus

Advances the keyboard focus to the next focusable control in a window.

OSErr AdvanceKeyboardFocus (
   WindowRef inWindow
);
Parameters
inWindow

A pointer to the window for which to advance keyboard focus.
Return Value

A result code. See “Control Manager Result Codes”.
Discussion

The AdvanceKeyboardFocus function skips over deactivated and hidden controls until it finds the next focusable control in the window. If it does not find a focusable item, it simply returns.

When AdvanceKeyboardFocus is called, the Control Manager calls your control definition function and passes kControlMsgFocus in its message parameter and kControlFocusNextPart in its param parameter. In response to this message, your control definition function should change keyboard focus to its next part, the entire control, or remove keyboard focus from the control, depending upon the circumstances. See ControlDefProcPtr for a discussion of possible responses to this message. 
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/

OSErr AdvanceKeyboardFocus (
   WindowRef inWindow
);

/*GetKeyboardFocus

Obtains a handle to the control with the current keyboard focus for a specified window.

OSErr GetKeyboardFocus (
   WindowRef inWindow,
   ControlRef * outControl
);
Parameters
inWindow

A pointer to the window for which to obtain keyboard focus.
outControl

On input, a pointer to a ControlHandle value. On return, the ControlHandle value is set to a handle to the control that currently has keyboard focus. Produces NULL if no control has focus. For a description of this data type, see 
Return Value

A result code. See “Control Manager Result Codes”.
Discussion

The GetKeyboardFocus function returns the handle of the control with current keyboard focus within a specified window.
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/
OSErr GetKeyboardFocus (
   WindowRef inWindow,
   ControlRef * outControl
);

/*IsControlHilited

Indicates whether or not the control is highlighted.

Boolean IsControlHilited (
   ControlRef control
);
Parameters
control

The control that is to be queried. For a description of this data type, see 
Return Value

A Boolean whose value is true if the control is highlighted; otherwise, false.
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/

Boolean IsControlHilited (
   ControlRef control
);

/*GetControlID

Gets the control ID for a control.

OSStatus GetControlID (
   ControlRef inControl,
   ControlID * outID
);
Parameters
inControl

The control to query. For a description of this data type, see “ControlRef”.
outID

A pointer to a value of type ControlID that, on return, contains the control ID of the control specified by inControl.
Return Value

A result code. See “Control Manager Result Codes”.
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/
OSStatus GetControlID (
   ControlRef inControl,
   ControlID * outID
);

/*DisposeControl

Decrements a control’s reference count and destroys it if the reference count becomes 0.

void DisposeControl (
   ControlRef theControl
);
Parameters
theControl

The control you want to dispose of. For a description of this data type, see “ControlRef”. 
Discussion

The DisposeControl function reduces the control’s reference count and, if the reference count becomes 0, releases the memory occupied by the control structure and any data structures associated with the control. Before destroying the control, DisposeControl removes the control (and any embedded controls it may possess) from the screen and deletes the control from the window’s control list.

To destroy all of the controls from a window you want to keep, use the function KillControls. If an embedding hierarchy is present, passing the root control to the DisposeControl function is the effectively the same as calling KillControls. In that situation, DisposeControl disposes of the controls embedded within a control before disposing of the container control.

You should use DisposeControl when you want to retain the window but remove one of its controls. The Window Manager functions CloseWindow and DisposeWindow automatically remove all controls associated with the window and release the memory the controls occupy. 
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/
void DisposeControl (
   ControlRef theControl
);

/*GetControl32BitMaximum

Obtains the maximum setting of a control.

SInt32 GetControl32BitMaximum (
   ControlRef theControl
);
Parameters
theControl

A handle to the control whose maximum setting you wish to obtain. For a description of this data type, see “ControlRef”.
Return Value

The maximum setting of the control. 
Discussion

Your application may use the GetControl32BitMaximum function to obtain a 32-bit value previously set with the function SetControl32BitMaximum.

If your application uses a 32-bit control maximum value, it should not attempt to obtain this value by calling the pre–Mac OS 8.5 function GetControlMaximum because the 16-bit value that is returned does not accurately reflect the current 32-bit control value.
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/
SInt32 GetControl32BitMaximum (
   ControlRef theControl
);

/*SetControl32BitMinimum

Changes the minimum setting of a control and, if appropriate, redraws it accordingly.

void SetControl32BitMinimum (
   ControlRef theControl,
   SInt32 newMinimum
);
Parameters
theControl

A handle to the control whose minimum setting you wish to change. For a description of this data type, see “ControlRef”.
newMinimum

A value specifying the new minimum setting of the control. In general, to avoid unpredictable behavior, do not set the minimum control value higher than the current maximum value. 
Discussion

Your application may use the SetControl32BitMinimum function to set a 32-bit value as the minimum setting for a control.

If your application uses a 32-bit control minimum value, it should not attempt to obtain this value by calling the pre–Mac OS 8.5 function GetControlMinimum because the 16-bit value that is returned does not accurately reflect the current 32-bit control value. Instead, use the function GetControl32BitMinimum. 
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/
void SetControl32BitMinimum (
   ControlRef theControl,
   SInt32 newMinimum
);

/*SizeControl

Changes the size of a control’s rectangle.

void SizeControl (
   ControlRef theControl,
   SInt16 w,
   SInt16 h
);
Parameters
theControl

A handle to the control you wish to resize. 
w

The new width, in pixels, of the resized control. 
h

The new height, in pixels, of the resized control.
Discussion

The SizeControl function changes the rectangle specified in the contrlRect field of the control structure. The lower-right corner of the rectangle is adjusted so that it has the width and height specified by the w and h parameters the position of the upper-left corner is not changed. If the control is currently visible, it’s first hidden and then redrawn in its new size. The SizeControl function will change the window’s update region. 
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/

void SizeControl (
   ControlRef theControl,
   SInt16 w,
   SInt16 h
);

/*GetSuperControl

Obtains a handle to an embedder control.

OSErr GetSuperControl (
   ControlRef inControl,
   ControlRef * outParent
);
Parameters
inControl

A handle to an embedded control. For a description of this data type, see “ControlRef”.
outParent

A pointer to a ControlHandle value. On return, the ControlHandle value is set to a handle to the embedder control. For a description of this data type, see “ControlRef”.
Return Value

A result code. See “Control Manager Result Codes”.
Discussion

The GetSuperControl function gets a handle to the parent control of the control passed in. 
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/
OSErr GetSuperControl (
   ControlRef inControl,
   ControlRef * outParent);

/*GetRootControl

Obtains a handle to a window’s root control. 

OSErr GetRootControl (
   WindowRef inWindow,
   ControlRef * outControl
);
Parameters
inWindow

A pointer to the window to be examined.
outControl

Pass a pointer to a ControlHandle value. On return, the ControlHandle value is set to a handle to the root control. For a description of this data type, see 
Return Value

A result code. See “Control Manager Result Codes”.
Discussion

You can call GetRootControl to determine whether or not a root control (and therefore an embedding hierarchy) exists within a specified window. Once you have the root control’s handle, you can pass it to functions such as DisposeControl, ActivateControl,and DeactivateControl to apply specified actions to the entire embedding hierarchy.

Note that the minimum, maximum, and initial settings for a root control are reserved and should not be changed. 
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/

OSErr GetRootControl (
   WindowRef inWindow,
   ControlRef * outControl
);

/*CopyControlTitleAsCFString

Makes a copy of the control’s title as a Core Foundation string.

OSStatus CopyControlTitleAsCFString (
   ControlRef inControl,
   CFStringRef * outString
);
Parameters
inControl

The control whose title is to be copied. For a description of this data type, see “ControlRef”.
outString

A copy of the control’s title.
Return Value

A result code. See “Control Manager Result Codes”.
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/
OSStatus CopyControlTitleAsCFString (
   ControlRef inControl,
   CFStringRef * outString
);

/*SetControlFontStyle

Sets the font style for a control.

OSErr SetControlFontStyle (
   ControlRef inControl,
   const ControlFontStyleRec * inStyle
);
Parameters
inControl

A handle to the control whose font style is to be set. For a description of this data type, see “ControlRef”.
inStyle

A pointer to a ControlFontStyleRec structure. If the flags field is cleared, the control uses the system font unless the control variant kControlUsesOwningWindowsFontVariant has been specified (control uses window font). 
Return Value

A result code. See “Control Manager Result Codes”.
Discussion

The SetControlFontStyle function sets the font style for a given control. To specify the font for controls in a dialog box, it is generally easier to use the dialog font table resource. SetControlFontStyle allows you to override a control’s default font (system or window font, depending upon whether the control variant kControlUsesOwningWindowsFontVariant has been specified). Once you have set a control’s font with this function, you can cause the control to revert to its default font by passing a control font style structure with a cleared flags field in the inStyle parameter. 
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/
OSErr SetControlFontStyle (
   ControlRef inControl,
   const ControlFontStyleRec * inStyle
);

/*CreateRootControl

Creates the root control for a specified window.

OSErr CreateRootControl (
   WindowRef inWindow,
   ControlRef * outControl
);
Parameters
inWindow

A pointer to the window in which you wish to create a root control.
outControl

On input, a pointer to a ControlHandle value. On return, the ControlHandle value is set to a handle to the root control. For a description of this data type, see 
Return Value

A result code. See “Control Manager Result Codes”.
Discussion

Establishing an embedding hierarchy can be accomplished in two steps: creating a root control and embedding controls within it.

To embed controls in a window, you must create a root control for that window. The root control is the container for all other window controls. You create the root control in one of two ways—by calling the CreateRootControl function or by setting the appropriate dialog flag. The root control can be retrieved by calling the function GetRootControl.

The CreateRootControl function creates the root control for a window if no other controls are present. If there are any controls in the window prior to calling CreateRootControl, an error is returned and the root control is not created. Note that the minimum, maximum, and initial settings for a root control are reserved and should not be changed. 

The root control is implemented as a user pane control. You can attach any application-defined user pane functions to the root control to perform actions such as hit testing, drawing, handling keyboard focus, erasing to the correct background, and processing idle and keyboard events.

Once you have created a root control, newly created controls will automatically be embedded in the root control when you call NewControl or GetNewControl. You can specify that a specific control be embedded into another by calling EmbedControl.

By acting on an embedder control, you can move, disable, or hide groups of items. For example, you can use a blank user pane control as the embedder control for all items in a particular “page” of a tab control. After creating as many user panes as you have tabs, you can hide one and show the next when a tab is clicked. All the controls embedded in the user pane will be hidden and shown automatically when the user pane is hidden and shown. 

In addition to calling CreateRootControl, you can establish an embedding hierarchy in a dialog box by either setting the feature bit kDialogFlagsUseControlHierarchy in the extended dialog resource or passing it in the inFlags parameter of the Dialog Manager function NewFeaturesDialog. An embedding hierarchy can be created in an alert box by setting the kAlertFlagsUseControlHierarchy bit in the extended alert resource. It is important to note that a preexisting alert or dialog item will become a control if it is in an alert or dialog box that now uses an embedding hierarchy.

The embedding hierarchy enforces drawing order by drawing the embedding control before its embedded controls. Using an embedding hierarchy also enforces orderly hit-testing, since it performs an “inside-out” hit test to determine the most deeply nested control that is hit by the mouse. An embedding hierarchy is also necessary for controls to make use of keyboard focus, the default focusing order for which is a linear progression that uses the order the controls were added to the window. For more details on keyboard focus, see “Handling Keyboard Focus”. 
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/
OSErr CreateRootControl (
   WindowRef inWindow,
   ControlRef * outControl
);


/*SetControlVisibility

Sets the visibility of a control, and any embedded controls, and specifies whether it should be drawn.

OSErr SetControlVisibility (
   ControlRef inControl,
   Boolean inIsVisible,
   Boolean inDoDraw
);
Parameters
inControl

A handle to the control whose visibility is to be set. 
inIsVisible

A Boolean value indicating whether the control is visible or invisible. If you set this value to true, the control will be visible. If false, the control will be invisible. If you wish to show a control (and latent embedded subcontrols) but do not want to cause screen drawing, pass true for this parameter and false in the inDoDraw parameter. 
inDoDraw

A Boolean value indicating whether the control should be drawn or erased. If true, the control’s display on the screen should be updated (drawn or erased) based on the value passed in the inIsVisible parameter. If false, the display will not be updated.
Return Value

A result code. See “Control Manager Result Codes”.
Discussion

You should call the SetControlVisibility function instead of setting the contrlVis field of the control structure to set the visibility of a control and specify whether it will be drawn. If the control has embedded controls, SetControlVisibility allows you to set their visibility and specify whether or not they will be drawn. If you wish to show a control but do not want it to be drawn onscreen, pass true in the inIsVisible parameter and false in the inDoDraw parameter. 
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/

OSErr SetControlVisibility (
   ControlRef inControl,
   Boolean inIsVisible,
   Boolean inDoDraw
);

/*EmbedControl

Embeds one control inside another.

OSErr EmbedControl (
   ControlRef inControl,
   ControlRef inContainer
);
Parameters
inControl

The control that is to be embedded. For a description of this data type, see “ControlRef”.
inContainer

The control in which the control specified by inControl is to be is to embedded. For a description of this data type, see “ControlRef”.
Return Value

A result code. See “Control Manager Result Codes”.
Discussion

Establishing an embedding hierarchy can be accomplished in two steps: creating a root control and embedding controls within it. 

To embed controls in a window, you must create a root control for that window. The root control is the container for all other window controls. You create the root control in one of two ways—by calling the CreateRootControl function or by setting the appropriate dialog flag. The root control can be retrieved by calling GetRootControl.

The root control is implemented as a user pane control. You can attach any application-defined user pane functions to the root control to perform actions such as hit testing, drawing, handling keyboard focus, erasing to the correct background, and processing idle and keyboard events.

Once you have created a root control, newly created controls will automatically be embedded in the root control when you call NewControl or GetNewControl. You can specify that a specific control be embedded into another by calling EmbedControl.

Note that an embedding hierarchy must be established before your application calls the EmbedControl function. If the specified control does not support embedding or there is no root control in the owning window, an error is returned. Prior to Mac OS X, if the control you wish to embed is in a different window from the embedder control, an error is returned. On Mac OS X, however, you can use EmbedControl to move a control from one window to another. On Mac OS X v.10.0 and v.10.1, you can move all controls except for the edit text and unicode edit text controls. Support for the edit text controls is available in Mac OS X v.10.2 and later. 

By acting on an embedder control, you can move, disable, or hide groups of items. For example, you can use a blank user pane control as the embedder control for all items in a particular “page” of a tab control. After creating as many user panes as you have tabs, you can hide one and show the next when a tab is clicked. All the controls embedded in the user pane will be hidden and shown automatically when the user pane is hidden and shown. 

In addition to calling CreateRootControl, you can establish an embedding hierarchy in a dialog box by either setting the feature bit kDialogFlagsUseControlHierarchy in the extended dialog resource or passing it in the inFlags parameter of the Dialog Manager function NewFeaturesDialog. An embedding hierarchy can be created in an alert box by setting the kAlertFlagsUseControlHierarchy bit in the extended alert resource. It is important to note that a preexisting alert or dialog item will become a control if it is in an alert or dialog box that now uses an embedding hierarchy.

The embedding hierarchy enforces drawing order by drawing the embedding control before its embedded controls. Using an embedding hierarchy also enforces orderly hit-testing, since it performs an “inside-out” hit test to determine the most deeply nested control that is hit by the mouse. An embedding hierarchy is also necessary for controls to make use of keyboard focus, the default focusing order for which is a linear progression that uses the order the controls were added to the window. For more details on keyboard focus, see “Handling Keyboard Focus”. 
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/
OSErr EmbedControl (
   ControlRef inControl,
   ControlRef inContainer
);

/*DrawControls

Draws all controls currently visible in the specified window. 

void DrawControls (
   WindowRef theWindow
);
Parameters
theWindow

A pointer to a window whose controls you want to display.
Discussion

Because the UpdateControls function redraws only those controls that need updating, your application should generally use it instead of DrawControls when you receive an update event for a window that contains controls. You should typically call either DrawControls or UpdateControls after calling the Window Manager function BeginUpdate and before calling EndUpdate.

While the Dialog Manager automatically draws and updates controls in alert boxes and dialog boxes, Window Manager functions such as SelectWindow, ShowWindow, and BringToFront do not automatically update the window’s controls.

When the Appearance Manager is not available, the DrawControls function draws all controls currently visible in the specified window in reverse order of creation; thus, in case of overlapping controls, the control created first appears frontmost in the window. If you only wish to draw controls in need of update, call UpdateControls instead.

Note that DrawControls generally should not be called if you are using compositing mode.
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/

void DrawControls (
   WindowRef theWindow
);

/*GetControlHilite

Gets the highlight status of a control.

UInt16 GetControlHilite (
   ControlRef control
);
Parameters
control

The control to query. For a description of this data type, see “ControlRef”.
Return Value
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/

UInt16 GetControlHilite (
   ControlRef control
);

/*SetControlBounds

Sets the bounds of a control. 

void SetControlBounds (
   ControlRef control,
   const Rect * bounds
);
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/

void SetControlBounds (
   ControlRef control,
   const Rect * bounds
);

/*HiliteControl

Changes the highlighting of a control.

Not recommended

void HiliteControl (
   ControlRef theControl,
   ControlPartCode hiliteState
);
Parameters
theControl

A handle to the control. For a description of this data type, see “ControlRef”.
hiliteState

A value from 0 to 255 that specifies the highlighting state of the control. The value of 0 signifies an active control with no highlighting. A value from 1 through 253 signifies a part code designating the part of the (active) control to highlight. Values 254 and 255 signify that the control is to be made disabled or inactive, respectively, and drawn accordingly. For a description of part code constants, see “Control Part Code Constants”, “Control Part Code Constants”, and “Control State Part Code Constants”. 
Discussion

If the Appearance Manager is available, you should call the functions ActivateControl and DeactivateControl instead of HiliteControl to activate or deactivate a control. This is important if the control is in an embedding hierarchy, since calling these functions will ensure that any latent embedded controls will be activated and deactivated correctly.

If the Appearance Manager is not available, then when you need to make a control inactive (such as when its window is not frontmost) or in any other way change the highlighting of a control, you can use the HiliteControl function.

The HiliteControl function calls the control definition function to redraw the control with the highlighting specified in the hiliteState parameter. The HiliteControl function uses the value in this parameter to change the value of the contrlHilite field of the control structure.

Except for scroll bars, which you should hide using HideControl, you should use HiliteControl to make all controls inactive when their windows are not frontmost. The function TrackControl automatically uses the HiliteControl function as appropriate; when you use TrackControl, you don’t need to call HiliteControl. 
Carbon Porting Notes

If you are activating or deactivating a control, you should use ActivateControl or DeactivateControl instead. Otherwise okay to use. 
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/
void HiliteControl (
   ControlRef theControl,
   ControlPartCode hiliteState
);

/*GetControlMinimum

Obtains a control’s minimum setting. (Deprecated. Use GetControl32BitMinimum instead.)

Not recommended

SInt16 GetControlMinimum (
   ControlRef theControl
);
Parameters
theControl

A handle to the control whose minimum value you wish to determine. 
Return Value

The specified control’s minimum setting.
Discussion

When you create a control, you specify an initial minimum setting either in the control resource or in the min parameter of the function NewControl. You can change the minimum setting by using the function SetControlMinimum. 
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/
SInt16 GetControlMinimum (
   ControlRef theControl
);

/*GetControlMaximum

Obtains a control’s maximum setting. (Deprecated. Use GetControl32BitMaximum instead.)

Not recommended

SInt16 GetControlMaximum (
   ControlRef theControl
);
Parameters
theControl

A handle to the control whose maximum value you wish to determine. For a description of this data type, see “ControlRef”.
Return Value

The specified control’s maximum setting. 
Discussion

When you create a control, you specify an initial maximum setting either in the control resource or in the max parameter of the function NewControl. You can change the maximum setting by using the function SetControlMaximum.
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/

SInt16 GetControlMaximum (
   ControlRef theControl
);

/*FindControlUnderMouse

Obtains the location of a mouse-down event in a control.

ControlRef FindControlUnderMouse (
   Point inWhere,
   WindowRef inWindow,
   ControlPartCode * outPart
);
Parameters
inWhere

A point, specified in coordinates local to the window, where the mouse-down event occurred. Before calling FindControlUnderMouse, use the QuickDraw GlobalToLocal function to convert the point stored in the where field of the event structure (which describes the location of the mouse-down event) to coordinates local to the window.
inWindow

A pointer to the window in which the mouse-down event occurred.
outPart

On input, a pointer to a signed 16-bit integer value. On return, the value is set to the part code of the control part that was selected; see “Control Part Code Constants”, “Control Part Code Constants”, and “Control State Part Code Constants”. 
Return Value

A handle to the control that was selected. If the mouse-down event did not occur over a control part, FindControlUnderMouse returns NULL. For a description of this data type, see “ControlRef”.
Discussion

You should call the FindControlUnderMouse function instead of FindControl to determine whether a mouse-down event occurred in a control, particularly if an embedding hierarchy is present. FindControlUnderMouse will return a handle to the control even if no part was hit and can determine whether a mouse-down event has occurred even if the control is deactivated, while FindControl does not. 

When a mouse-down event occurs, your application should call FindControlUnderMouse after using the Window Manager function FindWindow to ascertain that a mouse-down event has occurred in the content region of a window containing controls. 
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/

ControlRef FindControlUnderMouse (
   Point inWhere,
   WindowRef inWindow,
   ControlPartCode * outPart
);

/*HandleControlClick

Responds to cursor movements in a control while the mouse button is down and returns the location of the next mouse-up event.

ControlPartCode HandleControlClick (
   ControlRef inControl,
   Point inWhere,
   EventModifiers inModifiers,
   ControlActionUPP inAction
);
Parameters
inControl

A handle to the control in which the mouse-down event occurred. Pass the control handle returned by FindControl or FindControlUnderMouse. 
inWhere

A point, specified in local coordinates, where the mouse-down event occurred. Supply the same point you passed to FindControl or FindControlUnderMouse. 
inModifiers

Information from the modifiers field of the event structure specifying the state of the modifier keys and the mouse button at the time the event was posted. 
inAction

A universal procedure pointer to an action function defining what action your application takes while the user holds down the mouse button. See ControlActionProcPtr for a description of such an action function. The value of the inAction parameter can be a valid procPtr, NULL, or -1. A value of -1 indicates that the control should either perform auto tracking, or if it is incapable of doing so, do nothing (like NULL). For custom controls, what you pass in this parameter depends on how you define the control. If the part index is greater than 128, the pointer must be of type DragGrayRegionUPP unless the control supports live feedback, in which case it should be a ControlActionUPP. 
Return Value

Returns a value of type ControlPartCode identifying the control’s part see “Control Meta Part Code Constants”, “Control Part Code Constants”, and“Control State Part Code Constants”. For a description of this data type, see “ControlPartCode”.
Discussion

Call the HandleControlClick function after a call to FindControl or FindControlUnderMouse. The HandleControlClick function should be called instead of TrackControl to follow the user’s cursor movements in a control and provide visual feedback until the user releases the mouse button. Unlike TrackControl, HandleControlClick allows modifier keys to be passed in so that the control may use these if the control (such as a list box or editable text field) is set up to handle its own tracking.

The visual feedback given by HandleControlClick depends on the control part in which the mouse-down event occurs. When highlighting is appropriate, for example, HandleControlClick highlights the control part (and removes the highlighting when the user releases the mouse button). When the user holds down the mouse button while the cursor is in an indicator (such as the scroll box of a scroll bar) and moves the mouse, HandleControlClick responds by dragging a dotted outline or a ghost image of the indicator. If the user releases the mouse button when the cursor is in an indicator such as the scroll box, HandleControlClick calls the control definition function to reposition the indicator. 

While the user holds down the mouse button with the cursor in one of the standard controls, HandleControlClick performs the following actions, depending on the value you pass in the parameter inAction.
If you pass NULL in the inAction parameter, HandleControlClick uses no action function and therefore performs no additional actions beyond highlighting the control or dragging the indicator. This is appropriate for push buttons, checkboxes, radio buttons, and the scroll box of a scroll bar.
If you pass a pointer to an action function in the inAction parameter, it must define some action that your application repeats as long as the user holds down the mouse button. This is appropriate for the scroll arrows and gray areas of a scroll bar. 
If you pass (ControlActionUPP)-1L in the inAction parameter, HandleControlClick calls the control action function associated with the control. This is appropriate when you are tracking the cursor in a pop-up menu. You can call GetControlAction to get a pointer to the control action function that is associated with the control, and you can call SetControlAction to set the control action function that is associated with the control.

For 'CDEF' resources that implement custom dragging, you usually call HandleControlClick, which returns 0 regardless of the user’s changes of the control setting. To avoid this, you should use another method to determine whether the user has changed the control setting, for instance, comparing the control’s value before and after your call to HandleControlClick.
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h.*/
ControlPartCode HandleControlClick (
   ControlRef inControl,
   Point inWhere,
   EventModifiers inModifiers,
   ControlActionUPP inAction
);

/*SetControlTitle

Changes the title of a control and redraws the control accordingly. (Deprecated. Use SetControlTitleWithCFString instead.)

Not recommended

void SetControlTitle (
   ControlRef theControl,
   ConstStr255Param title
);
Parameters
theControl

A handle to a control, the title of which you want to change. 
title

The new title for the control. 
Discussion

The SetControlTitle function changes the contrlTitle field of the control structure to the given string and redraws the control, using the system font for the control title.

The Control Manager allows multiple lines of text in the titles of buttons, checkboxes, and radio buttons. When specifying a multiple-line title, separate the lines with the ASCII character code 0x0D (carriage return). If the control is a button, each line is horizontally centered, and the font leading is inserted between lines. (The height of each line is equal to the distance from the ascent line to the descent line plus the leading of the font used. Be sure to make the total height of the rectangle greater than the number of lines times this height.) If the control is a checkbox or a radio button, the text is justified as appropriate for the user’s current script system, and the checkbox or button is vertically centered within its rectangle.

When you create a control, you specify an initial title either in the control resource or in the title parameter of the function NewControl. To determine a control’s current title, use the function GetControlTitle. 
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/
void SetControlTitle (
   ControlRef theControl,
   ConstStr255Param title
);

/*GetNewControl

Creates a control from a control resource.

ControlRef GetNewControl (
   SInt16 resourceID,
   WindowRef owningWindow
);
Parameters
resourceID

The resource ID of the control you wish to create. 
owningWindow

A pointer to the window in which to place the control.
Return Value

A handle to the control created from the specified control resource. If GetNewControl can’t read the control resource from the resource file, it returns NULL. For a description of this data type, see “ControlRef”.
Discussion

The GetNewControl function creates a control structure from the information in the specified control resource, adds the control structure to the control list for the specified window, and returns as its function result a handle to the control. You use this handle when referring to the control in most other Control Manager functions. After making a copy of the control resource, GetNewControl releases the memory occupied by the original control resource before returning.

The control resource specifies the rectangle for the control, its initial setting, its visibility state, its maximum and minimum settings, its control definition ID, a reference value, and its title (if any). After you use GetNewControl to create the control, you can change the control characteristics with other Control Manager functions.

If the control resource specifies that the control should be visible, the Control Manager draws the control. If the control resource specifies that the control should initially be invisible, you can use the function ShowControl to make the control visible.

When an embedding hierarchy is established within a window, GetNewControl automatically embeds the newly created control in the root control of the owning window. 
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/

ControlRef GetNewControl (
   SInt16 resourceID,
   WindowRef owningWindow
);

/*FindControl

Obtains the location of a mouse-down event in a control.

ControlPartCode FindControl (
   Point testPoint,
   WindowRef theWindow,
   ControlRef * theControl
);
Parameters
testPoint

A point, specified in coordinates local to the window, where the mouse-down event occurred. Before calling FindControl, use the GlobalToLocal function to convert the point stored in the where field of the event structure (which describes the location of the mouse-down event) to coordinates local to the window. 
theWindow

A pointer to the window in which the mouse-down event occurred. Pass the window pointer returned by the FindWindow function.
theControl

A pointer to a control handle. On output, FindControl returns a handle to the control in which the mouse-down event occurred or NULL if the point was not over a control. For a description of this data type, see “ControlRef”.
Return Value

The control part code of the control in which the mouse-down event occurred; see “Control Meta Part Code Constants”, “Control Part Code Constants”, and“Control State Part Code Constants”. For a description of this data type, see “ControlPartCode”.
Discussion

The FindControl function is not recommended when the Appearance Manager is available. When the Appearance Manager is available, you should call FindControlUnderMouse to determine the location of a mouse-down event in a control. FindControlUnderMouse will return a handle to the control even if no part was hit and can determine whether a mouse-down event has occurred even if the control is deactivated, while FindControl does not.

If the Appearance Manager is not available, then, when a mouse-down event occurs, your application can call FindControl after using the Window Manager function FindWindow to ascertain that a mouse-down event has occurred in the content region of a window containing controls.

When the user presses the mouse button while the cursor is in a visible, active control, FindControl returns as its function result a part code identifying the control’s part the function also returns a handle to the control in the parameter theControl.

If the mouse-down event occurs in an invisible or inactive control, or if it occurs outside a control, FindControl sets the value referenced through theControl to NULL and returns 0 as its function result.

The FindControl function also returns NULL in the value referenced through the parameter theControl and 0 as its function result if the window is invisible or if it doesn’t contain the given point. (However, FindWindow won’t return a window pointer to an invisible window or to one that doesn’t contain the point where the mouse-down event occurred. As long as you call FindWindow before FindControl, this situation won’t arise.)

After using FindControl to determine that a mouse-down event has occurred in a control, you typically call the function TrackControl to follow and respond to the cursor movements in that control, and then to determine in which part of the control the mouse-up event occurs.

The pop-up control definition function does not define part codes for pop-up menus. Instead, your application should store the handles for your pop-up menus when you create them. Your application should then test the handles you store against the handles returned by FindControl before responding to users’ choices in pop-up menus.

The Dialog Manager automatically calls FindControl and TrackControl for mouse-down events inside controls of alert boxes and dialog boxes. 
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/

ControlPartCode FindControl (
   Point testPoint,
   WindowRef theWindow,
   ControlRef * theControl
);


/*UpdateControls

Draws controls in the specified update region of a window. 

void UpdateControls (
   WindowRef inWindow,
   RgnHandle inUpdateRegion
);
Parameters
theWindow

On input, a pointer to the window containing the controls to update.
updateRegion

On input, a handle to the update region of the specified window.
Discussion

The UpdateControls function, which should not be called in a compositing window, draws only those controls in the specified window that need updating. This function is faster than the DrawControls function, which draws all of the controls in a window. By contrast, UpdateControls draws only those controls in the update region.

Your application should call UpdateControls upon receiving an update event for a window that contains controls. While the Dialog Manager handles update events for controls in alert boxes and dialog boxes, Window Manager functions such as SelectWindow, ShowWindow, and BringToFront do not automatically call UpdateControls to display the window’s controls. 

In response to an update event, you normally call UpdateControls after using the Window Manager function BeginUpdate and before using the Window Manager function EndUpdate. You should set the updateRegion parameter to the visible region of the window’s port, as specified in the port’s visRgn field. Note that if your application draws parts of a control outside of its rectangle, UpdateControls might not redraw it. 
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/
void UpdateControls (
   WindowRef inWindow,
   RgnHandle inUpdateRegion
);

/*TrackControl

Responds to cursor movements in a control while the mouse button is down. (Deprecated. Use HandleControlClick instead.)

Not recommended

ControlPartCode TrackControl (
   ControlRef theControl,
   Point startPoint,
   ControlActionUPP actionProc
);
Parameters
theControl

A handle to the control in which a mouse-down event occurred. For a description of this data type, see “ControlRef”.
startPoint

A point, specified in coordinates local to the window, where the mouse-down event occurred. 
actionProc

A pointer to an action function defining the action your application takes while the user holds down the mouse button. The value of the actionProc parameter can be a valid procPtr, NULL, or -1. A value of -1 indicates that the control should either perform auto tracking, or if it is incapable of doing so, do nothing (like NULL). See ControlActionProcPtr for information about an action function to specify in this parameter.
Return Value

If the user releases the mouse button while the cursor is inside a control part, TrackControl returns a value of type ControlPartCodeidentifying the control part in which the mouse-up event occurs; see “Control Meta Part Code Constants”, “Control Part Code Constants”, and“Control State Part Code Constants”. TrackControl returns 0 if the user releases the mouse button while the cursor is outside the control part. If the user releases the mouse button when the cursor is in an indicator such as a scroll box, TrackControl calls the control’s control definition function to reposition the indicator. For a description of this data type, see “ControlPartCode”.
Discussion

When the Appearance Manager is available, you should typically call HandleControlClick instead of TrackControl to follow the user’s cursor movements in a control and provide visual feedback until the user releases the mouse button. Unlike the TrackControl function, HandleControlClick also accepts modifier key information so that the control may take into account the current modifier key state if the control is set up to handle its own tracking.

If the Appearance Manager is not available, you can use the TrackControl function to follow the user’s cursor movements in a control and provide visual feedback until the user releases the mouse button. The visual feedback given by TrackControl depends on the control part in which the mouse-down event occurs. When highlighting is appropriate, for example, TrackControl highlights the control part (and removes the highlighting when the user releases the mouse button). When the user holds down the mouse button while the cursor is in an indicator (such as the scroll box of a scroll bar) and moves the mouse, TrackControl responds by dragging a dotted outline of the indicator. 

While the user holds down the mouse button with the cursor in one of the standard controls, TrackControl performs the following actions, depending on the value you pass in the parameter actionProc. (For other controls, what you pass in this parameter depends on how you define the control.)
If you pass NULL in the actionProc parameter, TrackControl uses no action function and therefore performs no additional actions beyond highlighting the control or dragging the indicator. This is appropriate for buttons, checkboxes, radio buttons, and the scroll box of a scroll bar. 
If you pass a pointer to an action function in the actionProc parameter, you must provide the function, and it must define some action that your application repeats as long as the user holds down the mouse button. This is appropriate for the scroll arrows and gray areas of a scroll bar. 
If you pass Pointer(–1) in the actionProc parameter, TrackControl looks in the contrlAction field of the control structure for a pointer to the control’s action function. This is appropriate when you are tracking the cursor in a pop-up menu. (You can use the GetControlAction function to determine the value of this field, and you can use the SetControlAction function to change this value.) If the contrlAction field of the control structure contains a function pointer, TrackControl uses the action function it points to; if the field of the control structure also contains the value Pointer(–1), TrackControl calls the control’s control definition function to perform the necessary action you may wish to do this if you define your own control definition function for a custom control. If the field of the control structure contains the value NULL, TrackControl performs no action. 

Note that when you need to handle events in alert and dialog boxes, Dialog Manager functions automatically call FindControl and TrackControl. 
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/

ControlPartCode TrackControl (
   ControlRef theControl,
   Point startPoint,
   ControlActionUPP actionProc
);

/*GetControlFeatures

Obtains the features a control supports. 

Not recommended

OSErr GetControlFeatures (
   ControlRef inControl,
   UInt32 * outFeatures
);
Parameters
inControl

A handle to the control to be examined. For a description of this data type, see “ControlRef”.
outFeatures

On input, a pointer to an unsigned 32-bit integer value. On return, the value contains a bit field specifying the features the control supports. For a list of the features a control may support, see ControlDefProcPtr. 
Return Value

A result code. See “Control Manager Result Codes”. The result code errMsgNotSupported indicates that the control does not support Appearance-compliant features.
Discussion

The GetControlFeatures function obtains the Appearance-compliant features a control definition function supports, in response to a kControlMsgGetFeatures message. 
Carbon Porting Notes

Some feature bits may not be relevant when using Carbon event-based messages.
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/

OSErr GetControlFeatures (
   ControlRef inControl,
   UInt32 * outFeatures
);

/*NewControl

Creates a control based on parameter data. (Deprecated. Use the specific control creation function instead (for example, CreateCheckBoxControl).)

Not recommended

ControlRef NewControl (
   WindowRef owningWindow,
   const Rect * boundsRect,
   ConstStr255Param controlTitle,
   Boolean initiallyVisible,
   SInt16 initialValue,
   SInt16 minimumValue,
   SInt16 maximumValue,
   SInt16 procID,
   SInt32 controlReference
);
Parameters
owningWindow

A pointer to the window in which you want to place the control. All coordinates pertaining to the control are interpreted in this window’s local coordinate system.
boundsRect

A pointer to a rectangle, specified in the given window’s local coordinates, that encloses the control and thus determines its size and location. When specifying this rectangle, you should follow the guidelines presented in “Dialog Box Layout”, in Mac OS 8 Human Interface Guidelines, for control placement and alignment. 
controlTitle

The title string, used for push buttons, checkboxes, radio buttons, and pop-up menus. When specifying a multiple-line title, separate the lines with the ASCII character code 0x0D (carriage return). For controls that don’t use titles, pass an empty string. 
initiallyVisible

A Boolean value specifying the visible/invisible state for the control. If you pass true in this parameter, NewControl draws the control immediately, without using your window’s standard updating mechanism. If you pass false, you must later use ShowControl to display the control. 
initialValue

The initial setting for the control. For sliders and scrollbars, pass the appropriate integer value. For checkboxes and radio buttons, pass the constant indicating the current setting (as defined in “Checkbox Value Constants” and “Radio Button Value Constants”. For plain buttons that do not retain a setting, pass 0. 
minimumValue

The minimum setting for the control. For sliders and scrollbars, pass the appropriate minimum integer value. For checkboxes and radio buttons, pass 0 (or the equivalent constant from “Checkbox Value Constants” or “Radio Button Value Constants”). For plain buttons that do not retain a setting, pass 0. 
maximumValue

The maximum setting for the control. For sliders and scrollbars, pass the appropriate maximum integer value. For scroll bars, if the maximum value is equal to the minimum value, the control definition function automatically disables the scroll bar. For checkboxes and radio buttons, pass 1 (or the equivalent constant defined in “Checkbox Value Constants” or “Radio Button Value Constants”). For plain buttons that do not retain a setting, pass 0. 
procID

The control definition ID. If the control definition function isn’t in memory, it is read in. On Mac OS X, if you do not pass a valid procID (that is, if it does not correspond to a CDEF resource), NewControl will not create a control and will simply return NULL. On Mac OS 9 and earlier, passing an invalid procID will cause NewControl to create a pushbutton control.
controlReference

The control’s reference value, which is set and used only by your application. 
Return Value

A handle to the control described in its parameters. If NewControl runs out of memory or fails, it returns NULL. For a description of this data type, see “ControlRef”.
Discussion

The NewControl function creates a control structure from the information you specify in its parameters, adds the control structure to the control list for the specified window, and returns as its function result a handle to the control. You use this handle when referring to the control in most other Control Manager functions. Generally, you should use the function GetNewControl instead of NewControl, because GetNewControl is a resource-based control-creation function that allows you to localize your application without recompiling. 

When an embedding hierarchy is established within a window, NewControl automatically embeds the newly created control in the root control of the owning window. 
Carbon Porting Notes

Carbon does not support custom control definitions stored in'CDEF' resources. If you want to specify a custom control definition for NewControl, you must compile your definition function directly in your application and then register the function by calling RegisterControlDefinition. When NewControl gets a procID value that doesn’t recognize, it checks a special mapping table to find the pointer that is registered for the resource ID embedded in the procID parameter. It then calls that function to implement your control. 
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/

ControlRef NewControl (
   WindowRef owningWindow,
   const Rect * boundsRect,
   ConstStr255Param controlTitle,
   Boolean initiallyVisible,
   SInt16 initialValue,
   SInt16 minimumValue,
   SInt16 maximumValue,
   SInt16 procID,
   SInt32 controlReference
);

/*IsControlEnabled

Indicates whether a control is enabled. 

Boolean IsControlEnabled (
   ControlRef inControl
);
Parameters
inControl

The control that is to be queried. For a description of this data type, see 
Return Value

A Boolean whose value is true if the control is enabled; otherwise, false.
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/
Boolean IsControlEnabled (
   ControlRef inControl
);

/*IdleControls

Performs idle event processing. (Deprecated in Mac OS X v10.4. You should remove all calls to IdleControls because it uses unnecessary processor time. System-supplied controls do not respond to IdleControls in Mac OS X.)

Not recommended

void IdleControls (
   WindowRef inWindow
);
Parameters
inWindow

A pointer to a window containing controls that support idle events.
Discussion

Your application should call the IdleControls function to give idle time to any controls that want the kControlMsgIdle message. IdleControls calls the control with an idle event so the control can do idle-time processing. You should call IdleControls at least once in your event loop. See ControlDefProcPtr for more details on how a control definition function should handle idle processing. 
Special Considerations

Idle events are not recommended. If you have a custom control that needs time to perform tasks (such as animation), use Carbon Event timers instead. See Carbon Event Manager Programming Guide for more details. 
Availability
Available in Mac OS X v10.0 and later.
Deprecated in Mac OS X v10.4.
Declared In
Controls.h*/

void IdleControls (
   WindowRef inWindow
);

/*ClearKeyboardFocus

Removes the keyboard focus for the currently focused control in a window.

OSErr ClearKeyboardFocus (
   WindowRef inWindow
);
Parameters
inWindow

A pointer to the window in which to clear keyboard focus.
Return Value

A result code. See “Control Manager Result Codes”.
Discussion

When the ClearKeyboardFocus function is called, the Control Manager calls your control definition function and passes kControlMsgFocus in its message parameter and kControlFocusNoPart in its param parameter. See ControlDefProcPtr for a discussion of possible responses to this message. 
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/

OSErr ClearKeyboardFocus (
   WindowRef inWindow
);

/*MoveControl

Moves a control within its window.

void MoveControl (
   ControlRef theControl,
   SInt16 h,
   SInt16 v
);
Parameters
theControl

A handle to the control you wish to move. For a description of this data type, see 
h

The horizontal coordinate (local to the control’s window) of the new location of the upper-left corner of the control’s rectangle. 
v

The vertical coordinate (local to the control’s window) of the new location of the upper-left corner of the control’s rectangle.
Discussion

The MoveControl function moves the control to the new location specified by the h and v parameters, using them to change the rectangle specified in the contrlRect field of the control structure. When the control is visible, MoveControl first hides it and then redraws it at its new location.

For example, if the user resizes a document window that contains a scroll bar, your application can use MoveControl to move the scroll bar to its new location. 
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/

void MoveControl (
   ControlRef theControl,
   SInt16 h,
   SInt16 v
);

/*SetControlViewSize

Informs the Control Manager of the size of the content to which a control’s size is proportioned.

void SetControlViewSize (
   ControlRef theControl,
   SInt32 newViewSize
);
Parameters
theControl

A handle to the control whose view size is to be set. For a description of this data type, see “ControlRef”.
newViewSize

A value specifying the size of the content being displayed. This value should be expressed in terms of the same units of measurement as are used for the minimum, maximum, and current settings of the control. 
Discussion

Your application should call the SetControlViewSize function to support proportional scroll boxes. If the user selects the systemwide Appearance preference for proportional scroll boxes and your application doesn’t call SetControlViewSize, it will still have the traditional square scroll boxes.

To support a proportional scroll box, simply pass the size of the view area—in terms of whatever units the scroll bar uses—to SetControlViewSize. The system automatically handles resizing the scroll box, once your application supplies this information. 
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/
void SetControlViewSize (
   ControlRef theControl,
   SInt32 newViewSize
);

/*TestControl

Obtains the control part in which a mouse-down event occurred.

ControlPartCode TestControl (
   ControlRef theControl,
   Point testPoint
);
Parameters
theControl

A handle to the control in which the mouse-down event occurred. For a description of this data type, see 
testPoint

The point, in a window’s local coordinates, where the mouse-down event occurred. 
Return Value

The part code of the control part, or 0 if the point is outside the control; see “Control Meta Part Code Constants”, “Control Part Code Constants”, and“Control State Part Code Constants”. If the control is invisible or inactive, TestControl returns 0. For a description of this data type, see “ControlPartCode”.
Discussion

The TestControl function is called by the FindControl and TrackControl functions; your application does not normally call it.

When the control specified by the parameter theControl is visible and active, TestControl tests which part of the control contains the point specified by the parameter testPoint. 
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/
ControlPartCode TestControl (
   ControlRef theControl,
   Point testPoint
);

/*GetControlRegion

Obtains the region corresponding to a given control part.

OSStatus GetControlRegion (
   ControlRef inControl,
   ControlPartCode inPart,
   RgnHandle outRegion
);
Parameters
inControl

A handle to the control containing the part for which a region is to be obtained. For a description of this data type, see 
inPart

A constant identifying the control part for which a region is to obtained; you may specify the kControlStructureMetaPart and kControlContentMetaPart control part codes, as well as the standard control part codes. See “Control Part Code Constants”, “Control Part Code Constants”, and “Control State Part Code Constants” for descriptions of possible values. For a description of this data type, 
outRegion

On input, a value of type RgnHandle. On return, GetControlRegion sets the region to contain the actual dimensions and position of the control part, in local coordinates.
Return Value

A result code. See “Control Manager Result Codes”.
Availability
Available in Mac OS X v10.0 and later.
Declared In
Controls.h*/
OSStatus GetControlRegion (
   ControlRef inControl,
   ControlPartCode inPart,
   RgnHandle outRegion
);


#ifdef __cplusplus
}
#endif

#endif