Callback functions

The application has to implement a callback function for each modal, modeless, and palette dialog. The callback function is called with DG messages to handle user actions not handled by DG. The prototype of the callback function is the following:

    typedef short (*DGDialCallBack) (
      short  message,
      short  dialId,
      short  itemId,
      long   userData,
      long   msgData
    );

Parameters

message

One of the DG messages.

 

dialId

ID of the dialog or tab page.

 

itemId

1-based index of the dialog item.

 

userData

The user-specified data of the dialog.

 

msgData

Message-specific data.

Return Values

The return value of the callback function is not investigated except for the following cases:

Message	Item type	Value	Meaning
DG_MSG_CLICK	Push Button	Index of the button.	The dialog will be closed.
		0	The dialog will not be closed.
	Tab Control	1	Changing of tab pages is not permitted.
		0	Changing of tab pages is permitted.
	Tree View	1	The previous selection is kept and further processing of the click event is omitted. This message is sent only if the user clicks the state icon of a tree item
		0	The click message is processed by the usual way.
DG_MSG_CONTEXTMENU		1	The message is handled, and further processing of the context menu event is omitted.
		0	The message is not handled. The context sensitive help will be displayed.
DG_MSG_FILTERCHAR	Edit Control	1	The character will be filtered out.
		0	The character will not be filtered out.
DG_MSG_HOTKEY		1	The hotkey is handled and further processing of the keyboard event is omitted.
		0	The hotkey is not handled. Processing of the keyboard event is going on.
DG_MSG_ITEMHELP		1	The message is handled, help text is returned by the application.
		0	The message is not handled. Help text will be displayed from the GRC resource, if it is possible.
DG_MSG_MOUSEMOVE	List Box	DG_LIST_INDRAGAREA	The cursor is above the drag area of a list item.
		0	The cursor is not above the drag area.
	User Item	1	The application changes the cursor to a desired custom form.
		0	The default arrow cursor is acceptable over the user item.
DG_MSG_NULL		Any positive number.	The dialog will be closed.
		0	The dialog will not be closed.
DG_MSG_WHEELTRACK		1	The message is handled, and further processing of the wheel event is omitted.
		0	The message is not handled. Processing of the wheel event is going on.

In all other cases the application should return zero.

Remarks

The pointer to the callback function should be passed in the dCallBack parameter of the DGModalDialog or DGModelessInit functions. For the simplest modal dialogs that have only buttons and static items (static text, picture, icon, etc.) there is no need to implement a callback function. In this case DGModalDialog returns only if a button is clicked.

Tab pages are special dialogs, because they have no dialog callback function. Messages for controls on tab pages are sent to the callback function of the main dialog (the dialog that contains the tab control). For these messages, however, the ID of the tab page subdialog is passed to the callback function in the dialId parameter instead of the ID of the main dialog.

For DG messages that related to a dialog instead of a particular dialog item, the itemId parameter is zero. These messages are the following: DG_MSG_ACTIVATE, DG_MSG_GROW, DG_MSG_HOTKEY, DG_MSG_INIT and DG_MSG_NULL.

The application can assign a long value to every dialog. This long value can be used to store any dialog-specific user data. It can be given when creating the dialog by DGModalDialog or DGModelessInit as the userData parameter of these functions, or can be modified later by DGSetDialogUserData. When handling DG messages in the dialog callback function, this dialog specific data is available as the userData parameter of the message. You can retrieve this value whenever you need by DGGetDialogUserData. It is advised to gather all the dialog related data into a user-defined structure. After filling this structure, give its pointer (handle) cast to long to DGModalDialog or DGModelessInit. If a dialog has one ore more tab pages, they have a common user data.

In the msgData parameter of the callback function you can get message-specific data. For details see the description of the DG messages.

See Also

Dialog Manager, DG Messages, Modal dialogs, Modeless dialogs, Palette dialogs, Tab pages, Dialog item types
DGGetDialogUserData, DGModalDialog, DGModelessInit, DGSetDialogUserData