LStdControl

LStdControl is a PowerPlant class that encapsulates the standard Mac OS control behavior.

Methods :

The methods in this class are:

LStdControl()	~LStdControl()
AlignControlRect()	CalcBigValue()
CalcSmallValue()	CreateFromCNTL()
DisableSelf()	DrawSelf()
EnableSelf()	FindHotSpot()
FocusDraw()	GetDescriptor()
GetMacControl()	GetTrackingControl()
HideSelf()	HotSpotAction()
HotSpotResult()	InitStdControl()
MoveBy()	PointInHotSpot()
ResizeFrameBy()	SetActionProc()
SetDescriptor()	SetMaxValue()
SetMinValue()	SetStdMinAndMax()
SetThumbFunc()	SetValue()
ShowSelf()	TrackHotSpot()
ValueIsInStdRange()

Data Members:

The data members in this class are:

mMacControlH	mThumbFunc
mControlKind	mTextTraitsID
mUsingBigValues	sTrackingControl

Operation:

The specific design of this class supports scroll bar controls and controls that use custom control definitions (CDEFs). This class also forms the basis for the standard button, check box, pop-up menu, and radio button classes.

For detailed information on Mac OS controls, refer to Inside Mac: MacintoshToolbox Essentials, published by Addison-Wesley.

Source files:

(Pane Classes)

LStdControl.h

LStdControl.cp

Ancestors:

The ancestors for this class are:

LAttachable	LControl
LBroadcaster	LPane

LStdControl()

Purpose:

The constructors create objects from the passed-in parameters. Many of these constructors call LControl base class constructors to force a portion of the initialization chores.

Access:

Public

Prototype:

LStdControl();

LStdControl( SInt16 inControlKind );

LStdControl( const SPaneInfo &inPaneInfo,

MessageT inValueMessage,

SInt32 inValue,

SInt32 inMinValue,

SInt32 inMaxValue,

SInt16 inControlKind,

ResIDT inTextTraitsID,

ConstStringPtr inTitle,

SInt32 inMacRefCon );

LStdControl( const SPaneInfo &inPaneInfo,

MessageT inValueMessage,

SInt32 inValue,

SInt32 inMinValue,

SInt32 inMaxValue,

SInt16 inControlKind,

ResIDT inTextTraitsID,

ControlHandle inMacControlH );

LStdControl( LStream *inStream );

LStdControl( LStream *inStream, bool inDummy );

These constructors have the following parameters:

SInt16	inControlKind	The value to set for mControlKind.
const   SPaneInfo&	inPaneInfo	A reference to the SPaneInfo object that is the super view.
MessageT	inValueMessage	The message sent when the control is interacted with.
SInt32	inValue	The value to set for the control.
SInt32	inMinValue	The minimum value to allow for the control.
SInt32	inMaxValue	The maximum value to allow for the control.
ResIDT	inTextTraitsID	The resource ID that contains the text traits for control text.
ConstStringPtr	inTitle	The title to use for the control.
SInt32	inMacRefCon	The value to put in the Mac OS refcon storage space.
ControlHandle	inMacControlH	The Mac OS handle to the control.
LStream*	inStream	A pointer to a stream object that contains the information to create the LControl object.
bool	inDummy	This parameter is unused for this constructor.

Remarks:

• LStdControl( SInt16 inControlKind )-Construct a StdControl for a particular kind of Mac OS Toolbox Control. On entry, the current Port must be the Window into which to install the Control.

~LStdControl()

Purpose:

The destructor destroys the object.

Access:

Virtual, Public

Prototype:

virtual ~LStdControl();

AlignControlRect()

Purpose:

Set the rectangle inside the Mac OS Toolbox ControlRecord to the Frame rectangle of the standard control.

Access:

Protected

Prototype:

void AlignControlRect();

None

Return:

None

Remarks:At (almost) all times, the contrlRect field of the Mac OS Toolbox ControlRecord must be the same as the Frame rectangle of the StdControl object. We store directly to the ControlRecord rather than using the SizeControl and MoveControl traps because we want to bypass the automatic drawing (and the need to set the port and coordinate system) performed by those traps. The contrlRect is not the same as the Frame rectangle if the latter is outside the 16-bit QuickDraw coordinate space.

CalcBigValue()

Purpose:

Map from Small to Big value when using 32 bit values. Call this function only when mUsingBigValues is true.

Access:

