DM_GetToolkitData

3.32 DM_GetToolkitData

Mit Hilfe dieser Funktionen können fenstersystemspezifische Daten abgefragt werden.

FPTR DML_default DM_EXPORT DM_GetToolkitData
(
DM_ID objectID,
DM_Attribute attr
)

Parameter

-> DM_ID objectID

Dieser Parameter ist der Identifikator des Objekts, dessen fenstersystemspezifischen Daten erfragt werden sollen.

-> DM_Attribute attr

Dieser Parameter gibt das Attribut an, das abgefragt werden soll.

Die gültigen Belegungen des Parameters attr sind fenstersystemabhängig und können den nachfolgenden Kapiteln entnommen werden.

Rückgabewert

Je nach Art des abgefragten Wertes liefert diese Funktion die entsprechenden auf FPTR konvertierten Werte.

Anmerkungen

Die Funktion DM_GetToolkitData existiert nicht für die Serverseite und sollte dort nicht aufgerufen werden!

3.32.1 Motif

Mit Hilfe dieser Funktion können die für X-Windows notwendigen Daten wie window-id, widget und color abgefragt werden. Die Bedeutungen dieser Datentypen werden im entsprechenden X-Windows-Handbuch erklärt.

Folgende Werte sind für die Attribute zugelassen:

Attribut	Bedeutung
AT_CanvasData	Dieser Wert liefert die benutzerspezifischen Daten einer Canvas. Diese Daten wurden von einer Canvas-Callback-Funktion gesetzt und beinhalten benutzerspezifische Daten (siehe auch Kapitel „Strukturen für Canvas-Funktionen“ im Handbuch „C-Schnittstelle - Grundlagen“).
AT_IsNull	Liefert einen Wert<>0 wenn die Schriftart ein UI_NULL_FONT ist.
AT_Tile	Siehe auch AT_XTile
AT_XColor	Dieser Wert liefert die X-Windows-spezifische Struktur für die angegebene Farbe zurück. Der Rückgabewert ist dann vom Typ Pixel. Das angegebene Objekt muss eine Farbe sein.
AT_XColormap	Dieser Wert liefert die Colormap des Default-Screens zurück.
AT_XCursor	Dieser Wert liefert die X-Windows-spezifische Struktur für den angegebenen Cursor. Der Rückgabewert ist dann vom Typ Cursor. Das angegebene Objekt muss ein Cursor sein.
AT_XDepth	Dieser Wert liefert die Farbtiefe des Default-Screens als int.
AT_XDisplay	Dieser Wert liefert die Anzeige des angegebenen Dialogs. Der Rückgabewert der Funktion ist dann vom Typ Display *.
AT_XFont	Dieser Wert liefert die X-Windows-spezifische Struktur für den angegebenen Zeichensatz zurück. Der Rückgabewert der Funktion ist vom Typ XFontStruct *, sofern zur Font-Definition passend. Andernfalls 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.
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.
AT_XmFontList	Liefert die Default-Schriftart die typischerweise vom IDM bei einem nicht gesetzten font-Attribut verwendet wird.
AT_XScreen	Dieser Wert liefert den Bildschirm zu dem angegebenen Dialog. Der Rückgabewert der Funktion ist dann vom Typ Screen.
AT_XShell	Dieser Wert liefert das Shell-Widget eines Objekts. Der Rückgabewert der Funktion ist ein Widget.
AT_XtAppContext	Liefert den Application Context. Returns the Application Context.
AT_XTile	Dieser Wert liefert die X-Windows-spezifische Struktur eines Musters tile zurück. Der Rückgabewert der Funktion ist dabei davon abhängig, wie das Muster definiert worden ist. Wurde es in einer externen Datei im gif-Format hinterlegt, wird ein XImage* zurückgeliefert; wurde es direkt in der Dialog Manager Datei definiert, wird ein Pixmap zurückgegeben. Es wird empfohlen AT_XTile über die Funktion DM_GetToolkitDataEx abzufragen.
AT_XVisual	Dieser Wert liefert eine Visual Struktur für den Default-Screen.
AT_XWidget	Dieser Wert liefert das Widget zu dem angegebenen Objekt. Der Rückgabewert der Funktion ist dann vom Typ Widget.
AT_XWindow	Dieser Wert ist das zu gehörende Fenster. Der Rückgabewert der Funktion ist dann vom Typ Window.

