Creating a Multi Sheet Interactive Command

Mechanical Design	Drafting	Creating a Multi Sheet Interactive Command How to create an interactive command working on several sheets
Use Case

Abstract

This article discusses the CAADrwMultiSheetCmd use case. This use case explains how to create a command working on several sheets.

What You Will Learn With This Use Case
The CAADrwMultiSheetCmd Use Case
Step-by-Step
In Short
References

What You Will You With This Use Case

In this use case you will learn how to create an interactive command working on several sheets.

[Top]

The CAADrwMultiSheetCmd Use Case

CAADrwMultiSheetCmd is a use case of the CAADraftingInterfaces.edu framework that illustrates DraftingInterfaces framework capabilities.

[Top]

What Does CAADrwMultiSheetCmd Do

This use case shows a command working on several sheets. The use case interactive command has two steps:

Select a reference text
Select a text to move. The text position is modified according to the reference text position.

[Top]

How to Launch CAADrwMultiSheetCmd

To launch CAADrwMultiSheetCmd, you will need to set up the build time environment, then compile CAADrwMultiSheetCmd and CAADrwAddin along with its prerequisites, set up the run time environment, and then include the command in a workbench [1].

Launch CATIA session.
Right-click on Drafting workshop to activate CAAUseCaseCommands toolbar.
Launch the MultiSheet use case command.
Create a drawing document containing two sheets
Create "TEXT SHEET 1" text in Sheet 1. (See Fig: 1)
Create "TEXT SHEET 2" text in Sheet 2. (See Fig: 2)
Launch the use case interactive command. (Sheet 2 is the current sheet)
Select TEXT SHEET 1 text in Sheet 1. (Sheet 1 is the current sheet)
Select TEXT SHEET 2 text in Sheet 2. (Sheet 2 is the current sheet). The TEXT SHEET2 is moved (See Fig: 3) recording to TEXT SHEET1 text position.

Fig 1: Sheet.1 is the current sheet

Fig 2: Sheet.2 is the current sheet

Fig 3: Sheet.2 is the current sheet

[Top]

Where to Find the CAADrwMultiSheetCmd Code

The CAADrwMultiSheetCmd use case is made of two source files named CAADrwMultiSheetCmd.h and CAADrwMultiSheetCmd.cpp located in the CAADrwMultiSheetCmd.m module of the CAADraftingInterfaces.edu framework:

