Mechanical Modeler

Freezing or Unfreezing Internal Copy

 Using CATIMmiResultFreezer

Use Case

Abstract

The Use Case is an Interactive State Command to switch the Freeze state of  an Internal Copy with Link [1]. An Internal Copy is a feature copied "As result with Link" within a Part Document. It can be frozen while a feature copied across Part Document (External Reference) cannot be frozen.

The default state of an Internal Copy is Unfrozen. This implies any modification in the geometry of the source feature, is updated in the copied feature, as well, thanks to an Update mechanism which automatically handles this synchronization. When an Internal Copy is frozen, its link to its source feature is deactivated. So the geometry of the copied feature is not recomputed each time its source is modified.

The Use Case accomplishes this by deploying a State Command [2] located in the "Spec Tree" toolbar, a Part Workshop Add-in [3] within CATIA.


What You Will Learn With This Use Case

The Use Case illustrates the capabilities of the CATIMmiResultFreeze APIs, primarily to:

[Top]

The CAAMmrFreezeInternalCopy Use Case

CAAMmrFreezeInternalCopy is a use case of the CAAMechanicalModeler.edu framework that mainly illustrates MecModInterfaces frameworks capabilities. 

[Top]

What Does CAAMmrFreezeInternalCopy Do

This Use Case is an Interactive Exclusive State Command which switches the Freeze status (Freeze/Unfreeze) of a feature copied within a Part document, with Link (an Internal Copy). To begin with the Use Case integrates a Freeze/Unfreeze State Command, viewed as , in the     "Spec Tree" toolbar, a Part Workshop Add-in within CATIA, as depicted below. [Fig. 1].

Fig.1 "Spec Tree" Toolbar, a Part Workshop Add-in

We illustrate the execution of this Use Case, on an input model, as the one seen below [Fig. 2]. This Part document (*) contains a Geometrical Set.1 consisting of Point.1, and its copy "As Result with Link",  Point.2. Both points occur at the Origin, as [Fig. 2] depicts. The icon that appears alongside Point.2 in the spec tree implies that a link exists to the source feature Point.1.

Fig. 2 Input Model

 

On activating the State Command, the first state prompts an end-user to select an Internal Copy with Link in the model hierarchy. The selection is restricted to only those entities, implementing the CATIMmiResultFreeze. On selection, application continues to prompt the user for the same selection, owing to an incoming transition to the same state.

To begin with, Point.2 is in an Unfrozen state, a default state wherein the position/geometry of the copied feature (Point.2) is in sync with the original feature (Point.1), since the link between the two is active.

As the [Fig. 3] depicts, Point.1 was relocated at a distance of 100mm along the X-axis. Position of Point.2 is instantly updated to this new position. Both points are coincident, at the new location, as [Fig. 3] indicates.

Fig.3 Behavior of Point.2 (Internal Copy) while in Unfrozen (Default) State

At this stage, we launch the State Command . It prompts the user to select an Internal Copy in the spec tree, to freeze its state. As soon as Point.2 is selected, the icon   appears alongside it, in the model hierarchy [Fig. 4]. Now if the source feature Point.1 is relocated, say at a distance of 150mm along the X-axis, Point.2 remains frozen at its original location. This is owing to the fact that the link between the two has been temporarily deactivated.

Fig.4 Behavior of Point.2 (Internal Copy) while in Frozen State

The last step is to unfreeze Point.2, yet again through the state command . The icon reappears alongside Point.2, in the model hierarchy, as soon as it switches to an unfrozen (default) state. The link between the copied and the source feature is restored, thus enabling the Update mechanism to synchronize the geometry/positions of the source and copied geometries.

[Fig.5] depicts thus Update. You'll find Point.2 also gets relocated at 150mm from Origin, thus coinciding with Point.1.

Fig. 5 Position of Point.2 updated on being Unfrozen

[Top]

How to Launch CAAMmrFreezeInternalCopy

To launch CAAMmrFreezeInternalCopy, you will need to set up the build time environment, then compile CAAMmrFreezeInternalCopy along with its prerequisites, set up the run time environment, and then execute the use case [4].

