All Frameworks Class Hierarchy This Framework Indexes Previous Next

DialogEngine CATStateCommand

Usage: you can derive this class.

public class CATStateCommand

Base class for a State Command.
Role: A State Command is a command modeled as a state machine. It is a graph made of states linked between them using incoming and outgoing transitions. The states are composed of dialog agents which let the end user input the requested parameters. Conditions may be associated with states and transitions in order to guide the progression according to the user inputs. Actions are linked to states and transition to execute the know-how of the command.
To create a State Command, derive the CATStateCommand class and override the methods:

if needed to manage the activation cycle and above all

in order to build the state chart.

Life cycle

In general, a main State Command is allocated by the command header and is deallocated by the internal focus mechanism.
A main State Command ends when:

another exclusive command is activated: the State Command is cancelled by the focus manager.
the NULL state is reached: the State Command cancels itself.
the Cancel state is reached: same as the NULL state, but a global Undo is executed.
the method is called: a good State Command prefers to use transitions towards the NULL state.

Error Management during execution

Exceptions thrown during condition evaluation or action execution must be caught by the condition methods or the action methods.
Nevertheless, if DialogEngine catches one, the main State Command is desactivated while a default error dialog box displays information about the error. Then the main State Command resumes after the error dialog box is closed.

See also:: , , , ,

Constructor and Destructor Index

o CATStateCommand(CATString&,CATDlgEngBehavior,CATCommandMode): Constructs a State Command.
o ~CATStateCommand()

Method Index

o Action(ActionMethod,ActionMethod,ActionMethod,void*): Creates an action given the addresses of the methods to execute.
o AddCSOClient(CATCommand*): Declares an agent as a CSO client.
o AddDialogState(CATDialogState*): Adds an existing state to the command.
o AddDialogState(CATString&): Creates a state.
o AddLocalUndo(CATCommandGlobalUndo*,CATUnicodeString&,CATDlgEngBehavior,CATBoolean): Adds a local Undo step.
o AddSDOElement(CATBaseUnknown*): Sets the object in the CATSDO.
o AddTransition(CATDialogState*,CATDialogState*): Creates a transition given its source and target states.
o AddTransition(CATDialogState*,CATDialogState*,CATDiaAction*): Creates a transition given its source and target states, and its action.
o AddTransition(CATDialogState*,CATDialogState*,CATStateCondition*): Creates a transition given its source and target states, and its condition.
o AddTransition(CATDialogState*,CATDialogState*,CATStateCondition*,CATDiaAction*): Creates a transition given its source and target states, its condition and its action.
o AndAction(CATDiaAction*,CATDiaAction*): Creates a composite action which combines actions using the AND operator.
o AndCondition(CATStateCondition*,CATStateCondition*): Creates a composite condition which combines conditions using the AND operator.
o BuildGraph(): Builds the command statechart.
o Condition(ConditionMethod,void*): Creates a condition given the address of a method to execute.
o ExecuteUndoAtEnd(): Requests to undo the State Command when it ends.
o Filter(FilterMethod,void*): Creates an agent filter given the address of a method to execute.
o ForbidUndo(): Requests to forbid Undo before the next current state.
o GetCancelState(): Creates the cancel state or retrieves it if it already exists.
o GetCurrentState(): Returns the current state.
o GetDefaultCursor(): Gets the customized cursor.
o GetError(): Returns the error caught by DialogEngine during a condition evaluation or an action execution.
o GetGlobalUndo(): Returns the undo/redo object associated with the command.
o GetInitialState(CATString&): Creates the initial state or retrieves it if it already exists.
o GetLastModifiedAgent(): Returns the agent which has just been modified.
o GetLastNotification(): Returns the latest notification.
o GetLongHelpIdKey(CATString&,CATString&): Gets LongHelpId information.
o GetNextState(): Returns the pointed command state and points to the next one.
o GetNextTransition(): Returns the pointed command transition and points to the next one.
o InitStateList(): Points to the first command state.
o InitTransitionList(): Points to the first command transition.
o IsLastModifiedAgent(CATCommand*): Tests if an agent has just been modified.
o IsLastModifiedAgentCondition(CATCommand*,char*): Creates a condition which checks whether an agent is the latest modified agent.
o IsLastModifiedAgentCondition(CATCommand*,CATNotification*): Creates a condition which checks whether an agent is the latest modified agent.
o IsOutputSetCondition(CATCommand*): Creates a condition which checks whether an agent is valued.
o IsRedoMode(): Tests if a redo is being processed.
o NotCondition(CATStateCondition*): Creates a composite condition which uses the NOT operator on its subcondition.
o NotCondition(ConditionMethod,void*): Creates a NOT condition given the address of a method to execute.
o NotifyUndoRedoStackEmptied(): Notifies that the Undo/Redo stack has been emptied as a consequence of an irreversible operation.
o OrAction(CATDiaAction*,CATDiaAction*): Creates a composite action which combines actions using the OR operator.
o OrCondition(CATStateCondition*,CATStateCondition*): Creates a composite condition which combines conditions using the OR operator.
o RemoveState(CATDialogState*): Removes a state from a command.
o RemoveTransition(CATDialogTransition*): Removes a transition from a command.
o RequestDelayedDestruction(): Requests the state command delayed destruction.
o RequestLocalUndo(int,CATBoolean): Requests to undo local steps in the State Command.
o Rescue(): Cleans data if an error occurs.
o ResetDefaultCursor(): Resets the customized cursor.
o SetDebugMode(CATBoolean): Sets the debug mode.
o SetDefaultCursor(CATDialog::CATDlgHCursor): Sets a customized cursor.
o SetErrorCommand(CATCommand*): Sets a specific command to manage errors.
o SetInitialState(CATDialogState*): Declares a state as the initial state.
o _Condition(int,...)
o _Filter(int,...)
o _SetProperty(CATUnicodeString,CATListValCATBaseUnknown_var&)

