All Frameworks  Class Hierarchy  This Framework  Previous  Indexes

MechanicalCommands Interface CATIUdfInstantiate

System.IUnknown
  |
  +---System.IDispatch
    |
    +---System.CATBaseUnknown
      |
      +---CATIUdfInstantiate
 

Usage: an implementation of this interface is supplied and you must use it as is. You should not reimplement it.


interface CATIUdfInstantiate

Interface to instantiate a template reference.

Role: Interface that enables the instantiation of a template reference.

The template can be a User Feature, a Power Copy, a Document Template, and in that case, they have been created with the CATIUdfFactory interface and defined with the CATIUdfFeature interface.
But it can also be a Machining Process, an Action, or a set of features like an Ordered Geometrical Set, a Body, ...

The instantiation process depends on the reference: it can be based on a Copy/Paste mechanism, or on an Instance/Reference mechanism. Refer to the CAA Encyclopedia article entitled 'An Overview of Power Copies and User Features' for details about the different mechanisms of instantiation in the case of Power Copies and User Features.

However the instantiation process remains identical: you need to call the methods of this interface in the right order:

  1. First Step: Initialization:
    It is the step where you define the destination of instantiation.
    There are two different methods: only one of them should be called depending on what you want to instantiate.
  2. Second Step: Input valuation:
    It is the step where you valuate the inputs, either manually or automatically.
    Use GetOldInputs , GetOldInput , GetNewInput , GetNewInputPathElement to retrieve the inputs values either on the reference or on the instance.
    Use FilterInput , SetNewInput , UseIdenticalName to valuate the inputs.
  3. Third Step: Parameters modification:
    This step is optional: use the GetParameters method to retrieve the published parameters and modify their values.
  4. Fourth Step: Validation:
    It is the step where the reference is instantiated. After the Instantiate method, you can not modify the inputs and parameters values anymore.
  5. Fith Step: Analyse
    This step is optional: use the GetInstantiated method to retrieve the created feature, and SetDisplayName to modify its name.
    To retrieve this name, use GetDisplayName .
  6. Sixth Step: Ending of the instantiation process:
    Use EndInstantiate method to end the instantiation process.
Only the third and fifth steps are optional, while all others are mandatory.
Refer to the CAA Encyclopedia article entitled 'Instantiating a User Feature Reference' for details about the usage of this interface.
See also:
CATIUdfFactory, CATIUdfFeature


Method Index


o EndInstantiate()
Ends the instantiation process.
o FilterInput(int,CATPathElement*,CATPathElement**)
Filters the selection for the valuation of one input of the instance.
o GetDefaultDestinationOfInsertion(CATPathElement*,CATPathElement*&,CATUnicodeString&)
Retrieves the default destination path and its relative position.
o GetDisplayName(CATUnicodeString&)
Retrieves the name of the reference template.
o GetFilterInputMessage(CATUnicodeString&)
Gets an information message explaining the FilterInput failure.
o GetInstantiated(CATBaseUnknown_var)
Retrieves the instantiated feature.
o GetNewInput(int)
Retrieves one input of the instance.
o GetNewInputPathElement(int,CATPathElement*&)
Retrieves the path of one input of the instance.
o GetOldInput(int)
Retrieves one input of the reference template.
o GetOldInputs(CATListValCATBaseUnknown_var*&,CATListOfCATUnicodeString*&)
Retrieves the list of all the inputs of the reference along with their role.
o GetParameters(CATListValCATBaseUnknown_var*&,CATListOfCATUnicodeString*&)
Retrieves the list of all published parameters along with their role.
o Instantiate(CATBaseUnknown_var&)
Validates the instantiation.
o SetDestinationPath(CATPathElement*,CATPathElement*&,CATBaseUnknown_var&)
Sets the destination path for the instantiation.
o SetDestinationPathOfInsertion(CATPathElement*,CATUnicodeString&)
Sets the destination path and position for the instantiation.
o SetDisplayName(CATUnicodeString&)
Sets the name of the instantiated feature.
o SetNewInput(int,CATPathElement*)
Sets one input of the instance at a given position.
o UseIdenticalName(CATBaseUnknown_var)
Valuates automatically all the inputs of the instance.

Methods


