Meldungsdialog

Einleitung

Dieses Dokument beschreibt die Eigenschaften eines Dialogs zur Anzeige von Meldungen. Es wird das Format der verwendeten Meldungsdateien beschrieben und die Standard C Schnittstelle vorgestellt. Anhand von C-Programm­beispielen wird die Handhabung der Schnittstellenfunktionen erläutert.

Das Modul ist als dynamische Laufzeitbibliothek konzipiert und unter Windows 3.1 mit Visual C++ 1.5 und der MFC implementiert worden.

Format der Meldungsdatei

In einer Meldungsdatei sind i.a. mehrere Meldungen im ASCII-Format zusammengefaßt. Eine einzelne Meldung hat dabei die folgende Struktur:

[<Meldungsname>]

TYPE=<Dialogtyp>

ICON=<Icon>

TITLE=<Überschrift>

HEADING=<Kopftext>

TEXT=<Text>

[EOT]

Die eckigen Klammern umrahmen einen Meldungsnamen oder beinhalten den Ausdruck EOT, der das Ende einer Meldung kennzeichnet. Worte in Großbuchstaben, gefolgt von einem Gleichheitszeichen (=), sind fest definierte Schlüsselworte. Die Angaben in den spitzen Klammern (<>) stehen für beliebigen Text oder für eine Auswahl vorgegebener Einstellungen. Die Daten zu einem Schlüßelwort müssen einzeilig und in der gleichen Zeile stehen. Eine Ausnahme bildet das Schlüsselwort TEXT worauf weiter unten eingegangen wird.

Eine Zeile in der Meldungsdatei darf maximal MAX_LEN (siehe CMDFILE.H) Zeichen enthalten. Alle folgenden Zeichen werden nicht berücksichtigt.

Eine Anwendung wählt über den Meldungsnamen die anzuzeigende Meldung aus.

[], Meldungsname

Jede Meldung muß durch einen eindeutigen Namen gekennzeichnet sein. Der Meldungsname wird durch eckige Klammern eingerahmt. Die öffnende Klammer muß dabei am Zeilenanfang stehen. Der Meldungsname darf nicht über mehrere Zeilen stehen. Es wird zwischen Klein- und Großschreibung unterschieden.

TYPE  

Dieses Schlüßelwort kennzeichnet den Typ des Meldungsdialogs. Der Dialogtyp ist gekennzeichnet aus der Kombination und Anzahl der Buttons OK, Abbrechen, Ja, Nein, Detail. In Verbindung mit dem Button Detail besteht im Meldungsdialog die Möglichkeit ein Detailfenster auf bzw. zuzuklappen.

MSG_OK  Meldung mit OK-Button

MSG_OKDETAIL  Meldung mit OK- und Detail-Button

MSG_OKCANCEL  Meldung mit OK- und Abbrechen-Button

MSG_OKCANCELDETAIL  Meldung mit OK-, Abbrechen- und Detail-Button

MSG_YESNODETAIL  Abfrage mit Ja-, Nein- und Detail-Button

MSG_YESNO  Abfrage mit Ja-, Nein-Button

MSG_YESNOCANCELDETAIL Abfrage mit Ja-, Nein-, Abbrechen- und Detail-Button

MSG_YESNOCANCEL  Abfrage mit Ja-, Nein und Abbrechen-Button

MSG_NOYESDETAIL  Abfrage mit Ja-, Nein- und Detail-Button, Default-Button ist Nein

MSG_NOYES  Abfrage mit Ja-, Nein-Button, Default-Button ist Nein

MSG_NOYESCANCELDETAIL Abfrage mit Ja-, Nein-, Abbrechen- und Detail-Button, Default-Button ist Nein

MSG_NOYESCANCEL  Abfrage mit Ja-, Nein und Abbrechen-Button, Default-Button ist Nein

ICON  

Hier wird das Icon für den Meldungsdialog ausgewählt. Zur Auswahl stehen die folgenden Symbole:

IDI_APPLICATION Symbol der CMDMSG.DLL

