Catalog Modeler

What You Will Learn With This Use case

The ComponentsCatalogsInterfaces framework provides a Dialog box to browse catalogs and instantiate components. This Dialog box is the Catalog Browser and it implements the CATICatalogBrowser interface.

The aim of this article is to understand each methods of the CATICatalogBrowser interface. A demonstrator allows you

• To launch methods and so visualize automatically their effect on the Catalog browser instance 
• To see how to use the others methods

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

[Top]

The CAAMmrCatalogBrowser Use Case

CAAMmrCatalogBrowser is a use case of the CAAMechanicalModeler.edu framework that illustrates ComponentsCatalogsInterfaces framework capabilities.

[Top]

What Does CAAMmrCatalogBrowser Do

This use case is a Catalog Browser demonstrator. In an add-in of the Product Structure Workbench, the  "Catalog Browser Demonstrator ..." command is defined. This command is included in the Catalog toolbar as you can see in the next picture:

Fig.1 The Catalog Toolbar

When you launch the command, the following dialog box appears:

Fig.2 The Catalog Browser Demonstrator Dialog Box

This dialog box is made up of two frames at the first level:

• Catalog Browser Properties frame

This frame contains all the options to customize the display of the Catalog Browser. These options are group together by functionality in several sub-objects

• Window Options and Display frame 

All the options in this frame are for the Catalog Browser creation. During the life of the Catalog Browser you cannot change these options. This frame is unavailable while a Catalog Browser is opened.

• Modal, once the Catalog Browser is opened, the end user cannot select anything else outside the Catalog Browser
• Window Button: the Catalog Browser can have the Close button or the Ok and Cancel buttons
• Tree : the Catalog Browser displays the descriptions with a tree structure

The third options are exclusives:

• Large icons: the preview image of the description are a size of 131x110 pixels

Large icons

• Small icons: the preview image of the description are reduced- for a chapter the icons is "mixed" with the "file" icons: 

Small icons

• Detail: the visible keywords of the descriptions are displayed

Details mode

• Instantiation Options frame 

All the options in this frame are for the Catalog Browser creation and can be changed during the Catalog Browser life.

• Authorize Other Catalog Selection check button

This option can only be set after the Catalog Browser creation. 

• Open button

Launch the Catalog Browser creation [Fig.3]. This button is unavailable while a Catalog Browser is opened.

• Filtering frame

This frame is about the filtering and is available while a Catalog Browser is opened. 

• Query editor

The query to apply to the current chapter

• User check button

If the button is checked, the query set in the Query editor is an user query otherwise it is an "internal" query. 

• The filter on the chapter

It is the real filter applied to the chapter. Three possible cases:

• All the queries set in the Query editor are user queries, the filter is the current expression
• All the queries set in the Query editor are internal queries, the filter is the current expression
• The filter is a AND buildup between the last user query and the last internal  query.

This two levels of filtering enables to fix a query by code (internal query) and the end user can only make a filtering among the first filtering thanks to the Filter editor in the Catalog Browser dialog box. As soon as the chapter is changed, the filtering is lost. 

• Current Selection frame

This frame is available while the Catalog Browser is opened. It comprises the following objects:

• Catalog editor

The name of the current opened catalog

• Description editor

The name of the object pointed by the current selected description

• Launch button

The Launch button is available only if the current selected description pointes towards a component and not a chapter. The CAAMmrCatalogInstantiation [2] explains this part of code.

The Catalog Browser Dialog box:

Fig.3 The Catalog Browser Dialog Box

Advice: Once the Catalog Browser is opened, the end user can change some options about the display or the filter, and because these modifications are without notifications the Catalog Browser Demonstrator is not updated.  

[Top]

How to Launch CAAMmrCatalogBrowser

To launch CAAMmrCatalogBrowser , you will need to

• Set up the build time environment
• Compile the following modules of the CAAMechanicalModeler.edu framework with their prerequisites
• CAAMechanicalModelerEduUUID.m
• CAAMmrCatalogCombCrv.m
• CAAMmrCatalogProductAddin.m
• CAAMmrCatalogUI.m
• CAAMmrCombinedCurve.m
• CAAMmrCombinedCurveUI.m
• CAAMmrCreateCombCrvCatalog.m
• Set up the run time environment
• Remove the # character in the CAAMechanicalModeler.edu.dico in front of the following lines

CAAMmrCatalogPrdAddin CATIWorkbenchAddin libCAAMmrCatalogProductAddin CAAMmrCatalogPrdAddin CATIPrsConfigurationAddin libCAAMmrCatalogProductAddin

• Export the CAACatalogFileName variable

Unix: export CAACatalogFileName=InstallRootDirectory/CAAComponentsCatalogs.edu/InputData/CAATool.catalog Windows: set CAACatalogFileName=InstallRootDirectory\CAAComponentsCatalogs.edu\InputData\CAATool.catalog

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

• Launch CATIA
•  When the the application is ready: 
  • On the Start menu click Product Structure
  • Launch the Catalog Browser Demonstrator ... command
  • In the Catalog Browser Demonstrator dialog box try all the options described above.

[Top]

Where to Find the CAAMmrCatalogBrowser Code

The CAAMmrCatalogBrowser use case explains the CAAMmrBrowserCmdDlg class which defines the Catalog Browser Demonstrator dialog box [Fig.2]. This class is located in the CAAMmrCatalogUI.m module of the CAAMechanicalModeler.edu framework.

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

[Top]

