3D PLM Enterprise Architecture

User Interface - Frame

Creating an Interruptible Task

Using CATIProgressTask, CATIProgressTaskUI,and CATTaskController
Use Case

Abstract

This article shows how to create an interruptible task with an indicator of progression.

What You Will Learn With This Use Case

Some processes can take so long that a user interface indicating the progression can be very useful. It can be also interesting to give the end user the ability to stop the task. This article shows how this information and control can be implemented by a DS component. You will need to:

[Top]

The CAAAfrProgressTask Use Case

CAAAfrProgressTask is a use case of the CAAApplicationFrame.edu framework that illustrates ApplicationFrame framework capabilities.

[Top]

What Does CAAAfrProgressTask Do

This use case simulates a long process . The task is composed of fifty steps, each step consisting in to execution of the following code:

for ( int j= 0 ; j<= 5000000 ; j++)
{
   double k = 24.25 * (double) j ;
}

The progression of the process is indicated by using a DS component which displays the following dialog box:

Fig.1: Interface User

In this dialog box there are four parts (surrounded in red) that the programmer can customize:

The others parts are:

This task is launched from an interactive command, that has been added to the  " CAA V5 Geometrical Analysis" workbench of the CAAGeometry document. This command, "Progress Task", has been defined in the "Analysis" menu and in the  "Mathematical Analysis"  toolbar:

Fig.2: The "Mathematical Analysis" Toolbar

This command is a CATDlgDialog having the following user interface:

Fig.3: The "Progress Task" Command

[Top]

How to Launch CAAAfrProgressTask

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. For the specific scenario :

Launch CATIA. When the application is ready:

[Top]

Where to Find the CAAAfrProgressTask Code

The CAAAfrProgressTask use case is made of a single file located in the CAAAfrProgressTask.m module of the CAAApplicationFrame.edu framework:

Windows InstallRootDirectory\CAAApplicationFrame.edu\CAAAfrProgressTask.m\
Unix InstallRootDirectory/CAAApplicationFrame.edu/CAAAfrProgressTask.m/

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

[Top]

Step-by-Step

There are two logical steps in CAAAfrProgressTask:

  1. Creating the Interactive Command
  2. Implementing the CATIProgressTask Interface

[Top]

Creating the Interactive Command

This command is called CAAAfrProgressTaskSampleCmd. This section describes:

  1. The header file
  2. The source file
  3. The NLS resource file
  1. The header file
    2. // Dialog Framework
#include "CATDlgDialog.h"     // Needed to derive from CATDlgDialog

// Dialog Framework
class CATDlgCheckButton;
// ApplicationFrame Framework
class CATFrmEditor;

class CAAAfrProgressTaskSampleCmd : public CATDlgDialog
{
  ...
  DeclareResource(CAAAfrProgressTaskSampleCmd, CATDlgDialog);
  
  public :
    
    CAAAfrProgressTaskSampleCmd();

    virtual ~CAAAfrProgressTaskSampleCmd();  

    ...

  private : 

    void ClickCompute(CATCommand            *iPublishingCommand, 
                    CATNotification         *iNotification, 
                    CATCommandClientData     iUsefulData);
 
    void ClickClose(CATCommand              *iPublishingCommand, 
                    CATNotification         *iNotification, 
                    CATCommandClientData     iUsefulData);
                    
    void EditorClose  (CATCallbackEvent  iEvent,
                           void             *iFrom,
                           CATNotification  *iNotification,
                           CATSubscriberData iData,
                           CATCallback       iCallBack );
                           
    CAAAfrProgressTaskSampleCmd(const CAAAfrProgressTaskSampleCmd &iObjectToCopy);

    CAAAfrProgressTaskSampleCmd & operator = (const CAAAfrProgressTaskSampleCmd &iObjectToCopy);

  private : 

    CATDlgCheckButton * _pInterruptTask  ;
    CATFrmEditor      * _pEditor ;

};

    This header file contains the following declaration:

     

  2. The source file
  3. The NLS resource file:

    4. The CAAAfrProgressTaskSampleCmd.CATNls file is located in the CAAApplicationFrame.edu/Cnext/resources/msgcatalog directory. It contains:

[Top]

Implementing the CATIProgressTask  Interface

The CAAAfrProgressTaskSampleCmd class implements the CATIProgressTask interface. This section describes how this is done:

  1. Declaring the methods of the CATIProgressTask interface in the header file
  2. Adding the necessary included files in the source file
  3. Coding the PerformTask method
  4. Coding the GetCatalogName method
  5. Coding the GetIcon method
  6. Modifying the CAAAfrProgressTaskSampleCmd.CATNls file
  7. Declaring the command as a component 
  1. Declaring the methods of the CATIProgressTask interface in the header file
    2. ...
class CATIProgressTaskUI ;

class CAAAfrProgressTaskSampleCmd : public CATDlgDialog
{
    ...      
 public :
 
    ...
    virtual HRESULT PerformTask    (CATIProgressTaskUI  * iUI, void * iUserData);
    
    virtual HRESULT GetCatalogName (CATString           * oCatalogName);

