3D PLM Enterprise Architecture

User Interface - Frame

Creating a Command with Options in the "Tools Palette" Toolbar

How to implement CATIAfrCmdPaletteOptions and define options
Use Case

Abstract

This article shows how a state command can add "options" in a special toolbar during the life of the command. This special toolbar is named the "Tools Palette" and "options" are command headers. The definition and the usage of options are also explained.

What You Will Learn With This Use Case

The Tools Palette is a special toolbar which updates dynamically when:

Command headers are added in the Palette once the workbench is activated, and they are removed from the toolbar after the workbench deactivation.

Command headers may be added when the command is activated and they are removed when the command is canceled. For a state command, there is also the possibility to add command headers for a specific state, they are removed when the state is left. When the command is deactivated, the command headers become unavailable. 

This use case is intended to show you how to implement CATIAfrCmdPaletteOptions and how to create options using the CATAfrCheckHeaderAccessor class. 

[Top]

The CAADegCreateBoxCmd Use Case

CAADegCreateBoxCmd is a use case of the CAADialogEngine.edu framework that illustrates ApplicationFrame framework capabilities.

[Top]

What Does CAADegCreateBoxCmd Do

CAADegCreateBoxCmd is a state command to create a box. This command is defined in the CAA V5: Geometrical Creation workbench of the CAAGeometry document [1]. 

A box is defined by three dimensions: the width (W), the depth (D), and the height (H). The CAADegCreateBoxCmd command gives to the end user the possibility to define three kinds of boxes:

               Fig.1 - left                     Fig.1 - center                Fig.1 - right

The choice between these three kinds of boxes is possible thanks to options set in the Palette. This palette is the "Tools Palette" toolbar. The picture below shows this toolbar and icons added by the state command:

Fig.2

 The three icons, surrounded of a circle, enable the end user to create:
  • A cube:
  • A parallelepiped where the depth is equal to the height :
  • A real parallelepiped:

These three icons are not always in the palette, it depends on the current state:

  • The three icons are displayed once P1 is selected. 
  • The first icon disappears from the Palette as soon as P2 is selected. The end user cannot any more create a cube, he/she can only create a parallelepiped. Only the two lasts are available
  • Once P3 is indicated, the three icons disappear. The end user will create a "real" parallelepiped. 
is already present during the life of the command. 
  • The icon is highlighted: The origin of the box is the origin of the model (0,0,0)
  • The icon is normal: The origin of the box is the first selected point 

The CAADegCreateBoxCmd is a state dialog command that creates a box in the 3D space according to the following UML statechart diagram [2].

Fig.3

[Top]

How to Launch CAADegCreateBoxCmd

See the section entitled "How to Launch the CAAGeometry Use Case" in the "The CAAGeometry Sample" use case for a detailed description of how this use case should be launched. 

Then, in the window where you run the mkrun command, do not type the module name on the command line, but type CNEXT instead. When the application is ready, do the following:

[Top]

Where to Find the CAADegCreateBoxCmd Code

The CAADegCreateBoxCmd use case is made of several classes located in the CAADegGeoCommands.m module of the CAADialogEngine.edu framework:

Windows InstallRootDirectory\CAADialogEngine.edu\CAADegGeoCommands.m\
Unix InstallRootDirectory/CAADialogEngine.edu/CAADegGeoCommands.m/

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

[Top]

Step-by-Step

There are four logical steps in CAADegCreateBoxCmd:

  1. Defining the CAADegCreateBoxCmd class
  2. Defining Options
  3. Implementing the CATIAfrCmdPaletteOptions Interface
  4. Using Options

[Top]

Defining the CAADegCreateBoxCmd class

The CAADegCreateBoxCmd class is a state command.

  1. Defining the CAADegCreateBoxCmd.h 
  2. Defining the CAADegCreateBoxCmd.cpp

 

  1. Defining the CAADegCreateBoxCmd.h 
    2. // DialogEngine framework
#include "CATStateCommand.h"   
...
class CAADegCreateBoxCmd : public CATStateCommand
{
  CmdDeclareResource(CAADegCreateBoxCmd,CATStateCommand);

  CATDeclareClass ;

  public :
    CAADegCreateBoxCmd();
    virtual ~CAADegCreateBoxCmd();  
    ...
    virtual CATLISTP(CATCommandHeader) GetPaletteStateOptions() ;
    virtual CATLISTP(CATCommandHeader) GetPaletteOptions() ;