o EndInstantiate
public virtual HRESULT EndInstantiate()= 0
Ends the instantiation process.
Role: After this call, the instantiation is ended.
All the links to the reference are broken. In case of User Feature instantiation, you can modify the created instance using the CATIUdfFeatureInstance interface.
Returns:
o FilterInput
public virtual HRESULT FilterInput( const int iPos,
CATPathElement* iSelection,
CATPathElement** oFilteredSelection) = 0
Filters the selection for the valuation of one input of the instance.
Role: This method is called during the selection made by the user to valuate a given input at the iPos position. The filter is done on Replace compliancy. The output of this method is a new CATPathElement, oFilteredSelection, and if this path is not empty it is the new input.
Parameters:
iPos
Input position, from 1 to the size of the list returned by
GetOldInputs
iSelection
A CATPathElement with the new object, this path must contain the full selection path for a valid import mechanism in multidocument context.
oFilteredSelection
A subpath of iSelection containing the authorized feature for the
SetNewInput method.
Returns:
E_FAIL if the selection is not valid for the input valuation, S_OK otherwise.
o GetDefaultDestinationOfInsertion
public virtual HRESULT GetDefaultDestinationOfInsertion(CATPathElement* iPartPath,
CATPathElement*& oDefaultDestinatioPath,
CATUnicodeString& oDefaultRelativePosition) = 0
Retrieves the default destination path and its relative position.
Role: This method is used in combination with SetDestinationPathOfInsertion . Use it to retrieve the default destination feature and the default position of the insertion when it is defined.
For example, in case of mechanical features, the default destination is the current feature. If this feature is a set of features, the relative position is Inside, otherwise it is After.
Parameters:
iPartPath
The complete path of a Part where the instantiated elements will be created.
oDefaultDestinatioPath
The complete path of the default destination feature.
oDefaultRelativePosition
The default destination position.
Returns:
  • S_OK when the default destination path is retrieved.
  • E_FAIL when no default destination is valid. In that case, a CATError is raised, explining why there is no valid destination.
o GetDisplayName
public virtual HRESULT GetDisplayName(CATUnicodeString& iReferenceName) = 0
Retrieves the name of the reference template.
Parameters:
iReferenceName
It is the name of the reference template.
Note that this name is not modifiable even if you use the
SetDisplayName method as this last method applies on the instance and not on the reference.
Returns:
o GetFilterInputMessage
public virtual HRESULT GetFilterInputMessage(CATUnicodeString& oMsg) = 0
Gets an information message explaining the FilterInput failure.
Role: This method is called by standard instantiation command after the call of FilterInput . The goal is to customize the tooltip shown on selection agent to provide more information to the user. This can be used in customized instantiation commands to help the user in the instantiation process.
Parameters:
oMsg
The message that can be used as an help for the end user. In the standard instantiation command, if this message is not empty after the call of this method, the tooltip of the selection agent is modified with it
Returns:
S_OK if the method succeeds, E_FAIL otherwise
o GetInstantiated
public virtual CATBaseUnknown_var GetInstantiated( const CATBaseUnknown_var iFrom) = 0
Retrieves the instantiated feature.
Role: Use this method to retrieve a pointer to the new instance.
You can call this method only after the Instantiate method, and only before the EndInstantiate method.
Use this method only in the case of a User Feature instantiation.
Parameters:
iFrom
This.
Returns:
The instantiated object.
o GetNewInput
public virtual CATBaseUnknown_var GetNewInput( const int iPos) = 0
Retrieves one input of the instance.
Role: Use this method to retrieve the input set by the SetNewInput method or after the UseIdenticalName method.
Parameters:
iPos
Input position, from 1 to the size of the list returned by
GetOldInputs
Returns:
NULL_var if the iPosth input is not valuated otherwise the input of the current instance.
o GetNewInputPathElement
public virtual HRESULT GetNewInputPathElement(int iPos,
CATPathElement*& oPath) = 0
Retrieves the path of one input of the instance.
Role: Use this method to retrieve the path of an input set by the SetNewInput method or after the UseIdenticalName method.
Warning, this path can be different from the one set in the SetNewInput method: for example, the new input can be the result of an import of the given input.
Parameters:
iPos
The input position, from 1 to the size of the list returned by
GetOldInputs
oPath
The returned path element. It has to be released after use if method returs S_OK.
Returns:
E_FAIL if iPos position is outside the authorized range, otherwise S_OK.
o GetOldInput
public virtual CATBaseUnknown_var GetOldInput( const int iPos) = 0
Retrieves one input of the reference template.
Role: Use this method to retrieve the input of the reference template located at the iPos position.
You get the same result when getting the iPosth element of the list given by the GetOldInputs method.
Parameters:
iPos
Input position, from 1 to the size of the list returned by
GetOldInputs
Returns:
The iPosth input feature.
o GetOldInputs
public virtual HRESULT GetOldInputs(CATListValCATBaseUnknown_var*& oOldValues,
CATListOfCATUnicodeString*& oRoleList) = 0
Retrieves the list of all the inputs of the reference along with their role.
Role: Use this method to retrieve the inputs of the reference template along with their role (defined by the CATIUdfFeature.SetInputRole method).
Parameters:
oOldValues
The list of inputs of the reference template.
oRoleList
The list of NLS texts to help the user to better understand the inputs. This list has always the same size as the oOldValues list.
Returns:
S_OK if the inputs are retrieved correctly, E_FAIL if there is a problem while retrieving the inputs.
o GetParameters
public virtual HRESULT GetParameters(CATListValCATBaseUnknown_var*& oParamList,
CATListOfCATUnicodeString*& oRoleList) = 0
Retrieves the list of all published parameters along with their role.
Role: Use this method to retrieve all published parameters in order to change their value. But it is not necessary to modify them.
Parameters:
oParamList
The list of published parameters.
oRoleList
The list of roles dedicated to each published parameter. The list has the same size as oParamList.
o Instantiate
public virtual HRESULT Instantiate( const CATBaseUnknown_var& iDestination) = 0
Validates the instantiation.
Role: The new instance is now created, you can get a pointer to this instance when it exists, using the GetInstantiated method (Indeed, for Power Copy instantiation in One Step mode, no instance is created).
After this call you can not modify its inputs and its parameters anymore.
Parameters:
iDestination
The Part destination of instantiation.
  • For User Feature, there is no need to set a destination. Then the iDestination argument is NULL_var.
  • For Power Copy, the destination is the Part where the instantiation should be done.
    • In case you use the