Windows	`InstallRootDirectory\CAADraftingInterfaces.edu\CAADrwMultiSheetCmd.m\`
Unix	`InstallRootDirectory/CAADraftingInterfaces.edu/CAADrwMultiSheetCmd.m/`

where InstallRootDirectory is the directory where the CAA CD-ROM is installed.

[Top]

Step-by-Step

There are seven steps in CAADrwMultiSheetCmd:

Retrieve the current drawing from the Frame
Read the Current Multi Sheet Mode
Active the Multi Sheet Mode
Building the State Chart and Creating the Appropriate Selection Agent
Select the Reference Text and Store its Coordinates
Select the Text to Move and Store the New Position
Restore the Previous Multi Sheet Mode Value

[Top]

Retrieving the Current Drawing from the Frame

// ----------------------------------------------------------------------------
CAADrwMultiSheetCmd::CAADrwMultiSheetCmd()
                    :CATStateCommand(CATString("AlignText")),
                                     _pObjectAgent(NULL)
{
  // Get the current drawing from the frame
  __piSheetsOnDrawing = NULL;
  CATApplicationFrame *appFrame = CATApplicationFrame::GetFrame();
  CATIAApplication *ptApp = NULL;
  if (SUCCEEDED(appFrame->QueryInterface(IID_CATIAApplication, (void**) &ptApp)))
  {
    CATIADocument *ptDoc = NULL;
    if (SUCCEEDED(ptApp->get_ActiveDocument(ptDoc)))
    {
      CATIADrawingDocument *piDrawing = NULL;
      if (SUCCEEDED(ptDoc->QueryInterface(IID_CATIADrawingDocument, (void**) &piDrawing)))
      {
        piDrawing->get_Sheets(__piSheetsOnDrawing);
        piDrawing->Release();
      }
      ptDoc->Release();
    }
    ptApp->Release();
  }
  // Save Multi sheet mode to restitute it at the end of the command
  GetMultiSheetMode(_PreviousMode);

  // Activate Multi sheet mode
  if (!_PreviousMode) SetMultiSheetMode(TRUE);

  _Xposition =0.0;
  _Yposition =0.0;
}

[Top]

Reading the Current Multi Sheet Mode

// ----------------------------------------------------------------------------
// Save Multi sheet mode to restore it at the end of the command
   GetMultiSheetMode(_PreviousMode);
//
...
// This internal method is used to manage CATIDftMultiSheetCmd Interfaces.
void  CAADrwMultiSheetCmd::GetMultiSheetMode(boolean  &oMode)
{
  oMode = FALSE;
  if (!!__piSheetsOnDrawing)
  {
    CATIDftMultiSheetMode *multiSheetManager=NULL;
    if (SUCCEEDED(__piSheetsOnDrawing->QueryInterface(IID_CATIDftMultiSheetMode, (void **) &multiSheetManager)))
    {
      multiSheetManager->GetMultiSheetMode(&oMode);
      multiSheetManager->Release();
    }
  }
}

[Top]

Activating the Multi Sheet Mode

// Active Multi sheet mode
if (!_PreviousMode) SetMultiSheetMode(TRUE);
...
//This internal method is used to manage CATIDftMultiSheetCmd Interfaces.
void  CAADrwMultiSheetCmd::SetMultiSheetMode(boolean  iMode)
{
  if (!!__piSheetsOnDrawing)
  {
    CATIDftMultiSheetMode *multiSheetManager=NULL;
    if (SUCCEEDED(__piSheetsOnDrawing->QueryInterface(IID_CATIDftMultiSheetMode, (void **) &multiSheetManager)))
    {
      multiSheetManager->SetMultiSheetMode(iMode);
      multiSheetManager->Release();
    }
  }
}

[Top]

Building the State Chart and Creating the Appropriate Selection Agent

// ----------------------------------------------------------------------------
void CAADrwMultiSheetCmd::BuildGraph()
{  
  // Creation of the acquisition agent
  _pObjectAgent = new CATPathElementAgent("pObjectAgent");
  _pObjectAgent ->SetBehavior( CATDlgEngWithPrevaluation | 
                               CATDlgEngMultiAcquisition | 
                               CATDlgEngWithCSO); 

  // We want to select text
  _pObjectAgent ->SetElementType("CATIDrwText");
  AddCSOClient(_pObjectAgent);
   
  //  States definition
  CATDialogState* state1 = GetInitialState("Sel reference text");
  CATDialogState* state2 = AddDialogState("Sel text to align");
  state1->AddDialogAgent(_pObjectAgent);
  state2->AddDialogAgent(_pObjectAgent);
   
  // Transition definition
  AddTransition(state1, state2, IsOutputSetCondition(_pObjectAgent),
                Action((ActionMethod)&CAADrwMultiSheetCmd::CheckText, NULL, NULL));

  // Transition definition
  AddTransition(state2, NULL, IsOutputSetCondition(_pObjectAgent),
                Action((ActionMethod)&CAADrwMultiSheetCmd::MoveText, NULL, NULL));
}

In this section we create a CATPathElementAgent and set the corresponding element type to CATIDrwText. So only Complex Texts could be selected.

[Top]

Selecting the Reference Text and Storing its Coordinates

// ----------------------------------------------------------------------------
boolean CAADrwMultiSheetCmd::CheckText(void *)
{ 
  // We get the Selected set of objects
  CATSO* pObjSO = _pObjectAgent->GetListOfValues(); 
  CATPathElement *pElemPath = NULL;
   
   
  if (NULL != pObjSO)  
  {
    // There is a selection, we will scan it from the beginning
    pObjSO->InitElementList();
    while (NULL != (pElemPath = (CATPathElement*)pObjSO->NextElement()))
    {
      // Make sure the element is a text
      CATIDrwText *piText = (CATIDrwText *)pElemPath->FindElement(IID_CATIDrwText);
         
      if (NULL != piText)
      {            
        piText->GetPosition(_Xposition,_Yposition);
        piText->Release();
      }
    }
  _pObjectAgent -> InitializeAcquisition();
  return TRUE;
  }
  return FALSE;
}
...

The acquisition agent did put the selected text into the CSO. So we get the set of object and loop on it.

[Top]

Selecting the Text to Move and Storing the New Position

// ----------------------------------------------------------------------------
boolean CAADrwMultiSheetCmd::MoveText(void *)
{ 
  // We get the Selected set of objects
  CATSO* pObjSO = _pObjectAgent->GetListOfValues(); 
  CATPathElement *pElemPath = NULL;

  if (NULL != pObjSO)  
  {
    // There is a selection, we will scan it from the beginning
    pObjSO->InitElementList();
    while (NULL != (pElemPath = (CATPathElement*)pObjSO->NextElement()))
    {
      // Make sure the element is a text
      CATIDrwText *piText = (CATIDrwText *)pElemPath->FindElement(IID_CATIDrwText);

      if (NULL != piText)
      {            
        piText->SetPosition(_Xposition,_Yposition);
        CATIModelEvents_var event(piText);
        if (event !=NULL_var)
        {
          CATModify info((CATBaseUnknown *)piText);
          event->Dispatch(info);
        }
        piText->Release();
      }
    }
    _pObjectAgent -> InitializeAcquisition();
    return TRUE;
  }
...

Note: When a text is modified and needs to regenerate its graphical representations, it just has to send CATModify event to warn all its.

[Top]

Restoring the Previous Multi Sheet Mode Value

...            
// Restore Active Multi sheet mode
  SetMultiSheetMode(_PreviousMode);
  return FALSE;
}

Note: The Multi Sheet Mode Value has to be restore in the destructor.

[Top]

In Short

This use case shows how to create a command working on several sheets: Retrieve current drawing, manage the multi sheet Mode and move a text.

[Top]

References

[1]	Building and Lauching CAA V5 Samples
[2]	Implementing the Statechart Diagram
[Top]

History

Version: 1 [Aug 2000]	Document created
[Top]

Mechanical Design

Drafting