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:
- 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.
-
SetDestinationPath :
This method should be called when you want to instantiate the reference template:
- in a Product context: where a new Part may be created on the fly.
- in a Part context, when you do not need to indicate the location of insertion of the created objects.
-
SetDestinationPathOfInsertion :
This method should be called when you want to instantiate the reference template in a Part context and indicate
the location of insertion of the created objects.
You can retrieve the default destination using the
GetDefaultDestinationOfInsertion method.
- 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. - Third Step: Parameters modification:
This step is optional: use the
GetParameters method to retrieve the published parameters and modify their values. - 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. - 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 . - 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
-
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
-
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
-
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
-
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
-
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
-
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
-
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
-
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
-
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
-
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
-
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.
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
-
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
-
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
-
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
-
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
-
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