Step-by-Step

There are three logical steps in the CAAMmrCatalogBrowser use case:

1. The CAAMmrBrowserCmdDlg header file
2. The CAAMmrBrowserCmdDlg source file
3. The CAAMmrBrowserCmdDlg resource file

1. The header file

#include "CATDlgDialog.h" class CATDlgEditor; class CATDlgPushButton; class CATDlgRadioButton; class CATDlgCheckButton; class CATDlgFrame; class CATDlgPushButton; class CATFrmEditor ; class CATICatalogBrowser ; class CAAMmrBrowserCmdDlg : public CATDlgDialog { DeclareResource(CAAMmrBrowserCmdDlg,CATDlgDialog) ; public: CAAMmrBrowserCmdDlg(CATDialog * iParent); ~CAAMmrBrowserCmdDlg(); void Build(); private: void CloseCatalog(); void OKCatalog (CATCommand* iFrom, CATNotification* iNotif, CATCommandClientData iData); void CancelCatalog (CATCommand* iFrom, CATNotification* iNotif, CATCommandClientData iData); void ChangeChapter (CATCommand* iFrom, CATNotification* iNotif, CATCommandClientData iData); void SelectDescription(CATCommand* iFrom, CATNotification* iNotif, CATCommandClientData iData); void ChangeCatalogAuthorization (CATCommand* iFrom, CATNotification* iNotif, CATCommandClientData iData); void InstantiationAuthorization (CATCommand* iFrom, CATNotification* iNotif, CATCommandClientData iData); void ChangeQuery (CATCommand* iFrom, CATNotification* iNotif, CATCommandClientData iData); void LaunchInstantiation (CATCommand* iFrom, CATNotification* iNotif, CATCommandClientData iData); void CreateBrowser (CATCommand* iFrom, CATNotification* iNotif, CATCommandClientData iData); private: CATDlgEditor * _pDescEditor; CATDlgEditor * _pCatalogEditor; CATDlgEditor * _pQueryEditor ; CATDlgEditor * _pQueryResultEditor ; CATDlgCheckButton * _pModalButton ; CATDlgCheckButton * _pWithTreeButton; CATDlgCheckButton * _pInstantiateStateButton ; CATDlgCheckButton * _pChgtCatalogStateButton ; CATDlgCheckButton * _pQueryStateButton ; CATDlgRadioButton * _pWithOkButton; CATDlgRadioButton * _pWithCloseButton; CATDlgRadioButton * _pWithSmallIconsButton; CATDlgRadioButton * _pWithLargeIconsButton; CATDlgRadioButton * _pWithDetailsButton; CATDlgPushButton * _pInstButton ; CATDlgPushButton * _pOpenBrowserButton ; CATDlgFrame * _pBrowserOptionsFrame ; CATDlgFrame * _pBrowserQueryFrame ; CATDlgFrame * _pInstFrame ; CATFrmEditor * _pDocumentEditor ; CATBoolean _FirstOpen ; CATICatalogBrowser * _pICatalogBrowser; CATNotification * _pOKNotif ; CATNotification * _pCancelNotif; CATNotification * _pCloseNotif; CATNotification * _pSelectNotif; CATNotification * _pChangeNotif; };

The CAAMcaUdfLoftDlg class derives from the CATDlgDialog class and contains 

• The following methods:
• Methods called once: Build, to construct the dialog objects
• Four callback methods executed when a notification comes from the Catalog Browser (OKCatalog,CancelCatalog,ChangeChapter, SelectDescription)
• Six  callback methods executed when a notification comes from the current Dialog box (ChangeCatalogAuthorization ,InstantiationAuthorization ,DrapAndDropAuthorization ,ChangeQuery,LaunchInstantiation,CreateBrowser )
• The following data members:
• A set of Dialog objects (_pDescEditor to _pInstFrame ) which makes up the current Dialog box
• The editor associated with the current document, _pDocumentEditor 
• A boolean, _FirstOpen , which is initialized TRUE in the constructor and set to FALSE after the first Catalog Browser creation
• _pICatalogBrowser is the CATICatalogBrowser interface pointer on the current Catalog Browser instance
• There are five pointers on a CATNotification  class. These notifications are created by the Catalog Browser instance.

The DeclareResource macro declares that there is a CAAMmrBrowserCmdDlg.CATNls file - see at the end of the article;

2. The source file
• The includes

#include "CAAMmrBrowserCmdDlg.h" #include "CATIAlias.h" #include "CATDlgFrame.h" #include "CATDlgEditor.h" #include "CATDlgLabel.h" #include "CATDlgPushButton.h" #include "CATDlgCheckButton.h" #include "CATDlgRadioButton.h" #include "CATDlgGridConstraints.h" #include "CATFrmEditor.h" #include "CATICatalogBrowserFactory.h" #include "CATICatalogBrowser.h" #include "CATICatalogDescription.h" #include "CATICatalogChapter.h" #include "CATICatalogQueryResult.h" #include "CATICatalogLink.h" #include "CATICatalogInstantiation.h" #include "CATGetEnvValue.h" #include "iostream.h" ...

• The constructor