IDI_ASTERISK  Informationssymbol

IDI_EXCLAMATION Ausrufezeichen

IDI_HAND  Stopschild

IDI_QUESTION  Fragezeichen

NULL  kein Icon anzeigen

TITLE

Gibt die Überschrift für den Meldungsdialog an. Steht hier der Wert DEFAULT, muß die Anwendung den Titel kontextabhängig setzen.

HEADING

Der Kopftext dient als Kurzbeschreibung für die Meldung. Er ist immer sichtbar, auch wenn das Detail­fenster des Meldungsdialogs zugeklappt ist.

TEXT  

Hier steht ein ausführlicher Meldungstext, der in Verbindung mit dem Detail-Button in einem aufklappbaren Fenster angezeigt werden kann. Der Text kann mehrzeilig sein. Er kann direkt hinter dem Gleichheitszeichen oder auch in der nächten Zeile beginnen. Über Formatausgabeelemente in diesem Text hat die aufrufende Anwendung die Möglichkeit zur Laufzeit Integerwerte oder beliebige Strings in den Meldungstext einzufügen und darzustellen.

Aufbau eines Formatausgabeelements

Formatausgabeelmente dürfen in den Sektionen TITLE, HEADING und TEXT einer Meldungsbeschreibung verwendet werden.Eine Formatausgabeelement ist von geschweiften Klammern umrahmt und hat folgenden Aufbau:

oder

Feldbreite:
Hier steht die Breite der Ausgabefläche oder die Anzahl der Stellen, die ausgegeben werden sollen. Eine Null oder eine leere Angabe bedeutet, daß die Feldbreite sich automatisch aus der Anzahl der darzustellenden Zeichen ergibt. Für den Datentyp String hat die Feldbreite keine Bedeutung.

Formatkennzeichen:
Gibt das Format der Ausgabe an. Möglich sind die Zeichen: 's', 'S' für Strings, 'x' bzw. 'X' für hexa­dezimale (Klein- bzw. Großbuchstaben) und 'd', 'D' für dezimale Integerwerte. Ein Ausgabestring darf mehrzeilig sein, wobei eine neue Zeile aus der Zeichenkombination 'rn' bestehen muß.

Variablenindex:
Indentifiziert die Variable innerhalb des Meldungstextes. Der Index, von Null beginnend, ist unabhängig vom auszugebenden Datentyp (Integer oder String). Es können maximal MAX_VARs (siehe MSGFILE.H) Ausgabevariablen indiziert werden.

Systemvariable:
Als Systemvariablen sind definiert:

PRODUCT_NAME Produktnamen (z.B. IBS CMD G4 oder System WorX)
VERSION Versionskennzeichnung
DATE Datum der Erstellung
INI_NAME Name der Initialisierungsdatei.

Die Systemvariablen werden zur Laufzeit aus dem Modul CMDINI.DLL ausgelesen. Die Systemvariablen müssen sämtlich in Großbuchstaben geschrieben werden.

Dialogeigenschaften

Die Anzeigefunktionalität des Dialoges läßt sich in zwei Aufgabenbereiche unterteilen. Zum einen dient er als allgemeine Anzeige von Meldungen in Verbindung mit einem Quittierungsbutton (in diesem Fall OK).

Der Zweite Aufgabenbereich besteht aus einer Abfrage mit einer Ja-Nein Entscheidung durch den Anwender. Die Buttons Ja und Nein treten immer paarweise auf.

In beiden Aufgabenbereichen können die Buttons Abbrechen und Detail als zusätzliche Funktionalität eingeblendet werden.

Der Dialog besitzt einen Standarddialograhmen mit Systemmenu. Er ist frei beweglich, in der Größe aber nicht veränderbar.

Dialogüberschrift

Die Dialogüberschrift kann von der aufrufenden Anwendung oder über der Meldungsdatei aus dem Eintrag des Schlüsselwortes TITLE gesetzt werden. Die Überschrift der aufrufenden Anwendung hat eine höhere Priorität als die aus der Meldungsdatei.

