CATDialog

3D PLM Enterprise Architecture	User Interface - Dialogs	CATDialog Base class for all dialog classes
Quick Reference

CATDialog is the base class for all dialog object classes and implements their common mechanisms. All the tasks described here consequently apply to any dialog object instance.

*Events*
Notification	Method	Sent when
CATDlgCreateNotification	`GetCreateNotification`	When the object is created
CATDlgVisibilityNotification	`GetVisibilityNotification`	Whenever the object visibility is modified
CATDlgResizeNotification	`GetResizeNotification`	Whenever the object is resized
CATDlgHelpNotification	`GetHelpNotification`	Whenever the object is selected using the What's This command
CATDlgDragEnterNotification	`GetDragEnterNotification`	Whenever the mouse is dragged and enters the dialog object
CATDlgDragOverNotification	`GetDragOverNotification`	Whenever the mouse is being dragged over the dialog object
CATDlgDragLeaveNotification	`GetDragLeaveNotification`	Whenever the mouse is dragged and leaves the dialog object
CATDlgDropNotification	`GetDropNotification`	Whenever a drop occurs on the dialog object
CATDlgEndDropNotification	`GetEndDropNotification`	Whenever a drop occurs on the dialog object
CATDlgStartDragNotification	`GetStartDragNotification`	Whenever a mouse drag starts on the dialog object
CATDlgCancelDragNotification	`GetCancelDragNotification`	Whenever a mouse drag stops on the dialog object
CATDlgDragButtonNotification	`GetDragButtonNotification`	Whenever a mouse drag starts on a button of the dialog object

[Top]

Programmer's Guide

Three static tables contains:

KeyName: the accelerator names
MagnitudeName: the magnitudes [1] that you can set for the figures entered or displayed using combos, editors, and spinners, and that are expressed with the unit assigned to these magnitudes at the applicaiton level
UnitName: the units [1] associated with these magnitudes that you can reset for a given combo, editor, or spinner.

The programming tasks fall into the following topics:

Managing parent/child links
Managing properties
Managing location and extent in the grid
Managing resources

[Top]

Managing Parent/Child Links

Any dialog object has two parent/child links:

A dialog containment link to its dialog parent [2]. This dialog parent contains the object. It can be the window or dialog box, such as a frame or a tab page.
A CATCommand send/receive link to propagate notifications along the command tree structure [2] [3].

Usually, the same dialog object is the parent for these two parent/child link, since any dialog object that can contain others is also a CATCommand instance. Nevertheless, it can be efficient to sometimes have two different parent objects.

Retrieving the Contained Children of a Dialog Object

A given dialog object can be the containing parent of several others. Use the GetChildCount method to determine how many children exist.

int ChildrenCount = pDialog->GetChildCount();

Use the GetChildNumberFromChild method to retrieve the rank of a given child dialog object among all the children of a dialog object.

int ChildNumber = pDialog->GetChildNumberFromChild(pChild );

Use the GetChildFromChildNumber method to retrieve a child dialog object from its rank.

CATDialog * pChild = pDialog->GetChildFromChildNumber(nChild);

[Top]

Retrieving the Containing Dialog Window

Use the GetFatherWindow method to retrieve the dialog window that contains the dialog object.

CATDlgWindow * pContainingWindow = pDialog->GetFatherWindow();

[Top]

Changing the Dialog Containment Parent

Use the ReParent method to change the dialog containment parent.

int Succeeded = pDialog->Reparent(pNewParent);

pNewParent can be a CATDlgBox or a CATDlgWindow instance only, since it must contain pDialog.

Changing the CATCommand Send/Receive Parent

Use the CATCommand SetFather method to change the CATCommand send/receive parent.

pDialog->SetFather(pNewParent);

pNewParent must be a CATCommand instance to be able to receive the notifications sent by pDialog. This is the case of all dialog objects.

[Top]

Managing Properties

The dialog object properties are its visibility, its sensitivity to end user interaction, its style.

[Top]

Managing the Visibility

Use the SetVisibility and GetVisibility methods with the parameters CATDlgShow and CATDlgHide to manage the visibility of a dialog object.

set visibility

CATULong ObjectVisibility = CATDlgShow;
pDialog->SetVisibility(ObjectVisibility);
...

get visibility

ObjectVisibility = pDialog->GetVisibiliy(ObjectVisibility);
if (ObjectVisibility == CATDlgShow)
  ...   // Object is visible