... CAAMmrBrowserCmdDlg::CAAMmrBrowserCmdDlg(CATDialog* iParent) : CATDlgDialog (iParent, "CAAMmrBrowserCmdDlg", CATDlgWndBtnOKCancel|CATDlgWndAutoResize|CATDlgGridLayout) , _pDescEditor (NULL) , _pCatalogEditor (NULL) , _pQueryEditor (NULL) , _pQueryResultEditor(NULL) , _pModalButton (NULL) , _pWithOkButton (NULL) , _pWithCloseButton (NULL) , _pWithTreeButton (NULL) , _pWithSmallIconsButton (NULL) , _pWithLargeIconsButton (NULL) , _pWithDetailsButton (NULL) , _pInstantiateStateButton (NULL) , _pChgtCatalogStateButton (NULL) , _pOpenBrowserButton (NULL) , _pQueryStateButton (NULL) , _pInstButton (NULL) , _pBrowserQueryFrame (NULL) , _pInstFrame (NULL) , _pBrowserOptionsFrame (NULL) , _pOKNotif (NULL) , _pCancelNotif (NULL) , _pCloseNotif (NULL) , _pSelectNotif (NULL) , _pChangeNotif (NULL) , _pDocumentEditor (NULL) , _pICatalogBrowser (NULL) , _FirstOpen (TRUE) { _pDocumentEditor = CATFrmEditor::GetCurrentEditor(); SetDefaultButton(NULL); } ...

As usual, all the data members which are pointers are initialized to NULL. 

Notice that the _pDocumentEditor is initialized here. It is strongly recommended to use the static GetCurrentEditor method at the beginning of the command. At this time the editor is those which has launched the command. 

At last, it is set that there is no default button to avoid an enclosure of the Dialog box when the end user enters "enter" in an editor.

• The destructor

CAAMmrBrowserCmdDlg::~CAAMmrBrowserCmdDlg() { CloseCatalog(); _pDescEditor = NULL; _pCatalogEditor = NULL ; _pQueryResultEditor = NULL ; _pQueryEditor = NULL ; _pModalButton = NULL; _pWithOkButton = NULL; _pWithCloseButton = NULL; _pWithTreeButton = NULL; _pWithSmallIconsButton = NULL; _pWithLargeIconsButton = NULL; _pWithDetailsButton = NULL; _pInstantiateStateButton = NULL ; _pChgtCatalogStateButton = NULL ; _pQueryStateButton = NULL ; _pInstButton = NULL ; _pOpenBrowserButton = NULL ; _pBrowserOptionsFrame = NULL ; _pBrowserQueryFrame = NULL ; _pInstFrame = NULL ; _pDocumentEditor = NULL; _pICatalogBrowser = NULL; _pOKNotif = NULL; _pCancelNotif = NULL; _pCloseNotif = NULL; _pSelectNotif = NULL; _pChangeNotif = NULL; }...

As usual any pointer data members are set NULL. To be sure to close a possible Catalog Browser instance, the CloseCatalog method is called.

• The Build method

