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

  1. With an ordered list, thanks to the method

    2. 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.
  2. With a non ordered list, thanks to the method

    3. 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 method returns the path of the required object, in case of mono-selection, whenever the method returns the list of required objects in case of multi-selection.

See also:

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 AddElementType(CATClassId)
Sets an object type expected by the agent.
o AddOrderedElementType(CATClassId)
Appends an object type expected by the agent in the ordered type list.
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 RequestDelayedDestruction()
Requests the CATPathElementAgent delayed destruction.
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 SetOrderedElementType(CATClassId)
Resets the list of object types expected by the agent and adds an object type in the ordered type list.
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
public CATPathElementAgent( const iId,
iType=NULL,
iBehavior=NULL)
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
or you can specified later an ordered list thanks to the 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 from genuine or filtered paths: NULL (default), or CATDlgEngCSOAgentValuedFromFilteredPath.
  • 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
method.
o ~CATPathElementAgent
public virtual ~CATPathElementAgent()

Methods


o AddElementType
public AddElementType( const 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 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:
o AddElementType
public AddElementType( iTypeClassId)
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 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:
iTypeClassId
It is the identifier of an interface that the expected objects must implement.
See also:
o AddOrderedElementType
public AddOrderedElementType( iTypeClassId)
Appends an object type expected by the agent in the ordered type list.
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.
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:
iTypeClassId
It is the identifier of an interface that the expected objects must implement.
See also:
,
o GetElementType
public GetElementType( iIndex=1)
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 or methods.
Parameters:
iIndex
The index of the object type .
Legal values: iIndex range starts with 1, which is the default. Use
to get the object type count.
o GetElementTypeSize
public 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
public virtual 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 method.
Moreover, the returned value depends on the . 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 ( ) 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 GetListOfValues()
Returns the agent list of values.
Role: This method is usable only on MultiAcquisition objects, otherwise use the method.
Moreover, the returned list depends on the . 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 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
public GetOrderedTypeList()
Returns the ordered list of object types expected by the agent.
Returns:
The ordered type list.
See also:
o GetValue
public virtual 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 . 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:
,
Returns:
The value.
Lifecycle rules deviation: This method doesn't AddRef the returned value.
o RequestDelayedDestruction
public virtual RequestDelayedDestruction()
Requests the CATPathElementAgent delayed destruction.
Role: The CATPathElementAgent will be destroyed as soon as this will be possible
o ResetNoSelectionCursor
public ResetNoSelectionCursor()
Resets the customized "No Selection" cursor.
Role: This method cancels previous uses of .
o ResetPreselectionCursor
public ResetPreselectionCursor()
Resets the customized "Preselection" cursor.
Role: This method cancels previous uses of .
o SetListOfValues
public virtual SetListOfValues( iList)
Sets the agent list of values.
Role: This method is usable only on MultiAcquisition objects, otherwise use the method.
This method does not register an undo step.
Postcondition: Use the 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
public virtual SetMessage( const iMsg,
const iPath=NULL)
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 ( ) 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 SetNoSelectionCursor( 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
to define the new cursor.
o SetOrderedElementType
public SetOrderedElementType( iTypeClassId)
Resets the list of object types expected by the agent and adds an object type in the ordered type list.
Role: The type corresponds to an interface implemented by the object.
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:
iTypeClassId
It is the identifier of an interface that the expected objects must implement.
See also:
,
o SetOrderedTypeList
public SetOrderedTypeList( const iOrderedTypeList)
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 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:
o SetPreselectionCursor
public SetPreselectionCursor( cursor)
Sets a customized "Preselection" cursor.
Role: This method enables to display a cursor different from the standard "Preselection" one.
Parameters:
iCursor
The cursor. Use
to define the new cursor.
o SetValue
public virtual SetValue( iValue)
Sets the agent value.
Role: The value is a path object.
This method does not register an undo step.
Postcondition: Use the 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

Copyright © 1999-2014, Dassault Systèmes. All rights reserved.