  private :
    ...
    virtual void BuildGraph() ;
    CATBoolean  CheckChoice(void * iChoice);
    CATBoolean  CreateBox(void * iDummy);
    ...
    void BoxCreationChoiceChange (CATCommand        * iPublisher, 
		          CATNotification      * iNotification, 
		          CATCommandClientData   iUsefulData);

  private :
   ...
    int                            _CurrentBoxCreationTypeChoice ;

    CATAfrCheckHeaderAccessor    * _pTwoPointsCmdHdr ;
    CATAfrCheckHeaderAccessor    * _pThreePointsCmdHdr ;
    CATAfrCheckHeaderAccessor    * _pFourPointsCmdHdr ;
    CATAfrCheckHeaderAccessor    * _pOriginCheckHdr ;
};

    This class deriving from the CATStateCommand class contains:

    the following macros:

    the following (fully or partially explained) methods:

    and the following data:

    The class contains other methods and data, refer to the code for more details. 

  2. Defining the CAADegCreateBoxCmd.cpp

    3. The beginning of the source file is such as:

    ...
#include <CATCommandHeader.h>
MacDeclareHeader(CAADegCreateBoxPaletteHeader) ;

CATImplementClass(CAADegCreateBoxCmd, Implementation,CATStateCommand, CATNull);

...

#include "CATCreateExternalObject.h"
CATCreateClass(CAADegCreateBoxCmd);

...

[Top]

Defining Options

Options are command header instances set in the Palette toolbar. In the constructor of the CAADegCreateBoxCmd class the command headers are defined. Refer to the technical article entitled "The Command Headers"  [6] for details and warnings about command header creation.

This state command creates and uses two kinds of options

In these two cases, the command header is a check header  A check header being a non-exposed class, the CATAfrCheckHeaderAccessor class encapsulates its creation and its access. The CATAfrCheckHeaderAccessor class constructor creates a check header instance only if the instance does not already exist in the command header list associated with the current editor [6]. Consequently you can create as many CATAfrCheckHeaderAccessor class instances as you want, the methods of this class are redirected on the unique check header instance of the current editor. 

Note, that there is also the CAAAfrViewerFeedbackHdr use case [7] which describes the usage of the CATAfrCheckHeaderAccessor class in an add-in context. 

Option to define the way to create the box

...
  CATCommandHeader * pCmd = NULL ;
  ::CATAfrGetCommandHeader("CAADegTwoPointsBoxHdr",pCmd);
  
  _pTwoPointsCmdHdr = new CATAfrCheckHeaderAccessor("CAADegTwoPointsBoxHdr");
  
  if ( NULL == pCmd )
  {
     new CAADegCreateBoxPaletteHeader
                          ("CAADegTwoPointsBoxCheckHdr",
                          "CAADegGeoCommands",
                          "CAADegBoxPaletteChoiceCmd", (void *) 1);

     new CAADegCreateBoxPaletteHeader
                          ("CAADegTwoPointsBoxUncheckHdr",
                          "CAADegGeoCommands",
                          "CAADegBoxPaletteChoiceCmd", (void *) 1);
  
     _pTwoPointsCmdHdr->SetCheckCommand("CAADegTwoPointsBoxCheckHdr");
     _pTwoPointsCmdHdr->SetUncheckCommand("CAADegTwoPointsBoxUncheckHdr");

     _pTwoPointsCmdHdr->SetResourceFile("CAADegCreateBoxPaletteHeader");
     
     _pTwoPointsCmdHdr->SetCheck(TRUE,FALSE);
  }
...

_pTwoPointsCmdHdr is a newly CATAfrCheckHeaderAccessor class pointer. This pointer will be used in the state command to manage the exclusivity between the three icons. Refer to the Managing the exclusivity between the three icons sections. 

But, before to create a CATAfrCheckHeaderAccessor class instance, the CATAfrGetCommandHeader global function is used to retrieve a check header pointer. If the check header has never been created for the current editor, this method will return NULL. In this case, after the CATAfrCheckHeaderAccessor class construction you should:

Option to locate the newly box

...
  pCmd = NULL ;
  ::CATAfrGetCommandHeader("CAADegOriginBoxHdr",pCmd);
  
  _pOriginCheckHdr = new CATAfrCheckHeaderAccessor("CAADegOriginBoxHdr");
  
  if ( NULL == pCmd)
  {  
      _pOriginCheckHdr->SetResourceFile("CAADegCreateBoxCmd");
  }
...