void CAAMmrBrowserCmdDlg::Build() { //1- Dialog Object Construction //1-1 Catalog's browser Properties frame CATDlgFrame* pBrowserFrame = new CATDlgFrame (this, "FrameBrowser", CATDlgGridLayout); //1-1-1 Catalog's browser options - options used for open _pBrowserOptionsFrame = new CATDlgFrame (pBrowserFrame, "FrameBrowserOptions", CATDlgGridLayout); CATDlgLabel* pBehaviorLabel = new CATDlgLabel (_pBrowserOptionsFrame, "BehaviorLabel"); _pModalButton = new CATDlgCheckButton (_pBrowserOptionsFrame, "ModalCheckButton"); CATDlgLabel* pButtonLabel = new CATDlgLabel (_pBrowserOptionsFrame, "ButtonLabel"); CATDlgFrame* pButtonFrame = new CATDlgFrame (_pBrowserOptionsFrame, "ButtonFrame", CATDlgFraNoFrame|CATDlgGridLayout); _pWithOkButton = new CATDlgRadioButton (pButtonFrame, "WithOK"); _pWithCloseButton = new CATDlgRadioButton (pButtonFrame, "WithClose"); _pWithCloseButton->SetState (CATDlgCheck); CATDlgLabel* pDisplayOptionsLabel = new CATDlgLabel (_pBrowserOptionsFrame, "DisplayOptionsLabel"); CATDlgFrame* pDisplayOptionsFrame = new CATDlgFrame (_pBrowserOptionsFrame, "DispOpFrame", CATDlgFraNoFrame|CATDlgGridLayout); _pWithTreeButton = new CATDlgCheckButton (pDisplayOptionsFrame, "Tree"); _pWithSmallIconsButton = new CATDlgRadioButton (pDisplayOptionsFrame, "Small"); _pWithSmallIconsButton->SetState (CATDlgCheck); _pWithLargeIconsButton = new CATDlgRadioButton (pDisplayOptionsFrame, "Large"); _pWithDetailsButton = new CATDlgRadioButton (pDisplayOptionsFrame, "Detail"); //1-1-2 Options for Instantiation CATDlgFrame* pBrowserInstMngtFrame = new CATDlgFrame (pBrowserFrame, "FrameBrowserInstMngt", CATDlgGridLayout); _pInstantiateStateButton = new CATDlgCheckButton (pBrowserInstMngtFrame, "InstantiateState"); //1-1-3 Authorize or not the catalog changement- _pChgtCatalogStateButton = new CATDlgCheckButton (pBrowserFrame, "ChgtCatalogState"); //1-1-4 Button to open the Catalog Browser _pOpenBrowserButton = new CATDlgPushButton (pBrowserFrame, "ButtonOpenBrowser"); //1-1-5 Filtering _pBrowserQueryFrame = new CATDlgFrame (pBrowserFrame, "FrameBrowserQuery", CATDlgGridLayout); _pBrowserQueryFrame->SetSensitivity(CATDlgDisable); CATDlgLabel* pQueryLabel = new CATDlgLabel (_pBrowserQueryFrame, "QueryLabel"); _pQueryEditor = new CATDlgEditor (_pBrowserQueryFrame, "EditorQuery"); _pQueryEditor->SetVisibleTextWidth (25); _pQueryStateButton = new CATDlgCheckButton (_pBrowserQueryFrame, "QueryState"); _pQueryStateButton->SetState(CATDlgCheck); // Default behavior CATDlgLabel * pQueryResultLabel = new CATDlgLabel (_pBrowserQueryFrame, "QueryResultLabel"); _pQueryResultEditor = new CATDlgEditor (_pBrowserQueryFrame, "QueryResultEditor",CATDlgEdtReadOnly); // 1-2 Instantiation Frame _pInstFrame = new CATDlgFrame (this, "FrameInst", CATDlgGridLayout); _pInstFrame->SetSensitivity(CATDlgDisable); CATDlgLabel* pCatalogLabel = new CATDlgLabel (_pInstFrame, "CatalogLabel"); _pCatalogEditor = new CATDlgEditor (_pInstFrame, "EditorCatalog"); _pCatalogEditor->SetVisibleTextWidth (25); CATDlgLabel* pDescLabel = new CATDlgLabel (_pInstFrame,"DescLabel"); _pDescEditor = new CATDlgEditor (_pInstFrame,"EditorDesc"); _pDescEditor->SetVisibleTextWidth (25); _pInstButton = new CATDlgPushButton (_pInstFrame,"InstButton"); _pInstButton->SetSensitivity(CATDlgDisable); //2- Dialog Box Layout SetGridRowResizable (1, 1); SetGridColumnResizable (0, 1); // 2-1 Inside Catalog's browser Properties frame pBrowserFrame->SetGridConstraints (0, 0, 1, 1, CATGRID_4SIDES); _pInstFrame->SetGridConstraints (1, 0, 1, 1, CATGRID_4SIDES); _pInstFrame->SetGridColumnResizable (1, 1); // 2-2 Inside Catalog Browser Properties _pBrowserOptionsFrame->SetGridConstraints (0, 0, 1, 1, CATGRID_4SIDES); pBrowserInstMngtFrame->SetGridConstraints (1, 0, 1, 1, CATGRID_4SIDES); _pChgtCatalogStateButton->SetGridConstraints (2, 0, 1, 1, CATGRID_4SIDES); _pOpenBrowserButton->SetGridConstraints (3, 0, 1, 1, CATGRID_4SIDES); _pBrowserQueryFrame->SetGridConstraints (4, 0, 1, 1, CATGRID_4SIDES); // 2-2-1 Inside Catalog Browser Options frame pBehaviorLabel->SetGridConstraints (0, 0, 1, 1, CATGRID_LEFT|CATGRID_RIGHT|CATGRID_TOP); _pModalButton->SetGridConstraints (0, 1, 1, 1, CATGRID_4SIDES); pButtonLabel->SetGridConstraints (1, 0, 1, 1, CATGRID_LEFT|CATGRID_RIGHT|CATGRID_TOP); pButtonFrame->SetGridConstraints (1, 1, 1, 1, CATGRID_4SIDES); pButtonFrame->SetGridColumnResizable (0, 1); pDisplayOptionsLabel->SetGridConstraints (2, 0, 1, 1, CATGRID_LEFT|CATGRID_RIGHT|CATGRID_TOP); pDisplayOptionsFrame ->SetGridConstraints (2, 1, 1, 1, CATGRID_4SIDES); pDisplayOptionsFrame->SetGridColumnResizable (0, 1); // 2-2-1-a Inside the Button frame _pWithOkButton ->SetGridConstraints (0, 0, 1, 1, CATGRID_4SIDES); _pWithCloseButton ->SetGridConstraints (1, 0, 1, 1, CATGRID_4SIDES); // 2-2-1-b Inside the Display Option frame _pWithTreeButton ->SetGridConstraints (0, 0, 1, 1, CATGRID_4SIDES); _pWithSmallIconsButton->SetGridConstraints (1, 0, 1, 1, CATGRID_4SIDES); _pWithLargeIconsButton->SetGridConstraints (2, 0, 1, 1, CATGRID_4SIDES); _pWithDetailsButton ->SetGridConstraints (3, 0, 1, 1, CATGRID_4SIDES); // 2-2-2 Inside the Catalog Browser Managment _pInstantiateStateButton->SetGridConstraints (1, 0, 1, 1, CATGRID_4SIDES); // 2-2-2 Inside the Catalog Browser Query pQueryLabel->SetGridConstraints (0, 0, 1, 1, CATGRID_4SIDES); _pQueryEditor->SetGridConstraints (0, 1, 1, 1, CATGRID_4SIDES); _pQueryStateButton->SetGridConstraints (1, 0, 1, 1, CATGRID_4SIDES); pQueryResultLabel->SetGridConstraints (2, 0, 1, 1, CATGRID_4SIDES); _pQueryResultEditor->SetGridConstraints (2, 1, 1, 1, CATGRID_4SIDES); // 2-2 Inside Instantiation Frame pCatalogLabel->SetGridConstraints (0, 0, 1, 1, CATGRID_4SIDES); _pCatalogEditor->SetGridConstraints (0, 1, 1, 1, CATGRID_4SIDES); pDescLabel->SetGridConstraints (1, 0, 1, 1, CATGRID_4SIDES); _pDescEditor->SetGridConstraints (1, 1, 1, 1, CATGRID_4SIDES); _pInstButton ->SetGridConstraints (2, 0, 1, 1, CATGRID_4SIDES); //3- Dialog Box Callbacks AddAnalyseNotificationCB (_pOpenBrowserButton, _pOpenBrowserButton->GetPushBActivateNotification(), (CATCommandMethod) &CAAMmrBrowserCmdDlg::CreateBrowser, (CATCommandClientData) NULL); AddAnalyseNotificationCB (_pInstantiateStateButton, _pInstantiateStateButton->GetChkBModifyNotification (), (CATCommandMethod) &CAAMmrBrowserCmdDlg::InstantiationAuthorization, (CATCommandClientData) NULL); AddAnalyseNotificationCB (_pChgtCatalogStateButton, _pChgtCatalogStateButton->GetChkBModifyNotification (), (CATCommandMethod) &CAAMmrBrowserCmdDlg::ChangeCatalogAuthorization, (CATCommandClientData) NULL); AddAnalyseNotificationCB (_pQueryEditor, _pQueryEditor->GetEditModifyExtNotification(), (CATCommandMethod) &CAAMmrBrowserCmdDlg::ChangeQuery, (CATCommandClientData) NULL); AddAnalyseNotificationCB (_pInstButton, _pInstButton->GetPushBActivateNotification (), (CATCommandMethod) &CAAMmrBrowserCmdDlg::LaunchInstantiation, (CATCommandClientData) NULL); }

As usual, the Build method contains three parts:

• Dialog Objects construction
• Dialog Objects arrangement
• Callback methods definition
• The CreateBrowser method

This method is a callback method called when the end user clicks on the "Open" button of the Catalog Browser Demonstrator Dialog box. The goal of this method is to create a new Catalog Browser instance.

void CAAMmrBrowserCmdDlg::CreateBrowser(CATCommand* iFrom,CATNotification* iNotif, CATCommandClientData iData) { CATCciCatalogBrowserDisplayOptions options = CATCatalogDisplayCombo ; if ( NULL != _pModalButton) options |= (_pModalButton ->GetState() == CATDlgCheck) ? CATCatalogDisplayWndModal : NULL; if ( NULL != _pWithOkButton) options |= (_pWithOkButton ->GetState() == CATDlgCheck) ? CATCatalogDisplayWndBtnOKCancel : NULL; if (NULL != _pWithTreeButton) options |= (_pWithTreeButton ->GetState() == CATDlgCheck) ? CATCatalogDisplayTree : NULL; if (NULL != _pWithSmallIconsButton) options |= (_pWithSmallIconsButton->GetState() == CATDlgCheck) ? CATCatalogDisplayWithSmallIcons : NULL; if (NULL != _pWithLargeIconsButton) options |= (_pWithLargeIconsButton->GetState() == CATDlgCheck) ? CATCatalogDisplayWithLargeIcons : NULL; if (NULL != _pWithDetailsButton) options |= (_pWithDetailsButton ->GetState() == CATDlgCheck) ? CATCatalogDisplayWithDetails : NULL; int DragAndDropAuthorized = 0 ; int InstantiationAuthorized = 0 ; InstantiationAuthorized = (_pInstantiateStateButton ->GetState() == CATDlgCheck) ? 1: 0; }

The first step consists in to retrieve on the Dialog objects the options set by the end user. For the options value, notice that:

• It is initialized with the CATCatalogDisplayCombo value. It enables to have the last three options ( Large icons, Small icons and detail) in a combo. It is recommended to use this option.
• The third first options are not exclusive (CATCatalogDisplayWndModal,CATCatalogDisplayWndBtnOKCancel,CATCatalogDisplayTree)

_pModalButton and _pWithTreeButton are CATDlgCkeckButton and _pWithOkButton is a CATDlgRadioButton independent of the _pModalButton and _pWithTreeButton dialog objects.

• The third last are exclusive (CATCatalogDisplayWithSmallIcons,CATCatalogDisplayWithLargeIcons,CATCatalogDisplayWithDetails)

_pWithSmallIconsButton, _pWithLargeIconsButton,_pWithDetailsButton are CATDlgRadioButton class instances 

... if ( NULL != _pDocumentEditor) { CATICatalogBrowserFactory * pICatalogBrowserFactory = NULL; HRESULT rc = _pDocumentEditor->QueryInterface (IID_CATICatalogBrowserFactory, (void**) &pICatalogBrowserFactory); if (SUCCEEDED(rc)) { pICatalogBrowserFactory->OpenCatalogBrowser (_pICatalogBrowser, options, DragAndDropAuthorized, InstantiationAuthorized); ...

The editor, a CATFrmEditor class instance, implements the CATICatalogBrowserFactory interface. It enables you to create a Catalog Browser instance thanks to the OpenCatalogBrowser method:

• _pICatalogBrowser is the created instance.
• options is the display options initialized in the previous step
• DragAndDropAuthorized can only be  0 ( no drag and drop) in this sample.

Drag and drop is only possible if the current command is the Select command. In this sample, the CAAMmrBrowserCmdDlg command is undefined, since it is a CATDialog command, but it is launched by the CAAMmrBrowserCmd command which is an exclusive command. So the Select command is deleted when the CAAMmrBrowserCmd command is executed [3]. The CAAMmrBrowserCmd command is a state command launched from the Catalog toolbar [Fig.1]. It ends when the end user clicks either on the Ok button, or the Cancel button. This class is located in the CAAMmrCatalogUI.m module of the CAAMechanicalModeler.edu framework such as the CAAMmrBrowserCmdDlg command.

• InstantiationAuthorized, initialized in the previous step, specifies if the instantiations is possible by contextual menu, and double click.

... if ( NULL != _pICatalogBrowser) { CATDlgDialog* window = NULL; rc = _pICatalogBrowser->GetFatherWindow (window)) ; if (SUCCEEDED (rc) ) { window->SetFather (this); window->SetVisibility (CATDlgShow); ...

Once the Catalog browser is created, you must re-parent the Catalog browser window. The GetFatherWindow method retrieves the Catalog browser dialog box, window. SetFather a CATCommand method, enables to receive the notifications sent by the Catalog browser, and so you can set callback on these notifications:

... if (SUCCEEDED (_pICatalogBrowser->GetOKNotification (_pOKNotif)) && _pOKNotif) AddAnalyseNotificationCB (window, _pOKNotif , (CATCommandMethod) &CAAMmrBrowserCmdDlg::OKCatalog, NULL); if (SUCCEEDED (_pICatalogBrowser->GetCancelNotification (_pCancelNotif)) && _pCancelNotif) AddAnalyseNotificationCB (window, _pCancelNotif, (CATCommandMethod) &CAAMmrBrowserCmdDlg::CancelCatalog, NULL); if (SUCCEEDED (_pICatalogBrowser->GetCloseNotification (_pCloseNotif)) && _pCloseNotif) AddAnalyseNotificationCB (window, _pCloseNotif , (CATCommandMethod) &CAAMmrBrowserCmdDlg::CancelCatalog, NULL); if (SUCCEEDED (_pICatalogBrowser->GetChangeChapterNotification (_pChangeNotif)) && _pChangeNotif) AddAnalyseNotificationCB (window, _pChangeNotif , (CATCommandMethod) &CAAMmrBrowserCmdDlg::ChangeChapter, NULL); if (SUCCEEDED (_pICatalogBrowser->GetSelectDescriptionNotification (_pSelectNotif)) && _pSelectNotif) AddAnalyseNotificationCB (window, _pSelectNotif , (CATCommandMethod) &CAAMmrBrowserCmdDlg::SelectDescription, NULL); } ...

The Catalog Browser offers the possibility to initialize the catalog to browse. The SetCurrentCatalogDocId method enables to give a specific catalog from its complete path. To transform a file path to a CATIDocId interface pointer, use the RecoverDocId method of the CATOmDocIdFinder class.

• The first argument is always "File"
• The third is always "catalog"

... if ( TRUE == _FirstOpen ) { char * pCAACatalogFileName = NULL ; CATLibStatus result = ::CATGetEnvValue("CAACatalogFileName",&pCAACatalogFileName); if ( (CATLibSuccess == result) && ( NULL != pCAACatalogFileName) ) { CATUnicodeString CatalogName = pCAACatalogFileName ; free (pCAACatalogFileName) ; pCAACatalogFileName = NULL ; ... CATIDocId * pIDocId = NULL ; rc = CATOmbDocIdFinder::RecoverDocId("File",CatalogName,"catalog",&pIDocId); _pICatalogBrowser->SetCurrentCatalogDocId(pIDocId); pIDocId->Release(); pIDocId = NULL ; ... } ...

The second method BuildCurrentChapterString add the first element of the list, in the selectable chapter list. (The combo list just before the "Current" label )

... CATListOfCATUnicodeString * pList = NULL ; rc = _pICatalogBrowser->BuildCurrentChapterString(pList); if ( SUCCEEDED(rc) && ( NULL!= pList)) { pList->Append ("Nuts"); _pICatalogBrowser->SetCurrentChapter (pList); delete pList; pList = NULL ; } _FirstOpen = FALSE ; } } pICatalogBrowserFactory->Release(); pICatalogBrowserFactory = NULL ; } } ...

