Inside Macintosh: Macintosh Toolbox Essentials /: Chapter 5 - Control Manager

Summary of the Control Manager

Pascal Summary

Constants

CONST
   {control definition IDs}
   pushButProc          = 0;     {button}
   checkBoxProc         = 1;     {checkbox}
   radioButProc         = 2;     {radio button}
   useWFont             = 8;     {add to above to display control title in }
                                 { the window font}
   scrollBarProc        = 16;    {scroll bar}
   popupMenuProc        = 1008;  {pop-up menu}
   popupMenuCDEFproc    = popupMenuProc;  {synonym for compatibility}

   {pop-up menu CDEF variation codes}
   popupFixedWidth      = $0001;    {add to popupMenuProc to use }
                                    { fixed-width control}
   popupUseAddResMenu   = $0004;    {add to popupMenuProc to specify a }
                                    { value of type ResType in the }
                                    { contrlRfCon field of the control }
                                    { record; Menu Manager adds }
                                    { resources of this type to the menu}
   popupUseWFont        = $0008;    {add to popupMenuProc to show control }
                                    { title in the window font}

   {part codes}
   inButton             = 10;    {button}
   inCheckBox           = 11;    {checkbox or radio button}
   inUpButton           = 20;    {up arrow for a vertical scroll bar, }
                                 { left arrow for a horizontal scroll bar}
   inDownButton         = 21;    {down arrow for a vertical scroll bar, }
                                 { right arrow for a horizontal scroll bar}
   inPageUp             = 22;    {gray area above scroll box for a }
                                 { vertical scroll bar, gray area to }
                                 { left of scroll box for a horizontal }
                                 { scroll bar}
   inPageDown           = 23;    {gray area below scroll box for a }
                                 { vertical scroll bar, gray area to }
                                 { right of scroll box for a horizontal }
                                 { scroll bar}
   inThumb              = 129;   {scroll box (or other indicator)}

   {pop-up title characteristics}
   popupTitleBold       = $00000100;   {boldface font style}
   popupTitleItalic     = $00000200;   {italic font style}
   popupTitleUnderline  = $00000400;   {underline font style}
   popupTitleOutline    = $00000800;   {outline font style}
   popupTitleShadow     = $00001000;   {shadow font style}
   popupTitleCondense   = $00002000;   {condensed characters}
   popupTitleExtend     = $00004000;   {extended characters}
   popupTitleNoStyle    = $00008000;   {monostyled text}
   popupTitleLeftJust   = $00000000;   {place title left of pop-up box}
   popupTitleCenterJust = $00000001;   {center title over pop-up box}
   popupTitleRightJust  = $000000FF;   {place title right of pop-up box}

   {axis constraints for DragControl procedure}
   noConstraint         = 0;  {no constraint}
   hAxisOnly            = 1;  {drag along horizontal axis only}
   vAxisOnly            = 2;  {drag along vertical axis only}

   {constants for the message parameter in a control definition function}
   drawCntl             = 0;  {draw the control or its part}
   testCntl             = 1;  {test where mouse button is pressed}
   calcCRgns            = 2;  {calculate region for control or indicator in }
                              { 24-bit systems}
   initCntl             = 3;  {peform any additional control initialization}
   dispCntl             = 4;  {take any additional disposal actions}
   posCntl              = 5;  {move indicator and update its setting}
   thumbCntl            = 6;  {calculate parameters for dragging indicator}
   dragCntl             = 7;  {perform any custom dragging of control or }
                              { its indicator}
   autoTrack            = 8;  {execute action procedure specified by your }
                              { function}
   calcCntlRgn          = 10; {calculate region for control}
   calcThumbRgn         = 11; {calculate region for indicator}

   {part identifiers for ColorSpec records in a control color table resource}
   cFrameColor          = 0;  {frame color; for scroll bars, also fore- }
                              { ground color for scroll arrows and gray area}
   cBodyColor           = 1;  {for scroll bars, background color for }
                              { scroll arrows and gray area; for other }
                              { controls, the fill color for body of control}
   cTextColor           = 2;  {text color; unused for scroll bars}
   cThumbColor          = 3;  {Reserved}

Data Types

