GEM ganz light: PowerGEM-Library für Pure C, Teil 2
Dialoge in Fenstern finden bei Programmierern immer mehr Gefallen und auch MultiTOS entfaltet seine Vorteile bei Verwendung nicht-modaler Dialoge. Damit Sie das Rad nicht neu erfinden müssen, bietet unsere Library alle notwendigen Funktionen.
Die PowerGEM-Library stellt Ihnen drei verschiedene Fenstertypen zur Verfügung. Da wären einmal die ganz normalen Fenster, wie sie auch das AES erzeugt. Zudem gibt es Panel-Windows und Dialog-Windows (siehe Tabelle).
Die Ausmaße der Fenster werden durch zwei Rechteckstrukturen festgelegt, »max« gibt die maximalen Außenkoordinaten, »real« die Koordinaten zum Zeitpunkt des Öffnens an. »min_w« und »min_h« begrenzen die Mindestbreite und die Mindesthöhe des Fensters.
Der Parameter »flags« beschreibt die Komponenten, aus denen das Fenster besteht. Beim Erzeugen eines normalen Fensters übergeben Sie »type« die Konstante DATA_WINDOW, die in POWERGEM.H deklariert ist. »align« gibt bei Panel-Fenstern an, wie das Panel im Fenster angeordnet sein soll: Bei ALIGN_X wird das Panel oben links in Richtung Fensterbreite, bei ALIGN_Y oben links in Richtung Fensterhöhe ausgerichtet. »obj_name« gibt die Nummer des Dialoges im RSC-File an und »Start_obj« erwartet den Index des ersten zu editierenden Textes im Dialog. Enthält start_obj den Wert Null, positioniert PowerGEM den Cursor auf das hierarchisch erste editierbare Feld soweit vorhanden.
In »draw_code« übergeben Sie die Zeichenfunktion des Fensters. Mit »slide_code« dürfen Sie die Sliderverwaltung selbst übernehmen, falls Ihnen die Verwaltung von PowerGEM nicht genügen sollte. Der Funktion slide_code wird die Nummer des Ereignisses in »message« übergeben. Klickt der Anwender innerhalb des Fensters eine Maustaste, verzweigt PowerGEM in die Funktion »button_code«. Diese Funktion erhält x- und y-Koordinate des Mauszeigers, die Nummer des Mausbuttons und den Zustand der Sondertasten.
Der Pointer »key—code« zeigt auf eine Funktion, die sich um Eingaben druckbarer Zeichen seitens des Anwenders kümmert. Den ASCII-Code enthält die Variable »ascii«. Der Funktion »release« übergibt PowerGEM die Objektnummer und den Objektstatus eines angeklickten Objektes im Panel- oder Dialogfeld, um beispielsweise Schalter auszuwerten. Sie können hier aber auch spezielle Dialogformen wie z.B. Pop-Ups einfügen. Den in dem Aufruf deklarierten Funktionen wird ebenso ein Pointerauf die diesbezügliche WINDOW-Struktur übergeben.
Sollen Slider-Elemente Ihre Fenster zieren, initialisieren Sie diese über
init_slider(struct WINDOW *win, int x_elements, int y_elements, intx_size, int y_size);
Die Funktion erwartet in »win« einen Zeiger auf ein bereits erzeugtes Fenster. Achten Sie darauf, daß die Bits für Slider in der Variable »flags« bereits bei der Fenstererzeugung gesetzt sind. »x_elements« gibt die Anzahl der Elemente in x-Richtung, »y_elements« die Anzahl in y-Richtung an. Die Pixelgröße eines Elements enthält »x_size« für die x-Richtung und »y_size« für die y-Richtung.
Zum Öffnen des angelegten Fensters dient die Funktion
open_window(struct WINDOW *win, char *name, char *info);
»win« zeigt auf die Fensterstruktur, der String »name« erscheint als Fenstertitel, »info« enthält die Titelzeile des Fensters. Beachten Sie dabei bitte, daß die Flags »NAME« und »INFO« bei der Erzeugung eines Fensters gesetzt sein müssen.
Um auf ein bestimmtes Fenster zugreifen zu können, existieren die Funktionen »find_window()« und »find_name()«, die Ihnen einen Zeiger auf das gewünschte Fenster liefern.
struct WINDOW *find_window( int wh);
struct WINDOW *find_name (char *name);
Besonderheiten der Sliderprogrammierung
Die Sliderverwaltung von PowerGEM teilt die Gesamtinformation eines Fensters in Elemente auf. Bei der Darstellung des Fensterinhaltes ist es natürlich wichtig zu wissen, welcher Ausschnitt gezeichnet werden soll. PowerGEM stellt Ihnen hierfür zwei Offsets zur Verfügung, die die aktuelle Zeile und Spalte des Elementrasters repräsentieren. Diese Offsets beziehen sich dabei auf die obere linke Ecke des Fensterarbeitsbereiches. Zwei Funktionen liefern Ihnen diese Offsets:
get_x_slider(struct WINDOW *win);
get_y_slider(struct WINDOW *win);
Mit »add_row()« und »add_column« fügen Sie neue Zeilen und Spalten hinzu bzw. löschen diese. add_row(struct WINDOW *win, int count); add_column(struct WINDOW *win, int count);
Besonderheiten bei der Dialogprogrammierung
Um Ihnen die Programmierung von Dialogen zu erleichtern, sind verschiedene Funktionen vorhanden, die beispielsweise einen Textbuffer in eine TEDINFO-Struktur eintragen oder Buttons selektieren oder deselektieren.
button_action(struct WINDOW *win, int obj_index, void (*action) (void), boolean redraw);
Dem Button »obj_index« im Fenster win wird die Aktion »action« zugewiesen. Dieser Aktion werden keine Parameter übergeben, »redraw« gibt an, ob der Dialog neu gezeichnet werden soll (redraw = TRUE) oder nicht (redraw = FALSE).
set_text(struct WINDOW *win, int obj_index, char *buf j int length);
»set_text()« setzt die Adresse des Buffers »buf« in die TEDINFO-Struktur des Objektes mit der Objektnummer »obj_index« des Fensters »win« ein. Die Textlänge übergeben Sie im Parameter »length«.
select_btn(struct WINDOW *win, int obj_index, boolean redraw);
Der Button »obj_index« im Fenster »win« wird selektiert. Ist »redraw« „ TRUE, zeichnet PowerGEM den Button sofort neu, ansonsten beim nächsten Window-Redraw.
unselect_btn(struct WINDOW *win, int obj_index, boolean redraw);
Die Beschreibung entspricht der Funktion »select_btn«, nur wird hier der Button deselektiert. Welchen Status ein Objekt derzeit besitzt, klärt
get_objstate (struct WINDOW *win, int obj_index);
Als Parameter übergeben Sie wiederum die Nummer des Objekts »obj_index« im Fenster »win«. Wählt der Anwender einen Exit-Button wie »OK« oder »Abbruch«, beenden Sie den Dialog mit
break_dial(void);
Auskunftsfunktionen
Die Programmierung unter PowerGEM fordert natürlich auch Tribute. Folgendes Problem gilt es bei Verwendung von VDI-Ausgabefunktionen mittels eigenem Handle zu beachten: Bei einem Window-Redraw findet bei Grafikausgaben Ihrer Workstation kein Clipping statt, d.h. es werden Bereiche überschrieben. Da dies natürlich nicht wünschenswert ist, sollten Sie die virtuelle Workstation der PowerGEM-Library benutzen. Das Handle dieser Workstation erhalten Sie mit der Funktion:
get_handle(void);
Bei einer Ausgabe in ein Fenster ist es interessant zu wissen, wo sich überhaupt dessen Arbeitsbereich befindet. Die Funktion, die dies feststellt, heißt:
get_workarea(struct WINDOW *win, GRECT *rc);
Den Arbeitsbereich des Fensters »win« erhält man in der GRECT-Struktur »rc«. Über »get_winpos« erhalten Sie Auskunft über die aktuelle Fensterposition,
get_winpos (struct WINDOW *win, GRECT *rc);
Die Außenkoordinaten des Fensters »win« erhalten Sie in der GRECT-Struktur »rc«.
Den Einsatz der PowerGEM-Funktionen können Sie sehr schön anhand des auf Diskette befindlichen Demoprogrammes nachvollziehen. Das Modul »GEM_DEMO.C« übernimmt die Initialisierung der zu überwachenden Ereignisse und meldet die Menüaktionen an. Für jedes Fenster wurde ein eigenes Modul geschrieben, um die Besonderheiten besser hervorzuheben. Wie Sie unschwer erkennen, werden die Fenster bei jedem Modulaufruf neu erzeugt. Das hat folgenden Grund: beim Schließen eines Fensters werden alle Daten samt Window-Handle gelöscht, um Platz für andere Fenster zu machen. Achten Sie unbedingt darauf, daß jedem EXIT-Button eine Aktion zugeordnet wird. Wird der Dialog nicht beendet, muß das »redraw-Flag« auf TRUE gesetzt werden. (ah)
| Name: | create_window |
|---|---|
| Funktion: | normales Fenster erzeugen |
| Definition: | struct WINDOW *create_window(GRECT *max, GRECT *real, int min_w, int min_h, int flags, int type, void (*draw_code)(struct WINDOW *win), void (*slide_code)(struct WINDOW *win, int message), void {*button_code)(struct WINDOW *win, int mx, int my, int mb, int ks), void (*key_code)(struct WINDOW *win, char ascii)); |
| Ergebnis: | Zeiger auf die erzeugte WINDOW-Struktur |
| Name: | create_pwindow |
|---|---|
| Funktion: | Panel-Fenster erzeugen |
| Definition: | struct WINDOW *create_pwindow(int obj_name, GRECT *max, GRECT *real, int min_w, int min_h, int flags, int align, void (*draw_code)(struct WINDOW *win)# void (*slide_code)(struct WINDOW *win, int message), void (*button_code) (struct WINDOW *win, int mx, int my, int mb, int ks), void (*key_code)(struct WINDOW *win, char ascii), void (*release)(int obj, int state)); |
| Ergebnis: | s. create_window() |
| Name: | create_dial |
|---|---|
| Funktion: | Dialog-Fenster erzeugen |
| Definition: | struct WINDOW *create_dial(int obj_name, int start_obj, int flags, void (*slide_code)(struct WINDOW *win, int message), void (*button_code) (struct WINDOW *win, int mx, int my, int mb, int ks), void (*key_code) (struct WINDOW *win, char ascii), void (*release)(int obj, int state)); |
| Ergebnis: | s. create_window!) |
| Name: | init_slider |
|---|---|
| Funktion: | Slider-Elemente initialisieren |
| Definition: | boolean init_slider(struct WINDOW *win, int x_elements, int y_elements, int x_size, int y_size); |
| Beispiel: | boolean ret;int gl_wchar, gl_hchar; /* Zeichenbreite- und höhe */ struct WINDOW mywindow; / Zeiger auf Fenster */ ret = init_slider(mywindow, 80, 300, gl_wchar, gl_hchar); |
| Ergebnis: | FALSE, falls Speichermangel, sonst TRUE |
| Name: | open_window |
|---|---|
| Funktion: | erzeugtes Fenster öffnen und zur Verwaltung freigeben |
| Definition: | void open_window(struct |
| Beispiel: | struct WINDOW dialog; / Zeiger auf Fenster */ open_window(dialog, "Dialogfenster", "Bitte wählen Sie aus"); |
| Ergebnis: | - |
| Name: | find_window |
|---|---|
| Funktion: | Adresse einer WINDOW-Struktur bzgl. Window-Handle suchen |
| Definition: | struct WINDOW *find_window(int wh); |
| Ergebnis: | die Funktion liefert einen Zeiger auf die WINDOW-Struktur, deren Window-Handle mit wh übereinstimmt, ansonsten NULL |
| Name: | find_name |
|---|---|
| Funktion: | Adresse einer Window-Struktur bzgl. Window-Name suchen |
| Definition: | struct WINDOW *find_name(char "name); |
| Ergebnis: | die Funktion liefert einen Zeiger auf die WINDOW-Struktur, deren Fenstername mit name übereinstimmt, ansonsten NULL |
| Name: | get_x_slider |
|---|---|
| Funktion: | aktuelle Spaltenposition ermitteln |
| Definition: | int get_x_slider(struct WINDOW *win); |
| Ergebnis: | Spaltenposition des Fensters win |
| Name: | get_y_slider |
|---|---|
| Funktion: | aktuelle Zeilenposition ermitteln |
| Definition: | int get_y_slider(struct WINDOW *win); |
| Ergebnis: | Zeilenposition des Fensters win |
| Name: | add_row |
|---|---|
| Funktion: | Zeilen einfügen (löschen) |
| Definition: | void add_row(struct WINDOW *win, int count), |
| Ergebnis: | Die Funktion liefert kein Ergebnis zurück. Es werden count Zeilen eingefügt oder gelöscht (count < 0) |
| Name: | add_column |
|---|---|
| Funktion: | Spalten einfügen (löschen) |
| Definition: | void add column(struct WINDOW *win, int count); |
| Ergebnis: | Die Funktion liefert kein Ergebnis zurück. Es werden count Spalten eingefügt oder gelöscht (count < 0) |
| Name: | button_action |
|---|---|
| Funktion: | EXIT-Button-Aktion anmelden |
| Definition: | void button action (struct WINDOW *win, int obj index, void (*action)(void), boolean redraw); |
| Beispiel: | struct WINDOW win; / bereits erzeugtes Fenster / void take_data(void); / Dialogeinstellungen */ button_action(win, OKAY, take_data, TRUE); |
| Ergebnis: | - |
| Name: | set_text |
|---|---|
| Funktion: | Adresse eines Textbuffers in eine TEDINFO-Struktur setzen |
| Definition: | void set_text(struct WINDOW *win, int obj_index, char *buf, int length); |
| Ergebnis: | - |
| Name: | select_btn |
|---|---|
| Funktion: | Button selektieren |
| Definition: | void select_btn(struct WINDOW *win, int obj_index, boolean redraw); |
| Ergebnis: | - |
| Name: | unselect_btn |
|---|---|
| Funktion: | Button deselektieren |
| Definition: | void unselect_btn(struct WINDOW *win, int obj_index, boolean redraw); |
| Ergebnis: | - |
| Name: | get_objstate |
|---|---|
| Funktion: | SELECTED-Flag eines Buttons abfragen |
| Definition: | boolean get_objstate(struct WINDOW *win, int obj_index); |
| Ergebnis: | TRUE, wenn der Button selektiert ist, ansonsten wird FALSE zurückgeliefert. |
| Name: | break_dial |
|---|---|
| Funktion: | Dialog abbrechen (Abbruch- oder Okay-Button wurde gedrückt |
| Definition: | void break_dial(void); |
| Ergebnis: | - |
| Name: | get_handle |
|---|---|
| Funktion: | VDI-Werkstation ermitteln |
| Definition: | int get_handle(void); |
| Ergebnis: | Handle der virtuellen Werkstation von PowerGEM |
| Name: | get_workarea |
|---|---|
| Funktion: | Fensterarbeitsbereich ermitteln |
| Definition: | void get_workarea(struct WINDOW *win, GRECT *rc); |
| Ergebnis: | - |
| Name: | get_winpos |
|---|---|
| Funktion: | Fensterposition ermitteln |
| Definition: | void get_winpos(struct WINDOW *win, GRECT *rc); |
| Ergebnis: | - |
Boris Sander