LControl

LControl is a PowerPlant class that is used for manipulation and control of radio buttons, check boxes, pop-up menus, and other visual interface controls.

A control is an object of any class which inherits from the LControl class. All the standard Mac OS controls are provided by PowerPlant, and some additional controls as well.

Methods :

The methods in this class are:

LControl()	~LControl()
BroadcastValueMessage()	ClickSelf()
FindHotSpot()	GetMaxValue()
GetMinValue()	GetValue()
GetValueMessage()	HotSpotAction()
HotSpotResult()	IncrementValue()
PointInHotSpot()	SetMaxValue()
SetMinValue()	SetValue()
SetValueMessage()	SimulateHotSpotClick()
TrackHotSpot()

Data Members:

The data members in this class are:

mValueMessage	mValue
mMinValue	mMaxValue

Operation:

Controls are a large topic of discussion. In order to master the concepts and terminology of Controls within PowerPlant, a careful reading of the "Controls and Messaging" chapter in The PowerPlant Book is a good thing.

Source files:

(Pane Classes)

LControl.h

LControl.cp

Ancestors:

LAttachable

LBroadcaster

LPane

LControl()

Purpose:

The constructors create objects from the passed-in parameters.

Access:

Public

Prototype:

LControl();

LControl( const LControl &inOriginal );

LControl( const SPaneInfo &inPaneInfo,

MessageT inValueMessage,

SInt32 inValue,

SInt32 inMinValue,

SInt32 inMaxValue );

LControl( LStream *inStream );

These constructors have the following parameters:

const   LControl&	inOriginal	A reference to the LControl object you want to copy.
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 of the control.
SInt32	inMinValue	The minimum control value.
SInt32	inMaxValue	The maximum control value.
LStream*	inStream	A pointer to a stream object that contains the information to create the LControl object.

~LControl()

Purpose:

The destructor destroys the object.

Access:

Virtual, Public

Prototype:

virtual ~LControl();

BroadcastValueMessage()

Purpose:

Broadcasts a message indicating a control change to the Listeners.

Access:

Virtual, Protected

Prototype:

virtual void BroadcastValueMessage();

None

Return:

None

ClickSelf()

Purpose:

Tracks the mouse click and determines if a hot spot within a control was selected. If the hot spot was selected then this method responds to the mouse click by calling the HotSpotResult() method defined for the class.

Access:

Virtual, Protected

Prototype:

virtual void ClickSelf(

const SMouseDownEvent &inMouseDown );

This method has the following parameters:

const   SMouseDownEvent&

inMouseDown

The event information for the mouse down.

Return:

None

FindHotSpot()

Purpose:

Determine which hot spot, if any, was clicked.

Access:

Virtual, Protected

Prototype:

virtual SInt16 FindHotSpot( Point inPoint );

This method has the following parameters:

Point

inPoint

Local coordinates for the Control.

Return:

SInt16 containing the value of the hot spot selected.

Remarks:

If the return value is 0 then no hot spot was selected. Valid hot spots are integer values greater than 0.

GetMaxValue()

Purpose:

Get the maximum value for the control, found in the mMaxValue data member.

Access:

Public

Prototype:

SInt32 GetMaxValue() const;

None

Return:

SInt32 containing the value in mMaxValue.

GetMinValue()

Purpose:

Get the minimum value for the control, found in the mMinValue data member.

Access:

Public

Prototype:

SInt32 GetMinValue() const;

None

Return:

SInt32 containing the value in mMinValue.

GetValue()

Purpose:

Return the current value of a Control.

Access:

Virtual, Public

Prototype:

virtual SInt32 GetValue() const;

None

Return:

SInt32 containing the value in mValue

GetValueMessage()

Purpose:

Returns the value of the message.

Access:

Public

Prototype:

MessageT GetValueMessage() const;

None

Return:

MessageT containing the value in mValueMessage.

HotSpotAction()

Purpose:

This method allows you to take action while the hot spot is down clicked by the mouse.

Access:

Virtual, Protected

Prototype:

virtual void HotSpotAction( SInt16 inHotSpot,

Boolean inCurrInside,

Boolean inPrevInside );

This method has the following parameters:

SInt16	inHotSpot	The hot spot number.
Boolean	inCurrInside	Parameter is true if the mouse is currently inside the hot spot.
Boolean	inPrevInside	Parameter is true if the mouse was previously in the hot spot.