Zu Beachten bei Multiscreendialogen

Der Aufruf mit AT_ XTile bzw. AT_XColor liefert immer nur das tile bzw. die color des default Screen zurück (siehe auch Kapitel „Multiscreen Support unter Motif“ im Handbuch „Programmiertechniken“).

Beispiel

int DML_c AppMain (argc, argv)

int argc;

char far * far *argv;

{

DM_ID dialogID;

Widget toplevel; /* Application shell erhalten von

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);

}

/* Abfrage der application shell */

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

AT_XWidget)) != 0)

{

DM_ID my_bgc;

DM_ID my_font;

DM_ID my_FontOfExit;

/* weitere, eigene Statements */ }

3.32.2 Microsoft Windows

Mit Hilfe dieser Funktion können die für Microsoft Windows notwendigen Daten erfragt werden, wie window handle, instance handle und color.

Die Bedeutung dieser Datentypen wird im entsprechenden Microsoft Windows Handbuch erklärt.

Folgende Werte sind für die Attribute zugelassen:

Attribut	Objekt	Rückgabewert	Bedeutung
AT_CanvasData	canvas	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 „Strukturen für Canvas-Funktionen“).
AT_ClipboardText	setup oder 0	DM_String	Dieses Attribut gibt den Textinhalt des Microsoft Windows Clipboards zurück. Der Rückgabewert wird gepuffert und ist bis zur erneuten Abfrage des Attributes gültig. Auch ein Setzen des Attributes macht den Puffer ungültig. Um den String ohne Änderung des Clipboards freizugeben, dient der Aufruf: DM_SetToolkitData(0, AT_ClipboardText, (FPTR) 0, 0);
AT_Color	color	COLORREF	Siehe auch AT_XColor
AT_Color	tile	HPALETTE	Siehe auch AT_XColor
AT_DataType	tile	int	Die Abfrage ist nur noch aus Kompatibilitätsgründen vorhanden. Es sollte mit DM_GetToolkitDataEx das Attribute AT_Tile mit gesetztem "data" Parameter verwendet werden. Dieses Attribut gibt den Typ des Musters zurück. Die Zuordnung ist bei AT_XTile beschrieben.
AT_DPI	IDM Objekte	int	Siehe auch AT_GetDPI
AT_Font	font	HFONT	Siehe auch AT_XFont
	IDM Objekte	HFONT	Siehe auch AT_XFont
	setup	HFONT	Siehe auch AT_XFont
AT_GetDPI	setup oder 0	int	Dieses Attribut gibt den System DPI Wert zurück. Siehe Hinweis unten.
AT_GetDPI	IDM Objekte	int	Dieses Attribut gibt den DPI Wert des Objektes zurück. Dieser ist abhängig zu welchem Monitor das Objekt zugeordnet ist. Siehe Hinweis unten.
AT_IsNull	font oder 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 oder 0	int	Dieses Attribut gibt die Anzahl der noch freier WSI-ID’s zurück. Achtung: Die Anzahl noch verfügbarer WSI-IDs sagt nichts darüber aus, wie viele Objekte tatsächlich noch sichtbar gemacht werden können! Es ist die maximale Obergrenze.
AT_Raster	dialog editbox groupbox layoutbox module notebook notepage spinbox splitbox statusbar tablefield toolbar Window	DWORD	Dieses Attribut gibt die Größe des am Objekt definierten Rasters in IDM Pixel zurück. Die Breite und Höhe ist in ein DWORD gepackt, siehe Hinweis unten.
AT_Raster	font	DWORD	Dieses Attribut gibt die Größe der Schriftart in IDM Pixel, wie sie für die Rasterberechnung verwendet wird, zurück. Die Breite und Höhe ist in ein DWORD gepackt, siehe Hinweis unten.
AT_SrollbarDimension	groupbox notepage window	DWORD	Dieses Attribut gibt die Breite der senkrechten und die Höhe der waagrechten Scrollbar in IDM Pixel zurück. Die Breite und Höhe ist in ein DWORD gepackt, siehe Hinweis unten.
AT_Size	dialog module	DWORD	Dieses Attribut gibt die Größe des Arbeitsbereichs des primären Monitors in IDM Pixel zurück. Die Breite und Höhe ist in ein DWORD gepackt, siehe Hinweis unten.
	font	DWORD	Dieses Attribut gibt die Größe der Schriftart in IDM Pixel zurück. Die Breite wird anhand des Referenzstrings berechnet, falls einer angegeben ist. Die Breite und Höhe ist in ein DWORD gepackt, siehe Hinweis unten.
	Übrige IDM Objekteaußer menubox, menuitem und menuseparator	DWORD	Dieses Attribut gibt die Größe des Objektes in IDM Pixel zurück. Die Breite und Höhe ist in ein DWORD gepackt, siehe Hinweis unten.
