DM_GetToolkitData

3.31 DM_GetToolkitData

You can query window system-specific data by using this function.

FPTR DML_default DM_EXPORT DM_GetToolkitData
(
DM_ID objectID,
DM_Attribute attr
)

Parameters

-> DM_ID objectID

Identifier of the object whose window system-specific data is to be queried.

-> DM_Attribute attr

This parameter defines which window system attribute is to be queried.

The valid assignments of the parameter attr depend on the window system and can be taken from the following chapters.

Return value

Depending on the type of the queried value, this function returns the corresponding values converted to FPTR.

Remarks

The function DM_GetToolkitData does not exist for the server side and should not be called there!

3.31.1 Motif

Using this function you can query the data necessary for X-Windows, such as "window-id", "widget" and "color". The meanings of these datatypes are explained in the corresponding X-Windows manual.

The following values are permitted for the atttributes:

attribute	Meaning
AT_CanvasData	Returns the user-specific data of a canvas. This data have been set by a canvas callback function and contains any user-specific data (see also chapter “Structures for Canvas Functions” in the “C Interface - Basics” manual).
AT_IsNull	Returns a value<>0 if the font is a UI_NULL_FONT.
AT_Tile	See also AT_XTile
AT_XColor	Returns the X Windows-specific structure for the specified color. The return value of the function is of the type pixel. The specified object must be a color.
AT_XColormap	Dieser Wert liefert die Colormap des Default-Screens zurück. Returns a colormap of the default screen.
AT_XCursor	Returns the X Windows-specific structure for the specified cursor. The return value of the function is of the type Cursor. The specified object must be a cursor.
AT_XDepth	Dieser Wert liefert die Farbtiefe des Default-Screens als int. Returns the color depth of the default screen as int.
AT_XDisplay	Returns the display for the specified dialog. The return value of the function is of the type display *.
AT_XFont	Returns the X Windows-specific structure for the specified font. The return value of the function is of the type XFontStruct *, if supported by the font defintion. Otherwise NULL.
AT_XFontSet	Dieser Wert liefert die X-Windows-spezifische Struktur für den angegebenen Zeichensatz zurück. Der Rückgabewert der Funktion ist vom Typ XFontSet, sofern zur Font-Definition passend. Andernfalls NULL. Returns the X Windows-specific structure for the specified font. The return value of the function is of the type XFontSet, if supported by the font defintion. Otherwise NULL.
AT_XmFontList	Dieser Wert liefert die X-Windows-spezifische Struktur für den angegebenen Zeichensatz zurück. Der Rückgabewert der Funktion ist vom Typ XmFontList, sofern zur Font-Definition passend. Andernfalls NULL. Returns the X Windows-specific structure for the specified font. The return value of the function is of the type XFontSet, if supported by the font defintion. Otherwise NULL.
AT_XmFontList	Returns the default font typically used by the IDM when the font attribute is not set.
AT_XScreen	Returns the screen for the specified dialog. The return value of the function is of the type screen.
AT_XShell	Returns the shell widget of an object. The return value of the function is a widget.
AT_XtAppContext	Liefert den Application Context. Returns the Application Context.
AT_XTile	Returns the X Windows-specific structure for a tile. The return value of this function depends on how the tile was defined. If it was stored in an external ".gif"-format file, "XImage *" is returned. If it was defined directly in the Dialog Manager file, Pixmap is returned. It ist recommended to better query AT_XTile with function DM_GetToolkitDataEx.
AT_XVisual	Dieser Wert liefert eine Visual Struktur für den Default-Screen. Returns a visual structure for the default screen.
AT_XWidget	Returns the widget of the specified object. The return value of the function is of the type widget.
AT_XWindow	Is the window belonging to the object. The return value of the function is of the type window.

To be noted for multiscreen dialogs

The call with AT_ XTile or AT_XColor always returns only the tile or color of the default screen (see also chapter “Multiscreen support under Motif” in manual “Programming Techniques”).

Example

int DML_c AppMain (argc, argv)

int argc;

char far * far *argv;