Return:

None

Remarks:

Depending on whether the mouse in inside or outside the hot spot you can override to change the control's visual appearance.

While the mouse is down you can override to continuously perform some action.

HotSpotResult()

Purpose:

Perform an action as a result of clicking and releasing the mouse inside a hot spot.

Access:

Virtual, Protected

Prototype:

virtual void HotSpotResult( SInt16 inHotSpot );

This method has the following parameters:

SInt16

inHotSpot

The hotspot number.

Return:

None

Remarks:

Subclasses need to override this function to implement behavior associated with clicking in a Control hot spot.

IncrementValue()

Purpose:

Increment the current value of the control.

Access:

Virtual, Public

Prototype:

virtual void IncrementValue( SInt32 inIncrement );

This method has the following parameters:

SInt32

inIncrement

The amount the current control value is incremented.

Return:

None

Remarks:

The incremental change in the amount of the value can be a negative amount.

PointInHotSpot()

Purpose:

Determine if the mouse is in the hot spot while down-clicking the mouse.

Access:

Virtual, Protected

Prototype:

virtual Boolean PointInHotSpot( Point inPoint,

SInt16 inHotSpot);

This method has the following parameters:

Point	inPoint	The local coordinates for the control.
SInt16	inHotSpot	The hot spot number.

Return:

Boolean true if the point is with the hot spot, else false.

SetMaxValue()

Purpose:

If the value is greater than mMaxValue then set to the maximum value.

Access:

Virtual, Public

Prototype:

virtual void SetMaxValue( SInt32 inMaxValue );

This method has the following parameters:

SInt32

inMaxValue

Maximum value to set for the control.

Return:

None

SetMinValue()

Purpose:

If the value is less than mMinValue then set to the minimum value.

Access:

Virtual, Public

Prototype:

virtual void SetMinValue( SInt32 inMinValue);

This method has the following parameters:

SInt32

inMinValue

The minimum value to set for the control.

Return:

None

SetValue()

Purpose:

If the value has changed then set the new value and inform Listeners of the value change.

Access:

Virtual, Public

Prototype:

virtual void SetValue( SInt32 inValue );

This method has the following parameters:

SInt32

inValue

The new value to set for the control.

Return:

None

SetValueMessage()

Purpose:

Sets the value of the message.

Access:

Public

Prototype:

void SetValueMessage( MessageT inValueMessage);

This method has the following parameters:

MessageT

inValueMessage

The value to set for the message.

Return:

None

SimulateHotSpotClick()

Purpose:

This method allows you to simulate clicking the hot spot of a Control. Visual feedback is provided as if the user had clicked inside the hot spot of a Control.

HotSpotAction() is called to simulate a down of the mouse. Then HotSpotResult() is used to simulate release within a particular hot spot.

Access:

Virtual, Public

Prototype:

virtual void SimulateHotSpotClick(SInt16 
inHotSpot);

This method has the following parameters:

SInt16

inHotSpot

The hot spot number.

Return:

None

Remarks:

This function can be used to implement keystroke equivalents for Control-Click operations.

TrackHotSpot()

Purpose:

After down clicking this function tracks the mouse and PointInHotSpot() determines if a point is within a particular hopspot. Movement inside and outside the hotspot is tracked. HotSpotAction() is called to take action during mouse tracking.

Once the mouse is released the location of the event is recorded.

Access:

Virtual, Protected

Prototype:

virtual Boolean TrackHotSpot( SInt16 inHotSpot,

Point inPoint);

This method has the following parameters:

SInt16	inHotSpot	The hotspot number.
Point	inPoint	Local coordinates for the control.

Return:

Boolean true if mouse released inside the hot spot, else false.

mValueMessage

Purpose:

This data member is set using SetValueMessage(). The message is broadcast to all Listeners via BroadcastValueMessage().

Access:

Protected

Prototype:

MessageT mValueMessage;

mValue

Purpose:

Contains the value for the control.

Access:

Protected

Prototype:

SInt32 mValue;

mMinValue

Purpose:

Minimum value for the control.

Access:

Protected

Prototype:

SInt32 mMinValue;

mMaxValue

Purpose:

Maximum value for the control.

Access:

Protected

Prototype:

SInt32 mMaxValue;