AT_Tile	color	HBRUSH	Siehe auch AT_XTile
AT_Tile	tile	HANDLE	Die Abfrage ist nur noch aus Kompatibilitätsgründen vorhanden. Es sollte DM_GetToolkitDataEx mit gesetztem "data" Parameter verwendet werden. Siehe auch AT_XTile
AT_toolhelp	setup oder 0	HWND	Dieses Attribut gibt den Microsoft Windows Handle des tooltip Controls zurück, welches vom Dialog Manager zur Darstellung des .toolhelp Attributs verwendet wird. Siehe auch „Beispiel zu AT_toolhelp am setup Objekt“ weiter unten.
AT_value	RTF edittext	DM_String	Dieses Attribut gibt den vollständigen Inhalt, also mit allen Formatierungsanweisungen usw., eines RTF-Eingabefeldes zurück.
AT_VSize	IDM Objekte außer menubox, menuitem und menuseparator	DWORD	Dieses Attribut gibt die virtuelle Größe des Objektes in IDM Pixel zurück. Gibt es keine virtuelle Größe, dann wird die reale Größe in IDM Pixel zurückgegeben. Die Breite und Höhe ist in ein DWORD gepackt, siehe Hinweis unten.
AT_Widget	USW	HWND	Siehe auch AT_XWidget
AT_WinHandle	dialog module setup oder 0	HINSTANCE	Dieses Attribut gibt den Microsoft Windows Handle der Anwendungsinstanz zurück.
	menubox	HMENU	Dieses Attribut gibt den Microsoft Windows Menu Handle zurück.
	menuitem menuseparator	HMENU	Dieses Attribut gibt den Microsoft Windows Menu Handle des umgebenden menubox Objekts zurück.
	Übrige IDM Objekte	HWND	Dieses Attribut gibt den Microsoft Windows Handle des Objekts zurück. Die Gruppierungsobjekte (groupbox, notepage, window, …) sind meist aus mehreren Microsoft Windows Objekten aufgebaut, bei diesen wird das Handle des Client-Fensters (das Fenster in dem die Kindobjekte angelegt werden) zurückgegeben.
AT_wsidata	cursor	HCURSOR	Siehe auch AT_XCursor
	font	HFONT	Siehe auch AT_XFont
	tile	HANDLE	Die Abfrage ist nur noch aus Kompatibilitätsgründen vorhanden. Es sollte DM_GetToolkitDataEx mit gesetztem "data" Parameter verwendet werden. Siehe auch AT_XTile
	Übrige IDM Objekte	HWND	Dieses Attribut gibt den Microsoft Windows Handle des äußeren Microsoft Windows Objektes zurück, das innere kann mit AT_WinHandle erfragt werden.