_pOriginCheckHdr is a newly CATAfrCheckHeaderAccessor class pointer. This pointer will be used in the CreateBox method Refer to the Using Options section.

But, before to create a CATAfrCheckHeaderAccessor class instance, the CATAfrGetCommandHeader global function is used to retrieve a check header pointer. If the check header has never been created for the current editor, this method will return NULL. In this case, after the CATAfrCheckHeaderAccessor class construction you should only specify the resource file name. In the CNext/resources/msgcatalog directory of the CAADialogEngine.edu framework you find the CAADegCreateBoxCmd.CATNls and the CAADegCreateBoxCmd.CATRsc files. The first one contains the help, shorthelp,... and the second one contains the icon name [8].

This check header does not launch any command when the button is pushed. It is just a header which keeps a state.  

Managing Exclusivity Between the Three Icons

When an icon (, ,) is pushed, the CAADegBoxPaletteChoiceCmd command is launched. This command sends a notification to inform the CAADegCreateBoxCmd state command.

...
CAADegBoxPaletteChoiceCmd::CAADegBoxPaletteChoiceCmd(void *iArgument): 
                   CATCommand(NULL,"CAADegBoxPaletteChoiceCmd")
{
   int value = ( int) iArgument ;
  
   CAADegBoxCreationChoiceNotification * pNotification = NULL ;
   pNotification = new CAADegBoxCreationChoiceNotification();     
   pNotification->SetChoice(value);
   
   SendNotification(GetFather(),pNotification);

   pNotification = NULL ;

   RequestDelayedDestruction(); 
}
...

In the BuildGraph method of the CAADegCreateBoxCmd command, a callback method has been declared to be inform when a CAADegBoxCreationChoiceNotification class notification is sent. 

...
AddAnalyseNotificationCB(NULL, "CAADegBoxCreationChoiceNotification",
                (CATCommandMethod)&CAADegCreateBoxCmd::BoxCreationChoiceChange,
                            NULL);
...

The BoxCreationChoiceChange method unchecks the two other check buttons.

