All Frameworks Class Hierarchy This Framework Previous Next Indexes
DialogEngine Class CATPathElementAgent
System.IUnknown
|
+---System.IDispatch
|
+---System.CATBaseUnknown
|
+---System.CATEventSubscriber
|
+---System.CATCommand
|
+---DialogEngine.CATDialogAgent
|
+---DialogEngine.CATAcquisitionAgent
|
+---CATPathElementAgent
Usage: you must use this class as is. You should never derive it.
public class CATPathElementAgent
Class representing an agent dedicated to selection.
Role:
A Path element agent is a specific acquisition agent which
retrieves the path of the object under the mouse and stores it
as its value. The selection can be done in 3D/2D viewers or in
specification trees.
The required object can be directly under the mouse or can be in the path of the
object under the mouse. Here is an example to understand the path truncation:
Suppose a Point aggregated by an Open_Body inside a Part document included in a
Product document. The path of the Point is as follows:
Product.1/Part.1/Open_body.2/Point.3
In the specification tree or in 3D you select Point.3; the object under the mouse
is Point.3 but you can require an object of its path: Open_body.2 for example.
Point.3 is the selected object whenever Open_body.2 is the required object.
The object filtering is based on interface implementation. There are two kinds of filtering:
- With an ordered list, thanks to the SetOrderedTypeList method
The interface's order is more important than the object's position in the selected path.
For each interface of the list, a QI is done for all objects of the selected path
(from the leaf to the root), if one object implements the current interface, the process is
ended. The required path is from the root to this object.
- With a non ordered list, thanks to the
AddElementType method
The object's position in the selected path is more important than the interface's
order.
For each object of the selected path (from leaf to root), a QI of all
interfaces is done, if the current object implements one of them, the process is ended.
The required path is from the root to this current object.
In the previous sample, suppose that Point implements the Itf1 interface and Open_body
implements the itf2 interface.
case 1: An ordered list with itf2 then itf1.
The path of the agent is = Product.1/Part.1/Open_body.2/
case 2: A non ordered list with itf2 and itf1.
The path of the agent is = Product.1/Part.1/Open_body.2/Point.3
The
GetValue method returns the path of the required object, in case of mono-selection, whenever the
GetListOfValues method returns the list of required objects in case of multi-selection.
- See also:
- CATPathElement
Constructor and Destructor Index
- o
CATPathElementAgent(CATString&,CATClassId,CATDlgEngBehavior)
- Constructs a path element agent.
- o
~CATPathElementAgent()
-
Method Index
- o
AddElementType(IID&)
- Sets an object type expected by the agent.
- o
GetElementType(int)
- Returns an object type from those expected by the agent
by using the object type index.
- o
GetElementTypeSize()
- Returns the count of object types expected by the agent.
- o
GetElementValue()
- Returns the selected object.
- o
GetListOfValues()
- Returns the agent list of values.
- o
GetModifier()
- Returns whether the shift and control keys have been pushed during
the selection.
- o
GetOrderedTypeList()
- Returns the ordered list of object types expected by the agent.
- o
GetValue()
- Returns the agent value.
- o
ResetNoSelectionCursor()
- Resets the customized "No Selection" cursor.
- o
ResetPreselectionCursor()
- Resets the customized "Preselection" cursor.
- o
SetListOfValues(CATSO*)
- Sets the agent list of values.
- o
SetMessage(CATUnicodeString,CATPathElement*)
- Adds a message to the tooltip displayed over the selected object.
- o
SetNoSelectionCursor(CATDialog::CATDlgHCursor)
- Sets a customized "No Selection" cursor.
- o
SetOrderedTypeList(CATListOfCATString&)
- Sets an ordered list of object types expected by the agent.
- o
SetPreselectionCursor(CATDialog::CATDlgHCursor)
- Sets a customized "Preselection" cursor.
- o
SetValue(CATPathElement*)
- Sets the agent value.
Constructor and Destructor
o CATPathElementAgent
-
Constructs a path element agent.
- Parameters:
-
- iId
- The agent identifier. It is used to retrieve the undo/redo titles in
the command resource file.
- iType
- The type of the expected objects.
The type corresponds to an interface implemented by the object.
If it is NULL, all the objects
are accepted.
You can add interfaces with
AddElementType or you can specified later an ordered list thanks to the
SetOrderedTypeType method.
- 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 facets specific to this agent are :
- Highlight: CATDlgEngWithoutSO (default),
CATDlgEngWithPSO,
CATDlgEngWithHSO,
or CATDlgEngWithPSOHSO.
- HSO manager: CATDlgEngOldHSOManager (default),
or CATDlgEngNewHSOManager.
- Multi acquisition: CATDlgEngMonoAcquisition (default),
CATDlgEngMultiAcquisition,
CATDlgEngMultiAcquisitionCtrl,
CATDlgEngMultiAcquisitionUserCtrl,
CATDlgEngMultiAcquisitionSelModes or
CATDlgEngMultiAcquisitionCtrlNoFeedback.
- Deep acquisition: CATDlgEngWithoutDeepSel (default),
CATDlgEngWithDeepSel,
or CATDlgEngWithDeepFirstSel.
- Truncation: NULL (default),
or CATDlgEngNoSubPath.
- Valuation from CSO: CATDlgEngNotValuedFromCSO (default),
or CATDlgEngValuedFromCSO.
- Valuation mode: CATDlgEngSimpleValuation (default),
CATDlgEngWithPrevaluation,
CATDlgEngWithManipulation,
CATDlgEngWithEdit,
CATDlgEngWithContext,
or CATDlgEngWithDrag.
- Tooltip: CATDlgEngWithoutTooltip (default),
or CATDlgEngWithTooltip.
- User Selection Filter: CATDlgEngWithoutUserSelectionFilter (default),
or CATDlgEngWithUserSelectionFilter.
The behavior may be specified later with the
CATDialogAgent.SetBehavior method.
o ~CATPathElementAgent
public virtual ~CATPathElementAgent( | ) |
-
Methods
o AddElementType
public void AddElementType( | const IID& | iTypeIID) |
-
Sets an object type expected by the agent.
Role: The type corresponds to an interface implemented by the
object.
This method may be used several times: then the expected objects must
implement one of the given interfaces.
However this method cancels any previous use of
SetOrderedTypeList which is an incompatible method.
By using a non-ordered type list, for each object in the selection path
the agent checks whether it adheres to one of the types until it founds one.
- Parameters:
-
- iTypeIID
- It is the identifier of an interface that the expected objects
must implement.
- See also:
- SetOrderedTypeList
o GetElementType
-
Returns an object type from those expected by the agent
by using the object type index.
Role: This method returns the iIndexth object type
from those (ordered or not) expected by the dialog agent,
that is set using the
AddElementType or
SetOrderedTypeList methods.
- Parameters:
-
- iIndex
- The index of the object type .
Legal values: iIndex range starts with 1, which
is the default.
Use
GetElementTypeSize to get the object type count.
o GetElementTypeSize
public int GetElementTypeSize( | ) |
-
Returns the count of object types expected by the agent.
Role: The count of element types ranges from 1 to n
if one or more (ordered or not) types are expected, 0 otherwise.
o GetElementValue
-
Returns the selected object.
Role: The returned value is the required object that is the first
matching the requested type. In otherwords, it is the leaf of the path
returned by the
GetValue method.
Moreover, the returned value depends on the
CATAcquisitionAgent.ValuationState.
Indeed, if the agent valuation state is Valuated, the
GetElementValue method returns the real value; but if the agent
valuation state is PreValuated, the GetElementValue method
returns the prevalue even if the agent has got a value.
- Returns:
- The selected object.
If the behavior of the agent
(
CATDlgEngBehavior ) is not CATDlgEngMonoAcquisition, in other words in case of multi-selection, the
returned value is NULL.
Lifecycle rules deviation: This method doesn't AddRef the
returned value.
o GetListOfValues
public virtual CATSO * GetListOfValues( | ) |
-
Returns the agent list of values.
Role: This method is usable only on MultiAcquisition objects,
otherwise use the
GetValue method.
Moreover, the returned list depends on the
CATAcquisitionAgent.ValuationState.
Indeed, if the agent valuation state is Valuated, the
GetListofValues method returns the real list of values; but if
the agent valuation state is PreValuated, the
GetListOfValues method returns the list of prevalues even if
the agent has got values.
- Returns:
- The list of values.
Lifecycle rules deviation: This method doesn't AddRef the
returned list.
o GetModifier
public virtual int GetModifier( | ) |
-
Returns whether the shift and control keys have been pushed during
the selection.
- Returns:
- The key use.
Legal values: Use the defined values to decode the returned
integer:
- ShiftModifierOn
- ControlModifierOn
e.g.
#include "CATDeviceEvent.h"
...
if (Agent->GetModifier() & ControlModifierOn)
...
o GetOrderedTypeList
-
Returns the ordered list of object types expected by the agent.
- Returns:
- The ordered type list.
- See also:
- SetOrderedTypeList
o GetValue
-
Returns the agent value.
Role: The value is the path of the selected object.
If no type has been specified, the returned path contains all the
objects from the the root object to the selected object. Otherwise, with
a type query, if the selected object is a child of the required object,
the returned path is a subpath, that is a path that begins with the root
object and truncated with the first object matching the requested type.
Moreover, the returned value depends on the
CATAcquisitionAgent.ValuationState.
Indeed, if the agent valuation state is Valuated, the
GetValue method returns the real value; but if the agent
valuation state is PreValuated, the GetValue method
returns the prevalue even if the agent has got a value.
- See also:
- AddElementType, SetOrderedTypeList
- Returns:
- The value.
Lifecycle rules deviation: This method doesn't AddRef the
returned value.
o ResetNoSelectionCursor
public void ResetNoSelectionCursor( | ) |
-
Resets the customized "No Selection" cursor.
Role: This method cancels previous uses of
SetNoSelectionCursor.
o ResetPreselectionCursor
public void ResetPreselectionCursor( | ) |
-
Resets the customized "Preselection" cursor.
Role: This method cancels previous uses of
SetPreselectionCursor.
o SetListOfValues
public virtual void SetListOfValues( | CATSO* | iList) |
-
Sets the agent list of values.
Role: This method is usable only on MultiAcquisition objects,
otherwise use the
SetValue method.
This method does not register an undo step.
Postcondition: Use the
CATAcquisitionAgent.SetValuation method to make the agent accept the value list, otherwise this list is not
taken into account.
- Parameters:
-
- iList
- The list of values.
Cyclic reference: A copy of iList is kept and
AddRef'ed. It is Released in the agent destructor.
o SetMessage
-
Adds a message to the tooltip displayed over the selected object.
Role: This method enables to add a specific message
to the tooltip in addition to the path of the selected object. However, this
method is useless if the behavior of the agent (
CATDlgEngBehavior ) is CATDlgEngWithoutTooltip.
- Parameters:
-
- iMsg
- The message to display
- iPath
- The path object to display.
This is to be used only if the preselection contains several objects.
If it is NULL, the current path under the mouse is displayed.
o SetNoSelectionCursor
public void SetNoSelectionCursor( | CATDialog::CATDlgHCursor | iCursor) |
-
Sets a customized "No Selection" cursor.
Role: This method enables to display a cursor different
from the standard "No Selection" one.
- Parameters:
-
- iCursor
- The cursor.
Use
CATDialog.DefineCursor to define the new cursor.
o SetOrderedTypeList
-
Sets an ordered list of object types expected by the agent.
Role: A type corresponds to an interface implemented by the
object.
This method may give several types: then the expected objects must implement
one of the given interfaces.
Since an agent has only one ordered type list,
successive calls to SetOrderedTypeList for the same agent
successively overwrite the list.
Moreover this method cancels any previous use of
AddElementType which is an incompatible method.
By using an ordered type list, for each type in the list
the agent checks whether an object in the selection path adheres to it
until it founds one.
- Parameters:
-
- iOrderedTypeList
- The ordered type list.
- See also:
- AddElementType
o SetPreselectionCursor
public void SetPreselectionCursor( | CATDialog::CATDlgHCursor | iCursor) |
-
Sets a customized "Preselection" cursor.
Role: This method enables to display a cursor different
from the standard "Preselection" one.
- Parameters:
-
- iCursor
- The cursor.
Use
CATDialog.DefineCursor to define the new cursor.
o SetValue
-
Sets the agent value.
Role: The value is a path object.
This method does not register an undo step.
Postcondition: Use the
CATAcquisitionAgent.SetValuation method to make the agent accept the value, otherwise this value is not
taken into account.
- Parameters:
-
- iValue
- The value.
Cyclic reference: A copy of iValue is kept and
AddRef'ed. It is Released in the agent destructor.
This object is included in the file: CATPathElementAgent.h
If needed, your Imakefile.mk should include the module: CATDialogEngine