Gibt die aufrufende Anwendung keine Überschrift vor und der Eintrag aus der Meldungsdatei lautet 'DEFAULT' oder es ist keine Überschrift in der Meldungsdatei eingetragen, so wird die Dialogüberschrift aus der Überschrift des aufrufenden Fensters abgeleitet.

Icon  

Im Dialog kann ein Icon eingeblendet werden. Welches Symbol angezeigt wird, ergibt sich aus dem Eintrag des Schlüsselwortes ICON. Bei fehlendem oder unbekanntem Eintrag wird kein Icon angezeigt. Es stehen die von Windows vordefinierten Symbole zur Verfügung.

Kopftext

Ein mehrzeiliger Text, der aus dem Eintrag des Schlüsselwortes HEADING besteht.

Button-Leiste

Der Aufbau der Buttonleiste ergibt aus dem eingestellten Dialogtyp in der Meldungsdatei (Eintrag zum Schlüsselwort TYPE). Die sichtbaren Buttons werden entsprechend ihrere Anzahl als Gruppe mit gleichem Abstand zueinander in die Dialogmitte positioniert

OK-Button

Wird angezeigt beim Typ MSG_OK, MSG_OKCANCEL und MSG_OKCANCELDETAIL. Die Aktivierung veranlaßt das Schließen des Dialogs und liefert den Rückgabewert IDOK an die aufrufende Anwendung.

Abbrechen-Button

Der Abbrechen-Button zeigt sich beim Dialogtyp MSG_OKCANCEL, MSG_OKCANCELDETAIL, MSG_YESNOCANCEL und MSG_YESNOCANCELDETAIL. Die Aktivierung veranlaßt das Schließen des Dialogs und liefert den Rückgabewert IDCANCEL an die aufrufende Anwendung.

Detail-Button

Dieser Button bestimmt den Anzeigestatus des Detailfensters. Ist das Fenster zugeklappt trägt der Button die Inschrift 'Deatil >>', und die Aktivierung klappt das Fenster auf. Bei aufgeklapptem Fenster enthält der Button die Inschrift 'Deatil <<' und seine Aktivierung schließt das Detailfenster. Der Detail-Button wird angezeigt beim Typ MSG_OKDETAIL, MSG_OKCANCELDETAIL, MSG_YESNODETAIL und MSG_YESNOCANCELDETAIL.

Ja-Nein-Buttons

Die Buttons Ja und Nein treten immer paarweise auf. Sie werden angezeigt beim Typ MSG_YESNO, MSG_YESNOCANCEL, MSG_YESNODEATIL und MSG_YESNOCANCELDETAIL. Ihre Aktivierung veranlaßt das Schließen des Dialogs und liefert den Rückgabewert IDYES bzw IDNO an die aufrufende Anwendung.

Detailfenster

Das Detailfenster existiert nur, wenn der Button Detail sichtbar ist. Der Zustand des Detail-Buttons bestimmt, ob das Fenster sichtbar oder versteckt ist. Die Dialoghöhe paßt sich dabei automatisch an die Sichtbarkeit des Fensters an.

Der Fensterinhalt bestimmt sich aus dem Eintrag des Schlüsselwortes TEXT der Meldungsdatei.

Das Fenster wird automatisch um die Funktionen eines horizontalen und oder vertikalen Rollbalkens erweitert, wenn sich Zeilenanzahl und Zeilenlänge nicht komplett im Fenster darstellen lassen.

Der Text wird in Normalschrift angezeigt.

Standard C Schnittstelle

Im folgenden werden die Funktionen der Standard C Schnittstelle vorgestellt

MSG_InitMessage()

Syntax:  void FAR *MSG_InitMessage(HWND hWndParent, const char *pszFile,const char *pszName, const char *pszTitle)

