LCommander is a PowerPlant class that is used for managing the state of menu items while they are the active target or in the active chain of command.
Methods :
The methods in this class are:
Data Members:
The data members in this class are:
Operation:
A commander may be on or off duty, and has functions to manage the duty state. This is an important concept, because an off-duty commander will not receive or respond to events.
To learn more about Commanders and how to use them with PowerPlant, refer to The PowerPlant Book.
Source files:
Ancestors:
See Also:
LMenuBar
Purpose:
The constructor creates objects from the passed-in parameters.
Access:
Prototype:
LCommander();
LCommander( const LCommander &inOriginal );
LCommander( LCommander *inSuper );Parameters:
The parameters for these constructors are:
Purpose:
The destructor destroys the object.
Access:
Prototype:
virtual ~LCommander();
Purpose:
Adds a subcommander to the commander object.
Access:
Prototype:
virtual void AddSubCommander( LCommander *inSub );Parameters:
The parameter for this method is:
Return:
Purpose:
This method indicates whether removal of subcommanders is allowed.
Access:
Prototype:
virtual Boolean AllowSubRemoval(LCommander* inSub);Parameters:
The parameter for this method is:
Return:
Boolean indicating whether the removal is allowed.
Purpose:
Grant permission to switch the target to the specified Commander.
Both the current target and inNewTarget must be Subordinates of this Commander.
This method passes the request up the command chain by calling AllowTargetSwitch() for its SuperCommander.
Subclasses should override this function if they wish to disallow a target switch under certain circumstances.
Access:
Prototype:
virtual Boolean AllowTargetSwitch(Parameters:
LCommander *inNewTarget);
The parameter for this method is:
Return:
A Boolean indicating whether the target switch was allowed.
Purpose:
This method asks all subcommanders if we can quit.
Access:
Prototype:
virtual Boolean AttemptQuit(Parameters:
long inSaveOption);
The parameter for this method is:
|
Return:
Boolean indicating whether it is valid to quit, false if not.
Purpose:
This is a private method that indicates whether it is valid to quit.
Access:
Prototype:
virtual Boolean AttemptQuitSelf(Parameters:
SInt32 inSaveOption );
The parameter for this method is:
Return:
Boolean indicating whether it is valid to quit, false if not.
Purpose:
This method is called when the Commander is becoming the Target.
Subclasses should override this function if they wish to behave differently when they are and are not the target. At entry, the class variable sTarget points to this command.
Access:
Prototype:
virtual void BeTarget();Parameters:
Return:
Purpose:
This method is called when the commander will no longer be the target.
Subclasses should override this function if they wish to behave differently when they are and are not the target. At entry, the class variable sTarget points to this commander. sTarget will be changed soon afterwards to the new target.
Access:
Prototype:
virtual void DontBeTarget()Parameters:
Return:
Purpose:
This method passes back the status of a command.
Subclasses must override to enable/disable and mark commands. PowerPlant uses the enabling and marking information to set the appearance of Menu items.
Access:
Prototype:
virtual void FindCommandStatus(Parameters:
CommandT inCommand,
Boolean &outEnabled,
Boolean &outUsesMark,
UInt16 &outMark,
Str255 outName);
The parameters for this method are:
Return:
Purpose:
This method returns the value of the sDefaultCommander data member.
Access:
Prototype:
static LCommander* GetDefaultCommander();Parameters:
Return:
Returns the value of sDefaultCommander.
Purpose:
Find the latent subcommander of a Commander. A Commander may have one or no latent subcommander.
Access:
Prototype:
virtual LCommander* GetLatentSub();Parameters:
Return:
Returns the latent subcommander in a pointer to an LCommander.
Purpose:
Return the value of the mSuperCommander data member.
Access:
Prototype:
LCommander* GetSuperCommander();Parameters:
Return:
Returns the value of mSuperCommander.
Purpose:
Return the value of the sTarget data member.
Access:
Prototype:
static LCommander* GetTarget();Parameters:
Return:
Returns the value of sTarget.
Purpose:
Returns the value of sTopCommander data member.
Access:
Prototype:
static LCommander* GetTopCommander();Parameters:
Return:
Returns the value of sTopCommander.
Purpose:
Returns the value of sUpdateCommandStatus data member.
Access:
Prototype:
static Boolean GetUpdateCommandStatus()Parameters:
Return:
Returns the value of sUpdateCommandStatus.
Purpose:
This method processes key presses.
Access:
Prototype:
virtual Boolean HandleKeyPress(Parameters:
const EventRecord &inKeyEvent );
This method has the following parameter:
Return:
Boolean of true if the key press was handled, else false.
Purpose:
Private function for initializing data members from the constructors.
Access:
Prototype:
void InitCommander( LCommander *inSuper );Parameters:
This method has the following parameter:
Return:
Purpose:
Indicate whether this commander is on duty.
Access:
Prototype:
Boolean IsOnDuty() const;Parameters:
Return:
Boolean of true if the command is on duty, else false.
Purpose:
Indicate whether a command is synthetic. If so, pass back the
associated Menu ID and item number. If not synthetic, outMenuID and outMenuItem are undefined.
Access:
Prototype:
static Boolean IsSyntheticCommand(Parameters:
CommandT inCommand,
ResIDT &outMenuID,
SInt16 &outMenuItem);
This method has the following parameters:
Return:
Boolean of true if the command is synthetic, else false.
Remarks:
A synthetic command number has the Menu ID in the high 16 bits and the item number in the low 16 bits, with the result negatated.
syntheticCmd = - (MenuID << 16) - ItemNumber
A synthetic command is the negative of the value returned by the
Toolbox traps MenuSelect() and MenuKey().
The LMenu and LMenuBar classes return synthetic command numbers for menu items whose
actual command number is cmd_UseMenuItem. You should use synthetic command numbers when the menu choice
depends on the runtime name of the menu item. For example, an
item in a Font menu.
Purpose:
Return whether this Commander is the target
Access:
Prototype:
Boolean IsTarget() const;Parameters:
Return:
Return true if the Commander is the target, else false.
Purpose:
Issue a command to a Commander.
Subclasses must override this method in order to respond to commands.
Access:
Prototype:
virtual Boolean ObeyCommand(Parameters:
CommandT inCommand,
void *ioParam );
This method has the following parameters:
Return:
Returns whether the command was handled (true) or not (false).
Purpose:
If an attachment doesn't intercept the msg_PostAction, this function will post the action up to the supercommander
of this object. The default NULL parameter will effectively clear
or "commit" the last semantic action.
If an attachment didn't process the posting and there's no supercommander, this function will attempt to Redo, Finalize, and delete the action.
Access:
Prototype:
virtual void PostAction( LAction *inAction );Parameters:
This method has the following parameter:
Return:
Purpose:
Post the action to the present target. This is a static member function that can be used by anything needing to post an action.
If there is no present target, function will attempt to Redo, Finalize, and delete the action.
Access:
Prototype:
static void PostAnAction( LAction *inAction );Parameters:
This method has the following parameter:
Return:
Purpose:
Issue a command to a Commander.
This function lets Attachments handle the Command before calling the normal ObeyCommand() function.
Access:
Prototype:
virtual Boolean ProcessCommand(Parameters:
CommandT inCommand,
void *ioParam );
This method has the following parameters:
Return:
Returns whether the command was handled (true) or not (false).
Purpose:
Pass back the status of a command. This method lets Attachments set the command status before calling the normal FindCommandStatus() method.
Access:
Prototype:
virtual void ProcessCommandStatus(Parameters:
CommandT inCommand,
Boolean &outEnabled,
Boolean &outUsesMark,
UInt16 &outMark,
Str255 outName );
The parameters for this method are:
Return:
Purpose:
Access:
Prototype:
virtual Boolean ProcessKeyPress(Parameters:
const EventRecord &inKeyEvent );
This method has the following parameter:
Return:
Returns true if handled, else false.
Purpose:
Put on duty a chain of Commanders. This is a wrapper function that guarantees that a Commander can't be put on duty until all its Superiors are on duty.
Access:
Prototype:
void PutChainOnDuty();Parameters:
Return:
Purpose:
Called when a Commander is going on duty. Subclasses should override this function if they wish to behave differently when on duty than when off duty.
Access:
Prototype:
virtual void PutOnDuty();Parameters:
Return:
Purpose:
This method removes a Subcommander.
Access:
Prototype:
virtual void RemoveSubCommander(LCommander *inSub);Parameters:
This method has the following parameter:
Return:
Purpose:
Set target to the Commander which was the target when this Commander was last on duty.
Access:
Prototype:
virtual void RestoreTarget();Parameters:
Return:
Purpose:
Sets the value of the sDefaultCommander data member.
Access:
Prototype:
static void SetDefaultCommander(
LCommander *inCommander ); This method has the following parameter:
Return:
Purpose:
Specify the Subcommander that will be put on duty when this Commander is put on duty.
This method does nothing if this Commander is already on duty.
inSub may be nil, in which case this Commander will have no Latent Subcommander.
This will also be the case if inSub is not a Subordinate of this Commander (which raises a Signal).
Access:
Prototype:
virtual void SetLatentSub( LCommander *inSub );Parameters:
This method has the following parameter:
Return:
Purpose:
Command chain maintenance method.
Access:
Prototype:
virtual void SetSuperCommander(LCommander *inSuper);Parameters:
This method has the following parameter:
Return:
Purpose:
Set the Target class variable. Called internally.
Access:
Prototype:
static void SetTarget( LCommander *inNewTarget );Parameters:
This method has the following parameter:
Return:
Purpose:
This method sets the value of the sUpdateCommandStatus data member.
Access:
Prototype:
static void SetUpdateCommandStatus(Parameters:
Boolean inDirty );
This method has the following parameter:
Return:
Purpose:
Try to change Target and return whether the specified Commander did indeed become the Target.
A Target switch can fail if some superior of the old and new Target disallows the switch. For example, this could happen when performing data entry validation.
Access:
Prototype:
static Boolean SwitchTarget(Parameters:
LCommander *inNewTarget );
This method has the following parameter:
Return:
Boolean indicating whether the switch was allowed (true) or not (false).
Purpose:
Take a chain of Commanders off duty.
This is a wrapper function that traverses a command chain from
the Commander that firsts receives this message up to the specified
Commander. The inUpToCmdr is not taken off duty.
It is an error if inUpToCmdr is not a Superior of the Commander that first receives this message.
Note that this includes the case where inUpToCmdr is the Commander that first receives this message (since a Commander
is not a Superior of itself). nil is a valid value for inUpToCmdr, since the Commander at the top of a chain of command has a nil SuperCommander.
Access:
Prototype:
void TakeChainOffDuty(const LCommander *inUpToCmdr);Parameters:
This method has the following parameter:
Return:
Purpose:
A Commander is going off duty. Subclasses should override this method if they wish to behave differently when on duty than when off duty.
Access:
Prototype:
virtual void TakeOffDuty();Parameters:
Return:
Purpose:
Access:
Prototype:
static LCommander *sTopCommander;
Purpose:
Access:
Prototype:
static LCommander *sTarget;
Purpose:
The default Commander pointer.
Access:
Prototype:
static LCommander *sDefaultCommander;
Purpose:
Indicates whether command status should be updated.
Access:
Prototype:
static Boolean sUpdateCommandStatus;
Purpose:
The pointer to the Supercommander.
Access:
Prototype:
LCommander *mSuperCommander;
Purpose:
An array of pointers to Subcommanders.
Access:
Prototype:
TArray<LCommander*> mSubCommanders;
Purpose:
Indicates whether the Commander is on duty or not.
Access:
Prototype:
ETriState mOnDuty;