Constructor and Destructor

o CATStateCommand

public CATStateCommand(	const	`iId`,
		`iBehavior`	`=NULL`,
		`iMode`	`=CATCommandModeExclusive`)

Constructs a State Command.

Parameters:

iId: The command identifier. It must be unique and is used to retrieve the undo/redo titles in the command message file.
iBehavior: The behavior of the command.
iMode: The focus mode.
Legal values: With the default mode CATCommandModeExclusive, the command takes the focus and cancels the other commands. This mode is mandatory if the command modifies the model.
The other possible mode is CATCommandModeShared: the command only deactivates the active command and takes the focus. The previous command will resume when the current command ends.
The CATCommandModeUndefined mode is forbidden with a main State Command since it needs to take the focus, but must be used for a State Command used as an agent of another State Command.

o ~CATStateCommand

public virtual ~CATStateCommand(

)

Methods

o Action

public Action(	`iDo`,
	`iBeforeUndo`	`=NULL`,
	`iBeforeRedo`	`=NULL`,
	`iData`	`=NULL`)

Creates an action given the addresses of the methods to execute.
Role: These methods must be methods of the current state command.

Parameters:

iDo: The method to execute in the normal mode.
iBeforeUndo: The method to undo what has been done in the iDo method. This method is executed before the transaction undo and must not modify transactional objects.
iBeforeRedo: The method to redo what has been done in the iDo method. This method is executed before the transaction redo and must not modify transactional objects.
iData: An object that can be useful for the action. This data will be given as the argument of the ActionMethod methods.
Warning: A copy of iData is kept. Deallocate this object only in the command destructor.

Returns:

The action.
Cyclic reference: A pointer to the action is kept and Released at the end of the command before the command destructor call.
Lifecycle rules deviation: This method doesn't AddRef the returned value.

o AddCSOClient

public AddCSOClient( iPathElementAgent)

Declares an agent as a CSO client.
Role: At the beginning of the command, agents declared as CSO clients will try to get valued with the objects present in the CSO.
If there is only one CSO client, with the CATDlgEngMultiAcquisition behavior, it will decode a CATMultiSel notification gathering all the CSO content.
Else all the objects in the CSO are taken into account separately, one after another. For each object the CSO clients will decode a CATActivate notification. All the objects in the CSO must be used. If at least one object in the CSO does not value any agent, all the valuations from the CSO are then cancelled.
This CSO client mecanism is useful to program object/action commands.
As regards repeating commands, this mechanism only works at the first execution of the command.

Parameters:

iPathElementAgent: The CATPathElementAgent agent to be valued from the CSO.

o AddDialogState

public virtual AddDialogState( iState)

Adds an existing state to the command.
Role: Use this method only with states. Otherwise, use the method which creates and adds the state in the same time.

Parameters:

iState: The state.
Cyclic reference: A copy of iState is kept, and AddRef'ed. It is Released at the end of the command before the command destructor call.

o AddDialogState

public virtual AddDialogState( const iId)

Creates a state.

Parameters:

iId: The resource identifier used to retrieve the state prompt in the command message file.

Returns:

The state.
Cyclic reference: A pointer to the state is kept and Released at the end of the command before the command destructor call.
Lifecycle rules deviation: This method doesn't AddRef the returned value.

o AddLocalUndo

public AddLocalUndo(		`iUndoObject`,
	const	`iUndoTitle`,
		`iUndoBehavior`	`=CATDlgEngWithUndoStep`,
		`iRedoAllowed`	`=FALSE`)

Adds a local Undo step.
Role: This method adds a local step in the Undo stack.
When a transition is executed as a consequence of an explicit acquisition agent valuation (and not as a consequence of a user action) no Undo step is stacked (whatever the agent's behavior). This method enables you to explicitely add a local Undo step.

Parameters:

iUndoObject

The Undo/Redo step manager for this step. No specific Undo/Redo step manager is requested if there is no specific need (Undo/Redo for features is already managed).

iUndoTitle

The title displayed in the Undo history.

iUndoBehavior

The behavior.
Legal values:
CATDlgEngWithUndoStep: The step is displayed in the Undo history (default).
NULL: Reserved for internal usage.

iRedoAllowed

Defines whether the Undo step will be redoable.
Example of usage: When a selection is expected, sometimes the user uses a contextual menu to create an element which will be explicitely got as an input for the selection as soon as it is created. This can be done by explicitely valuating an acquisition agent with the CSO content during resume of the main command. By default, the Undo command then undoes both selection and creation of the element. In order to enable the user to undo the selection without undoing the creation of the element, this method can be used to add a local Undo step.
Example of implementation:

    CATPathElementAgent * curPathAgent = ...; 
    if (curPathAgent)
    {
      // create explicit local undo step
      CATCommandGlobalUndo * GlobalUndo = new CATCommandGlobalUndo;
      if (GlobalUndo)
      {
        AddLocalUndo(GlobalUndo,”MyStep”);
        GlobalUndo -> Release(); GlobalUndo = NULL;
      }
      // value curPathAgent
      curPathAgent -> SetValue(...);
      curPathAgent -> SetValuation();
    }

o AddSDOElement

public AddSDOElement( iObject)

Sets the object in the CATSDO.

Parameters:

iObject: This object is set in the SDO

See also:

o AddTransition

public virtual AddTransition(		`iSource`,
		`iTarget`)

Creates a transition given its source and target states.

Parameters:

iSource: The source state.
Cyclic reference: A copy of iSource is kept and AddRef'ed. It is Released at the end of the command before the command destructor call.
iTarget: The target state.
Cyclic reference: A copy of iTarget is kept and AddRef'ed. It is Released at the end of the command before the command destructor call.
Legal values: The target state may be NULL to represent the end of the command.

Returns:

The transition.
Cyclic reference: A pointer to the transition is kept and Released at the end of the command before the command destructor call.
Lifecycle rules deviation: This method doesn't AddRef the returned value.

o AddTransition

public virtual AddTransition(		`iSource`,
		`iTarget`,
		`iAction`)

Creates a transition given its source and target states, and its action.

Parameters:

iSource: The source state.
Cyclic reference: A copy of iSource is kept and AddRef'ed. It is Released at the end of the command before the command destructor call.
iTarget: The target state.
Cyclic reference: A copy of iTarget is kept and AddRef'ed. It is Released at the end of the command before the command destructor call.
Legal values: The target state may be NULL to represent the end of the command.
iAction: The action.
Legal values: The action may be NULL or specified later by the
Returns:: The transition.
Cyclic reference: A pointer to the transition is kept and Released at the end of the command before the command destructor call.
Lifecycle rules deviation: This method doesn't AddRef the returned value.

o AddTransition

public virtual AddTransition(		`iSource`,
		`iTarget`,
		`iCondition`)

Creates a transition given its source and target states, and its condition.

Parameters:

iSource: The source state.
Cyclic reference: A copy of iSource is kept and AddRef'ed. It is Released at the end of the command before the command destructor call.
iTarget: The target state.
Cyclic reference: A copy of iTarget is kept and AddRef'ed. It is Released at the end of the command before the command destructor call.
Legal values: The target state may be NULL to represent the end of the command.
iCondition: The condition.
Legal values: The condition may be NULL or specified later by the
Returns:: The transition.
Cyclic reference: A pointer to the transition is kept and Released at the end of the command before the command destructor call.
Lifecycle rules deviation: This method doesn't AddRef the returned value.

o AddTransition

public virtual AddTransition(		`iSource`,
		`iTarget`,
		`iCondition`,
		`iAction`)

Creates a transition given its source and target states, its condition and its action.

Parameters:

iSource: The source state.
Cyclic reference: A copy of iSource is kept and AddRef'ed. It is Released at the end of the command before the command destructor call.
iTarget: The target state.
Cyclic reference: A copy of iTarget is kept and AddRef'ed. It is Released at the end of the command before the command destructor call.
Legal values: The target state may be NULL to represent the end of the command.
iCondition: The condition.
Legal values: The condition may be NULL or specified later by the
iAction: The action.
Legal values: The action may be NULL or specified later by the
Returns:: The transition.
Cyclic reference: A pointer to the transition is kept and Released at the end of the command before the command destructor call.
Lifecycle rules deviation: This method doesn't AddRef the returned value.

o AndAction

public AndAction(		`iAct1`,
		`iAct2`)

Creates a composite action which combines actions using the AND operator.
Role: The iAct1 action is executed first. Then the iAct2 action is executed whatever iAct1 returned.

Parameters:

iAct1: The first action to execute.
Cyclic reference: A copy of iAct1 is kept and AddRef'ed. It is Released at the end of the command before the command destructor call.
iAct2: The second action to execute.
Cyclic reference: A copy of iAct2is kept and AddRef'ed. It is Released at the end of the command before the command destructor call.

Returns:

The composite action.
Cyclic reference: A pointer to the action is kept and Released at the end of the command before the command destructor call.
Lifecycle rules deviation: This method doesn't AddRef the returned value.

o AndCondition

public AndCondition(		`iCond1`,
		`iCond2`)

Creates a composite condition which combines conditions using the AND operator.
Role: The AND condition returns TRUE if its subconditions return both TRUE. The iCond1 condition is evaluated first. Then the iCond2 condition is evaluated only if iCond1 returned TRUE.

Parameters:

iCond1: The first condition to evaluate.
Cyclic reference: A copy of iCond1 is kept and AddRef'ed. It is Released at the end of the command before the command destructor call.
iCond2: The second condition to evaluate.
Cyclic reference: A copy of iCond2 is kept and AddRef'ed. It is Released at the end of the command before the command destructor call.

Returns:

The composite condition.
Cyclic reference: A pointer to the condition is kept and Released at the end of the command before the command destructor call.
Lifecycle rules deviation: This method doesn't AddRef the returned value.

o BuildGraph

public virtual BuildGraph(

)

Builds the command statechart.
Role: Override this method to define the command graph.

o Condition

public Condition(		`iEvaluate`,
		`iData`	`=NULL`)

Creates a condition given the address of a method to execute.
Role: This method must be a method of the current State Command.

Parameters:

iEvaluate: The method to execute to evaluate the condition.
iData: An object that can be useful for the condition. This data will be given as the argument of the iEvaluate method.
Warning: A copy of iData is kept. Deallocate this object only in the command destructor.

Returns:

The condition.
Cyclic reference: A pointer to the condition is kept and Released at the end of the command before the command destructor call.
Lifecycle rules deviation: This method doesn't AddRef the returned value.

o ExecuteUndoAtEnd

public ExecuteUndoAtEnd(

)

Requests to undo the State Command when it ends.
Role: This method can be used:

in the method or in the command which is in charge of the error management (defined using the method).
during an action execution.

It requests a global undo at the end of the State Command.
Note: It is recommended to use transitions towards the Cancel state rather than using this method.

o Filter

public Filter(		`iMeth`,
		`iData`)

Creates an agent filter given the address of a method to execute.
Role: This method must be a method of the current State Command.

Parameters:

iMeth: The method to filter the agent value.
iData: An object that can be useful for the filter. This data will be given as the argument of the iMeth method.
Warning: A copy of iData is kept. Deallocate this object only in the command destructor.

Returns:

The filter.
Cyclic reference: A pointer to the filter is kept and Released at the end of the command before the command destructor call.
Lifecycle rules deviation: This method doesn't AddRef the returned value. See also: , and methods.

o ForbidUndo

public ForbidUndo(

)

Requests to forbid Undo before the next current state.
Role: This method can be used:

in the method or in the command which is in charge of the error management (defined using the method).
during an action execution.

It requests an emptying of the Undo stack.

o GetCancelState

public virtual GetCancelState(

)

Creates the cancel state or retrieves it if it already exists.
Role: When the dialog reaches the cancel state, the command ends as if it had reached the NULL state, and a global undo is executed.

Returns:: The cancel state.
Cyclic reference: A pointer to the state is kept and Released at the end of the command before the command destructor call.
Lifecycle rules deviation: This method doesn't AddRef the returned value.

o GetCurrentState

public virtual GetCurrentState(

)

Returns the current state.
Role: In a transition action, the current state is the source state of the transition.

Returns:: The current state.
Lifecycle rules deviation: This method doesn't AddRef the returned value.

o GetDefaultCursor

public GetDefaultCursor(

)

Gets the customized cursor.
Role: This method retrieves the command customized cursor if any.

Returns:: The cursor.

o GetError

public GetError(

)

Returns the error caught by DialogEngine during a condition evaluation or an action execution.
Role: This method can be used in the method or in the command which is in charge of the error management to get information about the error.

Returns:: The error.

o GetGlobalUndo

public virtual GetGlobalUndo(

)

Returns the undo/redo object associated with the command.
Role: This method returns an object with methods to execute when the command is undone or redone.
Example of implementation:

in MyCommand.h:

   protected:
     virtual CATCommandGlobalUndo * GetGlobalUndo ();
     static void UndoMethod (void * iData);
     static void RedoMethod (void * iData);
     static void DeallocateMethod (void * iData);

in MyCommand.cpp:

   //----------------------------------------------------------------------------
   CATCommandGlobalUndo * MyCommand::GetGlobalUndo ()
   {   
     // example of data used in Undo and/or Redo methods
     int * num = new int;
     *num = ...
     void * data = num;
     // define Undo object with Undo, Redoand Deallocate methods
     CATCommandGlobalUndo * Undo = new CATCommandGlobalUndo (
                                          (CATGlobalUndoMethod) &MyCommand::UndoMethod,
                                          (CATGlobalUndoMethod) &MyCommand::RedoMethod,
                                          data,
                                          (CATGlobalUndoMethod) &MyCommand::DeallocateMethod); 
     // return Undo object.
     return Undo;
   }
   //----------------------------------------------------------------------------
   void MyCommand::UndoMethod (void * Data)
   {
     int value = *((int*)Data);
     printf("UndoMethod : value = %d\n",value); fflush(stdout);
     ...
   }
   //----------------------------------------------------------------------------
   void MyCommand::RedoMethod (void * Data)
   {
     int value = *((int*)Data);
     printf("RedoMethod : value = %d\n",value); fflush(stdout);
     ...
   }
   //----------------------------------------------------------------------------
   void MyCommand::DeallocateMethod (void * Data)
   {
     int * pValue = (int*) Data;
     if (pValue) { delete pValue; pValue = NULL; }
   }

Returns:: The undo/redo object.

o GetInitialState

public virtual GetInitialState( const iId)

Creates the initial state or retrieves it if it already exists.
Role: The initial state is the state with which the command starts. There is only one initial state.

Parameters:

iId: The resource identifier used to retrieve the state prompt in the command message file. This identifier is useful only if the initial state doesn't already exist.

Returns:

The initial state.
Cyclic reference: A pointer to the state is kept and Released at the end of the command before the command destructor call.
Lifecycle rules deviation: This method doesn't AddRef the returned value.

o GetLastModifiedAgent

public virtual GetLastModifiedAgent(

)

Returns the agent which has just been modified.

Returns:: The agent.
Lifecycle rules deviation: This method doesn't AddRef the returned value.

o GetLastNotification

public virtual GetLastNotification(

)

Returns the latest notification.
Role: This method only works just after the notification reception. So it cannot be used in undo/redo methods.

Returns:: The notification.

o GetLongHelpIdKey

public virtual GetLongHelpIdKey(		`oKey`,
		`oCatalog`)

Gets LongHelpId information.
Role: Enables contextual help for commands not started through command headers.

Parameters:

oKey: The key.
It must follow the standard LongHelpId syntax to be taken into account in the mapping file.
oCatalog: Name of the resource catalog file, without the .CATRsc suffix.

o GetNextState

public virtual GetNextState(

)

Returns the pointed command state and points to the next one.
Precondition: Set the pointer to the first command state using before traversing out the command state list using calls to GetNextState enclosed in a loop.

Returns:: The pointed state.
Lifecycle rules deviation: This method doesn't AddRef the returned value.

o GetNextTransition

public virtual GetNextTransition(

)

Returns the pointed command transition and points to the next one.
Precondition: Set the pointer to the first command transition using before traversing out the command transition list using calls to GetNextTransition enclosed in a loop.

Returns:: The pointed transition.
Lifecycle rules deviation: This method doesn't AddRef the returned value.

o InitStateList

public virtual InitStateList(

)

Points to the first command state.

See also:

o InitTransitionList

public virtual InitTransitionList(

)

Points to the first command transition.

See also:

o IsLastModifiedAgent

public virtual IsLastModifiedAgent( iAgent)

Tests if an agent has just been modified.

Parameters:

iAgent: The agent.

Returns:

The result of the test.

o IsLastModifiedAgentCondition

public IsLastModifiedAgentCondition(		`iAgent`,
	const	`iNotifClass`)

Creates a condition which checks whether an agent is the latest modified agent.
Role: The condition evaluates TRUE if the iAgent agent has just been modified and if it was due to a notification which belongs to the iNotifClass class.

Parameters:

iAgent: The agent.
iNotifClass: The notification class.
Legal values: It can be NULL: the condition only checks if the iAgent agent has just been modified.

Returns:

o IsLastModifiedAgentCondition

public IsLastModifiedAgentCondition(		`iAgent`,
		`iNotif`	`=NULL`)

Parameters:

iAgent: The agent.
iNotif: The address of a notification.
Legal values: It can be NULL: the condition only checks if the iAgent agent has just been modified.

Returns:

o IsOutputSetCondition

public IsOutputSetCondition( iAgent)

Creates a condition which checks whether an agent is valued.
Role: The condition evaluates TRUE if the iAgent agent is valued.

Parameters:

iAgent: The agent.

Returns:

o IsRedoMode

public virtual IsRedoMode(

)

Tests if a redo is being processed.
Role: It may be useful if a method is used as a Do and a Redo method, to avoid modifying transactional objects in Redo mode.

Returns:: The result of the test.
Legal values:1 in redo mode, 0 in normal or undo mode.

o NotCondition

public NotCondition( iCond)

Creates a composite condition which uses the NOT operator on its subcondition.
Role: The NOT condition returns TRUE if its subcondition returns FALSE.

Parameters:

iCond: The subcondition.
Cyclic reference: A copy of iCond is kept and AddRef'ed. It is Released at the end of the command before the command destructor call.

Returns:

o NotCondition

public NotCondition(		`iEvaluate`,
		`iData`	`=NULL`)

Creates a NOT condition given the address of a method to execute.
Role: This method must be a method of the current State Command.
The condition returns TRUE if the method returns FALSE.

Parameters:

iEvaluate: The method to execute to evaluate the condition. This method gives a result opposite to the condition result.
iData: An object that can be useful for the condition. This data will be given as the argument of the iEvaluate method.
Warning: A copy of iData is kept. Deallocate this object only in the command destructor.

Returns:

o NotifyUndoRedoStackEmptied

public virtual NotifyUndoRedoStackEmptied(

)

Notifies that the Undo/Redo stack has been emptied as a consequence of an irreversible operation.
Role: This method can be overridden to perform any useful task after such an event occurred.

o OrAction

public OrAction(		`iAct1`,
		`iAct2`)

Creates a composite action which combines actions using the OR operator.
Role: The iAct1 action is executed first. Then the iAct2 action is executed only if iAct1 returned TRUE.

Parameters:

iAct1: The first action to execute.
Cyclic reference: A copy of iAct1 is kept and AddRef'ed. It is Released at the end of the command before the command destructor call.
iAct2: The second action to execute.
Cyclic reference: A copy of iAct2 is kept and AddRef'ed. It is Released at the end of the command before the command destructor call.

Returns:

o OrCondition

public OrCondition(		`iCond1`,
		`iCond2`)

Creates a composite condition which combines conditions using the OR operator.
Role: The OR condition returns TRUE if one of its subconditions returns TRUE. The iCond1 condition is evaluated first. Then the iCond2 condition is evaluated only if iCond1 returned FALSE.

Parameters:

iCond1: The first condition to evaluate.
Cyclic reference: A copy of iCond1 is kept and AddRef'ed. It is Released at the end of the command before the command destructor call.
iCond2: The second condition to evaluate.
Cyclic reference: A copy of iCond2 is kept and AddRef'ed. It is Released at the end of the command before the command destructor call.

Returns:

o RemoveState

public virtual RemoveState( iState)

Removes a state from a command.
Role: May be useful if you need to modify a graph inherited from the base class but don't use it dynamically during the dialog.
This state must not be linked to a transition (the transition must be removed first) and must not be the cancel state nor the initial state.

Parameters:

iState: The state to remove.

Returns:

The error return code.
Legal values:

0: the state is removed successfully.
1: the state is not found.
2: the remove operation failed because the state is still useful. (it is the initial or the cancel state or it is linked to a transition.

o RemoveTransition

public virtual RemoveTransition( iTrans)

Removes a transition from a command.
Role: May be useful if you need to modify a graph inherited from the base class but don't use it dynamically during the dialog.

Parameters:

iTrans: The transition to remove.

Returns:

The error return code.
Legal values:

0: the transition is removed successfully.
1: the transition is not found.

o RequestDelayedDestruction

public virtual RequestDelayedDestruction(

)

Requests the state command delayed destruction.
Role: The state command will be destroyed as soon as this will be possible. This must be used only when the state command is used as an agent of another state command, in this state command's destructor. This must not be used inside a state command to stop its execution.

o RequestLocalUndo

public RequestLocalUndo(		`iCount`	`=1`,
		`iRedoAllowed`	`=FALSE`)

Requests to undo local steps in the State Command.
Role: This method can be used:

in the method or in the command which is in charge of the error management (defined using the method).
during an action execution.

It requests to undo local steps at the end of the transition.

Parameters:

iCount: The number of local Undos to execute.
Legal values: from one (default) to the number of local undos possible for the State Command.
iRedoAllowed: Defines whether the Undo steps will be redoable.

o Rescue

public virtual Rescue(

)

Cleans data if an error occurs.
Role: Override this method to clean data after the default error dialog box is closed.
Warning: If the method is used, it is useless to override this method.

o ResetDefaultCursor

public ResetDefaultCursor(

)

Resets the customized cursor.
Role: This method cancels previous uses of .

o SetDebugMode

public SetDebugMode( iMode)

Sets the debug mode.
Role: Activates or desactivates the State Command debug trace mode.
When activated, information about the command and its components is displayed in the standard output at different steps of its life cycle.

Parameters:

iMode: Legal values:
FALSE :The trace mode is not activated.
TRUE :The trace mode is activated.

o SetDefaultCursor

public SetDefaultCursor( iCursor)

Sets a customized cursor.
Role: This method enables to display a cursor different from the standard one.

Parameters:

iCursor: The cursor. Use

o SetErrorCommand

public SetErrorCommand( iCmd)

Sets a specific command to manage errors.
Role: This command replaces the default error dialog box displayed when an exception is caught during a condition evaluation or an action execution.
It must be instantiated with the CATCommandModeUndefined mode in the method of the main State Command, and the error treatment must be done in the overridden method.
When an exception occurs, DialogEngine requires a shared focus for this command and after the error treatment the State Command resumes.

See also:

Parameters:

iCmd: The command.
Warning: A pointer to the error command is kept without being AddRef'ed. Deallocate this command only at the end of the main State Command.

o SetInitialState

public virtual SetInitialState( iState)

Declares a state as the initial state.
Role: May be useful if you need to modify a graph inherited from the base class but don't use it dynamically during the dialog. It replaces the previous initial state but this former state still belongs to the graph.

Parameters:

iState: The new initial state.
Cyclic reference: A copy of iState is kept and AddRef'ed. It is Released at the end of the command before the command destructor call.

o _Condition

protected _Condition(		`iUseless`,
		)

o _Filter

protected _Filter(		`iUseless`,
		)

o _SetProperty

protected virtual _SetProperty(		`iPropertyId`,
	const	`ispPropValue`)

This object is included in the file: CATStateCommand.h
If needed, your Imakefile.mk should include the module: CATDialogEngine

DialogEngine writeClassCharacteristic(); CATStateCommand

Constructor and Destructor Index

Method Index

Constructor and Destructor

Methods

DialogEngine CATStateCommand