AT_XColor	color	COLORREF	Dieses Attribut gibt die Microsoft Windows-spezifische Struktur für die angegebene Farbe zurück. Der Zugriff auf die Farbwerte erfolgt mit den entsprechenden Makros von Microsoft Windows: 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	Dieses Attribut gibt die Microsoft Windows Farbpalette, die von dem Muster verwendet wird, zurück.
AT_XCursor	cursor	HCURSOR	Dieses Attribut gibt den Microsoft Windows Cursor Handle zurück.
AT_XFont	font	HFONT	Dieses Attribut gibt den Microsoft Windows Font Handle zurück.
	IDM Objekte	HFONT	Dieses Attribut gibt den Microsoft Windows Font Handle der an diesem Objekt verwendeten Schriftart zurück.
	setup	HFONT	Es wird der Font-Handle der verwendeten Standardschriftart zurück geliefert.
AT_XTile	color	HBRUSH	Dieses Attribut gibt eine Microsoft Windows Brush der Farbe zurück. Diese Brush kann zum Füllen des Hintergrunds verwendet werden.
AT_XTile	tile	HANDLE	Die Abfrage von AT_wsidata, AT_Tile und AT_XTile ohne Angabe des "data" Parameters ist nur noch aus Kompatibilitätsgründen vorhanden. Es sollte der "data" Parameter verwendet werden. Dieses Attribut gibt die Microsoft Windows spezifische Struktur für das Muster (tile) wie in Version A.06.03.a und früher zurück. Hierzu müssen GDI Objekte zusätzlich angelegt werden. Um die neuen Microsoft Direct2D Daten, die der IDM intern verwendet, zu erhalten, muss der "data" Parameter gesetzt werden. Der Typ des Microsoft Windows Handle ist abhängig von AT_DataType, wobei AT_DataType erst nach der Abfrage von AT_wsidata, AT_Tile oder AT_XTile abgefragt werden darf: DMF_TlkDataIsIcon: HICON DMF_TlkDataIsWMF: HMETAFILE DMF_TlkDataIsEMF: HENHMETAFILE Sonst: HBITMAP WICHTIG: Die zurückgelieferten Daten sollten nicht gespeichert werden, da diese automatisch freigegeben werden, wenn die tile Resource von keinem sichtbaren IDM Objekt mehr verwendet wird. Hinweis: Wenn mittels DM_SetToolkitData Daten gesetzt wurden, dann werden die gesetzten und nur die gesetzten Daten zurückgeliefert.
AT_XWidget	USW	HWND	Dieses Attribut gibt den Microsoft Windows Handle des USW Objektes zurück.

Hinweis zum Objekt und Attribut

Das beim Aufruf angegebene Objekt muss im Allgemeinen sichtbar und damit im WSI angelegt sein, damit die zurückgegebenen Daten Sinn machen. Ressourcen werden in der Regel beim Aufruf angelegt. Wird ein Objekttyp angegeben, der beim betreffenden Attribut nicht erwähnt ist, wird in der Regel eine Fehlermeldung in die Logdatei geschrieben und (FPTR) 0 zurückgegeben.

Hinweis zum Zugriff auf den Rückgabewert

Der Rückgabewert der Funktion ist ein FPTR bzw. void *, dieser muss auf den dokumentierten Rückgabewert gecastet werden, um beim Kompilieren keine Warnungen zu erhalten.

Da ein void * Zeiger auf jeden beliebigen anderen Zeiger gecastet werden kann, reicht bei allen Zeiger-Datentypen ein einfacher Castoperator. Zu den Zeiger-Datentypen zählen zum Beispiel sämtliche Microsoft Windows Handle, wie zum Beispiel HWND, HFONT, ... :

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

Bei Zahlenwerten muss meist ein Zwischencast eingefügt werden, da die Größe des Datenwerts beim Cast von einem Zeiger zu einer Zahl erhalten bleiben muss, um Warnungen zu vermeiden. Hierzu kann der Datentyp size_t verwendet werden, da dieser per Definition dieselbe Größe wie ein Zeiger besitzt. Anschließend kann dann auf einen kleineren Zahlentyp gecastet werden:

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

Hinweis Breite und Höhe in DWORD gepackt

