All Frameworks Class Hierarchy This Framework Previous Next Indexes
DialogEngine Class CATDialogAgent
System.IUnknown
|
+---System.IDispatch
|
+---System.CATBaseUnknown
|
+---System.CATEventSubscriber
|
+---System.CATCommand
|
+---CATDialogAgent
Usage: you must use this class as is. You should never derive it.
public class CATDialogAgent
Base class for a state command agent.
Role: A dialog agent translates a user interaction into a user
input. It is created to match a given end user interaction and is valued
when the end user performs the interaction. It is associated with one
or possibly several states. Its valuation triggers the evaluation
of the state exit condition and, then, of the transition guard conditions
if the state condition returns TRUE.
An end user interaction is always defined using a notification whose
type reflects the interaction, and a notifier, that is, the object that
sends the notification.
A basic dialog agent is valued when both notification and notifier match
the dialog agent's required ones.
Agents must be created in the CATStateCommand.BuildGraph method, along with the states they are dedicated to.
- See also:
- CATDialogState, CATStateCommand
Constructor and Destructor Index
- o
CATDialogAgent(CATString&,CATDlgEngBehavior,CATCommandMode)
- Constructs a dialog agent.
Method Index
- o
Accept(CATNotification*,int)
- Values an agent dynamically.
- o
AcceptOnNotify(CATCommand*,CATNotification*)
- Specifies the user interaction expected by the agent.
- o
AcceptOnNotify(CATCommand*,char*)
- Specifies the user interaction expected by the agent.
- o
AddPanelForNLS(CATDialog*)
- Declares that the command shares its resource file with a dialog.
- o
AfterRedo()
- After an agent's redo.
- o
AfterUndo()
- After an agent's undo.
- o
AndFilter(CATAcquisitionFilter*,CATAcquisitionFilter*)
- Creates a AND combination of two filters.
- o
BeforeRedo()
- Before an agent's redo.
- o
BeforeUndo()
- Before an agent's undo.
- o
GetBehavior()
- Returns the agent behavior.
- o
GetEditor()
- Returns the editor associated with the command.
- o
IgnoreOnNotify(CATCommand*,CATNotification*)
- Cancels the effect of the AcceptOnNotify method.
- o
IgnoreOnNotify(CATCommand*,char*)
- Cancels the effect of the AcceptOnNotify method.
- o
InitializeAcquisition()
- Resets an agent to have it reusable.
- o
IsOutputSet()
- Tests whether the agent is valued.
- o
NotFilter(CATAcquisitionFilter*)
- Creates a filter reverse of another one.
- o
OrFilter(CATAcquisitionFilter*,CATAcquisitionFilter*)
- Creates a OR combination of two filters.
- o
RequestDelayedDestruction()
- Requests the command delayed destruction.
- o
SetBehavior(CATDlgEngBehavior)
- Sets the agent behavior.
- o
TryValue(CATBaseUnknown*)
- Tries to value an agent with a given value.
Constructor and Destructor
o CATDialogAgent
-
Constructs a dialog agent.
- Parameters:
-
- iId
- The agent identifier. It is used to retrieve the undo/redo titles in
the command message file.
- iBehavior
- The behavior of the agent.
Legal values: The behavior is given in the form of a
concatenation of the facet values using the | character.
e.g.: CATDlgEngRepeat|CATDlgEngActive
If it is NULL, the agent has the default behavior value for each
facet.
The behavior may be specified later with the
SetBehavior method.
- iMode
- The focus mode.
Legal values: Must always be
CATCommandModeUndefined.
The focus of an agent is managed by the state command it belongs to.
Methods
o Accept
-
Values an agent dynamically.
Role: When using this method on an agent, the agent becomes
valued immediately as if it had received an expected notification.
Moreover, this method enables to specify a notification which can be
considered as the valuating notification by methods like
CATStateCommand.GetLastNotification or
CATStateCommand.IsLastModifiedAgentCondition.
However, this method doesn't register an undo step.
- Parameters:
-
- iNotif
- The notification to consider as the valuing notification
Legal values: The notifier may be NULL. It is an optional
parameter.
- iDoNotRegisterUndo
- Internal argument. Do not use it.
Legal values: Its default value must always be used.
o AcceptOnNotify
-
Specifies the user interaction expected by the agent.
Role: The agent becomes valued when it receives a notification
which belongs to the iNotif notification class from the
iNotifier notifier.
- Parameters:
-
- iNotifier
- The notifier.
Legal values: The notifier may be NULL: the reception of the
notification is sufficient to value the agent whatever the notifier.
- iNotif
- The notification address.
The agent checks whether the received notifications belong to the
same class as the iNotif notification. So, only the
notification class matters.
Legal values: It can be NULL: any notification sent by the
iNotifier notifier values the agent.
o AcceptOnNotify
public void AcceptOnNotify( | CATCommand* | iNotifier, |
| const char* | iNotifClass) |
-
Specifies the user interaction expected by the agent.
Role: The agent becomes valued when it receives a notification
which belongs to the iNotifClass class from the iNotifier
notifier.
- Parameters:
-
- iNotifier
- The notifier.
Legal values: The notifier may be NULL: the reception of the
notification is sufficient to value the agent whatever the notifier.
- iNotifClass
- The notification class.
Legal values: It can be NULL: any notification sent by the
iNotifier notifier values the agent.
o AddPanelForNLS
public virtual void AddPanelForNLS( | CATDialog* | iDialog) |
-
Declares that the command shares its resource file with a dialog.
Role: The resources of the iDialog dialog are written
in the command resource file and their research keys are prefixed with
the command research key.
- Parameters:
-
- iDialog
- The dialog.
o AfterRedo
public virtual void AfterRedo( | ) |
-
After an agent's redo.
Role:
This method is executed after the transaction redo and must not
modify transactional objects.
Method to overwrite, if necessary, if your
CATStateCommand is a CATDialogAgent
o AfterUndo
public virtual void AfterUndo( | ) |
-
After an agent's undo.
Role:
This method is executed after the transaction undo and must not
modify transactional objects.
Method to overwrite, if necessary, if your
CATStateCommand is a CATDialogAgent
o AndFilter
-
Creates a AND combination of two filters.
- Parameters:
-
- iFilter1
- The first filter.
- iFilter2
- The second filter.
- Returns:
- The resulting 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:
CATStateCommand.Filter method.
o BeforeRedo
public virtual void BeforeRedo( | ) |
-
Before an agent's redo.
Role:
This method is executed before the transaction redo and must not
modify transactional objects.
Method to overwrite, if necessary, if your
CATStateCommand is a CATDialogAgent
o BeforeUndo
public virtual void BeforeUndo( | ) |
-
Before an agent's undo.
Role:
This method is executed before the transaction undo and must not
modify transactional objects.
Method to overwrite, if necessary, if your
CATStateCommand is a CATDialogAgent
o GetBehavior
-
Returns the agent behavior.
Role: A behavior is made of behavioral facets that can be each
set to a given value. These facets are listed in the
CATDlgEngBehavior definition.
- Returns:
- The behavior.
o GetEditor
-
Returns the editor associated with the command.
Role: Do use this method instead of the
CATFrmEditor.GetCurrentEditor method which gives the current editor which
may be the editor of another document, during a Drag&Drop for example.
- Returns:
- The editor.
o IgnoreOnNotify
-
Cancels the effect of the AcceptOnNotify method.
Role: The agent won't be valued anymore when receiving a
notification which belongs to the iNotif notification class
from the iNotifier notifier.
- Parameters:
-
- iNotifier
- The notifier.
Legal values: Must have the same value as in the
AcceptOnNotify method to cancel.
- iNotif
- The notification address.
Legal values: Must have the same value as in the
AcceptOnNotify method to cancel.
o IgnoreOnNotify
public void IgnoreOnNotify( | CATCommand* | iNotifier, |
| const char* | iNotifClass) |
-
Cancels the effect of the AcceptOnNotify method.
Role: The agent won't be valued anymore when receiving a
notification which belongs to the iNotifClass class
from the iNotifier notifier.
- Parameters:
-
- iNotifier
- The notifier.
Legal values: Must have the same value as in the
AcceptOnNotify method to cancel.
- iNotifClass
- The notification class.
Legal values: Must have the same value as in the
AcceptOnNotify method to cancel.
o InitializeAcquisition
public virtual void InitializeAcquisition( | ) |
-
Resets an agent to have it reusable.
Role: The agent is no more valued and is able to accept
notifications again.
o IsOutputSet
-
Tests whether the agent is valued.
- Returns:
- The result of the test.
o NotFilter
-
Creates a filter reverse of another one.
- Parameters:
-
- iFilter
- The genuine filter.
- Returns:
- The resulting 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:
CATStateCommand.Filter method.
o OrFilter
-
Creates a OR combination of two filters.
- Parameters:
-
- iFilter1
- The first filter.
- iFilter2
- The second filter.
- Returns:
- The resulting 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:
CATStateCommand.Filter method.
o RequestDelayedDestruction
public virtual void RequestDelayedDestruction( | ) |
-
Requests the command delayed destruction.
Role: The command will ve destroyed as soon as this will be possible
o SetBehavior
-
Sets the agent behavior.
Role: A behavior is made of behavioral facets that can be each
set to a given value. These facets are listed in the
CATDlgEngBehavior definition.
- Parameters:
-
- iBehavior
- The behavior.
Legal values: The behavior is given in the form of a
concatenation of the facet values using the | character.
e.g.: CATDlgEngRepeat|CATDlgEngActive
o TryValue
-
Tries to value an agent with a given value.
Role: It only works with
CATPathElementAgent agents and the value must be a
CATPathElement. The Path Element is tested as if the object it represents had been selected
by the end user. If the object dosen't have the expected type, the agent
is not valued and the method returns FALSE.
- Parameters:
-
- iValue
- The value.
Legal values: Must be a
CATPathElement.
- Returns:
- The result of the valuation.
This object is included in the file: CATDialogAgent.h
If needed, your Imakefile.mk should include the module: CATDialogEngine