    virtual HRESULT GetIcon        (CATString           * oIcon) ;
    ...
}

    These are the three methods of the CATIProgressTask interface.

  2. Adding the necessary  include files:
    3. ...
// Dialog Framework
...
#include "CATMsgCatalog.h"
...

//Application Frame Framework
...
#include "CATIProgressTaskUI.h"
...
  3. Coding the PerformTask method
    4. ...
HRESULT CAAAfrProgressTaskSampleCmd::PerformTask (CATIProgressTaskUI  * iUI, void * iUserData)
{
    if ( NULL == iUI ) return E_FAIL ;

    int min = 1 ;
    int max = 50 ;
    iUI->SetRange(min,max);
    
    for ( int i= min ; i <= max ; i++)
    {
        iUI->SetProgress(i);

        CATUnicodeString usMessage ;
        CATUnicodeString usParam[1] ;
        
        usParam[0].BuildFromNum(i);

        usMessage = CATMsgCatalog::BuildMessage("CAAAfrProgressTaskSampleCmd",
                                        "ProgressTaskUI.CommentRuntime",usParam,1,
                                        "Step ...");

        iUI->SetComment(usMessage);

        // begin of the step'simulation 
        for ( int j= 0 ; j<= 5000000 ; j++)
        {
            double k = 24.25 * (double) j ;
        }
        // end of the step'simulation 

        CATBoolean interrupt ;
        if ( S_OK != iUI->IsInterrupted(&interrupt) || (TRUE == interrupt) )
        {
            return E_FAIL ;
        }
    }

    return S_OK ;
}
...

    This method consists in executing the task and giving information to the dialog box managed by the CATIProgressTaskUI  interface [Fig 1]. 

    At first, before beginning the task, it is necessary to define the range of the process by using the SetRange method.

    At each step, the dialog box is modified:

    The task is stopped if the end user clicks on the Cancel button. The IsInterrupted method returns FALSE if the end user has clicked on the button or if the Cancel button does not exist. If the command has been interrupted, the method returns E_FAIL, and the dialog box will be closed. 

  4. Coding the GetCatalogName method
    5. ...
HRESULT CAAAfrProgressTaskSampleCmd::GetCatalogName (CATString * oCatalogName)
{
    if ( NULL == oCatalogName ) return E_FAIL ;

    *oCatalogName = CATString("CAAAfrProgressTaskSampleCmd");
    return S_OK ;
}
...

    This method returns the name of the NLS file which contains the title, the default name of the object concerned and the default comment. See the next section "Modifying the Nls file"

  5. Coding the GetIcon method
    6. ...
HRESULT CAAAfrProgressTaskSampleCmd::GetIcon(CATString  * oIcon) 
{
    if ( NULL == oIcon ) return E_FAIL ;

    *oIcon = CATString("I_CAAProgressClock");
    return S_OK ;
}
...

    The  I_CAAProgressClock.bmp icon can be found in the CNext/resources/graphic/icons/normal of the CAAApplicationFrame.edu.

  6. Modifying the CAAAfrProgressTaskSampleCmd.CATNls file

    7. Each label of the dialog box is prefixed by the keyword ProgressTaskUI:

    ...
ProgressTaskUI.Title = "Computing...";
ProgressTaskUI.ObjectName = "Model";
ProgressTaskUI.Comment = "Step ..."; // Not used in the use case
...

    In this use case, only the Title and the ObjectName are useful. For the comment, the message is changed at each step, so the default text "Step ..." is not used. At each step the message is constructed thanks to the CommentRuntime keyword. The parameter is the number of the step. 

    ...
ProgressTaskUI.CommentRuntime = "Step /p1 ...";
  7. Declaring the command as a component

    8. An object which implements an interface must be a component. 

    ...
class CAAAfrProgressTaskSampleCmd : public CATDlgDialog
{
    CATDeclareClass;
    ...      
 public :      

...
    The CATDeclareClass macro declares that the class CAAAfrProgressTaskSampleCmd belongs to a component. 
    ...
CATImplementClass(CAAAfrProgressTaskSampleCmd, Implementation, CATCommand, CATNull);
...

    The CATImplementClass macro declares that the CAAAfrProgressTaskSampleCmd class is a component main class thanks the Implementation keyword, and OM-derives [1] from CATCommand. 

    ...
#include <TIE_CATIProgressTask.h> 
TIE_CATIProgressTask(CAAAfrProgressTaskSampleCmd);
...
    The CAAAfrProgressTaskSampleCmd class states that it implements the CATIProgressTask interface thanks to the TIE_CATIProgressTask macro. 

    The interface dictionary, the CAAApplicationFrame.edu.dico file, located in the CNext/code/dictionary of the CAAApplicationFrame.edu framework contains the following line:

    ...
CAAAfrProgressTaskSampleCmd CATIProgressTask  libCAAAfrProgressTask
...

[Top]

In Short

This article shows how to create an interruptible task with an indicator of progression. The object which contains the task implements the CATIProgressTask interface and the task is itself launched by an CATTaskControler class instance.

[Top]

References

[1] Object Modeler Component and Implementation Inheritance
[Top]

History

Version: 1 [Mar 2002] Document created
[Top]

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