TYPE  ControlPtr        = ^ControlRecord;
      ControlHandle     = ^ControlPtr;

      ControlRecord =
      PACKED RECORD
         nextControl:   ControlHandle; {next control}
         contrlOwner:   WindowPtr;     {control's window}
         contrlRect:    Rect;          {rectangle}
         contrlVis:     Byte;          {255 if visible}
         contrlHilite:  Byte;          {highlight state}
         contrlValue:   Integer;       {control's current setting}
         contrlMin:     Integer;       {control's minimum setting}
         contrlMax:     Integer;       {control's maximum setting}
         contrlDefProc: Handle;        {control definition function}
         contrlData:    Handle;        {data used by contrlDefProc}
         contrlAction:  ProcPtr;       {action procedure}
         contrlRfCon:   LongInt;       {control's reference value}
         contrlTitle:   Str255;        {control's title}
      END;

      AuxCtlPtr      = ^AuxCtlRec;
      AuxCtlHandle   = ^AuxCtlPtr;

      AuxCtlRec = 
      RECORD
         acNext:        AuxCtlHandle;  {handle to next AuxCtlRec}
         acOwner:       ControlHandle; {handle to this record's control}
         acCTable:      CCTabHandle;   {handle to color table record}
         acFlags:       Integer;       {reserved}
         acReserved:    LongInt;       {reserved for future use}
         acRefCon:      LongInt;       {for use by application}
      END;



      CCTabPtr       = ^CtlCTab;
      CCTabHandle    = ^CCTabPtr;

      CtlCTab = 
      RECORD
         ccSeed:        LongInt;       {reserved; set to 0}
         ccRider:       Integer;       {reserved; set to 0}
         ctSize:        Integer;       {number of ColorSpec records in next }
                                       { field; 3 for standard controls}
         ctTable:       ARRAY[0..3] OF ColorSpec;
      END;

Control Manager Routines

Creating Controls

FUNCTION GetNewControl (controlID: Integer; owner: WindowPtr)
: ControlHandle;
FUNCTION NewControl (theWindow: WindowPtr; boundsRect: Rect; 
title: Str255; visible: Boolean; 
value: Integer; min: Integer; max: Integer; 
procID: Integer; refCon: LongInt) 
: ControlHandle;

Drawing Controls

{UpdateControls is also spelled as UpdtControl}
PROCEDURE ShowControl(theControl: ControlHandle);
PROCEDURE UpdateControls(theWindow: WindowPtr; updateRgn: RgnHandle);
PROCEDURE DrawControls (theWindow: WindowPtr);
PROCEDURE Draw1Control(theControl: ControlHandle);

Handling Mouse Events in Controls

FUNCTION FindControl (thePoint: Point; theWindow: WindowPtr; 
VAR theControl: ControlHandle): Integer;
FUNCTION TrackControl (theControl: ControlHandle; thePoint: Point; 
actionProc: ProcPtr): Integer;
FUNCTION TestControl(theControl: ControlHandle; thePt: Point)
: Integer;

Changing Control Settings and Display

{some routines have 2 spellings----see Table 5-1 for the alternate spellings}
PROCEDURE SetControlValue (theControl: ControlHandle; theValue: Integer);
PROCEDURE SetControlMinimum (theControl: ControlHandle; minValue: Integer);
PROCEDURE SetControlMaximum (theControl: ControlHandle; maxValue: Integer);
PROCEDURE SetControlTitle(theControl: ControlHandle; title: Str255);
PROCEDURE HideControl(theControl: ControlHandle);
PROCEDURE MoveControl (theControl: ControlHandle; h: Integer;
v: Integer);
PROCEDURE SizeControl(theControl: ControlHandle; w: Integer; h: 
Integer);
PROCEDURE HiliteControl (theControl: ControlHandle;
hiliteState: Integer);
PROCEDURE DragControl (theControl: ControlHandle; startPt: Point; 
limitRect: Rect; slopRect: Rect; 
axis: Integer);
PROCEDURE SetControlColor(theControl: ControlHandle; newColorTable: 
CCTabHandle);
PROCEDURE SetControlAction(theControl: ControlHandle;
actionProc: ProcPtr);

Determining Control Values

{some routines have 2 spellings----see Table 5-1 for the alternate spellings}
FUNCTION GetControlValue(theControl: ControlHandle): Integer;
FUNCTION GetControlMinimum(theControl: ControlHandle): Integer;
FUNCTION GetControlMaximum (theControl: ControlHandle): Integer;
PROCEDURE GetControlTitle(theControl: ControlHandle; VAR title: Str255);
FUNCTION GetControlReference
   (theControl: ControlHandle): LongInt;
PROCEDURE SetControlReference
   (theControl: ControlHandle; data: LongInt);
FUNCTION GetControlAction(theControl: ControlHandle): ProcPtr;
FUNCTION GetControlVariant(theControl: ControlHandle): Integer;
FUNCTION GetAuxiliaryControlRecord
   (theControl: ControlHandle; 
VAR acHndl: AuxCtlHandle): Boolean;

Removing Controls

PROCEDURE DisposeControl(theControl: ControlHandle);
PROCEDURE KillControls(theWindow: WindowPtr);

Application-Defined Routines

Defining Your Own Control Definition Function

FUNCTION MyControl (varCode: Integer; theControl: ControlHandle; 
message: Integer; param: LongInt) : LongInt;

Defining Your Own Action Procedures

PROCEDURE MyAction(theControl: ControlHandle; partCode: Integer);
PROCEDURE MyIndicatorAction;

C Summary

Constants

enum {
      /*control definition IDs*/
      pushButProc          = 0,     /*button*/
      checkBoxProc         = 1,     /*checkbox*/
      radioButProc         = 2,     /*radio button*/
      useWFont             = 8,     /*add to above to display control */
                                    /* title in the window font*/
      scrollBarProc        = 16,    /*scroll bar*/
      popupMenuProc        = 1008,  /*pop-up menu*/

      /*pop-up menu CDEF variation codes*/
      popupFixedWidth  = 1 << 0,    /*add to popupMenuProc to use */
                                    /* use fixed-width control*/
      popupUseAddResMenu = 1 << 2,  /*add to popupMenuProc to specify a */
                                    /* value of type ResType in the */
                                    /* contrlRfCon field of the control */
                                    /* record; Menu Manager adds */
                                    /* resources of this type to the menu*/
      popupUseWFont  = 1 << 3       /*add to popupMenuProc to display */
                                    /* control title in the window font*/
};





enum {
      /*part codes*/
      inButton             = 10, /*button*/
      inCheckBox           = 11, /*checkbox or radio button*/
      inUpButton           = 20, /*up arrow for a vertical scroll bar, */
                                 /* left arrow for a horizontal scroll bar*/
      inDownButton         = 21, /*down arrow for a vertical scroll bar, */
                                 /* right arrow for a horizontal scroll bar*/
      inPageUp             = 22, /*gray area above scroll box for a */
                                 /* vertical scroll bar, gray area to */
                                 /* left of scroll box for a horizontal */
                                 /* scroll bar*/
      inPageDown           = 23, /*gray area below scroll box for a */
                                 /* vertical scroll bar, gray area to */
                                 /* right of scroll box for a horizontal */
                                 /* scroll bar*/
      inThumb              = 129 /*scroll box (or other indicator)*/
};

enum {
      /*pop-up title characteristics*/
      popupTitleBold  = 1 << 8,        /*boldface font style*/
      popupTitleItalic = 1 << 9,       /*italic font style*/
      popupTitleUnderline = 1 << 10,   /*underline font style*/
      popupTitleOutline = 1 << 11,     /*outline font style*/
      popupTitleShadow = 1 << 12,      /*shadow font style*/
      popupTitleCondense = 1 << 13,    /*condensed text*/
      popupTitleExtend = 1 << 14,      /*extended text*/
      popupTitleNoStyle = 1 << 15      /*monostyled text*/
};

enum {
      /*pop-up title characteristics*/
      popupTitleLeftJust = 0x00000000,    /*place title left of pop-up box*/
      popupTitleCenterJust = 0x00000001,  /*center title over pop-up box*/
      popupTitleRightJust = 0x000000FF,   /*place title right of pop-up box*/

   /*axis constraints for DragControl procedure*/
      noConstraint   = 0,  /*no constraint*/
      hAxisOnly      = 1,  /*constrain movement to horizontal axis only*/
      vAxisOnly      = 2,  /*constrain movement to vertical axis only*/


/*constants for the message parameter in a control definition function*/
      drawCntl       = 0,  /*draw the control or control part*/
      testCntl       = 1,  /*test where mouse button was pressed*/
      calcCRgns      = 2,  /*calculate region for control or indicator in */
                           /* 24-bit systems*/
      initCntl       = 3,  /*do any additional control initialization*/
      dispCntl       = 4,  /*take any additional disposal actions*/
      posCntl        = 5,  /*move indicator and update its setting*/
      thumbCntl      = 6,  /*calculate parameters for dragging indicator*/
      dragCntl       = 7,  /*peform any custom dragging of control or */
                           /* its indicator*/
      autoTrack      = 8,  /*execute action procedure specified by your */
                           /* function*/
      calcCntlRgn    = 10, /*calculate region for control*/
      calcThumbRgn   = 11, /*calculate region for indicator*/

/*part identifiers for ColorSpec records in a control color table resource*/
      cFrameColor    = 0,  /*frame color; for scroll bars, also foreground */
                           /* color for scroll arrows and gray area*/
      cBodyColor     = 1,  /*for scroll bars, background color for scroll */
                           /* arrows and gray area; for other controls, */
                           /* the fill color for body of control*/
      cTextColor     = 2,  /*text color; for scroll bars, unused*/
      cThumbColor    = 3   /*Reserved*/
};

Data Types

struct ControlRecord {
      struct ControlRecord **nextControl;    /*next control*/
      WindowPtr      contrlOwner;   /*control's window*/
      Rect           contrlRect;    /*rectangle*/
      unsigned char  contrlVis;     /*255 if visible*/
      unsigned char  contrlHilite;  /*highlight state*/
      short          contrlValue;   /*control's current setting*/
      short          contrlMin;     /*control's minimum setting*/
      short          contrlMax;     /*control's maximum setting*/
      Handle         contrlDefProc; /*control definition function*/
      Handle         contrlData;    /*data used by contrlDefProc*/
      ProcPtr        contrlAction;  /*action procedure*/
      long           contrlRfCon;   /*control's reference value*/
      Str255         contrlTitle;   /*control's title*/
   };
typedef struct ControlRecord ControlRecord;
typedef ControlRecord *ControlPtr, **ControlHandle;

struct AuxCtlRec { 
      Handle         acNext;        /*handle to next AuxCtlRec*/
      ControlHandle  acOwner;       /*handle to this record's control*/
      CCTabHandle    acCTable;      /*handle to color table record*/
      short          acFlags;       /*reserved*/
      long           acReserved;    /*reserved for future use*/
      long           acRefCon;      /*for use by application*/
   };

typedef struct AuxCtlRec AuxCtlRec;
typedef AuxCtlRec *AuxCtlPtr, **AuxCtlHandle;

struct CtlCTab { 
      long           ccSeed;        /*reserved; set to 0*/
      short          ccRider;       /*reserved; set to 0*/
      short          ctSize;        /*number of ColorSpec records in next */
                                    /* field; 3 for standard controls*/
      ColorSpec      ctTable[4];
   };
typedef struct CtlCTab CtlCTab;
typedef CtlCTab *CCTabPtr, **CCTabHandle;

Control Manager Routines

Creating Controls

pascal ControlHandle GetNewControl
   (short controlID, WindowPtr owner);
pascal ControlHandle NewControl
   (WindowPtr theWindow, const Rect *boundsRect,
ConstStr255Param title, Boolean visible,
short value, short min, short max, 
short procID, long refCon);

Drawing Controls

/*UpdateControls is also spelled as UpdtControl*/
pascal void ShowControl(ControlHandle theControl);
pascal void UpdateControls(WindowPtr theWindow, RgnHandle updateRgn);
pascal void DrawControls(WindowPtr theWindow);
pascal void Draw1Control(ControlHandle theControl);

Handling Mouse Events in Controls

pascal short FindControl(Point thePoint, WindowPtr theWindow, 
ControlHandle *theControl);
pascal short TrackControl(ControlHandle theControl, Point thePoint, 
ProcPtr actionProc);
pascal short TestControl(ControlHandle theControl, Point thePt);

Changing Control Settings and Display

/*some routines have 2 spellings----see Table 5-1 for the alternate spellings*/
pascal void SetControlValue(ControlHandle theControl, short theValue);
pascal void SetControlMinimum
(ControlHandle theControl, short minValue);
pascal void SetControlMaximum
(ControlHandle theControl, short maxValue);
pascal void SetControlTitle(ControlHandle theControl,
ConstStr255Param title);
pascal void HideControl(ControlHandle theControl)
pascal void MoveControl(ControlHandle theControl, short h, short v);
pascal void SizeControl(ControlHandle theControl, short w, short h);
pascal void HiliteControl(ControlHandle theControl, short hiliteState);
pascal void DragControl(ControlHandle theControl, Point startPt, 
const Rect *limitRect,  
const Rect *slopRect, short axis);
pascal void SetControlAction(ControlHandle theControl, ProcPtr actionProc)
pascal void SetControlColor(ControlHandle theControl, 
CCTabHandle newColorTable);

Determining Control Values

/*some routines have 2 spellings----see Table 5-1 for the alternate spellings*/
pascal short GetControlValue
   (ControlHandle theControl);
pascal short GetControlMinimum
   (ControlHandle theControl);
pascal short GetControlMaximum
   (ControlHandle theControl);
pascal void GetControlTitle(ControlHandle theControl, Str255 title);
pascal long GetControlReference
	(ControlHandle theControl);
pascal void SetControlReference
   (ControlHandle theControl, long data);
pascal ProcPtr GetControlAction
    (ControlHandle theControl);
pascal short GetControlVariant
   (ControlHandle theControl);
pascal Boolean GetAuxiliaryControlRecord
   (ControlHandle theControl, 
AuxCtlHandle *acHndl);

Removing Controls

pascal void DisposeControl(ControlHandle theControl);
pascal void KillControls(WindowPtr theWindow);

Application-Defined Routines

Defining Your Own Control Definition Function

pascal long MyControl(short varCode, ControlHandle theControl,
short message, long param);

Defining Your Own Action Procedures

pascal void MyAction(ControlHandle theControl, short partCode);
pascal void MyIndicatorAction;

Assembly-Language Summary

Data Structures

ControlRecord Data Structure
0 `nextControl` long handle to next control in control list
4 `contrlOwner` long pointer to this control's window
8 `contrlRect` 8 bytes control's rectangle
16 `contrlVis` 1 byte value of 255 if control is visible
17 `contrlHilite` 1 byte highlight state
18 `contrlValue` word control's current setting
20 `contrlMin` word control's minimum setting
22 `contrlMax` word control's maximum setting
24 `contrlDefProc` long handle to control definition function
28 `contrlData` long data used by control definition function
32 `contrlAction` long address of action procedure
36 `contrlRfCon` long control's reference value
40 `contrlTitle` 256 bytes control title (preceded by length byte)

AuxCtlRec Data Structure
0 acNext long handle to next AuxCtlRec record in control list
4 acOwner long handle to this record's control
8 acCTable long handle to color table for this control
12 acFlags word miscellaneous flags
14 acReserved long reserved for use by Apple Computer, Inc.
18 acRefCon long for use by application

Global Variables
AuxCtlHead First in a linked list of auxiliary control records
AuxWinHead Contains a pointer to the linked list of auxiliary control records
DragHook Address of procedure to execute during `TrackControl` and `DragControl`
DragPattern Pattern of dragged region's outline (8 bytes)

0	`nextControl`	long	handle to next control in control list
4	`contrlOwner`	long	pointer to this control's window
8	`contrlRect`	8 bytes	control's rectangle
16	`contrlVis`	1 byte	value of 255 if control is visible
17	`contrlHilite`	1 byte	highlight state
18	`contrlValue`	word	control's current setting
20	`contrlMin`	word	control's minimum setting
22	`contrlMax`	word	control's maximum setting
24	`contrlDefProc`	long	handle to control definition function
28	`contrlData`	long	data used by control definition function
32	`contrlAction`	long	address of action procedure
36	`contrlRfCon`	long	control's reference value
40	`contrlTitle`	256 bytes	control title (preceded by length byte)

0	acNext	long	handle to next AuxCtlRec record in control list
4	acOwner	long	handle to this record's control
8	acCTable	long	handle to color table for this control
12	acFlags	word	miscellaneous flags
14	acReserved	long	reserved for use by Apple Computer, Inc.
18	acRefCon	long	for use by application

AuxCtlHead	First in a linked list of auxiliary control records
AuxWinHead	Contains a pointer to the linked list of auxiliary control records
DragHook	Address of procedure to execute during `TrackControl` and `DragControl`
DragPattern	Pattern of dragged region's outline (8 bytes)

Summary of the Control Manager

Pascal Summary

Constants

Data Types

Control Manager Routines

Creating Controls

Drawing Controls

Handling Mouse Events in Controls

Changing Control Settings and Display

Determining Control Values

Removing Controls

Application-Defined Routines

Defining Your Own Control Definition Function

Defining Your Own Action Procedures

C Summary

Constants

Data Types

Control Manager Routines

Creating Controls

Drawing Controls

Handling Mouse Events in Controls

Changing Control Settings and Display

Determining Control Values

Removing Controls

Application-Defined Routines

Defining Your Own Control Definition Function

Defining Your Own Action Procedures

Assembly-Language Summary

Data Structures

Global Variables AuxCtlHeadFirst in a linked list of auxiliary control records AuxWinHeadContains a pointer to the linked list of auxiliary control records DragHookAddress of procedure to execute during TrackControl and DragControl DragPatternPattern of dragged region's outline (8 bytes)

Global Variables
AuxCtlHead First in a linked list of auxiliary control records
AuxWinHead Contains a pointer to the linked list of auxiliary control records
DragHook Address of procedure to execute during `TrackControl` and `DragControl`
DragPattern Pattern of dragged region's outline (8 bytes)