Launch CATIA, when the application is ready:

The Use Case is now ready for further execution further explained in the [What does the UC do] section.

(*) The CAAMmrFreezeInternalCopy.CATPart document is delivered in the InputData directory of the CAAMechanicalModeler.edu fw.

[Top]

Addin Access

The  Spec Tree  Add-In to the Product Workshop within CATIA, is available thanks to a data extension of the CAAMmrPartWksAddin component.  This necessitates the following entries uncommented in the CAAMechanicalModeler.edu.dico file.

...
#CAAMmrPartWksAddin CATIWorkbenchAddin libCAAMmrPartWksAddin
#CAAMmrPartWksAddin CATIPrtWksAddin libCAAMmrPartWksAddin
...

The dico file entries imply that the Add-in implements CATIPrsWksAddin. It also implements CATIWorkbenchAddin, owing to the fact that it is a data extension of CAAMmrPartWksAddin.

[Top]

Where to Find the CAAMmrFreezeInternalCopy Code

The CAAMmrFreezeInternalCopy use case is made of a Class defined in the CAAMmrFreezeInternalCopy.m module of the CAAMechanicalModeler.edu framework:

InstallRootDirectory\CAAMechanicalModeler.edu\CAAMmrFreezeInternalCopy.m\

The use case pre-reqs an Add-in module too:

InstallRootDirectory\CAAMechanicalModeler.edu\CAAMmrPartWksAddin.m\

where InstallRootDirectory [4] is the directory where the CAA CD-ROM is installed.

[Top]

Step-by-Step

The steps in the CAAMmrFreezeInternalCopy use case are

  1. Building the StateCommand and Integrating it within CATIA
  2. Implementing the Callback to an Incoming Transition associated with this State Command

[Top]

Building the StateCommand and Integrating it within CATIA

The first step implements an exclusive State Command [2], the UML diagram for which is seen below [Fig. 6]. This implementation occurs in the State Command BuildGraph routine.

This command is integrated in the Spec Tree toolbar, a Part Workshop Add-in within CATIA. The steps involved in these implementations are detailed in the Wintop Command and Wintop Frame sections of the User Interface domain within the V5 Encyclopedia.

Fig. 6 UML Representation of the State Command

As the UML diagram [Fig. 6] indicates, the State Command has a state prompting an end user to select an Internal Copy with Link in the model hierarchy. The selection is restricted to only those entities, which implement CATIMmiResultFreeze as the code below depicts.

	CATPathElementAgent* _daObjectToSelect;
...
	_daObjectToSelect = new CATPathElementAgent("SelCopiedFeature");
	_daObjectToSelect->AddElementType(IID_CATIMmiResultFreeze);
...

This state has an incoming transition to itself associated with it, as a result of which, it remains eternally prompting an end-user to select an entity whose freeze status is to be switched. An action associated with this incoming transition namely. CAAMmrPartWksFreezeUnfreezeCmd::FreezeOrUnfreeze switches the freeze status of the selected feature. We proceed to now detail this implementation of this callback routine.

[Top]

Implementing the Callback to an Incoming Transition associated with the State Command

Here we detail the implementation of the Callback associated with the State Command. This callback is triggered in response to the user selecting an Internal Copy, in the spec tree within CATIA. It retrieves the selected feature, seeks its freeze status and switches its state (freeze/unfreeze)

To begin with, it retrieves the chosen copied feature from the Selection Agent.

