------------------------------- | GLIB | | ----- | | | | Autor: | | Amin Coja-Oghlan | | Eekholtesweg 12 | | W-2000 Hamburg 74 | | | ------------------------------- Vorwort zur GLIB ---------------- GLIB ist eine C-Easy-Gem-Library. Das bedeutet, daž GLIB den Umgang mit GEM unter ANSI-C erleichtert. Sollten Sie schon einmal versucht haben, ein Programm mit grafischer Benutzeroberfl„che auf einem Rechner ohne Funktionen zur grafischen Benutzerfhrung, wie Sie z.B. GEM bietet, zu schreiben, so wird das Entsetzen sicherlich monatelang nicht von Ihnen gewichen sein (ich spreche aus Erfahrung...). Sollten Sie schon einmal versucht haben, ein Programm mit grafischer Benutzeroberfl„che unter GEM zu schreiben, so wird das Entsetzen je nach Kondition vielleicht nur einige Tage angehalten haben, da auch dies nicht zu den Dingen z„hlt, die man als einfach bezeichnen kann (zumindest fr den Anf„nger). Sollten Sie bereits Erfahrung mit GEM gesammelt und sich GLIB sowieso nur besorgt haben, um zu prfen, ob auch alles richtig ist, so werden Sie sp„testens dann auf GLIB zurckgreifen, wenn Ihr Chef wieder einmal einen Kunden anschleppt, der binnen einer Stunde eine Datenbank mit Iconge- steuertem Desktop, Mens in Fenstern, Popup-Mens und mindestens 4 M”glich- keiten, einen Menpunkt aufzurufen zu erhalten verlangt (die Installation auf seinem Rechner natrlich eingeschlossen, der 32.000 Farben auf einmal darstellt und das ganze in 1024 mal 800 Pixeln). Es ist selbstverst„ndlich, daž GLIB-Programme automatisch mit allen m”glichen und unm”glichen System- konfigurationen zusammenarbeiten. Die Vorteile gegenber Programmentwicklungswerkzeugen wie z.B. dem ACS (Application Construction System, ein Programm, das die Programmierung der Benutzeroberfl„che selbst bernimmt) liegen auf der Hand: Sie sind nicht an feste Programmskelette gefesselt, sondern k”nnen selbst alle Bausteine der Bibliothek zu einem Programm zusammenfgen. Da die Quelltexte mit- geliefert sind, k”nnen selbst sie eingesehen und fr spezielle Anwendungen abgewandelt werden. GLIB stellt also eine Erweiterung der M”glichkeiten auch fr den Profi dar und gibt dem Einsteiger die M”glichkeit, sich zun„chst mit GEM anzufreunden. Allerdings m”chte ich als Voraussetzung vorschlagen, sich wenigstens einmal einen šberblick ber das GEM-System verschafft zu haben. Dies erleichtert dem Einsteiger die Arbeit mit GLIB ungemein. Aužerdem werden natrlich gute Kenntnisse ber die Sprache C vorausgesetzt. Zur PD-Version der GLIB ----------------------- Sie haben nun die PD-Version der GLIB erhalten. Diese Version ist in vollem Umfange funktionstchtig. Eine so komplexe Library wie die GLIB verlangt jedoch ausfhrliche Erl„uter- ungen und Hilfen zum Verst„ndnis ihrer Funktionalit„t und zur Aussch”pfung ihrer M”glichkeiten. Dies kann eine README-Datei nicht gew„hrleisten, da ihr Rahmen gesprengt werden wrde. Bei mir ist jedoch ein vernnftiges, gedrucktes Handbuch erh„ltlich, das ausfhrlich auf alle Funktionen und Variablen eingeht und viele Hilfestell- ungen bietet. Es ist unter meiner Adresse (s.o.) gegen einen Betrag von DM 50,- zu erhalten. Des weiteren werden Sie als Benutzer meiner Bibliothek eingetragen und erhalten Updates sowie die M”glichkeit, Fragen an mich zu richten. Das Handbuch wird fr Benutzer von Pure-C durch eine Hilfsdatei erg„nzt, die sich in das Online-Hilfssystem von Pure-C eingliedert. Ihnen stehen dann jederzeit ausfhrliche Hilfestellungen zur Verfgung. GLIB insallieren ---------------- Auf der GLIB-Diskette sollten sich folgende Dateien befinden: GLIB.TXT lesen Sie gerade GLIB.H Include-File, in dem (fast) alle GLIB-Externals deklariert werden und das in Ihre Quelltexte einzubinden ist G2COM.C 1. Sourcefile der GLIB G1COM.C 2. Sourcefile (diese Reihenfolge ist korrekt) GLIB.PRJ Projektfile fr Pure-C, das GLIB.LIB erzeugt GLIB.LIB Pure-C-Library ohne Debug-Infos GLIB_DB.PRJ Projektfile fr Pure-C, das Debug-Infos anfgt und GLIB_DB.LIB erzeugt GLIB_DB.LIB Pure-C-Library mit Debug-Infos IMGMAIN.C Sourcedatei eines kleinen Beispielprogrammes IMG.PRG Das Ganze ausfhrbar IMGLOAD.PRJ Projektdatei GDEFAULT.PRJ Pure-C Projektdatei, die anstelle der DEFAULT.PRJ tritt. HAUS.IMG Beispiel-GEM-Image-Datei fr IMG.PRG Als Pure-C-User f„llt Ihnen die Installation besonders leicht: Kopieren Sie GLIB.LIB und GLIB_DB.LIB zu den anderen LIBs, GLIB.H zu den anderen Hs und zuletzt GDEFAULT.PRJ zu DEFAULT.PRJ - fertig. Andere User sollten zuerst GLIB.H zu ihren anderen Hs kopieren. Kompilieren Sie die .Cs neu und binden Sie dann ein. ACHTUNG: Achten Sie beim Kompilieren darauf, daž auch Sprnge ber ber 32kB vorkommen k”nnen, also Compiler-Schalter o.Ž.anknipsen! Was GLIB bietet --------------- GLIB bietet eine Funktionssammlung an, die (meiner Meinung nach) alle Berei- che der GEM-Programmierung anspricht. Um es noch einmal klarzustellen: GLIB ist kein ausfhrbares Programm wie du und ich, sondern eine Bibliothek, wie z.B. die C-Standartbibliothek. Und genauso werden auch Ihre Funktionen ange- sprochen. Fr diese Funktionen werden globale Variablen deklariert, die, und das ist ein Unterschied zur Standartbibliothek, dem Benutzer der GLIB zug„nglich sind. Dies erh”ht fr den Fortgeschrittenen die Flexibilit„t. Hier eine šbersicht ber die Funktionen: - rc_intersect schneidet zwei Rechtecke. Es benutzt die globalen Variablen GRECT t1,t2. GRECT ist eine GEM-Struktur, die in vdi.h deklariert wird. - g_newdesk meldet einen neuen Desktop an. Der Desktop ist die graue Fl„che (bei Farbe grn), auf der sich im DESKTOP die Laufwerksicons befinden. Es ist klar zwischen DESKTOP und Desktop zu unterscheiden, denn der DESKTOP ist die GEM-Kommandooberfl„che, die im Handbuch Ihres Rechners beschrieben wird, der Desktop dagegen halt die graue bzw. grne Fl„che, auf der Menleiste und Fenster liegen. Der Desktop selbst ist ein Objektbaum (s. GEM-Dokumentation z.B. im "Atari ST Profibuch"), in dem auch die Icons enthalten sind. Das besondere am Desktop ist, daž das GEM selbst das Redrawing bernimmt. Der Desktop hat das Window- Handle 0, wird also vom GEM als Window benutzt. Dies ist jedoch eine interne Angelegenheit, die uns nicht zu kmmern hat. - g_deskdraw zeichnet den Desktop-Objektbaum auf den Desktop. - g_icondraw zeichnet ein Icon aus einem Objektbaum in ein Fenster (auch in das Fenster mit Handle 0, also auf den Desktop). - g_rubberbox erlaubt eine Selektion aller Icons, die sich in einem Ob- jektbaum in einem gegebenen Rechteck befinden. Diese Funktion ist speziell fr den Einsatz mit Rubberboxen (s. graf_rbox, GEM-Dokumenta- tion) in zusammenhang mit Desktopicons ausgelegt. - g_swap vertauscht zwei gegebene Integer-Werte. - g_test prft, welches Objekt aus einem Objektbaum sich innerhalb eines gegebenen Rechtecks befindet. - g_icon ist eine der komplexesten Funktionen der GLIB. Sie handelt eine Icon-Aktion komplett ab, dazu geh”ren Anklicken, Verschieben, auf ein anderes Icon schieben, Doppelklicken und ins leere Klicken. - g_c_wind zeichnet ein gegebenes Rechteck weiž. - g_cwork zeichnet den Arbeitsbereich eines Fensters weiž. - g_find_new_slot dient dazu, in einem Vektor (Vektor bedeutet Array) von Strukturen, die GLIB zur Fensterverwaltung nutzt, ein freies Element zu finden. Diese Struktur (die WIND-Struktur) wird im Handbuch beschrieben. - g_find_slot sucht ein Element in diesem WIND-Vektor, dessen zugeh”riges Fenster benutzt, nicht aber ge”ffnet ist. - g_find_handle sucht in diesem Vektor nach dem Fenster mit dem gegebenen Handle. - g_structset setzt alle komponenten einer WIND-Struktur mit einem Funk- tionsaufruf. Dies kann natrlich auch einzeln mithlife des '='-Operators geschehen, wird aber sehr viel aufwendiger. - g_slidsize berechnet die Slidergr”že fr ein Fenster. - g_sldpos berechnet die Sliderposition fr ein Fenster. - g_windpos berechnet, wie das gesamte Dokument (damit sind die Daten ge- meint, von denen ein Teil im Fenster dargestellt wird, z.B. w„re das Inhaltsverzeichnis von Laufwerk C: auf dem DESKTOP ein Dokument, von dem ein Teil im Fenster dargestellt wird, wenn man C: ”ffnet) "unter dem Fenster verschoben" werden muž, um der Sliderposition zu entsprechen - g_scroll scrollt (Scrollen nennt sich der Effekt, den man beim DESKTOP beobachten kann, wenn man die Pfeiltasten an den Fenstern bet„tigt und ihr Inhalt nicht ganz in ein Fenster pažt) ein Fenster. - g_windcset kombiniert mehrere wind_set (s. GEM-Dokumentation) Aufrufe. - g_varset kombiniert mehrere wind_get Aufrufe (s. GEM-Dokumentation). - g_wind_open ”ffnet ein Fenster. - g_rast veranlažt GLIB nicht etwa zu einem kleinen Kaffep„uschen, nein, es rechnet ein Koordinatenpaar so um, daž es auf N'er Koordinaten einrastet, wobei N fr x und y-Koordinaten verschieden sein kann. - g_calc_redraw berechnet anhand der Rechteckliste eines Fensters und des Message-Buffers (globaler Vektor msgbuff), welche Teile eines Fensters neu zu zeichnen sind und ruft dementsprechend eine benutzerdefinierte Funktion auf, die dies bernimmt. Dazu ist bei den einzelnen Funktions- beschreibungen im Handbuch ein Beispiel gegeben. - g_wind_close schliežt ein Fenster. - g_full_window bringt es je nach dem Eintrag in der zugeh”rigen WIND- Struktur auf volle oder auf vorherige Gr”že. Die folgenden Fenster-Funktionen bauen auf den eben beschriebenen auf. Sie erm”glich eine bequeme und noch recht flexible Art, Fenster zu verwalten. Die obigen Routinen hatten zum Ziel, Ihnen das Gr”bste abzunehmen, deshalb sei derjenige, der lieber alles selbst und dafr mit viel Schnickschnack macht, auf jene verwiesen. - g_redraw bernimmt das Redrawing eines Fensters von GEM-Seite her. Dazu wird wie bei g_calc_redraw eine Funktion zum zeichnen des Gesamten Fen- sters ben”tigt. - g_top sorgt dafr, daž ein Fenster entsprechend den Informationen im Message-Buffer "getoppt" wird, d.h. daž es nach oben geholt und zum Aktiven wird. - g_wclose reagiert auf einen Klick auf den Close-Button des Fensters und schliežt es. - g_full bringt das Fenster auf volle oder vorherige Gr”že. - g_rfull bringt ein Fenster auf volle oder vorherige Gr”že, jedoch kann angegeben werden, wie das Fenster einrasten soll (s.o., g_rast). - g_arrow bernimmt die Abhandlung von Clicks auf Fenster-Pfeilbuttons und das seitenweise Bl„ttern in einem Fenster mittels Clicks neben die Sli- der entsprechend dem Message-Buffer. - g_hslide verschiebt den horizontzalen Slider des Fenstwers entsprechend den Informationen des Message-Buffers. - g_vslide tut dasselbe mit dem Vertikalen. - g_size sorgt entsprechend den Informationen im Message-Buffer fr eine Gr”ženver„nderung des Fensters, wobei dessen minimale Ausmaže und die Einrastwerte angegeben werden k”nnen. - g_move bernimmt anhand der Informationen im Message-Buffer Fensterver- schiebungen. - g_init initialisiert das komplette GEM-System und GLIB und meldet Fens- ter an. Die globalen Variablen phys_handle, vdi_handle, x_desk, y_desk, w_desk, h_desk, gl_wchar, gl_hchar, gl_wbox, gl_hbox, charw, charh, cw, ch, swidth, shight und nplanes werden gesetzt. Was diese im einzelnen bedeuten, wird im Handbuch beschrieben. Es wird eine gegebene Anzahl von Fenstern angemeldet (wind_create, s. GEM-Dokumentation), deren Ausmaže ebenfalls zu geben sind. - g_rsrc_init bernimmt das Laden vor Resource-Dateien. - g_mouse zeigt oder versteckt den Mauscursor. - g_update zeigt oder versteckt den Mauscursor und meldet Fenster-Redraw- Aktionen an oder ab. - g_clip setzt das Clipping-Rechteck. - g_multi wartet auf GEM-Ereignisse mittels evnt_multi. Dazu dienen die globalen Variablen msgbuff, mox, moy, mokstate, mobutton, mclicks, bmask, bstate, breturn, kstate, kreturn, event, m1flag, m2flag, m1x, m1y, m1w, m1h, m2x, m2y, m2w, m2h,mreturn, lowcunt und hicount. Anm.: Die Deklarationen der Variablen k”nnen Sie in glib.h einsehen. N„here Beschreibungen finden Sie im Handbuch. - g_invert_state invertiert ein Flag im Objekt-Status eines Objekts in einem Objektbaum. g_hndl_dial bernimmt die Dialogabhandlung mithlife einer gegebenen benutzerdefinierten Funktion, die fr Extras zust„ndig ist. Es kann allerdings auch eine GLIB-Interne (g_dialdummy) Funktion angegeben werden, wenn keine Extras vorhanden sind. - g_dummy dient als Dummy-Parameter fr g_multi, wenn ein Ereignistyp nicht auftritt. (s. Handbuch: Datailinformationen zu g_multi). - g_cwindows schliežt alle offenen Fenster und meldet sie ab. (s. GEM- Dokumentation wind_delete). - g_exit reinstalliert eine GEM-Applikation und sollte als letzter Aufruf in einem GEM-Programm erfolgen. - g_get liefert einen Zeiger auf eine Kopie eines gegebenen Bildschirm- bereichs. - g_put kopiert den mittels g_get geholten Bildschirmbereich auf den Bild- schirm. - g_popup_menu l„žt ein Popup-Men erscheinen und liefert den Index des angeclickten Eintrags zurck. - g_windall bernimmt die Komplette Fensterverwaltung, vom Empfang der Message bis zu deren Auswertung. Die Funktion bedient sich lediglich der beiden globalen Zeiger auf Funktionen all_a1f und all_b1f. all_a1f zeigt auf eine benutzerdefinierte Funktion, die ein komplettes Dokument zeichnet ohne ein Clipping-Rechteck zu setzen (das wird von GLIB ber- nommen) und all_b1f auf eine, die ein dafr sorgt, daž ber den Arbeitsbereich des Fensters (also das Fensterinnere ohne die Randelemen- te, die selbstverst„ndlich vom GEM selbst redrawt werden) gem„ž den Informationen der Rechteckliste Clipping-Rechtecke gesetzt werden und all_a1f aufruft. Dies kann z.B. ber g_redraw geschehen (s. u., Beispielprogramm). - g_dialdummy ist eine Dummy-Funktion fr g_hndl_dial. - g_owind ”ffnet ein Fenster. - g_load_image entpackt Daten einer GEM-Image-Datei, auf die ein Zeiger bergeben wird, setzt eine IMGHEADER-Struktur (der Header einer Image- Datei, s. glib.h und GEM-Dokumentation), auf die ein Zeiger gegeben wird und liefert einen Zeiger auf die entpackten Bilddaten. Accessories und die Applikationsnummer -------------------------------------- Auch Accessories k”nnen mit GLIB-Untersttzung laufen. Der einzige Unter- schied ist der, daž ACCs sich mittels menu_register Anmelden mssen. Dafr ist die Applikations-Identifizierung n”tig. Diese leifert appl_init. Sie wird auch von g_init zwischengespeichert, und zwar unter "ap_id" (Int- eger). Diese Variable muž als extern eingefhrt werden, denn sie ist nicht in der Header-Datei glib.h deklariert, weil normale Applikationen sie ja nicht brauchen. Aužerdem ist es selbstverst„ndlich, daž ACCs keinen Desktop anmelden k”nnen... IMG - Ein praktisches Beispiel ------------------------------ IMG ist ein leicht verst„ndliches Testprogramm, das ein GEM-Image-File einleist und in einem Fenster das entpackte Bild darstellt. Der Anwender wird also zum Programmstart in einer Fileselector-Box (diese Funktion (s. GEM-Dokumentation) ist so einfach zu handhaben, daž eine GLIB-vereinfachung Unsinn w„re) aufgefordert, eine ".IMG"-Datei auszuw„hlen. Diese wird nun von IMG in den Speicher geladen und per GLIB entpackt. Nun kommt die Fensterverwaltung, die ja bereits initialisiert ist, da mit g_init am Anfang ein Fenster angemeldet wurde, zum Zuge. Zun„chst werden die Dokumenttypischen Daten aus der IMGHEADER-Struktur sowie die brigen Fensterinfos fr den Programmstart mittels g_structset in den Slot bertragen. Nachdem das Fenster ge”ffnet und die all_a1f und all_b1f gesetzt sind, tritt g_multi in Aktion. Zun„chst sendet GEM fr das neue Fenster eine Redraw-Message, da es ja sonst leer w„re. Hierdurch wird durch g_windall die Redraw-Funktion alarmiert. Diese mutet etwas kompliziert an, ist es aber nicht. Eigendlich wrde es reichen, das Bild nach fwx und fwy verschoben in den Arbeitsbereich hineinzukopieren. Jedoch ist erst zur Laufzeit bekannt, wie grož das Bild ist. Es k”nnte ja theoretisch auch kleiner als das Fenster sein. Deshalb wird der m”glicherweise brige Bereich ermittelt und mit einem grauen Recht- eck ausgefllt. Die weitere Arbeit des Users mit dem Fenster schert uns praktisch nicht mehr. GLIB handelt alles brav ab und arbeitet dabei mit unseren Redraw- Funktionen zusammen. Allerdings bleibt ein Ereignis in diesem Beispiel un- serer Obhut berlassen: Das Schliežen des Fensters. Das Programm soll dann ja beendet werden. Also melden wir unsere eigene Funktion g_multi zum Schliežen an (es ist m”glich, einen Teil der Ereignisse g_windall zu ber- lassen, w„hrend der Rest anders gemanagt wird). Diese ruft nun die GLIB- Funktion zum Schliežen des Fensters auf, schaltet g_update ab und gibt TRUE an g_multi zurck, worauf diese Funktion ihre Arbeit beendet, an das Haupt- programm zurckspringt und dessen Arbeit fortgesetzt wird. Eine Anmerkung zur Arbeit mit mehreren Fenstern: Es tritt hierbei ja das Problem auf, daž die alles redrawnde Funktion keinen Parameter erh„lt. Woher soll diese also wissen, welches Window zu redrawn ist ? Nun, sie fhrt einfach ein g_find_handle auf msgbuff[3] aus und erh„lt den slot, den sie nun weiterreichen bzw. fr das Clipping verwenden kann.