Beschreibung: Diese Funktion Initialisiert den Zugriff auf die Instanz des Meldungsdialogs. Es wird der Name der Datei mit den Meldungstexten, der Suchstring und die Überschrift des Meldungsdialogs gesetzt. Der Suchstring kennzeichnet den Meldungstext, der angezeigt werden soll. Wird für die Dialogüberschrift ein NULL-Zeiger übergeben, wird der Fenstername des Vaterfensters übernommen. Der Rückgabewert der Funktion ist ein typenloser Zeiger auf die Dialoginstanz. Sie wird für alle weiteren Schnittstellenfunktionen benötigt. Der Rückgabewert ist bei fehlerfreier Ausführung ungleich NULL.
Um die Instanz wieder zu löschen, muß entweder die Funktion MSG_ShowMessage() oder das Funktionenpaar MSG_GetLengths() und MSG_GetMessageData() ausgeführt werden.

Parameter: hWndParent: Bezeichner des Vaterfensters

pszFile: Dateiname mit dem Meldungstext

pszName: Name der Meldung

pszTite: Dialogüberschrift

Rückgabe: Typenloser Zeiger auf die Dialoginstanz

MSG_SetIntVar()

Syntax:  BOOL MSG_SetIntVar(const void FAR *pInstance, int nIndex, int nValue)

Beschreibung: Setzt einen Integerwert für ein Ausgabeformatelement im Meldungstext. Es können maximal 10 Integer- und Stringvariablen gesetzt werden.

Parameters: pInstance: Zeiger auf die Dialoginstanz

nIndex: Variablenindex [0..9]

nValue: Datum

Rückgabe: TRUE wenn erfolgreich, sonst FALSE

MSG_SetStringVar()

Syntax:  BOOL MSG_SetStringVar(const void FAR *pInstance, int nIndex, const char FAR *pszValue)

Beschreibung: Setzt einen String in ein Ausgabeformatelement des Meldungstextes. Es können maximal 10 Integer- und Stringvariablen gesetzt werden.

Parameter: pInstance: Zeiger auf die Dialoginstanz

nIndex: Variablenindex [0..9]

pszValue: String

Rückgabe: TRUE wenn erfolgreich, sonst FALSE

MSG_ShowMessage()

Syntax:  int MSG_ShowMessage(const void FAR *pInstance);

Beschreibung: Öffnet taskmodal den Dialog des Meldungsfensters. Die Funktion liefert den Bezeichner des Steuerelements zurück, daß das Schließen des Dialogs veranlaßt hat (IDOK, IDYES, IDNO, IDCANCEL). Die Dialoginstanz der Funktion MSG_InitMessage() ist nach Rückkehr der Funktion ungültig. Die Funktion darf nicht in Verbindung mit den Funktionen MSG_GetLengths() und MSG_GetMessageData() verwendet werden.

Parameter: pInstance: Zeiger auf die Dialoginstanz

Rückgabe: Bezeichner des schließenden Steuerelements.

MSG_GetLengths()

Die Funktion MSG_GetLengths() in Verbindung mit der Funktion MSG_GetMessageData() stellt dem Anwender einen Zugriff auf die gesamte Information zu einer Meldung zur Verfügung. Der Meldungsdialog wird nicht angezeigt. Die Visualisierung der Meldungstexte obligt dem Aufrufer.

Syntax:  BOOL MSG_GetLengths(const void FAR *pInstance, int *const pnTitleLen, int *const pnHeadLen, int *const pnTextLen)

Beschreibung: Liefert die Stringlängen (ohne abschließendes Null-Zeichen), der Titelzeile, des Kopf- und Detailtextes zurück. Die Funktion darf nicht in Kombination mit der Funktion MSG_ShowMessage() verwendet werden. Sie ist in Verbindung mit der Funktion MSG_GetMessageData() anzuwenden, und muß vor dieser aufgerufen werden.

Parameter: pInstance: Zeiger auf die Dialoginstanz

pnTitleLen: Länge der Dialogüberschrift

pnHeadLen: Länge des Kopftextes

pnTextLen: Länge des Detailtextes

Rückgabe: TRUE wenn erfolgreich, sonst FALSE

MSG_GetMessageData()