SetDestinationPath method, it is the first argument of this method if it is a Part, otherwise it is the last argument of the method if the first agument is a Product.
  • In case you use the SetDestinationPathOfInsertion method, it is the Part containing the destination feature of the first argument of this method.
  • Returns:
    E_FAIL if the instantiation fails, S_OK otherwise.
    o SetDestinationPath
    public virtual HRESULT SetDestinationPath(CATPathElement* iPath,
    CATPathElement*& oDestinationPath,
    CATBaseUnknown_var& oDestination) = 0
    Sets the destination path for the instantiation.
    Role: This is the first step of the instantiation process.
    Use this method when you want to instantiate a template reference in a Product context or if you want to instantiate it in a Part context without specifying the location of insertion of the created features.
    If you want to set this location, you should use the other method SetDestinationPathOfInsertion .
    Parameters:
    iPath
    It is the complete path of a Part or a Product where the instantiated elements will be created.
    The created features will be set in the current set of features of the active Part.
    • If iPath represents the path of a Part, this Part is the destination Part.
    • If iPath represents the path of a Product, a new Part may be automatically created depending on the reference.
    oDestinationPath
    • This value is NULL if iPath is the complete path of a Part
    • This value is the complete path of the created Part (when it exists).iPath is then the complete path of a Product.
    The command must UIactivate this new path before modifying the inputs, this is mandatory to create links between documents (Reference Elements in the Part).
    oDestination
    • This value is NULL_var if iPath is the complete path of a Part.
    • This Value is the pointer of the created Part (when it exists). iPath is then complete path of a Product.
    o SetDestinationPathOfInsertion
    public virtual HRESULT SetDestinationPathOfInsertion(CATPathElement* iPathOfInsertion,
    const CATUnicodeString& iRelativePosition) = 0
    Sets the destination path and position for the instantiation.
    Role: This is the first step of the instantiation process.
    Use this method when you want to instantiate a template reference in a Part context and specify the location of insertion of the created features.
    If you do not need to specify the location of insertion, or if you want to instantiate the template reference in a Product context, you should use the other SetDestinationPath method.
    Parameters:
    iPathOfInsertion
    The complete path of the feature where you want to insert the result of the instantiation.
    • If this destination feature is a set of features (like a Geometrical Set, a Body, ...), the instantiation is done either inside or after it, depending on the iRelativePosition argument.
    • Otherwise if the destination feature is not a set of features, the instantiation is done after it and the iRelativePosition is imperatively positioned on After.
    iRelativePosition
    The position of insertion relatively to the destination feature.
    For mechanical features, it is either After or Inside, depending on the destination feature.
    Returns:
    • S_OK when the destination of insertion is valid.
    • E_FAIL when the destination of insertion is not valid. An error message is then raised with a CATError.
      It is the case for example when you set a Body as destination of insertion of a Power Copy that contains a Geometrical Set and you use the Inside position. As a Geometrical Set can not be inserted inside a Body, the method returns E_FAIL and an error message explaining why the destination is not possible is raised.
    o SetDisplayName
    public virtual HRESULT SetDisplayName( const CATUnicodeString& iName) = 0
    Sets the name of the instantiated feature.
    Role: Use this method to modify the name of the instance in the case of a User Feature instantiation.
    The default name is the name of the User Feature reference followed by a number. This name is returned by GetDisplayName .
    This method is available only if the reference object is a single object (not available for PowerCopy with multiple features for example).
    Parameters:
    iName
    The new name of the instance.
    Returns:
    S_OK
    o SetNewInput
    public virtual HRESULT SetNewInput( const int iPos,
    CATPathElement* iSelection) = 0
    Sets one input of the instance at a given position.
    Role: Use this method to valuate the input located at the iPos position of the instance.
    Parameters:
    iPos
    Input position, from 1 to the size of the list returned by
    GetOldInputs
    iSelection
    A CATPathElement with the object. This path must contain the full selection path for a valid import mechanism in multidocument context.
    Returns:
    E_FAIL if the valuation fails, S_OK otherwise.
    o UseIdenticalName
    public virtual HRESULT UseIdenticalName( const CATBaseUnknown_var iRoot) = 0
    Valuates automatically all the inputs of the instance.
    Role: This method tries to find a feature for each input, looking for features having the same CATIAlias name than the role of the input.
    After this method, some inputs may be still unvaluated. Test the valuation with the GetNewInput method.
    Parameters:
    iRoot
    The location where to search for the inputs.
    Returns:
    E_FAIL if the iRoot argument is not valid, S_OK otherwise.

    This object is included in the file: CATIUdfInstantiate.h
    If needed, your Imakefile.mk should include the module: CATUdfInterfaces

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