Mechanical Design |
3D Functional Tolerancing & Annotation |
Creating a 3D Text AnnotationAssociating a text on a selected geometry and modifying some of it's properties |
| Use Case | ||
AbstractThis article discusses the CAATpiCreateText use case. This use case explains how to create a 3D text annotation associated to a selected geometry and how to modify some properties such as position, text size, font and leader extremity symbol. |
This use case is intended to help you to use Technological Product Specifications (TPS) interfaces [1]. The use case demonstrates CATITPSFactoryAdvanced interface usage to create a 3D text annotation. It also illustrates how to modify 3D annotation properties by using interfaces from DraftingInterfaces framework.
[Top]
CAATpiCreateText is a use case of the CAATPSInterfaces.edu framework that illustrates CATTPSInterfaces framework capabilities.
[Top]
The use case is an interactive command that prompt the user to select a geometrical element and then create a 3D text annotation associated to that geometry.
[Top]
The use case command is available in the toolbar "CAA Sample" of the workbench Functionnal & Tolerancing & Annotation.
To launch CAATpiCreateText, you will need to set up the build time environment, then compile CAATPSInterfaces.edu framework along with its prerequisites, set up the run time environment, and then execute the use case [2].
Do not type the module name on the command line, but type CNEXT instead. When the application is ready, do the following:
Notice that the toolbar CAA Sample is also available in other workbenches :
[Top]
The CAATpiCreateText use case is located in the CAATpiCreateText.m module of the CAATPSInterfaces.edu framework:
| Windows | InstallRootDirectory\CAATPSInterfaces.edu\CAATpiCreateText.m\ |
| Unix | InstallRootDirectory/CAATPSInterfaces.edu/CAATpiCreateText.m/ |
where InstallRootDirectory is the directory where the CAA CD-ROM
is installed.
[Top]
There are seven logical steps in CAATpiCreateText:
We will now comment each of these sections by looking at the code.
[Top]
The use case is the class CAATpiCreateTextCmd which is a CATStateCommand that implement the following statechart diagram.
[Top]
void CAATpiCreateTextCmd::BuildGraph ()
{
// Create selection agent
_pAgentGeometry = new CATPathElementAgent ("AgentGeometry",
NULL,
CATDlgEngWithPrevaluation|
CATDlgEngMultiAcquisition|
CATDlgEngWithPSOHSO);
CATListOfCATString TypeList(15);
// Retrieve CATITPSFactoryTTRS interfaces
CATITPSFactoryTTRS * piFactTTRS = NULL;
rc = CATTPSInstantiateComponent (DfTPS_ItfTPSFactoryTTRS,
(void**) & piFactTTRS);
if ( SUCCEEDED(rc) )
{
// Obtain Filter that must be used for selecting geometry
// to create 3D annotation.
piFactTTRS -> GetOrderedTypeList (&TypeList);
piFactTTRS -> Release();
piFactTTRS = NULL;
}
_pAgentGeometry -> SetOrderedTypeList(TypeList);
AddCSOClient (_pAgentGeometry);
...
|
The selection agent is created in the Buildgraph method of the command. It's a standard CATPathElementAgent. It's behavior CATDlgEngMultiAcquisition allows him to accept several selection. It's behavior CATDlgEngWithPSOHSO and the call to the AddCSOClient method allow the command to work in the object-action mode. That means that the user can select one or several geometrical elements then launch the command to create a text that will be associated to the whole selection.
On which kind of geometrical element is it possible to create a 3D Text ? The answer to this question is given by the CATITPSFactoryTTRS ::GetOrderedTypeList method. It returns a list of interface name (TypeList) that is provided to the selection agent by SetOrderedTypeList method. The selection agent use that list of interfaces to filter selection and keep only the geometrical elements on which it is possible to create a 3D annotation.
CATITPSFactoryTTRS interface is obtained from the global service CATTPSInstantiateComponent.
[Top]
boolean CAATpiCreateTextCmd::CreateTextOnSelection (void * ipData)
{
if ( !_pAgentGeometry ) return (TRUE);
HRESULT rc = E_FAIL;
// Retrieve the selected geometry
CATSO * pSelection = _pAgentGeometry -> GetListOfValues();
if ( pSelection )
{
// Retrieve CATITPSFactoryAdvanced interfaces
CATITPSFactoryAdvanced * piFactAdv = NULL;
rc = CATTPSInstantiateComponent (DfTPS_ItfTPSFactoryAdvanced,
(void**) & piFactAdv);
if ( SUCCEEDED(rc) )
{
CATITPSText * piText = NULL;
CATUnicodeString TextString("Sample 3D Text");
CATMathPlane Plane = CATMathOIJ;
rc = piFactAdv -> CreateTextOnGeometry (pSelection, &Plane,
&TextString , &piText);
if ( SUCCEEDED(rc) )
{
...
piText -> Release();
piText = NULL;
}
piFactAdv -> Release();
piFactAdv = NULL;
}
}
return (TRUE);
}
|
When selection agent is valuated the transition method CreateTextOnSelection is called. The selected geometry is retrieved by calling GetListOfValues on the selection agent. Selection is returned as a CATSO which contains one or more CATPathElement. CATITPSFactoryAdvanced interface is obtained from the global service CATTPSInstantiateComponent. The method CreateTextOnGeometry is called with the following input arguments :
It's output is a CATITPSText pointer on the created text.
[Top]
CATIDrwAnnotation * piAnnot = NULL;
rc = piText -> QueryInterface (IID_CATIDrwAnnotation,
(void**) & piAnnot);
if ( SUCCEEDED(rc) )
{
double DeltaX = -20.0;
double DeltaY = +20;
piAnnot -> Move (DeltaX, DeltaY);
piAnnot -> Release();
piAnnot = NULL;
}
...
|
The interface CATIDrwAnnotation from DraftingInterface framework [3] is available on 3D Text Annotation. It can be used to retrieve and manipulate annotation's position in annotation plane.
[Top]
CATIDrwEltWithLeader * piEltWithLeader = NULL;
rc = piText -> QueryInterface(IID_CATIDrwEltWithLeader,
(void **) &piEltWithLeader);
if ( SUCCEEDED(rc) )
{
int LeaderCount = piEltWithLeader -> GetNbLeader ();
if ( LeaderCount >= 1 )
{
CATIDrwLeader_var spDrwLeader = piEltWithLeader -> GetLeader (1);
if ( NULL_var !=spDrwLeader )
{
}
}
piEltWithLeader -> Release();
piEltWithLeader = NULL;
}
...
|
The interface CATIDrwEltWithLeader from DraftingInterface framework [3] is available on 3D Text Annotation. It can be used to retrieve annotation's leaders and to modify them.
[Top]
CATIDrwTextProperties * piTxtProp = NULL;
rc = piText -> QueryInterface (IID_CATIDrwTextProperties,
(void**) & piTxtProp);
if ( SUCCEEDED(rc) )
{
// Change Font Size to 7.0 millimeters
piTxtProp -> SetFontSize (7.0);
// Use Gothic Font
CATUnicodeString FontName("GOTH");
piTxtProp -> SetFontName(FontName);
piTxtProp -> Refresh();
piTxtProp -> Release();
piTxtProp = NULL;
}
...
|
The interface CATIDrwTextProperties from DraftingInterface framework [3] is available on 3D Text Annotation. It can be used to retrieve and modify annotation's properties like Size and Font.
The Refresh method must be called to update 3D Text visualization.
[Top]
The use case finishes when the command ended. A new 3D text is created. It appears in the graph and in the 3D view. It's leader is pointing on the selected geometry.
[Top]
This use case has demonstrated the integration of 3D Text creation and modifications APIs in an interactive command.
[Top]
| [1] | Technological Product Specification Overview |
| [2] | Building and Launching a CAA V5 Use Case |
| [3] | Drafting |
[Top]
| History | |
| Version: 1 [Feb 2002] | Document created |
|
[Top] |
|
Copyright © 2002, Dassault Systèmes. All rights reserved.