Protected

Prototype:

SInt32 CalcBigValue( SInt16 inSmallValue );

This method has the following parameter:

SInt16

inSmallValue

The Small value to be converted.

Return:

SInt32 containing the Big value.

Remarks:

The control class uses Big (32 bit) values, but the Mac Control Manager only supports Small (16 bit) values. See the discussion for the SetStdMinAndMax() method.

CalcSmallValue()

Purpose:

Map from Big to Small value when using 32 bit values. Call this function only when mUsingBigValues is true.

Access:

Protected

Prototype:

SInt16 CalcSmallValue( SInt32 inBigValue );

This method has the following parameter:

SInt16

inBigValue

The Big value to be converted.

Return:

SInt16 containing the Small value.

Remarks:

The control class uses Big (32 bit) values, but the Mac Control Manager only supports Small (16 bit) values. Refer to the discussion for the SetStdMinAndMax() method.

CreateFromCNTL()

Purpose:

Create a StdControl from a `CNTL' resource.

Access:

Static, Public

Prototype:

static LStdControl* CreateFromCNTL(

ResIDT inCNTLid,

MessageT inValueMessage,

ResIDT inTextTraitsID,

LView *inSuperView);

This method has the following parameters:

ResIDT	inCNTLid	The resource ID of the CTNL resource.
MessageT	inValueMessage	The message that the control should send when it is changed.
ResIDT	inTextTraitsID	The resource ID of the text traits to use for drawing text.
LView*	inSuperView	The pointer to the SuperView that the control will belong to.

Return:

None

DisableSelf()

Purpose:

Disable a standard control.

Access:

Virtual, Protected

Prototype:

virtual void DisableSelf();

None

Return:

None

DrawSelf()

Purpose:

This method is an override of the base class method DrawSelf() in LPane. It draws the standard control.

EnableSelf()

Purpose:

Enable a StdControl

Access:

Virtual, Protected

Prototype:

virtual void EnableSelf();

None

Return:

None

FindHotSpot()

Purpose:

This method is an override of the base class method FindHotSpot() in LControl. It determines which hot spot, if any, contains the specified point.

FocusDraw()

Purpose:

This method is an override of the base class method FocusDraw() in LPane. It prepares for drawing in the Pane, and signals if the Pane has no SuperView.

GetDescriptor()

Purpose:

This method is an override of the base class method GetDescriptor() in LPane. It returns the Descriptor, which is the Title, of a standard control.

GetMacControl()

Purpose:

This method returns the value of mMacControlH.

Access:

Inline, Public

Prototype:

ControlHandle GetMacControl() const;

None

Return:

The ControlHandle held in mMacControlH.

GetTrackingControl()

Purpose:

This method returns the value of sTrackingControl.

Access:

Static, Inline, Public

Prototype:

static LStdControl* GetTrackingControl();

None

Return:

A pointer to an LStdControl, containing the value of sTrackingControl.

HideSelf()

Purpose:

This method is an override of the base class method GetDescriptor() in LPane. It hides a standard control.

HotSpotAction()

Purpose:

This method is an override of the base class method HotSpotAction() in LControl. It makes mouse tracking easier.

HotSpotResult()

Purpose:

This method is an override of the base class method HotSpotAction() in LControl. It performs the result of clicking and releasing mouse inside a hot spot.

InitStdControl()

Purpose:

This is a private initializer which creates the Mac OS Toolbox Control.

Access:

Private

Prototype:

void InitStdControl( SInt16 inControlKind,

ResIDT inTextTraitsID,

ConstStringPtr inTitle,

SInt32 inMacRefCon);

This method has the following parameters:

SInt16	inControlKind	The value to set for mControlKind.
ResIDT	inTextTraitsID	The resource ID of the resource containing the text traits to use for drawing text.
ConstStringPtr	inTitle	The title to use for the control.
SInt32	inMacRefCon	The value to put in the Mac OS refcon storage space for the control.

Return:

None

MoveBy()

Purpose:

This method is an override of the base class method FocusDraw() in LPane. This method is an override to update the Mac ControlHandle. It moves the location of the Frame by the specified amounts.

PointInHotSpot()

Purpose:

This method is an override of the base class method PointInHotSpot() in LControl. It tells whether a particular point is inside a hot spot or not.

ResizeFrameBy()

Purpose:

This method is an override of the base class method FocusDraw() in LPane. This method is an override to update the Mac ControlHandle. It changes the Frame size by the specified amounts.

SetActionProc()

Purpose:

This method sets the control action proc (ControlActionUPP) for the control.

Access:

Public

Prototype:

void SetActionProc( ControlActionUPP inActionProc 
);

This method has the following parameter:

Control-ActionUPP

inActionProc

The procedure pointer to set the control action proc to.

Return:

None

SetDescriptor()

Purpose:

This method is an override of the base class method SetDescriptor() in LPane. This method sets the Descriptor, which is the title, of a standard control.

SetMaxValue()

Purpose:

This method is an override of the base class method SetMaxValue() in LControl. It sets the maximum value that a control can have.

SetMinValue()

Purpose:

This method is an override of the base class method SetMinValue() in LControl. It sets the minimum value that a control can have.

SetStdMinAndMax()

Purpose:

Sets the minimum and maximum values for the standard Mac OS control associated with this object.

Access:

Public

Prototype:

void SetStdMinAndMax();

None

Return:

None

Remarks:The Control class uses Big (32 bit) values, but the Mac Control Manager only supports Small (16 bit) values. So this object class has to map between Big and Small values. When either the minimum or maximum value is outside 16 bit range (below -32,768 or above 32,767), we set mUsingBigValues to true. In that case, you must call CalcSmallValue() and CalcBigValue() to map between the Small values used by the Mac Control Manager and the Big values used by this class. The mapping strategy is as follows. When using Big values, we always set the minimum value for the Mac Control to zero. There are two cases for the maximum value, depending on whether the difference between the Big Max and Min is greater than or less than 32,767. If greater, we set the Mac Control maximum to 32,767. If less, we set the Mac Control maximum to that difference. These choices simplify the math for converting between Big and Small values. The functions CalcSmallValue() and CalcBigValue() use the following equations to convert between Big and Small values.
  (1) BigMax - BigMin > 32,767   SmallValue = BigValue - BigMin
  ----------- = ------------------
  32,767 (BigMax - BigMin)
  (2) BigMax - BigMin <= 32,767
  SmallValue = BigValue - BigMin

SetThumbFunc()

Purpose:

This method sets the value of the mThumbFunc data member.

Access:

Public

Prototype:

void SetThumbFunc( ThumbActionUPP inThumbFunc );

This method has the following parameter:

ThumbActionUPP

inThumbFunc

The procedure pointer to set for the control's thumb action proc.

Return:

None

SetValue()

Purpose:

This method is an override of the base class method SetValue() in LPane. This method sets the value of a standard control. It overrides the inherited function to map from 32 bit numbers to the 16 bit numbers supported by the Mac OS Control Manager.

ShowSelf()

Purpose:

This method is an override of the base class method ShowSelf() in LPane. This method shows the control.

TrackHotSpot()

Purpose:

This method is an override of the base class method TrackHotSpot() in LControl. It tracks the mouse while it is down after clicking in a Control hot spot, and tells whether the mouse is released within the hot spot.

ValueIsInStdRange()

Purpose:

Indicates whether a value for a control is within the range supported by the Mac OS Control Manager.

Access:

Static, Protected

Prototype:

static Boolean ValueIsInStdRange( SInt32 inValue 
);

This method has the following parameter:

SInt32

inValue

The value to check against the control's range.

Return:

Returns true if the value is in the range, else returns false.

mMacControlH

Purpose:

This data member stores the handle to the Mac OS control.

Access:

Protected

Prototype:

ControlHandle mMacControlH;

mThumbFunc

Purpose:

This data member stores a pointer to the thumb action procedure for the control.

Access:

Protected

Prototype:

ThumbActionUPP mThumbFunc;

mControlKind

Purpose:

This data member stores the value for the control kind. Refer to the Mac OS system header named Controls.h for more information on these enumerations.

Access:

Protected

Prototype:

SInt16 mControlKind;

mTextTraitsID

Purpose:

This data member stores the value of the resource ID to use for text traits.

Access:

Protected

Prototype:

ResIDT mTextTraitsID;

mUsingBigValues

Purpose:

This data member remembers whether we are using Big values for the control or not.

Access:

Protected

Prototype:

Boolean mUsingBigValues;

sTrackingControl

Purpose:

This data member stores the pointer to the current standard control that is being tracked.

Access:

Static, Protected

Prototype:

static LStdControl* sTrackingControl;