else if (ObjectVisibility == CATDlgHide)
  ...   // Object is not visible

[Top]

Managing the Sensitivity

The sensitivity of a dialog object is its ability to react to an end user interaction. It applies to dialog objects designed for this purpose, and can therefore be managed for thses objects only, such as push buttons, combos, and spinners.

	A sensitive Apply push button. When the end user pushes it, it reacts by sending a notification to its parent in the command tree structure
	A non sensitive Apply push button. It is displayed dimmed and can't be pushed.

On the opposite, a label or a separator, that is used to display a text or an image, or to help dialog object layout, are not sensitive objects.

Use the SetSensitivity, GetSensitivity, and IsSetSensitivity methods with the parameters CATDlgEnable and CATDlgDisable to manage the sensitivity of a dialog object.

set sensitivity

CATULong ObjectSensitivity = CATDlgEnable;
pDialog->SetSensitivity(ObjectSensitivity);
...

get sensitivity

ObjectSensitivity = pDialog->GetSensitivity(ObjectSensitivity);
if (ObjectSensitivity == CATDlgEnable)
  ...   // Object is sensitive
else if (ObjectSensitivity == CATDlgDisable)
  ...   // Object is not sensitive

ask for sensitivity

...
CATBool IsSensitive;
if(pDialog->IsSetSensitivity())
  ...   // Object is sensitive
else
  ...   // Object is not sensitive

[Top]

Retrieving the Object's Style

The object's style can be retrieved thanks to the GetStyle method.

CATDlgStyle ObjectStyle;
ObjectStyle = pDialog->GetStyle();

Linking to the Power Input

You can link an editor or a spinner to the PowerInput using the SetPowerInputLink method. The PowerInput mode should be already enabled.

int PowerInputLinkMode = 1;
pEditor->SetPowerInputLink(PowerInputLinkMode);

Valid values are:

1	The object is linked to the Power Input
0	The object is not linked to the Power Input

[Top]

Managing Location and Extent in the Grid

Any object can set itself its location and extent in the grid [1] of its parent object using the SetGridConstraints and GetGridConstraints methods.

set grid constraint

CATDlgGridConstraints GridCsts(4, 2, 1, 1, CATGRID_4SIDES);
pDialog->SetGridConstraints(GridCsts);

set grid constraint parameters

... // OR
pDialog->SetGridConstraints(4, 2, 1, 1, CATGRID_4SIDES);

get grid constraint

...
CATDlgGridConstraints NewGridCsts;
NewGridCsts = pDialog->GetGridConstraints();

[Top]

Managing Resources

The resources [1) are assigned to a dialog object from the resource files using the object identifier or name passed as the second argument of the dialog object constructor. Some resources can be automatically set using the DeclareResource macro. If the resource files doen't exist or are not found, resources can be hardcoded and assigned using methods, even if this is not recommended. In addition, some resources, such as the values displayed in a combo, must be extracted from the resource files, and set as the combo lines.

[Top]

Managing the Resource Files and Keys

You can do the following:

Get the object's identifier or name used to build its resource keys in the resource files using the GetName method.
CATString ObjectId; ObjectId = pDialog->GetName();

Get and set the object's resource key using the GetResourceID and SetResourceID methods.

get key	CATString ObjectKey; ObjectKey = pDialog->GetResourceID(); ...
set key	ObjectKey = "NewKey"; pDialog->SetResourceID(ObjectKey);

Add a resource file to be searched for by providing a pointer to either a message catalog, instance of the CATMsgCatalog class, or a resource catalog, instance of the CATRscCatalog class, or the resource file name, and its path.

add message catalog

CATMsgCatalog * MsgCat = new CATMsgCatalog();
//Message catalog is in file MsgFileName.CATNls
MsgCat->LoadMsgCatalog("MsgFileName");
CATString Path("/u/users/psr/catalog");
pDialog->AddResourcePath(*MsgCat, Path);
...

add resource catalog

CATRscCatalog * RscCat = new CATRscCatalog();
//Resource catalog is in file RscFileName.CATRsc
RscCat->LoadRscCatalog("RscFileName");
pDialog->AddResourcePath(*RscCat, Path);
...

add message or resource catalog using its name

CATString Name("CatalogName");
pDialog->AddResourcePath(Name, Path);

The message catalogs are files suffixed by CATNls, such as MsgFileName.CATNls, and resource catalogs are files suffixed by CATRsc, such as RscFileName.CATRsc.

