LApplication

LApplication is a PowerPlant class that is used for encapsulating the common behaviors of a typical Mac OS application.

Methods :

The methods in this class are:

LApplication()	~LApplication()
CountSubModels()	DoQuit()
FindCommandStatus()	GetPositionOfSubModel()
GetState()	GetSubModelByName()
GetSubModelByPosition()	HandleAppleEvent()
Initialize()	MakeMenuBar()
MakeModelDirector()	MakeSelfSpecifier()
ObeyCommand()	ProcessNextEvent()
Run()	SendAEQuit()
SetSleepTime()	ShowAboutBox()
StartUp()

Data Members:

The data members in this class are:

mState

mSleepTime

Operation:

You create a single object of this class in your application. This object manages the execution of the application program. It handles initialization, destruction, the main event loop, application-level events using LEventDispatcher , Apple Events, updating of the menu bar, cursor adjustment, and printing of documents.

Source files:

(Commander Classes)

LApplication.h

LApplication.cp

See also:

LAttachable

LCommander

LDocApplication

LEventDispatcher

LMenuBar

LApplication()

Purpose:

The constructor initializes parameters such as the default event loop sleep time, Color QuickDraw, and some PowerPlant-specific parameters.

Access:

Public

Prototype:

LApplication();

None

~LApplication()

Purpose:

The destructor destroys the application object.

Access:

Virtual, Public

Prototype:

virtual ~LApplication();

None

CountSubModels()

Purpose:

This method counts the number of windows or documents open in the application.

Access:

Virtual, Public

Prototype:

virtual SInt32 CountSubModels( DescType inModelID 
) const;

The parameter for this method is:

DescType

inModelID

This is a resource descriptor parameter, which you can set to cWindow to count the number of windows open.

Return:

SInt32 indicating the number of open windows (if inModelID == cWindow) or open documents.

DoQuit()

Purpose:

Quit the Application, if the conditions specified by AttemptQuit() in LCommander() are met.

Access:

Virtual, Public

Prototype:

virtual void DoQuit( SInt32 inSaveOption );

The parameter for this method is:

SInt32

inSaveOption

This is a parameter passed on to AttemptQuit() in LCommander().

Return:

None

FindCommandStatus()

Purpose:

Pass back status information on whether a Command is enabled and/or marked in a Menu.

Access:

Virtual, Public

Prototype:

virtual void FindCommandStatus( CommandT 
inCommand,

Boolean &outEnabled,

Boolean &outUsesMark,

USInt16 &outMark,

Str255 outName);

The parameters for this method are:

CommandT	inCommand	This is the command type being passed in.
Boolean	outEnabled	This passed-out value indicates whether the command is enabled.
Boolean	outUsesMark	This passed-out value indicates whether the command has a check mark.
USInt16&	outMark	The character to use as a mark.
Str255	outName	A passed-out string containing the menu command text.

Return:

None

GetPositionOfSubModel()

Purpose:

Return the position (1 means the first) of an Apple Event SubModel within an Application.

Access:

Virtual, Public

Prototype:

virtual SInt32 GetPositionOfSubModel(

DescType inModelID,

const LModelObject *inSubModel) const;

The parameters for this method are:

DescType	inModelID	A resource descriptor that describes the SubModel, or you can set it to cWindow to find the window index using GetMacPort().
const   LModelObject*	inSubModel	This passed-in pointer is the address of the LModeObject to search for.

Return:

SInt32 containing the position of the Apple Event SubModel.

GetState()

Purpose:

This method returns the value of the mState data member.

Access:

Inline, Public

Prototype:

EProgramState GetState() const;

None

Return:

EProgramState containing the value of mState.

GetSubModelByName()

Purpose:

Pass back a token to an Apple Event SubModel specified by name.

Access:

Virtual, Public

Prototype:

virtual void GetSubModelByName( DescType 
inModelID,

Str255 inName,

AEDesc &outToken) const;

The parameters for this method are:

DescType	inModelID	A resource descriptor that describes the SubModel, or you can set it to cWindow to search for a window by name.
Str255	inName	A string pointer containing the name of the SubModel to search for.
AEDesc&	outToken	This passed-out reference is the AEDesc for the specified SubModel.

Return:

None

GetSubModelByPosition()

Purpose:

Get the token of an Apple Event SubModel specified by its position.

Access:

Virtual, Public

Prototype:

virtual void GetSubModelByPosition( 

DescType inModelID,

SInt32 inPosition,

AEDesc &outToken) const;

The parameters for this method are:

DescType	inModelID	This is a resource descriptor parameter that describes the SubModel, or you can set it to cWindow to search for a window by its position.
SInt32	inPosition	The position of the SubModel to retrieve a token for, 1 means first position.
AEDesc&	outToken	This passed-out reference is the AEDesc for the specified SubModel.

Return:

None

HandleAppleEvent()

Purpose:

This method handles the Apple Events that are sent to the application.

Access:

Virtual, Public

Prototype:

virtual void HandleAppleEvent(

const AppleEvent &inAppleEvent,

AppleEvent &outAEReply,

AEDesc &outResult,

long inAENumber);

The parameters for this method are:

const   AppleEvent&	inAppleEvent	This is a reference to the AppleEvent passed-in for the application to handle.
AppleEvent&	outAEReply	This is a reference to the reply received after the AppleEvent.
AEDesc&	outResult	This passed-out reference is the AEDesc for the specified SubModel.
long	inAENumber	This is the passed-in Apple Event number, something like ae_Clone or ae_Move.

Initialize()

Purpose:

Calling this method provides a last chance to initialize the application before event processing begins.

Access:

Virtual, Protected

Prototype:

virtual void Initialize();

None

Return:

None

MakeMenuBar()

Purpose:

Create the MenuBar object for the application. You should override this to use a class other than LMenuBar.

Access:

Protected

Prototype:

virtual void MakeMenuBar();

None

Return:

None

MakeModelDirector()

Purpose:

Create ModelDirector (an AppleEvent handle) object for the application. You should override this if you want to use a class other than LModelDirector.

Access:

Virtual, Protected

Prototype:

virtual void MakeModelDirector();

None

Return:

None

MakeSelfSpecifier()

Purpose:

Make an Object Specifier for the application.

Access:

Virtual, Protected

Prototype:

virtual void MakeSelfSpecifier(

AEDesc& inSuperSpecifier,

AEDesc& outSelfSpecifier) const;

The parameters for this method are:

AEDesc&	inSuperSpecifier	This passed-in reference is an AEDesc, and is not needed in this method implementation.
AEDesc&	outSelfSpecifier	This is the passed-out AEDesc that contains the Object Specifier created.

Return:

None

ObeyCommand()

Purpose:

Process commands that are generated when running the application.

Access:

Virtual, Public

Prototype:

virtual Boolean ObeyCommand( CommandT inCommand,

void *ioParam);

The parameters for this method are:

CommandT	inCommand	This is the command type being passed in.
void*	ioParam	This is a pointer to a data block that accompanies the command.

Return:

A Boolean containing true if the command was handled by this call, and false otherwise.

ProcessNextEvent()

Purpose:

Retrieve and handle the next event in the application event queue. This includes letting Attachments process the event, updating menu item status, and calling Repeaters.

Access:

Virtual, Public

Prototype:

virtual void ProcessNextEvent();

None

Return:

None

Run()

Purpose:

Run the Application by processing events until quitting. This includes doing some menu management, cursor updating, and other housekeeping.

Access:

Virtual, Public

Prototype:

virtual void Run();

None

Return:

None

Remarks:

You should catch all exceptions in your code. If an exception occurs when calling ProcessNextEvent(), a signal will occur and the application will continue running.

SendAEQuit()

Purpose:

Sends a Quit AppleEvent to this application.

Access:

Virtual Public

Prototype:

virtual void SendAEQuit();

None

Return:

None

SetSleepTime()

Purpose:

This method sets the value of the mSleepTime data member.

Access:

Inline, Public

Prototype:

void SetSleepTime( SInt32 inSleepTime);

The parameter for this method is:

SInt32

inSleepTime

This is the value to set for mSleepTime.

Return:

None

ShowAboutBox()

Purpose:

Display the About Box for the application. This basic implementation just puts up an Alert Box. You should override this if you wish to display a more elaborate About Box.

Access:

Virtual, Public

Prototype:

virtual void ShowAboutBox();

None

Return:

None

StartUp()

Purpose:

This method is meant to provide a place to perform actions at application start up when launched without any documents. You should override this if you wish to instead perform some default action, such as creating a new, untitled document.

Access:

Virtual, Protected

Prototype:

virtual void StartUp();

None

Return:

None

mState

Purpose:

This data member contains a value signifying the state of the program, such as programState_StartingUp.

Access:

Protected

Prototype:

EProgramState mState;

mSleepTime

Purpose:

This data member contains the overridable value of the sleep time parameter for the main event loop. This member is set to a default value by the constructor.

Access:

Protected

Prototype:

long mSleepTime;