• The ChangeChapter method

This method is a callback method called when the end user changes the current chapter in the Catalog Browser Dialog box.

void CAAMmrBrowserCmdDlg::ChangeChapter(CATCommand* iFrom, CATNotification* iNotif, CATCommandClientData iData) { if ( NULL != _pICatalogBrowser ) { if ( NULL != _pCatalogEditor ) { CATIDocId * pIDocId = NULL; HRESULT rc = _pICatalogBrowser->GetCurrentCatalogDocId(&pIDocId); ... if ( SUCCEEDED(rc) && (NULL !=pIDocId) ) { CATUnicodeString CatalogName ; pIDocId->GetIdentifier(CatalogName); _pCatalogEditor->SetText(CatalogName); }else { _pCatalogEditor->SetText(""); } if ( NULL != pIDocId ) { pIDocId->Release(); pIDocId = NULL ; } } if ( NULL != _pQueryResultEditor) { CATICatalogQueryResult * pIQueryResult = NULL ; HRESULT rc = _pICatalogBrowser->GetCurrentQueryResult(pIQueryResult); if ( SUCCEEDED(rc) && ( NULL!=pIQueryResult)) { CATUnicodeString ResultExpression ; ResultExpression = pIQueryResult->GetQuery(); _pQueryResultEditor->SetText(ResultExpression) ; pIQueryResult->Release(); pIQueryResult = NULL ; } } } }