[Top]

Managing the Resource Values

You can do the following:

Get and set the title using the GetTitle and SetTitle methods.

get title	CATUnicodeString ucTitle; ucTitle = pDialog->GetTitle(); ...
set title	ucTitle = ...; pDialog->SetTitle(ucTitle);

Get and set the mnemonic using the GetMnemonic and SetMnemonic methods.

get mnemonic	CATUnicodeChar ucMnemonic; ucMnemonic = pDialog->GetMnemonic(); ...
	set mnemonic	ucMnemonic = ...; pDialog->SetMnemonic(ucMnemonic);

Get and set the accelerator as a keystroke combination using the GetAccelerator and SetAccelerator methods.

get accelerator	CATDlgAccelerator Accelerator; Accelerator = pDialog->GetAccelerator(); ...
set accelerator	pDialog->SetAccelerator(Meta\|UIK_a);

Get and set the accelerator as a CATUnicodeString instance using the GetAcceleratorString and SetAcceleratorString methods.

get accelerator	CATUnicodeString ucAccelerator; ucAccelerator = pDialog->GetAcceleratorString(); ...
set accelerator	pDialog->SetAcceleratorString("Ctrl+a");

Set the icon names and types using the SetIconName and SetIconType methods.

set icon names	pDialog->SetIconName("IconNameNormal", "IconNameSelected", "IconNameFocussed", "IconNameDisabled",);
set icon type	pDialog->SetIconType(Modification);

Valid icon types are Default, General, Creation, Modification, Analysis, and NonTransparent.

Get and set the help message displayed in the message area of the status bar using the GetHelp and SetHelp methods.

get help	CATUnicodeString ucHelp; ucHelp = pDialog->GetHelp(); ...
set help	ucHelp = ...; pDialog->SetHelp(ucHelp);

Get and set the short help message, or tooltip, displayed in box beside the objetc when the mouse moves above the object using the GetShortHelp and SetShortHelp methods.

get short help	CATUnicodeString ucShortHelp; ucShortHelp = pDialog->GetShortHelp(); ...
set short help	ucShortHelp = ...; pDialog->SetShortHelp(ucShortHelp);

Get and set the Power Input help message displayed in front of the Power Input entry field using the GetPowerInputHelp and SetPowerInputHelp methods.

get Power Input help	CATUnicodeString ucPowerInputHelp; ucPowerInputHelp = pDialog->GetPowerInputHelp(); ...
set Power Input help	ucPowerInputHelp = ...; pDialog->SetPowerInputHelp(ucPowerInputHelp);

Get and set the long help message displayed in a box when the What's This command is used using the GetLongHelp and SetLongHelp methods.

get long help	CATUnicodeString ucLongHelp; ucLongHelp = pDialog->GetLongHelp(); ...
set long help	ucLongHelp = ...; pDialog->SetLongHelp(ucLongHelp);

Set the status bar text and temporary text using the SetStatusBarText and SetStatusBarTemporaryText methods.

set status bar message	CATUnicodeString ucStatusBarMsg = ...; pDialog->SetStatusBarText(ucStatusBarMsg); ...
set status bar temporary message	CATUnicodeString ucStatusBarTempMsg ...; pDialog->SetStatusBarTemporaryText(ucStatusBarTempMsg);

Get a resource value from its key, and possibly by passing the associated parameters, if any, using the GetResourceValueFromKey method.

CATString ObjectKey = "sKey";
CATUnicodeString ucValue;
CATUnicodeSring ucParm[n];
ucParm[0] = ...;
ucParm[1] = ...;
...
int rc = pDialog->GetResourceValueFromKey(sKey, ucValue, ucParm);
...

[Top]

References

[1]	Magnitude and Unit Reference
[2]	Creating Dialog Objects
[3]	Using Callbacks to Trigger Actions
[4]	Editor
[5]	Spinner

[Top]

History

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

3D PLM Enterprise Architecture

User Interface - Dialogs

CATDialog

Programmer's Guide

Managing Parent/Child Links

Retrieving the Contained Children of a Dialog Object

Retrieving the Containing Dialog Window

Changing the Dialog Containment Parent

Changing the CATCommand Send/Receive Parent

Managing Properties

Managing the Visibility

Managing the Sensitivity

Retrieving the Object's Style

Linking to the Power Input

Managing Location and Extent in the Grid

Managing Resources

Managing the Resource Files and Keys

Managing the Resource Values

References

History