3D PLM Enterprise Architecture

User Interface - Frame

Creating Search Queries

How to create queries to look for objects in V5 document ?
Use Case

Abstract

This article shows how to create and launch queries to look for objects in V5 documents.

What You Will Learn With This Use Case

This use case is intended to show you how to create and launch queries to look for objects in V5 documents. You will specially learn:

Before getting to the use case itself, it is important to already be familiar with the basic notions of the Search. See the referenced article [1] for an overview.

[Top]

The CAACafSearch Use Case

CAACafSearch is a use case of the CAACATIAApplicationFrm.edu framework that illustrates InteractiveInterfaces framework capabilities.

[Top]

What Does CAACafSearch Do

The CAACafSearch use case is a state command [2] integrated in the frame V5 thanks to an add-in of the General workshop [3]. It means that the command is available whatever the open document. 

Fig.1: The Search Demonstrator Command 

This command, the Search Demonstrator... command,  proposes to the end user the choice between pre-defined criteria and several contexts thanks to this user interface:

Fig.2: The Search Demonstrator Dialog Box

There are height pre-defined criteria which are the following:

Fig.3: The Criterion List

All the criteria will be created and deleted at the beginning of the state command. Only the text of the criteria (in NLS or Transformat format) will be kept before its destruction. When the end user clicks the Launch button, an action method is triggered. In this method, a criterion is re-created from the text. A query with this criterion and with the current context is launched.

 

There are four contexts which are the following:

Fig.4: The Context List
Refer to the technical article [1] for more details about these four contexts.

When the end user clicks on the Launch button, the count of found elements is displayed in the editor and the elements are pre-highlighted. 

Fig.5: A Query Result
This picture shows the result for the first query. Three elements are highlighted in the specification tree. In the visible space of the 3D viewer, only the point and the extrude are pre-highlighted. The sketch will appear in  pre-highlighted mode if you switch to the hidden space. 

[Top]

How to Launch CAACafSearch

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

But just before launching the execution, edit the CAAApplicationFrame.edu.dico interface dictionary file located in the dictionary directory of the CAAApplicationFrame.edu framework:

Windows InstallRootDirectory\CAAApplicationFrame.edu\CNext\code\dictionary\
UNIX InstallRootDirectory/CAAApplicationFrame.edu/CNext/code/dictionary/

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

In this file, remove the "#" character before the two following lines, and then run mkCreateRuntimeView.

...
#CAAAfrGeneralWksAddin       CATIWorkbenchAddin          libCAAAfrGeneralWksAddin  
#CAAAfrGeneralWksAddin       CATIAfrGeneralWksAddin      libCAAAfrGeneralWksAddin
...

The two line deal with the General workshop add-in described in the CAAAfrGeneralWksAddin use case [3] located in the CAAAfrGeneralWksAddin.m module (CAAApplicationFrame.edu framework)

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:

  1. On the File menu, click Open
  2. File Selection Dialog box click CAACafSearch.CATPart (*) and click Open
  3. On the Edit menu, click Search Demonstrator...
  4. In the Search Demonstrator Dialog box choose a criterion and a context
  5. Push Launch 
  6. Click Close
  7. On the File menu, click Open
  8. File Selection Dialog box click CAACafSearch.CATProduct (*) and click Open
  9. On the Edit menu, click Search Demonstrator...
  10. In the Search Demonstrator Dialog box choose a criterion and a context 
  11. Push Launch 
  12. Click Close

(*) The document is located in the InputData directory of the CAACATIAApplicationFrm.edu framework:

Windows InstallRootDirectory\CAACATIAApplicationFrm.edu\InputData\
Unix InstallRootDirectory/CAACATIAApplicationFrm.edu/InputData/

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

[Top]

Where to Find the CAACafSearch Code

The CAACafSearch use case is made of several classes located in the CAACafSearch.m module of the CAACATIAApplicationFrm.edu framework:

Windows InstallRootDirectory\CAACATIAApplicationFrm.edu\CAACafSearch.m\
Unix InstallRootDirectory/CAACATIAApplicationFrm.edu/CAACafSearch.m/

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