{

DM_ID dialogID;

Widget toplevel; /* Application shell obtained from

XtInitialize(). */

static char * dialogfile = "xres.dlg";

/* Initialize the dialog manager */

DM_Initialize (&argc, argv, 0);

dialogID = DM_LoadDialog (dialogfile, 0);

if (!dialogID)

{

DM_TraceMessage("%s: Could not load dialog \"%s\"",

DMF_LogFile | DMF_InhibitTag | DMF_Printf,

argv[0], dialogfile);

return(1);

}

/* Querying the application shell */

if ((toplevel = (Widget) DM_GetToolkitData (dialogID,

AT_XWidget)) != 0)

{

DM_ID my_bgc;

DM_ID my_font;

DM_ID my_FontOfExit;

/* further, own statements */ }

3.31.2 Microsoft Windows

Using this function, the data necessary for Microsoft Windows such as window-handle, instance handle and color can be queried.

The meanings of these data types are explained in the corresponding Microsoft Windows manuals.

The following values are permitted for these attributes:

attribute	object	Return value	Meaning
AT_CanvasData	canvas	FPTR	This attribute can be used to retrieve the user-specific data of a canvas object. This data was set by DM_SetToolkitData or a canvas callback function and contains any user-specific data (See also chapter “Structures for Canvas Functions”).
AT_ClipboardText	setup or 0	DM_String	This attribute returns the string content of the Microsoft Windows clipboard. The return value is buffered and is valid until the attribute is queried again. Setting the attribute also invalidates the buffer. To release the string without changing the clipboard, invoke: DM_SetToolkitData(0, AT_ClipboardText, (FPTR) 0, 0);
AT_Color	color	COLORREF	See also AT_XColor
AT_Color	tile	HPALETTE	See also AT_XColor
AT_DataType	tile	int	The query is only available for compatibility reasons. The attribute AT_Tile with set “data” parameter should be used with DM_GetToolkitDataEx. This attribute returns the type of the pattern. The assignment is described at AT_XTile.
AT_DPI	IDM Objects	int	See also AT_GetDPI
AT_Font	font	HFONT	See also AT_XFont
	IDM Objects	HFONT	See also AT_XFont
	setup	HFONT	See also AT_XFont
AT_GetDPI	setup or 0	int	This attribute returns the system DPI value. See the note below.
AT_GetDPI	IDM Objects	int	This attribute returns the DPI value of the object. This depends on which monitor the object is assigned to. See note below.
AT_IsNull	font or color	int	Hiermit kann abgefragt werden, ob die Resource auf NULL definiert wurde (UI_NULL_FONT bzw. UI_NULL_COLOR). Die Resource wurde auf NULL definiert, wenn der Rückgabewert nicht 0 ist. Hereby it can be queried whether the resource was defined to NULL (UI_NULL_FONT or UI_NULL_COLOR). The resource has been defined to NULL if the return value is not 0.
AT_maxsize	setup or 0	int	This attribute returns the number of WSI ID's that are still free. Attention: The number of WSI IDs still available has nothing to do with how many objects can actually still be made visible! It is the maximum upper limit.
AT_Raster	dialog editbox groupbox layoutbox module notebook notepage spinbox splitbox statusbar tablefield toolbar Window	DWORD	This attribute returns the size of the raster defined on the object in IDM pixels. The width and height is packed into a DWORD, see note below.
AT_Raster	font	DWORD	This attribute returns the size of the font in IDM pixels as used for raster calculation. The width and height is packed into a DWORD, see note below.
AT_SrollbarDimension	groupbox notepage window	DWORD	This attribute returns the width of the vertical scrollbar and the height of the horizontal scrollbar in IDM pixels. The width and height is packed into a DWORD, see note below.
AT_Size	dialog module	DWORD	This attribute returns the size of the primary monitor's workspace in IDM pixels. The width and height is packed into a DWORD, see note below.
	font	DWORD	This attribute returns the size of the font in IDM pixels. The width is calculated from the reference string if one is specified. The width and height is packed into a DWORD, see note below.
	Remaining IDM Objectsexcept menubox, menuitem and menuseparator	DWORD	This attribute returns the size of the object in IDM pixels. The width and height is packed into a DWORD, see note below.
AT_Tile	color	HBRUSH	See also AT_XTile
AT_Tile	tile	HANDLE	The query is only available for compatibility reasons. DM_GetToolkitDataEx should be used with the “data” parameter set. See also AT_XTile
AT_toolhelp	setup or 0	HWND	This attribute returns the Microsoft Windows handle of the tooltip control used by Dialog Manager to display the .toolhelp attribute. See also “Example for AT_toolhelp at the setup object” below.
AT_value	RTF edittext	DM_String	This attribute returns the complete content, i.e. with all formatting instructions etc., of an RTF input field.
AT_VSize	IDM Objekte except menubox, menuitem and menuseparator	DWORD	This attribute returns the virtual size of the object in IDM pixels. If there is no virtual size, then the real size is returned in IDM pixels. The width and height is packed into a DWORD, see note below.
AT_Widget	USW	HWND	See also AT_XWidget
AT_WinHandle	dialog module setup or 0	HINSTANCE	This attribute returns the Microsoft Windows handle of the application instance.
	menubox	HMENU	This attribute returns the Microsoft Windows Menu Handle.
	menuitem menuseparator	HMENU	This attribute returns the Microsoft Windows menu handle of the surrounding menubox object.
	Remaining IDM Objects	HWND	This attribute returns the Microsoft Windows handle of the object. The grouping objects (groupbox, notepage, window, ...) are usually composed of several Microsoft Windows objects, for these the handle of the client window (the window in which the child objects are created) is returned.
AT_wsidata	cursor	HCURSOR	See also AT_XCursor
	font	HFONT	See also AT_XFont
	tile	HANDLE	The query is only available for compatibility reasons. DM_GetToolkitDataEx should be used with the “data” parameter set. See also AT_XTile
	Remaining IDM Objects	HWND	This attribute returns the Microsoft Windows handle of the outer Microsoft Windows object, the inner one can be queried with AT_WinHandle.
AT_XColor	color	COLORREF	This attribute returns the Microsoft Windows-specific structure for the specified color. The color values are accessed using the appropriate Microsoft Windows macros: COLORREF u1RGB = (COLORREF) (size_t) DM_GetToolkitDataEx(colorID, AT_XColor, (FPTR) 0, 0); BYTE ucRed = GetRValue(u1RGB); BYTE ucGreen = GetGValue(u1RGB); BYTE ucBlue = GetBValue(u1RGB);
AT_XColor	tile	HPALETTE	This attribute returns the Microsoft Windows color palette used by the pattern.
AT_XCursor	cursor	HCURSOR	This attribute returns the Microsoft Windows cursor handle.
AT_XFont	font	HFONT	This attribute returns the Microsoft Windows font handle.
	IDM Objects	HFONT	This attribute returns the Microsoft Windows font handle of the font used on this object.
	setup	HFONT	The font handle of the default font used is returned.
AT_XTile	color	HBRUSH	This attribute returns a Microsoft Windows Brush of the color. This brush can be used to fill the background.
AT_XTile	tile	HANDLE	The query of AT_wsidata, AT_Tile and AT_XTile without set "data" parameter is only available for compatibility reasons. The "data" parameter should be used. This attribute returns the Microsoft Windows specific structure for the pattern (tile) as in version A.06.03.a and before. GDI objects have to be created for this purpose. In order to obtain the new Microsoft Direct2D data, that the IDM uses internally, the "data" parameter must be set. The type of Microsoft Windows handle depends on AT_DataType, whereby AT_DataType may only be queried after AT_wsidata, AT_Tile or AT_XTile has been queried: DMF_TlkDataIsIcon: HICON DMF_TlkDataIsWMF: HMETAFILE DMF_TlkDataIsEMF: HENHMETAFILE Otherwise: HBITMAP IMPORTANT: The returned data should not be saved, as it is automatically released when the tile resource is no longer used by a visible IDM object. Note: If data was set using DM_SetToolkitData, then the set data and only the set data is returned.
AT_XWidget	USW	HWND	This attribute returns the Microsoft Windows handle of the USW object.

Note for object and attribute

The object specified in the call must generally be visible and thus created in the WSI for the returned data to make sense. Resources are generally created when they are called. If an object type is specified that is not mentioned for the attribute in question, an error message is usually written to the log file and (FPTR) 0 is returned.

Note for access on the return value

The return value of the function is a FPTR or void *, this must be cast to the documented return value to avoid getting warnings when compiling.

Since a void * pointer can be cast to any other pointer, a simple cast operator is sufficient for all pointer data types. Pointer data types include, for example, all Microsoft Windows handles, such as HWND, HFONT, ... :

HWND hwnd = (HWND) DM_GetToolkitData(idObj, AT_wsidata);

For numerical values, an intermediate cast must usually be inserted, since the size of the data value must be preserved when casting from a pointer to a number in order to avoid warnings. The data type size_t can be used for this purpose, since it has the same size as a pointer by definition. Subsequently, it is possible to cast to a smaller number type:

DM_UInt2 val = (DM_UInt2) (size_t) DM_GetToolkitData(idObj, AT_wsidata);

Note width and height packed in DWORD

Under Microsoft Windows, width and height are often packed into a DWORD. This is also partly handled in this way by the IDM. The individual values can then be extracted with the Microsoft Windows macros LOWORD and HIWORD:

DWORD size = (DWORD) (size_t) DM_GetToolkitData(id, AT_Size);

WORD width = LOWORD(size);

WORD height = HIWORD(size);

Note IDM pixel

The IDM for Windows 11 supports high resolutions. To minimize impact on existing dialog scripts, ISA Dialog Manager uses virtual pixel coordinates. These are based on the size of an application that does not support high resolutions, such as IDM for Windows 10.

Note for DPI values

Note that all DPI values are dynamic and can be changed by the user. For example, IDM objects can be moved to another monitor or the user can set other scale factors via the control panel.

If the application is not DPI Aware (for example IDM for Windows 10) then the default DPI value of 96 is always used.

Note for NULL values with ressources

The DM_GetToolkitData function returns a NULL value for font and color resources under Microsoft Windows if the resource has been defined to UI_NULL_FONT or UI_NULL_COLOR, respectively. This affects the following attributes:

AT_wsidata, AT_Font, AT_XFont:

The return value for UI_NULL_FONT becomes (HFONT) 0.
AT_Color, AT_XColor:

The return value for UI_NULL_COLOR becomes (COLORREF) -1L.
AT_Tile, AT_XTile:

The return value for UI_NULL_COLOR becomes (HBRUSH) 0.

Note IDM pixel

Example

Querying a canvas-specific structure. If the structure is not yet defined at the canvas, the necessary memory will be allocated and the data will be transferred to the canvas.

void DML_default DM_ENTRY HoleCanvasDaten __3(

(DM_ID, thisID),

(DM_ID, canvasID),

(DM_ID, stvarID))

{

MyData *d;

/* Holen der Daten aus der Canvas und Abprüfen, ob man sie

* wirklich bekommen hat, sonst Allokieren der Struktur

/* Fetching data from the canvas and checking whether it has

* actually arrived. Otherwise allocating the structure.

if ((d = (MyData *) DM_GetToolkitData (canvasID,

AT_CanvasData)) == (MyData *) 0)

if ((d = DM_Calloc (sizeof(MyData)))

== (MyData *) 0)

return;

else

if (!DM_SetToolkitData (canvasID, AT_CanvasData, d, 0))

DM_TraceMessage ("Cannot set canvas toolkit data",

0);

}

Example for AT_toolhelp at the setup object

Note

The functions CloseToolhelp and SetToolhelpDisplayTime used in the example must be defined accordingly within the dialog.

Temporarily closing an open tooltip control in a canvas function to redraw the canvas

#include <windows.h>

#include <commctrl.h>

#include IDMuser.h

void DML_default DM_ENTRY CloseToolhelp __0() {

DM_ID idSetup =

DM_ParsePath((DM_ID) 0, (DM_ID) 0, "setup", 0, 0);

if (idSetuo != (DM_ID) 0) {

HWND hwndToolhelp =

(HWND) DM_GetToolkitData(idSetup, AT_toolhelp);

if (hwndToolhelp != (HWND) 0) {

SendMessage(

hwndToolhelp, TTM_POP,

(WPARAM) 0, (LPARAM) 0);

}

Change the display time of the tooltip

#include <windows.h>

#include <commctrl.h>

#include IDMuser.h

void DML_default DM_ENTRY SetToolhelpDisplayTime __1(

(DM_Integer, iDisplayTime)) {

DM_ID idSetup =

DM_ParsePath((DM_ID) 0, (DM_ID) 0, "setup", 0, 0);

if (idSetuo != (DM_ID) 0) {

HWND hwndToolhelp =

(HWND) DM_GetToolkitData(idSetup, AT_toolhelp);

if (hwndToolhelp != (HWND) 0) {

SendMessage(

hwndToolhelp, TTM_SETDELAYTIME,

(WPARAM) TTDT_AUTOPOP,

(LPARAM) iDisplayTime);

}

3.31.3 Qt

The following values are permitted for these attributes:

attribute	object	Return value	Meaning
AT_Application	0	FPTR auf QApplication	This attribute can be used to query the QApplication on which the application is based.
AT_CanvasData	cancas	FPTR	Über dieses Attribut können die benutzerspezifischen Daten eines Canvas-Objekts erfragt werden. Diese Daten wurden von DM_SetToolkitData oder einer Canvas-Callback-Funktion gesetzt und beinhalten jegliche benutzerspezifischen Daten (Siehe auch Kapitel “Structures for Canvas Functions”). This attribute can be used to retrieve the user-specific data of a canvas object. This data was set by DM_SetToolkitData or a canvas callback function and contains any user-specific data (See also chapter “Structures for Canvas Functions”).
AT_Color	color	QColor / QBrush	This attribute can be used to query the color or color gradient (as a QBrush) used by the Color resource. Attention: It should always be checked first for a valid color (QColor), since a QBrush can be automatically cast to a QColor, which then however is an uninitialized but valid QColor.
AT_Font	font	QFont	This attribute can be used to query the QFont used by the font resource.
AT_FontName	font	char*	This attribute can be used to get the name of the QFont used by the font resource.
AT_Tile	tile	QPixmap	This attribute can be used to query the QPixmap of the pattern (tile).
AT_XTile	tile	QPixmap	See AT_Tile
AT_XWidget	IDM Objekte	QWidget	This attribute determines the QWidget associated with a DM_ID.