All Frameworks Class Hierarchy This Framework Indexes Previous Next

DialogEngine 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 method, along with the states they are dedicated to.

See also:: ,

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*,char*): Specifies the user interaction expected by the agent.
o AcceptOnNotify(CATCommand*,CATNotification*): 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*,char*): Cancels the effect of the AcceptOnNotify method.
o IgnoreOnNotify(CATCommand*,CATNotification*): 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 Agent 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

public CATDialogAgent(	const	`iId`,
		`iBehavior`	`=NULL`,
		`iMode`	`=CATCommandModeUndefined`)

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
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

public Accept(		`iNotif`	`=NULL`,
		`iDoNotRegisterUndo`	`=0`)

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 or .
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

public AcceptOnNotify(		`iNotifier`,
	const	`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 AcceptOnNotify

public AcceptOnNotify(		`iNotifier`,
		`iNotif`)

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 AddPanelForNLS

public virtual AddPanelForNLS( 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 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 is a CATDialogAgent

o AfterUndo

public virtual 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 is a CATDialogAgent

o AndFilter

public AndFilter(		`iFilter1`,
		`iFilter2`)

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: method.

o BeforeRedo

public virtual 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 is a CATDialogAgent

o BeforeUndo

public virtual 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 is a CATDialogAgent

o GetBehavior

public virtual 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 definition.

Returns:: The behavior.

o GetEditor

public GetEditor(

)

Returns the editor associated with the command.
Role: Do use this method instead of the 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

public IgnoreOnNotify(		`iNotifier`,
	const	`iNotif`)

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
iNotifClass: The notification class.
Legal values: Must have the same value as in the

o IgnoreOnNotify

public IgnoreOnNotify(		`iNotifier`,
		`iNotif`)

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
iNotif: The notification address.
Legal values: Must have the same value as in the

o InitializeAcquisition

public virtual InitializeAcquisition(

)

Resets an agent to have it reusable.
Role: The agent is no more valued and is able to accept notifications again.

o IsOutputSet

public virtual IsOutputSet(

)

Tests whether the agent is valued.

Returns:: The result of the test.

o NotFilter

public NotFilter( iFilter)

Creates a filter reverse of another one.

Parameters:

iFilter: The genuine filter.

Returns:

o OrFilter

public OrFilter(		`iFilter1`,
		`iFilter2`)

Creates a OR combination of two filters.

Parameters:

iFilter1: The first filter.
iFilter2: The second filter.

Returns:

o RequestDelayedDestruction

public virtual RequestDelayedDestruction(

)

Requests the Agent delayed destruction.
Role: The Agent will be destroyed as soon as this will be possible

o SetBehavior

public virtual SetBehavior( iBehavior)

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 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

public TryValue( iValue)

Tries to value an agent with a given value.
Role: It only works with agents and the value must be a . 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
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

DialogEngine writeClassCharacteristic(); CATDialogAgent

Constructor and Destructor Index

Method Index

Constructor and Destructor

Methods

DialogEngine CATDialogAgent