There are three classes:

CAACafSearchCmd The state command which creates the queries and enables the end user to launch them and see the result in the PSO. Only the piece of code in relationship with the Search API will be explained here.
CAACafSearchDlg The dialog box associated with the CAACafSearchCmd state command. This class will be not detailed here.
CAACafLaunchNextQueryNotification The notification sent by the CAACafSearchDlg command when the end user clicks the Launch button. This notification will be received by the CAACafSearchCmd command to valuate a dialog agent [5] and trigger an action to launch the query and display the result. This class will be not detailed here.

The pre-requisite code is the add-in of the General workshop. This add-in contains the Search Demonstrator command. Refer to the Where to Find the CAAAfrGeneralWksAddin Code section of the CAAAfrGeneralWksAddin [3] use case for details.

[Top]

Step-by-Step

There are four logical steps in CAACafSearch:

  1. Creating the Engine, Context and Services Components
  2. Creating Criteria
  3. Launching Queries
  4. Displaying Found Objects in PSO

[Top]

Creating the Engine, Context and Services Components

In the CAACafSearchCmd class constructor, the Search components always used during the state command are created. Each component (xxx) is instantiated by the CATCreateInstance global function and thanks a CLSID contained in the CATIniSearchxxxComponent file [6]

...
#include "CATIIniSearchServices.h"
#include "CATIIniSearchEngine.h"
#include "CATIIniSearchContext.h"
#include "CATIniSearchEngineComponent.h"
#include "CATIniSearchContextComponent.h"
#include "CATIniSearchServicesComponent.h"
...      
    ::CATCreateInstance(CLSID_CATIniSearchEngineComponent, NULL, 0, 
                                     IID_CATIIniSearchEngine,
                                     (void**)&_pIniSearchEngineOnCurrentEngine);

    ::CATCreateInstance(CLSID_CATIniSearchContextComponent, NULL, 0, 
                                     IID_CATIIniSearchContext,
                        (void**)&_pIniSearchContextOnCurrentContext);


    ::CATCreateInstance(CLSID_CATIniSearchServicesComponent, NULL, 0, 
                                     IID_CATIIniSearchServices,
                                     (void**)&_pIniSearchServices);
...

The first component is the Search engine component. It is handled by _pIniSearchEngineOnCurrentEngine  a CATIIniSearchEngine interface pointer. It will be used in an action method of the CAACafSearchCmd to launch the query selected by the end user. 

The second component is the Search context component. It is handled by _pIniSearchContextOnCurrentContext a CATIIniSearchContext interface pointer. Before launching the query, the context selected by the end user will be retrieved from the CAACafSearchDlg class instance. The context component is one parameter of the query, the second being the criterion. 

The third component is a component of services. It is handled by _pIniSearchServices a CATIIniSearchServices interface pointer.

The service's component is used in the Creating Queries section for the Name Based Criterion, and like the first two components, in the Launching Queries section too.

[Top]

Creating Criteria

eight criteria (Fig. 3) are created in a method called by the CAACafSearchCmd constructor. For each criterion the methodology is the same: 

  1. The criterion is created
  2. Its text is kept in a global list 
  3. The criterion is deleted. 

The text is kept for two raisons:  to build the contents of the CAACafSearchDlg's combo and to re-create the criterion just before launching the query.

Simple criteria:

Advanced criteria:

 

[Top]

Launching Queries

The end user has pushed the Launch button - See Fig 2 - an action method of the CAACafSearchCmd class is trigerred. This action method should first re-create the criterion from a text, retrieve the current context and then launch a query. 

First the text of the criterion is retrieved from the end user selection. 

...
  int CriterionIndex = -1 ;
  _pSearchDlg->GetCurrentCriterion(CriterionIndex);

  CATUnicodeString CriterionText = "";
  if ( NULL != _pListCriterionTexts )
  {
     if ( (CriterionIndex >= 1) && (CriterionIndex <= _pListCriterionTexts->Size()) )
     {
        CriterionText = (*_pListCriterionTexts)[CriterionIndex];
     }
  }