// Within the State Command Class
CATPathElementAgent* _daObjectToSelect;
...
void CAAMmrPartWksFreezeUnfreezeCmd::FreezeOrUnfreeze(void* iData)
{
	CATPathElement* pathModel = _daObjectToSelect->GetValue();
	CATBaseUnknown* pSelectedObj = NULL;

	pSelectedObj = (*pathModel)[pathModel->GetSize()-1];
...

On selecting an entity within CATIA, the Selection Agent, a CATPathElementAgent object, _daObjectToSelect  is valuated. The call to GetValue of the Selection Agent returns the chosen entity, as a CATPathElement object, *pathModel.

This object consists of the entity selected, with all its ancestors up the product model hierarchy until Root. We retrieve the first element in this list, which is just the copied feature, for further processing.

We next seek the freeze status of the selected feature. If Unfrozen it is switched to the frozen state and vice versa.

On being Unfrozen, since the link is restored, an update is explicitly launched, to synchronize the geometry of the copied feature with that of its source.

...
	CATIMmiResultFreeze* pIMmiResultFreezeOnSelFeat = NULL;
	HRESULT hr = pSelectedObj->QueryInterface(IID_CATIMmiResultFreeze,
				      (void**)&pIMmiResultFreezeOnSelFeat);
	
	CATBoolean FreezeStatus = pIMmiResultFreezeOnSelFeat->IsFrozen();
	if (TRUE == FreezeStatus)
	{
		hr = pIMmiResultFreezeOnSelFeat->Unfreeze();

		CATISpecObject_var spSpecObjOnSelFeat = 
						pIMmiResultFreezeOnSelFeat;
		CATTry 
		{
			spSpecObjOnSelFeat->Update();
		}
		CATCatch(CATError,error) 
		{
			cout << "update error:" 
			     << (error->GetNLSMessage()).CastToCharPtr() << endl;
			Flush(error); 
		}
		CATEndTry	
	} else
	{
		hr = pIMmiResultFreezeOnSelFeat->Freeze();
...

The CATIMmiResultFreeze::IsFrozen call returns a CATBoolean, FreezeStatus (TRUE, if frozen, else FALSE)

If Unfrozen, the CATIMmiResultFreeze::Freeze call freezes the selected feature. The call is valid only for an Internal Copy, meaning features copied across Part documents (External Reference) cannot be frozen. On freeze, the Internal Copy is no longer linked with its source feature, and hence its geometry is no longer recomputed during an Update operation.

The CATIMmiResultFreeze::Unfreeze call unfreezes the selected feature. The link with its source feature is now restored and hence an Update operation, synchronizes the geometry of the copied feature with its source. This Update is accomplished by seeking a CATISpecObject type on the copied feature. The CATISpecObject::Update call does an Update. Please note that it is mandatory to call an Update within a CATTry-CATCatch block, since Update is likely to throw an error which should be handled (caught) and displayed to an end-user.

Its significant to note that immediately after an Unfreeze an explicit call to Update is essential. While, any further modification of the source geometry, is automatically reflected in the copied feature, since it is implicitly handled by the Update mechanism.

[Top]


In Short

The Use Case retrieves the freeze status of an Internal Copy with Link and switches its state (Freeze/Unfreeze) [1]. An Internal Copy is a feature copied within a Part document. It can be frozen while a feature copied across Part documents (External Reference) cannot be frozen.

The Use Case is executed through an Interactive State Command [2], integrated in the Spec Tree toolbar, a Part Workshop Add-in [3] within CATIA. On activating this state command, it prompts an end-user to select a copied feature within the product hierarchy. The Selection Agent associated with the State Command restricts the selection to only those entities which implement CATIMmiResultFreeze. An Internal Copy is one of them.

The default state of an Internal Copy is Unfrozen. In this state, the copied geometry is synchronized with its source. On freezing it, the link between the source and its copy, is deactivated, implying that the geometry of the copied feature is not recomputed, in response to any modification in the source geometry. On unfreezing, this link is restored and the copied feature is yet again in sync with its source.

Its significant to note that immediately after an Unfreeze, an explicit call to the CATISpecObject::Update is essential to achieve synchronization. However, any further modifications in the source geometry, are automatically reflected in the copied feature, since it is implicitly handled by the Update mechanism.

[Top]


References

[1] Freezing Internal Copy With Link
[2] Getting stated with State Dialog Commands
[3] Creating an Add-in
[4] Building and Launching a CAA V5 Use Case

[Top]


History

Version: 1 [June 2007] Document created
[Top]

Copyright © 1999-2007, Dassault Systèmes. All rights reserved.
Special Notices CAA V5 CATIA | CAA V5 DELMIA | CAA V5 ENOVIA