Syntax:  BOOL MSG_GetMessageData(const void FAR *pInstance, char *const pszTitle, char *const pszHead, char *const pszText, int *const pnType, LPCSTR *const ppIconId)

Beschreibung: Liefert sämtliche Daten zu einer Meldung ohne den Meldungsdialog zu öffnen. Die Funktion darf nicht in Verbindung mit der Funktion MSG_ShowMessage() verwendet werden. Ihr Aufruf erfolgt nach Rückkehr der Funktion MSG_GetLengths() und entsprechender Speicherreservierung für die Textarrays. Datenelemente die nicht benötigt werden, kann ein NULL-Zeiger übergeben werden. Die Dialog­instanz der Funktion MSG_InitMessage() ist nach Rückkehr der Funktion ungültig.

Parameter: pInstance: Zeiger auf die Dialoginstanz

pszTitle: Zielstring für die Dialogüberschrift

pszHead: Zielstring für den Kopftext

pszText: Zielstring für den Detailtext

pnType: Zeiger auf eine Variable für den Dialogtyp

ppIconId: Zeiger auf eine Variable für den ICON-Bezeichner

Rückgabe: TRUE wenn erfolgreich, sonst FALSE

MSG_ExistMessage()

Syntax:  BOOL MSG_ExistMessage (LPCSTR pszFile, LPCSTR pszName)

Beschreibung: Überprüft ob in der Datei pszFile die Meldung mit dem Namen pszName vorhanden ist.

Parameter: pszFile Name der Meldungsdatei

pszName: Name der Meldung

Rückgabe: TRUE wenn Meldung existiert, sonst FALSE

Programmbeispiele

Die Meldung für die folgenden Beispiele habe folgenden Aufbau und sei in der Datei MESSAGE.TXT untergebracht:

[Meldung 1]

TYPE=MSG_OKDETAIL

ICON=IDI_ASTERISK

TITLE=DEFAULT

HEADING=Meldung mit OK- und Detail-Button!

TEXT=

Dies ist ein Integer-Ausgabeformatelement:

Dies ist ein Ausgabeformatelement für einen String:

[EOT]

Meldung im Dialog anzeigen

Dieses erste Beispiel zeigt die notwendigen Arbeitsschritte für das Öffnen des Meldungsdialoges.

int Beispiel1()

Daten zu einer Meldung auslesen

In diesem Beispiel möchte der Anwender die Texte zu einer Meldung selbständig verwalten. Die folgende Programmsequenz zeigt die Vorgehensweise, wie die Daten in der Meldungsdatei ausgelesen werden können, ohne daß der Meldungsdialog erscheint. Zu beachten ist, daß nicht beide Funktionalitäten gleichzeitig genutzt werden können.

void Beispiel2()

Fehlerbehandlung

Fehler in der Meldungsdatei

Treten Formatfehler in der Meldungsdatei auf, werden diese im Meldungsdialog angezeigt. Der Dialog stellt sich dabei als Typ MSG_OKDETAIL dar. Als Icon wird das Stopschild eingeblendet. In der Dialogüberschrift wird der Name der Meldungsdatei eingetragen. Der Kopftext zeigt einen allgemeinen Text für einen Formatfehler an. Im Detailfenster wird die Fehlerursache näher spezifiziert.

Landessprachen

Bei der Initialisierung der DLL des Meldungsdialoges wird der Landeskode aus der Initialisierungsdatei des IBS CMD ausgelesen. Der Zugriff auf die Initialisierungsdatei erfolgt über die Schnittstellenfunktionen der CMDINI.DLL.

Aus einer Dateinamenschablone und dem dreistelligen Landeskode wird ein Name für eine Resourcen DLL generiert.

Schablone: MSGnnn.DLL

mit nnn = dreistelliger Landeskode

Gelingt es dem Meldungsdialog die Resourcen DLL zu laden, ersetzt diese die Standardresource. Die Standardresource hat den Länderkode '000'.

Anderungsnachweis

Freigabevermerk

Das vorliegende Dokument - in der Revision 00 vom und Seiten umfassend - wurde heute geprüft und freigegeben.