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:

  1. With an ordered list, thanks to the SetOrderedTypeList 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.
  3. With a non ordered list, thanks to the AddElementType method

  4. 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
public CATPathElementAgent( const CATString& iId,
CATClassId iType=NULL,
CATDlgEngBehavior 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
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
public CATClassId GetElementType(int 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 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
public virtual CATBaseUnknown * 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
public CATListOfCATString & GetOrderedTypeList()const
Returns the ordered list of object types expected by the agent.
Returns:
The ordered type list.
See also:
SetOrderedTypeList
o GetValue
public virtual CATPathElement * 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
public virtual void SetMessage( const CATUnicodeString iMsg,
const CATPathElement* 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 ( 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
public void SetOrderedTypeList( const CATListOfCATString& 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 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
public virtual void SetValue(CATPathElement* iValue)
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

Copyright © 2003, Dassault Systèmes. All rights reserved.