...
void CAADegCreateBoxCmd::BoxCreationChoiceChange (CATCommand  * iPublisher ,
                                    CATNotification      * iNotification,
                                    CATCommandClientData   iUsefulData)
{
 ...
          CAADegBoxCreationChoiceNotification * pNotif = NULL ;
          pNotif = ( CAADegBoxCreationChoiceNotification *) iNotification ;
          
          int value = 0 ;
          HRESULT rc = pNotif->GetChoice(value);
          ...
          {
             if ( value == 1  )
             {
                 _pThreePointsCmdHdr->SetCheck(FALSE,FALSE);
                 _pFourPointsCmdHdr->SetCheck(FALSE,FALSE);
             }
             if ( value == 2 )
             {
                 _pTwoPointsCmdHdr->SetCheck(FALSE,FALSE);
                 _pFourPointsCmdHdr->SetCheck(FALSE,FALSE);
             }
             if ( value == 3 )
             {
                 _pTwoPointsCmdHdr->SetCheck(FALSE,FALSE);
                 _pThreePointsCmdHdr->SetCheck(FALSE,FALSE);             
             }
             _CurrentBoxCreationTypeChoice = value ;
...

GetChoice retrieves the last activated check button.  _CurrentBoxCreationTypeChoice, a data member, keeps the current activated check button. See its usage in the Using Options- Define the way to create a box section.

[Top]

Implementing the CATIAfrCmdPaletteOptions Interface

The CAADegCreateBoxCmd class states that it implements the CATIAfrCmdPaletteOptions interface thanks to the TIE_CATIAfrCmdPaletteOptions macro.

...
#include "TIE_CATIAfrCmdPaletteOptions.h"
TIE_CATIAfrCmdPaletteOptions(CAADegCreateBoxCmd);
...

This interface has two methods:

  1. GetPaletteOptions
  2. GetPaletteStateOptions

 

  1. GetPaletteOptions

    2. This method is called when the command is activated. It is the reason why the command must be an exclusive or shared command [9]. 

    In the use case, the option to add in the Palette is the command header represented by this icon: . 

    ...
CATLISTP(CATCommandHeader) CAADegCreateBoxCmd::GetPaletteOptions() 
{
   CATLISTP(CATCommandHeader) PaletteOptions;

   CATCommandHeader * pCmd = NULL ;
   ::CATAfrGetCommandHeader("CAADegOriginBoxHdr",pCmd);

   if ( NULL != pCmd ) 
   {
       PaletteOptions.Append(pCmd);
       pCmd = NULL ;
   }
   return PaletteOptions ;
}
...

    PaletteOptions is a list of command header instance pointers to return. The CATAfrGetCommandHeader global function is the means to retrieve a command header instance pointer from its name. The name being the first argument of the function. This header is kept in the list associated with the current editor [6].

    The CAADegOriginBoxHdr command header instance is a check header to specify if the newly box should be created at the origin of the model . Refer to the Defining Options section for details about the header creation. 

  2. GetPaletteStateOptions

    3. This method is called each time the state command enters in a state. In most cases, the goal of this method is to retrieve the name of the current state, and whether the state's name, add the specific command header instance pointers in the returned list.

    ...
CATLISTP(CATCommandHeader) CAADegCreateBoxCmd::GetPaletteStateOptions() 
{
   CATLISTP(CATCommandHeader) PaletteStateOptions;

   CATDialogState * pCurrentState = GetCurrentState();
   if ( NULL != pCurrentState )
   {
      CATString StateName = pCurrentState->GetResourceID();
     
      if ( ! strcmp("stWidthPointId",StateName) )
      {
         Case stWidthPointId State
      }else if (  ! strcmp("stDepthPointId" ,StateName) )
      {
         Case stDepthPointId State - not detailed
      }
   }
   return PaletteStateOptions ;
...

    The GetCurrentState method retrieves a pointer to the current state. The GetResourceID method retrieves the resource identifier of the state. It is the unique argument of the AddDialogState or GetInitialState methods. 

    In the BuildGraph method, four states are created:

    ...
CATDialogState *stCornerPoint = GetInitialState("stCornerPointId"); 

CATDialogState *stWidthPoint = AddDialogState("stWidthPointId"); 

CATDialogState *stDepthPoint = AddDialogState("stDepthPointId"); 

CATDialogState *stHeightPoint = AddDialogState("stHeightPointId"); 

...

    stCornerPoint is the state to select P1, stWidthPoint is the state to select P2, stDepthPoint is the state to indicate P3 and stHeightPoint is the state to indicate P4. Refer to Fig.1 for explanations about these four points and Fig.3 for the UML state chart. For the stWidthPoint state, the three icons (,,)  are added in the Palette, and for the stDepthPoint state only the two lasts (,) are set. 

    Here is the code to process the state whose the identifier is stWidthPointId: 
    ...
          CATCommandHeader * pCmd = NULL ;
          ::CATAfrGetCommandHeader("CAADegTwoPointsBoxHdr",pCmd);
          if ( NULL != pCmd ) 
          {
             PaletteStateOptions.Append(pCmd);
             pCmd = NULL ;
          }

          ::CATAfrGetCommandHeader("CAADegThreePointsBoxHdr",pCmd);
          if ( NULL != pCmd ) 
          {
             PaletteStateOptions.Append(pCmd);
             pCmd = NULL ;
          }

          ::CATAfrGetCommandHeader("CAADegFourPointsBoxHdr",pCmd);
          if ( NULL != pCmd ) 
          {
             PaletteStateOptions.Append(pCmd);
             pCmd = NULL ;
          }
...

    PaletteStateOptions, defined just above,  is a list of command header instance pointers. The CATAfrGetCommandHeader global function is the means to retrieve a command header instance pointer from its name. The name being the first argument of the function. This header is kept in the list associated with the current editor [8].

    In this state, all the possibilities to create the box are valid. The CAADegTwoPointsBoxHdr, CAADegThreePointsBoxHdr, and CAADegFourPointsBoxHdr command header instances are check headers to specify if the newly box should be created with two, three or four points respectively. Refer to the Defining Options section for details about the header creations.

[Top]

Using Options

The state command has defined two options:

These two options are used in different parts of the command.

[Top]

In Short

This use case has explained how to implement the CATIAfrCmdPaletteOptions interface to add options in the Tools Palette toolbar. 

[Top]

References

[1] The CAAGeometry Sample
[2] Describing State Dialog Commands Using UML
[3] Assigning Resources to a State Dialog Command
[4] Implementing the Command Statechart Diagram
[5] Object Modeler Inheritances
[6] The Command Headers
[7] Creating a Check Button
[8] Creating Resources for Command Headers
[9] The CAA Command Model
[10] Using the "Tools Palette" Toolbar for a Workbench
[Top]

History

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

Copyright © 2003, Dassault Systèmes. All rights reserved.