MecModInterfaces InstanceFactory (Object)

Represents the CATIAInstanceFactory.
Role: This interface is used to create a new instance of a shape reference ( ) or a hybrid shape reference ( ) in case of the instantiation of a User Feature.
It is also used to instantiate a Power Copy reference.

This interface contains two protocols of instantiation:

The first protocol is dedicated to User Feature instantiation only.
It is defined by a single method: . It creates a shape or hybrid shape instance depending on the result of the User Feature.
Use this method when you want to perform only one instantiation of the reference. Read the document containing the User Feature reference and instantiate it.
As the document containing the reference is released from the session at the end of the instantiation, it is not recommmended to use this method if you want to perform several instantiations of the same reference in a loop.
In that case, prefer the second protocol of instantiation.
The second protocol is dedicated to both User Feature and Power Copy instantiations.
It is defined by several methods that must be called in order.
- For User Feature instantiation, these methods are an alternative way of the method.
  It is recommended to use the second protocol to perform several instantiations of the same reference in a loop.
- For Power Copy instantiation, it is the only way of instantiating a reference.
The instantiation process is composed of three major steps:
1. The first step consists in initializing the with the reference and the document where it is stored.
  This step must be called once at the beginning whatever the number of instantiations are done.
2. Optional step allow the user to specify the mode of the instantiation, that is to say "After" or "Inside".
  If this method is not called, the instantiation mode will be chosen according to the BeginInstantiate method.
3. The second step is the instantiation itself: it is composed of five methods that must be called in the order.
  This set of five methods can be called in a loop in order to make several instantiations.
  1. The method is used to initialize all data of the reference.
  2. The method is used to set a value to any input of the reference.
  3. The method is used to retrieve any parameter of the reference in order to modify its value.
  4. The method is used to duplicate the reference. It returns the created instance when it does exist.
  5. The method is used to indicate that the instantiation is done.
4. The third step consists in ending the instantiation and cleaning the .
  When doing several instantiations in a loop, this step must be called just once at the end of all instantiations.

Method Index
AddInstance	Creates a new instance of a shape or hybrid shape.
BeginInstanceFactory	Initializes the instantiation process with the document containing the reference.
BeginInstantiate	Initializes the data of the reference.
EndInstanceFactory	Ends the instantiation process.
EndInstantiate	Ends the instantiation of the reference.
GetParameter	Retrieves a parameter of the reference by its name.
Instantiate	Instantiates the reference in the current document.
PutInputData	Sets a value to an input of the reference.

Properties

Property InstantiationMode( iInstantiationModeBSTR) (Write Only)

Sets the mode of instantiation to "Inside" or "After".
Role: This method should be called BEFORE the method BeginInstantiate to take into account the desired instantiation mode.
It is used to set the destination path of insertion of the template reference.

Example:

The following example shows how to determine the instantiation mode (Mode's value is "Inside" or "After"):

 InstanceFactory.InstantationMode = Mode

Methods

Func AddInstance( iReference) As

Creates a new instance of a shape or hybrid shape.

Parameters:

iReference: The reference shape or hybrid shape.

Example:

This example creates the instance NewInstance in the part.

 Set NewInstance = instanceFactory.AddInstance(reference)

Sub BeginInstanceFactory( iNameOfReference, iNameOfDocument)

Initializes the instantiation process with the document containing the reference.
Role: Use this method to start instantiating a reference in the current document.
In that method, the document containing the reference is locked in session.
It will be unlocked in the last step .

Parameters:

iNameOfReference: The name of the reference to be instantiated.
iDocumentFileName: The name of the file containing the document where to find the reference to be instantiated.

Example:

The following example initializes the factory with a document and a reference:

 InstanceFactory.BeginInstanceFactory"NameOfReference","c:\tmp\NameOfDocument.CATPart"

Sub BeginInstantiate()

Initializes the data of the reference.
Role: This is the first method of the second step of instantiation.
It is used to initialize all data of the reference in the factory.

Example:

The following example shows how to initialize the factory:

 InstanceFactory.BeginInstantiate

Sub EndInstanceFactory()

Ends the instantiation process.
Role: Use this method to end the instantiation process.
In that method the document containing the reference is unlocked and released from the session.

Example:

The following example shows how to end the instantiation:

 InstanceFactory.EndInstanceFactory

Sub EndInstantiate()

Ends the instantiation of the reference.
Role: This is the fifth and last method of the second step of instantiation.
It is used to end the instantiation: after this step, all the links to the reference are broken.

Example:

The following example shows how to end the instantiation:

 InstanceFactory.EndInstantiate

Func GetParameter( iName) As

Retrieves a parameter of the reference by its name.
Role: This is the third method of the second step of instantiation.
This step is optional.
It is used to retrieve a parameter of the reference in order to change its value, using the ValuateFromString method of the Parameter interface.
It has to be called on each parameter whose value has to be changed.

Parameters:

iName: The name of the parameter.

Example:

The following example retrieves a parameter on the reference:

 Set parameter = InstanceFactory.GetParameter("Parameter1")

Func Instantiate() As

Instantiates the reference in the current document.
Role: This is the fourth method of the second step of instantiation.
It is used to duplicate or instantiate the data of the reference.

In case of Power Copy instantiation, the data are duplicated and there is no created instance.
In case of User Feature instantiation, the data are instantiated and an instance is created and returned.

Example:

The following example instantiates the reference:

 Set Instance = InstanceFactory.Instantiate

Sub PutInputData( iName, iInput)

Sets a value to an input of the reference.
Role: This is the second method of the second step of instantiation.
It is used to set a value to any input of the reference.
It has to be called on each input of the reference.

Parameters:

iName: The name of the input.
iInput: The element to set as the new value of the input.
All types of object are possibly supported.

Example:

The following example sets a value to an input of the reference: The input is a point and its name is Input1.

 InstanceFactory.PutInputData "Input1",point1