...

Then, the context is retrieved with the GetCurrentContext method, a CAACafSearchDlg class method. 

...
  CATIIniSearchContext::Scope ContextValue = CATIIniSearchContext::Everywhere ;
  _pSearchDlg->GetCurrentContext(ContextValue);
...

A criterion is re-created thanks to the DecodeStringToCriterion method of the CATIIniSearchServices interface. _pIniSearchServices is an handle on the service's component created in the Creating the Engine, Context and Services Components section. CriterionText is the text of the criterion, just above retrieved, and pIniSearchCriterion is the CATIIniSeachCriterion interface pointer on the newly criterion. The second argument, FALSE, means that in case of error, no window will be launched. 

...
     CATIIniSearchCriterion * pIniSearchCriterion = NULL ;
     rc = _pIniSearchServices->DecodeStringToCriterion(CriterionText,
                                                        FALSE,
                                                        pIniSearchCriterion);
...

After the criterion creation, the context component can be updated with the current scope. _pIniSearchContextOnCurrentContext is an handle on the context component created in the Creating the Engine, Context and Services Components section. 

...
 rc = _pIniSearchContextOnCurrentContext->SetScope(ContextValue);
...

Then, the query is composed by using the context and the criterion. _pIniSearchEngineOnCurrentEngine is an handle on the search engine component created in the Creating the Engine, Context and Services Components section. 

...
 rc = _pIniSearchEngineOnCurrentEngine->SetCriterionAndContext(pIniSearchCriterion,
                                                 _pIniSearchContextOnCurrentContext);
...

Finally, the query can be launched. The default argument of the LaunchSearchOnDocument method, NULL, is used. It means that the search is done on the current document. 

...
 rc = _pIniSearchEngineOnCurrentEngine->LaunchSearchOnDocument()
...

The result of the search is analyzed in the next section.

[Top]

Displaying Found Objects in PSO

The found objects should be pre-highlighted. They will be set in the CATPSO instance associated with the current document (in fact the editor of the current document). This instance, _pPso, has been retrieved in the CAACafSearchCmd class constructor such as:

...
  CATFrmEditor * pEditor = GetEditor();
  if ( NULL !=  pEditor )
  {
      _pPso = pEditor->GetPSO();
  }
...

The GetEditor method is a CATStateCommand method. It retrieves the CATFrmEditor class instance associated with the active document. This instance has created the CATPSO class instance [6].

The GetFoundObjects method of the CATIIniSeachEngine interface retrieves all the found objects. The returned value, pListOfFoundObjects, is a CATSO object, it means that the method returns a list of complete paths. Each value of the list is a CATPathElement (Visualization framework). Note that pListOfFoundObjects cannot be NULL, because the GetFoundObjects method returns E_FAIL if no object are found. 

...
  CATSO * pListOfFoundObjects = NULL ;
  int nbelt = 0 ;
  _pIniSearchEngineOnCurrentEngine->GetFoundObjects(pListOfFoundObjects);
...

Since several objects can be found, the complete path of the objects are set in the CATPSO thanks to the AddElements method, and after the last addition, the EndAddElements is called.

...
  nbelt = pListOfFoundObjects->GetSize();
        
  if ( NULL != _pPso )
  {
     for ( int i= 0 ; i < nbelt ; i++ )
     {
        CATBaseUnknown * pCurrent = (*pListOfFoundObjects)[i] ;
        if ( NULL != pCurrent )
        {
                 _pPso->AddElements(pCurrent);
        }
      }
      _pPso->EndAddElements();
  }
...

[Top]

In Short

This use case explains how to use the Search API to create queries and launch them. 

[Top]

References

[1] Search Overview
[2] Getting Started with State Dialog Commands
[3] Making Your Document Independent Command Available in All Workbenches
[4] Building and Launching a CAA V5 Use Case
[5] Associating a Dialog Box with a Dialog Agent - 2
[6] Instantiating a Component Using its CLSID
[7] Application Frame Overview
[Top]

History

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

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