Unter Microsoft Windows werden häufig Breite und Höhe in eine DWORD gepackt. Dies wird vom IDM zum Teil auch so gehandhabt. Die einzelnen Werte können dann mit den Microsoft Windows Makros LOWORD und HIWORD extrahiert werden:

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

WORD width = LOWORD(size);

WORD height = HIWORD(size);

Hinweis IDM Pixel

Der IDM für Windows 11 unterstützt hohe Auflösungen. Um Auswirkungen auf bestehende Dialogskripte so gering wie möglich zu halten, werden vom ISA Dialog Manager virtuelle Pixelkoordinaten verwendet. Diese basieren auf der Größe einer Anwendung, die hohe Auflösungen nicht unterstützt, wie zum Beispiel IDM für Windows 10.

Hinweis zu DPI-Werten

Achtung, alle DPI Werte sind dynamisch und können durch den Anwender geändert werden. Zum Beispiel können IDM Objekten auf einen anderen Monitor verschoben werden oder der Anwender stellt über die Systemsteuerung andere Vergrößerungsfaktoren ein.

Ist die Anwendung nicht DPI Aware (zum Beispiel IDM für Windows 10) dann wird immer der Standard DPI Wert von 96 verwendet.

Hinweis zu NULL-Werten bei Resourcen

Die Funktion DM_GetToolkitData liefert unter Microsoft Windows bei den font- und color Resourcen einen NULL Wert zurück, wenn die Resource auf UI_NULL_FONT bzw. UI_NULL_COLOR definiert wurde. Dies betrifft folgende Attribute:

AT_wsidata, AT_Font, AT_XFont:
Der Rückgabewert ist bei UI_NULL_FONT dann (HFONT) 0.
AT_Color, AT_XColor:
Der Rückgabewert ist bei UI_NULL_COLOR dann (COLORREF) -1L.
AT_Tile, AT_XTile:
Der Rückgabewert ist bei UI_NULL_COLOR dann (HBRUSH) 0.

Hinweis IDM Pixel

Beispiel

Abfragen einer Canvas spezifischen Struktur. Falls die Struktur noch nicht an der Canvas definiert ist, allokieren des notwendigen Speichers und übergeben der Daten an die 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);

}

Beispiel zu AT_toolhelp am setup Objekt

Hinweis

Die im Beispiel verwendeten Funktionen CloseToolhelp und SetToolhelpDisplayTime sind innerhalb des Dialogs entsprechend zu definieren.

Temporäres Schließen eines geöffneten Tooltip-Controls in einer Canvas-Funktion um die Canvas neu zu zeichnen

#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);

}

Anzeigezeit des Tooltip ändern

#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.32.3 Qt

Folgende Werte sind für die Attribute zugelassen:

Attribut	Objekt	Rückgabewert	Bedeutung
AT_Application	0	FPTR auf QApplication	Über dieses Attribut kann die der Anwendung zu Grunde liegende QApplication erfragt werden.
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 „Strukturen für Canvas-Funktionen“).
AT_Color	color	QColor / QBrush	Über dieses Attribut kann die von der Color-Ressource verwendete Farbe oder Farbverlauf (als QBrush) erfragt werden. Achtung: Es sollte als erstes immer auf eine zulässige Farbe (QColor) geprüft werden, da sich ein QBrush automatisch in eine QColor casten lässt, welche dann jedoch eine uninitialisierte aber zulässige Farbe darstellt.
AT_Font	font	QFont	Über dieses Attribut kann die von der Font-Ressource verwendete QFont erfragt werden.
AT_FontName	font	char*	Über dieses Attribut kann der Name der von der Font-Ressource verwendeten QFont erfragt werden.
AT_Tile	tile	QPixmap	Über dieses Attribut kann das QPixmap von einem Muster (tile) erfragt werden.
AT_XTile	tile	QPixmap	Siehe AT_Tile
AT_XWidget	IDM Objekte	QWidget	Dieses Attribut ermittelt das zu einer DM_ID gehörende QWidget.

Siehe auch

Funktion DM_GetToolkitDataEx