The path of the current chapter is displayed in the "Catalog" editor of the Catalog Browser Demonstrator. The "Query" editor is updated because when a new chapter is selected the current filter is reset. See the "ChangeQuery" method. 

• The SelectDescription method

  This method is a callback method called when the end user clicks on a description in the Catalog Browser Dialog box.

  void CAAMmrBrowserCmdDlg::SelectDescription(CATCommand* iFrom, CATNotification* iNotif, CATCommandClientData iData) { if ( NULL != _pICatalogBrowser ) { CATICatalogDescription* pICatalogDescription = NULL; HRESULT rc = _pICatalogBrowser->GetSelectedDescription (pICatalogDescription); ...

  The current description is retrieved thanks to the GetSelectedDescription method.

  ... if (pICatalogDescription->IsObjectASubchapter()) { // Case of a chapter selection CATICatalogChapter* pICatalogChapter = NULL; pICatalogChapter = pICatalogDescription->GetSubChapter(); if ( NULL != pICatalogChapter ) { CATUnicodeString chap_name ; chap_name = pICatalogChapter->GetChapterName(); pICatalogChapter->Release(); pICatalogChapter = NULL; _pDescEditor->SetText (chap_name); } ... // The OK button cannot be accessible in the Catalog Browser if (NULL != _pWithOkButton) { if ( CATDlgCheck == _pWithOkButton->GetState() ) { _pICatalogBrowser->OKActivationMode(0); } } }...

  If the current description has a link towards a chapter, IsObjectASubchapter returns true, the "Description" editor displays its name. Since it is not an instantiable object, the OK button of the Catalog Browser is not activated.

  ... CATBaseUnknown * pObject = NULL ; rc = pICatalogDescription->GetObject(pObject); if ( SUCCEEDED(rc) ) { CATIAlias * pIAliasOnObject = NULL ; rc = pObject->QueryInterface(IID_CATIAlias,(void**) & pIAliasOnObject); { CATUnicodeString obj_name = pIAliasOnObject->GetAlias(); _pDescEditor->SetText (obj_name); ... if (NULL != _pWithOkButton) { if ( CATDlgCheck == _pWithOkButton->GetState() ) { _pICatalogBrowser->OKActivationMode(1); } } ... ...

  In the second part of the method it is the case when the description has a link towards a component (not a chapter). The component is retrieved thanks to the GetObject method. The "Description" editor displays the alias name of the component. Since it is an instantiable object, the OK button of the Catalog Browser is activated.

• The CancelCatalog method

This method is a callback method called when the end user clicks on the "Cancel" or "Close" buttons of the Catalog Browser Dialog box.

void CAAMmrBrowserCmdDlg::CancelCatalog(CATCommand* iFrom, CATNotification* iNotif, CATCommandClientData iData) { CloseCatalog(); }

• The OKCatalog method

This method is a callback method called when the end user clicks on the "Ok" button of the Catalog Browser Dialog box.

void CAAMmrBrowserCmdDlg::OKCatalog(CATCommand* iFrom, CATNotification* iNotif, CATCommandClientData iData) { CloseCatalog(); }

• The CloseCatalog method

This method enables to close the current Catalog Browser. It is done by the CloseBrowser method on the CATICatalogBrowser interface pointer on the Catalog Browser. Before that, it is more safe to remove the callbacks set at the Catalog Browser opening.

void CAAMmrBrowserCmdDlg::CloseCatalog() { if ( NULL != _pICatalogBrowser ) { if ( NULL != _pOKNotif) RemoveAnalyseNotificationCB (this, _pOKNotif , NULL); if (NULL !=_pCancelNotif) RemoveAnalyseNotificationCB (this, _pCancelNotif , NULL); if (NULL !=_pChangeNotif) RemoveAnalyseNotificationCB (this, _pChangeNotif , NULL); if (NULL !=_pSelectNotif) RemoveAnalyseNotificationCB (this, _pSelectNotif , NULL); if (NULL !=_pCloseNotif) RemoveAnalyseNotificationCB (this, _pCloseNotif , NULL); _pOKNotif = _pCancelNotif = _pCloseNotif = _pSelectNotif = _pChangeNotif = NULL ; _pICatalogBrowser->CloseBrowser(); _pICatalogBrowser->Release(); _pICatalogBrowser = NULL ; ...

• The InstantiationAuthorization method

This method is a callback method called when the end user clicks on the "Authorize Instantiation" check button of the Catalog Browser Demonstrator Dialog box. 

void CAAMmrBrowserCmdDlg::InstantiationAuthorization(CATCommand* iFrom, CATNotification* iNotif, CATCommandClientData iData) { if ( (NULL != _pInstantiateStateButton) && (NULL != _pICatalogBrowser) ) { if ( _pInstantiateStateButton->GetState() == CATDlgCheck ) { _pICatalogBrowser->AuthorizeInstantiation(1) ; }else { _pICatalogBrowser->AuthorizeInstantiation(0) ; } } }

1: the end user can instantiate from the catalog browser  with a double click or the contextual menu. 

0: otherwise

• The ChangeCatalogAuthorization method

This method is a callback method called when the end user clicks on the "Authorize Other Catalog Selection" check button of the Catalog Browser Demonstrator Dialog box. 

void CAAMmrBrowserCmdDlg::ChangeCatalogAuthorization(CATCommand* iFrom, CATNotification* iNotif, CATCommandClientData iData) { if ( (NULL != _pChgtCatalogStateButton) && (NULL != _pICatalogBrowser)) { if ( _pChgtCatalogStateButton->GetState() == CATDlgCheck ) { _pICatalogBrowser->AuthorizeChangeCatalog(1) ; }else { _pICatalogBrowser->AuthorizeChangeCatalog(0) ; } } }

1: The  button is sensible, the end user can change catalogs. 

0: The button is not sensible, the end user cannot change the catalog

This option is also available for catalog's modification in the left editor list. 

• The ChangeQuery method

This method is a callback method called when the end user enters a query  in the "Query" editor of the Catalog Browser Demonstrator Dialog box. 

The new query is sent to the Catalog Browser thanks to the SetCurrentQuery method. The type of the query: user query or internal query is retrieved on the _pQueryStateButton check button.

void CAAMmrBrowserCmdDlg::ChangeQuery(CATCommand* iFrom, CATNotification* iNotif, CATCommandClientData iData) { if ( NULL != _pICatalogBrowser ) { CATUnicodeString Query ; Query = _pQueryEditor->GetText(); int UserQuery = 1; if (NULL != _pQueryStateButton) UserQuery = (_pQueryStateButton ->GetState() == CATDlgCheck) ? 1: 0; HRESULT rc = _pICatalogBrowser->SetCurrentQuery(Query,UserQuery); ... }

The "The filter on the chapter" editor (not editable) allows you to understand the filter applied to the chapter. The filter value is retrieved by the GetCurrentQueryResult method.

CATICatalogQueryResult * pIQueryResult = NULL ; rc = _pICatalogBrowser->GetCurrentQueryResult(pIQueryResult); if ( SUCCEEDED(rc) && ( NULL!=pIQueryResult)) { CATUnicodeString ResultExpression ; ResultExpression = pIQueryResult->GetQuery(); _pQueryResultEditor->SetText(ResultExpression) ; pIQueryResult->Release(); pIQueryResult = NULL ; } } }

There are three possibilities for the filter since the chapter has been chosen

• Only an "internal" query has been sent 

The filter is the current "internal" query

• Only a "user" query has been sent ( from the "Query" editor of the Catalog Browser Demonstrator of from the "Filter" editor of the Catalog Browser )

The filter is the current "user" query

• At least one "internal" and one "user" queries have been sent

The filter is a logical AND between the current "user" and the current "internal" queries.

As soon as the chapter is left, the filter is reset. 

3. The resource file

// Title of the dialog box
Title ="Catalog Browser Demonstrator" ;

// Help message displayed in the status bar when you pass over the dialog box
Help = "Dialog box to understand the Catalog Browser options and to make instantiation";

// Frames 
FrameBrowser.Title= "Catalog Browser Properties" ;

FrameBrowser.FrameBrowserOptions.Title="Window Options & Display";
FrameBrowser.FrameBrowserOptions.BehaviorLabel.Title ="Behavior";
FrameBrowser.FrameBrowserOptions.ModalCheckButton.Title ="Modal";
FrameBrowser.FrameBrowserOptions.ButtonLabel.Title="Window Button";
FrameBrowser.FrameBrowserOptions.ButtonFrame.WithOK.Title="OK";
FrameBrowser.FrameBrowserOptions.ButtonFrame.WithClose.Title="Close";
FrameBrowser.FrameBrowserOptions.DisplayOptionsLabel.Title="Display";
FrameBrowser.FrameBrowserOptions.DispOpFrame.Tree.Title="Tree";
FrameBrowser.FrameBrowserOptions.DispOpFrame.Small.Title="Small";
FrameBrowser.FrameBrowserOptions.DispOpFrame.Large.Title="Large";
FrameBrowser.FrameBrowserOptions.DispOpFrame.Detail.Title="Detail";

FrameBrowser.FrameBrowserInstMngt.Title="Instantiation Options";
FrameBrowser.FrameBrowserInstMngt.InstantiateState.Title= "Authorize Instantiation" ;

FrameBrowser.ButtonOpenBrowser.Title="Open";

FrameBrowser.ChgtCatalogState.Title = "Authorize Other Catalog Selection" ;

FrameBrowser.FrameBrowserQuery.Title="Filtering";
FrameBrowser.FrameBrowserQuery.QueryLabel.Title="Query";
FrameBrowser.FrameBrowserQuery.QueryState.Title="User";
FrameBrowser.FrameBrowserQuery.QueryResultLabel.Title="The filter on the chapter";

FrameInst.Title="Current Selection";
FrameInst.CatalogLabel.Title="Catalog";
FrameInst.DescLabel.Title="Description";
FrameInst.InstButton.Title="Launch";

This Nls file is not complete. For each Dialog object you can add

• The Long help message - displayed in a ballon when you select the Dialog object with the question mark

FrameBrowser.ButtonOpenBrowser.LongHelp="...";

• The Short help message - displayed in a ballon when you passes over the Dialog object 

FrameBrowser.ButtonOpenBrowser.ShortHelp="...";

• The help message  - displayed in the status bar when you passes over the Dialog object 

FrameBrowser.ButtonOpenBrowser.Help="...";

[Top]

In Short

A Catalog Browser instance is created thanks to the CATICatalogBrowserFactory interface. Once the instance is created, you can customize it or retrieve data, enter by the end user, thanks to the CATICatalogBrowser interface. 

[Top]

References

History

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