All Frameworks Class Hierarchy This Framework Indexes Previous Next

CATRepTemplateUseItf Interface 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.
The template has been retrieved with .

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.
- :
  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.
- :
  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 method.
Second Step: Input valuation:
It is the step where you valuate the inputs, either manually or automatically.
Use , , , to retrieve the inputs values either on the reference or on the instance.
Use , , to valuate the inputs.
Third Step: Parameters modification:
This step is optional: use the method to retrieve the published parameters and modify their values.
Fourth Step: Validation:
It is the step where the reference is instantiated. After the method, you can not modify the inputs and parameters values anymore.
Fith Step: Analyse
This step is optional: use the method to retrieve the created feature, and to modify its name.
To retrieve this name, use .
Sixth Step: Ending of the instantiation process:
Use method to end the instantiation process.
Seventh Step: Reset once the instantiation process is fully completed:
Use method to clean up data when instantiation is terminated.

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:

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 GetComponentsToSet(CATListValCATBaseUnknown_var*&,CATListValCATBaseUnknown_var*&): Retrieves the components to be set during Instantiation.
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 Reset(): This method has to be called at the end of the instantiation.
o SetComponents(): Sets the components as specified through the lists given by the GetComponentsToSet method.
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 EndInstantiate(

)

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 interface.

Returns:

o FilterInput

public virtual FilterInput(	const	`iPos`,
		`iSelection`,
		`oFilteredSelection`)

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
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
Returns:: E_FAIL if the selection is not valid for the input valuation, S_OK otherwise.

o GetComponentsToSet

public virtual GetComponentsToSet(		`oOriginalComponents`,
		`oNewComponents`)

Retrieves the components to be set during Instantiation.

Parameters:

oOriginalComponents: The components that can be replaced during instantiation as they appeared in the original context. Note that this list should not be modified.
oNewComponents: The components that will replace the original ones in the new context. The content of this list can be modified.

Returns:

E_FAIL if the lists were not filled properly, S_OK otherwise.

o GetDefaultDestinationOfInsertion

public virtual GetDefaultDestinationOfInsertion(		`iPartPath`,
		`oDefaultDestinatioPath`,
		`oDefaultRelativePosition`)

Retrieves the default destination path and its relative position.
Role: This method is used in combination with . 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#Release: 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 GetDisplayName( iReferenceName)

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

o GetFilterInputMessage

public virtual GetFilterInputMessage( oMsg)

Gets an information message explaining the FilterInput failure.
Role: This method is called by standard instantiation command after the call of . 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 GetInstantiated( const iFrom)

Retrieves the instantiated feature.
Role: Use this method to retrieve a pointer to the new instance.
You can call this method only after the method, and only before the method.
Use this method only in the case of a User Feature instantiation.

Parameters:

iFrom: This.

Returns:

The instantiated object.

o GetNewInput

public virtual GetNewInput( const iPos)

Retrieves one input of the instance.
Role: Use this method to retrieve the input set by the method or after the method.

Parameters:

iPos: Input position, from 1 to the size of the list returned by
Returns:: NULL_var if the iPosth input is not valuated otherwise the input of the current instance.

o GetNewInputPathElement

public virtual GetNewInputPathElement(		`iPos`,
		`oPath`)

Retrieves the path of one input of the instance.
Role: Use this method to retrieve the path of an input set by the method or after the method.
Warning, this path can be different from the one set in the 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
oPath#Release: 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 GetOldInput( const iPos)

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 method.

Parameters:

iPos: Input position, from 1 to the size of the list returned by
Returns:: The iPosth input feature.

o GetOldInputs

public virtual GetOldInputs(		`oOldValues`,
		`oRoleList`)

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.

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 GetParameters(		`oParamList`,
		`oRoleList`)

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.

Returns:

classic HRESULT

o Instantiate

public virtual Instantiate( const iDestination)

Validates the instantiation.
Role: The new instance is now created, you can get a pointer to this instance when it exists, using the 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

In case you use the 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 Reset

public virtual Reset(

)

This method has to be called at the end of the instantiation.
Role: It cleans memory, resets the template so that it can be re-instantiated. Its call is mandatory for Document Templates instantiation.

Returns:: S_OK

o SetComponents

public virtual SetComponents(

)

Sets the components as specified through the lists given by the GetComponentsToSet method. The original components will be replaced by the new components.

Returns:: E_FAIL if the replace failed, S_OK otherwise.

o SetDestinationPath

public virtual SetDestinationPath(		`iPath`,
		`oDestinationPath`,
		`oDestination`)

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 .

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.

Returns:

classic HRESULT

o SetDestinationPathOfInsertion

public virtual SetDestinationPathOfInsertion(		`iPathOfInsertion`,
	const	`iRelativePosition`)

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 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 SetDisplayName( const iName)

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 .
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 SetNewInput(	const	`iPos`,
		`iSelection`)

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
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 UseIdenticalName( const iRoot)

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 name than the role of the input.
After this method, some inputs may be still unvaluated. Test the valuation with the 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: CATRepTemplateUseItf