Power-Programmierung

home *** CD-ROM | disk | FTP | other *** search

/ Power-Programmierung / CD2.mdf / c / library / dos / window / windowc / window.doc < prev

Wrap

Text File | 1993-07-29 | 166.4 KB | 3,385 lines

Jürgen Altfeld Hofkurat-Diehl-Str. 7 D-8042 Oberschleißheim (bei München) West Germany Tel.: (089) 315 44 44 Mitglied der I.d.S ┌──────────────────────────────────────────────────────────────────────┐ │ │ │ █▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ ████████ Autoren │ │ ██ ┌─╖ ┌╖┌───╖ ▒▒ █▒▒▒▒▒▒▒▒ Händler │ │ ██ │ ║ │║│╔══╝ ▒▒ █▒▓▓▓▓▓▓▓▓ Anwender │ │ ██ │ ║┌──┘║│╙──╖ ▒▒ █▒▓ │ │ ██ │ ║│╔═╕║╘══╕║ ▒▒ ────────────────────── │ │ ██ │ ║│╙─┘║┌──┘║ ▒▒ Interessengemeinschaft │ │ ██ ╘═╝╘═══╝╘═══╝ ▒▒ deutschsprachiger │ │ ██████████████████▒ Shareware │ │ │ └──────────────────────────────────────────────────────────────────────┘ ╔══════════════════════════════════════════════════════════════════════╗ ║ ║ ║ ╔═╗ ╔═╗ ╔═╗ ║ ║ ║ ║ ║ ║ ╔═╗ ║ ║ ║ ║ ║ ║ ║ ║ ╚═╝ ║ ║ ║ ║ ║ ║ ╔═╗ ║ ║ ╔═╗ ╔══════╗ ╔════╝ ║ ╔══════╗ ╔═╗ ╔═╗ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ╔══╗ ║ ║ ╔══╗ ║ ║ ╔══╗ ║ ║ ║ ╔═╗ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ║ ╚═╝ ╚═╝ ║ ║ ║ ║ ║ ║ ║ ║ ╚══╝ ║ ║ ╚══╝ ║ ║ ╚═╝ ╚═╝ ║ ║ ║ ╚═════════╝ ╚═╝ ╚═╝ ╚═╝ ╚══════╝ ╚══════╝ ╚═════════╝ ║ ║ ║ ╚══════════════════════════════════════════════════════════════════════╝ ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐ ┌─┐ ┌┐ │ ┌─────┘ └──┐ ┌──┘ │ ┌───┐ │ │ ┌───┐ │ │ │ └┘ ┌──────┐ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ ┌────┘ │ │ ┌─────┐ │ │ │ │ │ │ │ │ │ │ │ │ │ └────┐ │ │ └─────┘ │ │ │ │ │ │ │ │ │ │ │ │ └────┐ │ │ └─────┐ │ │ │ └───┘ │ │ └───┘ │ │ └────┐ ┌────┘ │ └───────┘ └─┘ └───────┘ └───────┘ └──────┘ └──────┘ Anfragen jeder Art, die eine schriftliche Antwort oder einen telefonischen Rückruf von mir erfordern, werden nur gegen einen Unkostenbeitrag von DM 3,-- (am besten in Briefmarken) bearbeitet! WINDOW.C - Die Toolbox für Quick-C ab Version 2.0 =================================================== Inhaltsverzeichnis: Kapitel: Themen: 1. Allgemeines 1.1 Kurzbeschreibung 1.2 Hard- und Softwarevoraussetzungen 1.3 Konfiguration der Quick-C-Entwicklungsumgebung 1.4 Installation der Toolbox auf Festplatte / Disk. 1.5 Erweiterungen der Toolbox 2. Haftung und Lizenzvertrag 2.1 Lizenzvertrag und Rechte Dritter 2.2 Haftung und Gewähr 3. Einleitung 4. Neue Datentypen und Variablen der Toolbox 4.1 Windows 4.2 Menüpunkte 4.3 Globale Variablen 5. Funktionen der Toolbox 5.1 Verwaltung der Toolbox 5.2 Allgemeine Ein- / Ausgaben beim Bildschirm 5.3 Windows 5.4 Menüs 5.5 Dateiverwaltung 5.6 Sonstige 6. Beispiele und praktische Hinweise 7. Programm-Beispiel 8. Anwenderfreundliche Menüs Anhang: A Kurzreferenz / Zusammenfassung der wichtigsten globalen Variablen und Funktionen 1. Globale Variablen 2. Funktionen 3. Einfügedateien innerhalb der Toolbox B Evtl. auftretende Probleme und deren Lösung C Inkrementales Compilieren Dokumentation von WINDOW.C ============================ Stand der Dokumentation: 16.07.90 Versions-Nummer der Toolbox "WINDOW.C": v1.0 (bei Vollversion) v1.0sw (bei Shareware) Diese Dokumentation beschreibt sowohl die registrierte Vollversion als auch die Shareware-Version. Bitte beachten Sie, daß in der Shareware-Version einige leistungsstarke Funktionen nicht enthalten sind (z. B. "inhalt", "color" u. a.)! Auch wurden einige Hinweis-Fenster eingebaut. Ansonsten hat die Shareware-Version keinerlei programmtechnische Einschränkungen. Die Shareware-Version ist voll aufwärtskompatibel zur Vollversion. In der Shareware-Version dürfen keinerlei Veränderungen an dem Quelltext der Toolbox vorgenommen werden! Außerdem dürfen die mit der Shareware-Version der Toolbox erstellten Programme nur für persönliche (unentgeltliche) Zwecke verwendet werden. Sobald Sie die Programme unentgeltlich weitergeben oder verkaufen wollen, müssen Sie sich registrieren lassen! ----- 1. Allgemeines ------------------------------------------------------- 1.1 Kurzbeschreibung Die Toolbox "WINDOW.C" beinhaltet eine Reihe von Unterroutinen, mit deren Hilfe man komfortable Benutzeroberflächen in eigene Programme einbauen kann. Sie haben nun die Möglichkeit, fast unbegrenzt viele Bildschirmfenster (Windows) zu öffnen. Dabei wird der alte Bildschirm- hintergrund nach dem Schließen des Windows wieder restauriert. Sie können außerdem beliebige Auswahl-Menüs in Ihre Programme einbauen, seien es Pop-Up- oder Pull-Down-Menüs. Mit Hilfe von Fenstern können beliebige Dialogboxen erstellt werden. Sämtliche Farben sind vom Anwender anpassbar. Es existiert sogar eine Funktion, die in einem Window alle Farben anzeigt. Der Anwender kann dann die Farben auswählen, die seinen Wünschen am meisten entsprechen. Die Toolbox arbeitet mit allen Grafikkarten zusammen, die einen Textmodus darstellen können, d. h. die kompatibel zur MDA-Karte sind. Beim Aktivieren der Toolbox wird automatisch die passende Bildschirmkarte erkannt und der beste Textmodus eingeschaltet. Der Grafikmodus wird NICHT unterstützt. Es kann nur in den Textmodi gearbeitet werden, die den Text mit einer Breite von 80 Zeichen und mindestens 25 Zeilen darstellen. Des weiteren ist eine Funktion integriert, die die bequeme Auswahl einer Datei erlaubt. In komfortabelster Weise kann man den Pfad oder das Laufwerk wechseln, ohne daß man deren Bezeichnungen eintippt. Die gesamte Steuerung erfolgt innerhalb eines Windows und ist menü-orientiert! Es wird eine Funktion zur komfortablen Eingabe und Bearbeitung von Strings mitgeliefert. Die Toolbox ermöglicht es, die eigenen Programme mit kontext-sensitiven Hilfefunktionen zu versehen. Die bereits in der Toolbox vorgefertigten Funktionen beinhalten ebenfalls, soweit notwendig, kontext-sensitive Hilfsbildschirme. Das mitgelieferte Programm "DEMO.EXE" demonstriert, was die Toolbox alles kann. Die Toolbox unterstützt übrigens alle Speichermodelle (Small, Medium, Compakt, Large und Huge). Probleme sind mir bisher nicht bekannt. Für entsprechende Hinweise bin ich dankbar. Zeitkritische Routinen wurden komplett in Assembler geschrieben. Hierdurch wird die hohe Verarbeitungsgeschwin- digkeit der Toolbox erreicht. Die Auslieferung der Toolbox erfolgt mit dem vollständig dokumentierten Quellcode in C und Assembler! Somit sind Änderungen ohne weiteres möglich. 1.2 Hard- und Softwarevoraussetzungen Hardware-Voraussetzungen zum Compilieren: - mind. 2 Diskettenlaufwerke (Festplatte empfohlen) für den Microsoft Quick C Compiler - mind. 512 KByte verfügbaren Arbeitsspeicher - DOS 3.0 oder höher - beliebige Grafikkarte Software-Voraussetzungen zum Compilieren: - Microsoft Quick C Compiler Version 2.0 oder höher zum Compilieren des Quelltextes (WINDOW.C). Der Microsoft C Compiler MSC kann nicht benutzt werden, da der eingebaute In-Line-Assembler von Quick C 2.0 zum Einbinden von Assembler-Routinen verwendet wird; ebensowenig kann der Turbo-C, Power C oder sonst ein anderer C-Compiler verwendet werden, ohne daß die Toolbox vorher an diese Compiler angepaßt wurde. Hard- und Software-Voraussetzungen für die mit der Toolbox erstellten Programme: - DOS 3.0 oder höher - mind. 1 Diskettenlaufwerk - beliebige Grafikkarte - mind. 512 KB Speicherplatz 1.3 Konfiguration der Quick-C-Entwicklungsumgebung !!! W I C H T I G: !!! Für die Benutzung der Toolbox innerhalb der Quick-C-Entwicklungsumgebung müssen die nachfolgend aufgeführten Einstellungen vorgenommen werden, ansonsten arbeitet die Toolbox nicht korrekt! Die Benutzung der Entwicklungsumgebung wird sehr empfohlen, weil sie keinerlei Nachteile mit sich bringt! Die Größe des Stacks muß mindestens auf 8192 Bytes festgelegt werden. Innerhalb der Quick-C-Entwicklungsumgebung geschieht dies in dem Menü "Optionen -> Make... -> Linker-Marken" bei dem Eingabefeld "Stapelgröße". Sollten Sie Ihre Programme von der Befehlszeile aus compilieren, müssen Sie einen entsprechenden "Schalter" angeben (z. B. "qcl /F2000 Beispiel.C", wobei /F2000 den Stapel auf die hexadezimale Größe 0x2000 = dezimal 8192 Bytes einstellt). In dem Menü "Optionen -> Make... -> Compiler-Marken" muß außerdem - die Warnstufe auf "Stufe 1", - die Programmiersprache auf "MS Erweiterung", - die Zeigerprüfung auf "ausgeschaltet" und - "Inkrementaler Compiler" auf "eingeschaltet" (mit "X" angekreuzt) gesetzt werden. 1.4 Installation der Toolbox auf Festplatte bzw. Diskette Der Quick-C-Compiler benötigt für seine Arbeit mindestens zwei Diskettenlaufwerke. Um das ständige Wechseln von Disketten zu vermeiden, wird für diese Toolbox jedoch eine Festplatte mit mindestens einem Megabyte freien Speicherplatz empfohlen. Zur Installation der Toolbox muß man zuerst die Einfügedatei "WINDOW.H" in das Unterverzeichnis der Headerdateien kopieren. Dadurch wird das inkrementale Compilieren erst ermöglicht. Inkrementales Compilieren ist nur mit der Vollversion der Toolbox möglich! Bei der !!! Installation der Shareware-Version entfällt dieser Schritt. "Headerdateien" sind alle Einfügedateien mit der Datei-Extension ".H" (z. B. die altbekannte Datei "stdio.h"). Standardmäßig befinden sich diese Dateien in einem Unterverzeichnis mit dem Namen "INC", z. B. "C:\QC2\INC". Wird mit dem "#include"-Befehl eine Headerdatei in ein C-Programm eingebunden, so sucht Quick-C auch in diesem Verzeichnis nach der gewünschten Headerdatei. Die Toolbox wird ebenfalls mit "#include" in die eigenen Programme eingebunden. Deshalb muß die Toolboxdatei "WINDOW.H" in das richtige Header-Verzeichnis kopiert werden. Sollten Sie den Verzeichnisnamen Ihrer Einfügedateien nicht mehr wissen, geben Sie einfach "set" im Kommando-Modus von DOS ein. Sie sehen dann den Inhalt aller Umgebungsvariablen. Neben dem Variablennamen "INCLUDE" können Sie nun den Pfad der Headerdateien ablesen (z. B. "INCLUDE=C:\QC2\INC"). Zum Kopieren gehen Sie folgendermaßen vor: - Legen Sie die Toolbox-Diskette in das Laufwerk A: - Schalten Sie auf das Laufwerk A: um - kopieren Sie die Datei "WINDOW.H" auf Ihre Festplatte in das Verzeichnis Ihrer Headerdateien: copy window.h c:\qc2\inc - Arbeiten Sie ohne Festplatte, müssen Sie stattdessen die Datei "WINDOW.H" in das Headerverzeichnis Ihrer Quick-C- Diskette kopieren (in das Laufwerk B: einlegen!): copy window.h b:\qc2\inc Natürlich ist beim "copy"-Befehl der tatsächliche Pfadname zu dem Header-Verzeichnis anzugeben. !!! Jetzt müssen Sie (sowohl bei der Vollversion als auch bei der Shareware-Version) nur noch den Quelltext der eigentlichen Toolbox (Datei "WINDOW.C") in dasjenige Verzeichnis kopieren, in dem Sie Ihre Programme entwerfen und kompilieren. Dazu gehen Sie folgendermaßen vor: copy window.c c:\qc2 (bei Festplatte) copy window.c b:\qc2 (bei Diskette) Sie können beim "copy"-Befehl natürlich auch jeden anderen Pfadnamen angeben, wenn sich Ihre C-Programme in einem anderen Verzeichnis befinden. Ich persönlich würde den Quelltext "WINDOW.C" sogar in das gleiche Verzeichnis wie die Datei "WINDOW.H" kopieren, also in das Verzeichnis der Include-Dateien. Der Vorteil hierbei ist, daß Quick-C beim Einfügen der Toolbox die Datei "WINDOW.C" praktisch immer findet, weil der Suchpfad für die Einfügedateien bekannt ist. Die Toolbox ist nun einsatzbereit. Bitte beachten Sie, daß keine anderen Dateien mit dem Namen "WINDOW.C" oder "WINDOW.H" in den jeweiligen Arbeitsverzeichnissen von Quick-C existieren dürfen. Es könnte sonst passieren, daß eine andere Datei (und nicht die Toolbox) in Ihre Programme eingebunden wird. Sollte ein solcher Namenskonflikt auftreten, benennen Sie die andere Datei einfach um (z. B. "ren window.c window1.c") oder löschen Sie diese, wenn Sie nicht mehr benötigt wird. 1.5 Erweiterungen der Toolbox Haben Sie irgendwelche neuen Funktionen entworfen, die auch andere C-Programmierer interessieren könnten? Wenn ja, dann setzen Sie sich doch einfach mit mir in Verbindung! Ich bin an sinnvollen Erweiterungen der Toolbox sehr interessiert. Gute Erweiterungen werden von mir angekauft und in die Toolbox eingebaut! Voraussetzung ist, daß Ihre neuen Funktionen möglichst fehlerfrei arbeiten, strukturiert und modular programmiert sind und mit einer ausführlichen Dokumentation versehen wurden. Wie ich inzwischen erfahren habe, kommt demnächst eine neue Version von Turbo-C auf den Markt (Turbo-C v3.0 mit objektorientiertem C++). Diese Version besitzt nun endlich die Fähigkeit, mit Hilfe des "_asm"-Befehls Assembler-Programm in ein C-Programm einzubauen (genau wie in Quick-C). Leider weiß ich noch nicht, inwieweit die beiden "_asm"-Befehle kompatibel zueinander sind. Da meine Toolbox neben diesem "_asm"-Befehl und einigen kleineren Ausnahmen keine Microsoft-spezifischen Befehle verwendet, dürfte eine Anpassung an Turbo-C v3.0 ohne größere Probleme möglich sein. Sollte es jemand schaffen, die Toolbox an diesen Compiler (oder auch an jeden anderen C-Compiler) anzupassen, bin ich am Ankauf dieser angepaßten Version brennend interessiert! Bitte wenden Sie sich in diesem Fall umgehend an mich. ------ 2. Haftung und Lizenzvertrag ----------------------------------------- 2.1 Lizenzvertrag und Rechte Dritter Alle Rechte an dieser Toolbox liegen bei Jürgen Altfeld, Hofkurat-Diehl-Str. 7 in D-8042 Oberschleißheim (West Germany). Mit dem Erwerb dieses Produkts wird dem Käufer ein einfaches Recht zur Benutzung der urheberrechtlich geschützten Toolbox eingeräumt. Die Vollversion der Toolbox darf nur auf einem einzigen Rechner zur gleichen Zeit benutzt werden. Der Käufer der Toolbox muß dafür Sorge tragen, daß kein Dritter die Toolbox benutzen kann. Mehrfachinstallationen bedürfen eines gesonderten Kaufvertrages (es werden Rabatte gewährt!). Es ist verboten, die registrierte Vollversion weiterzugeben. Der Käufer der reg. Vollversion kann seine Nutzungsrechte nicht an einen Dritten übertragen. Benutzer der registrierten Vollversion brauchen hierfür keine Lizenzgebühren bei der gewerblichen Veräußerung der mit dieser Toolbox erstellten Applikationen zu zahlen (keine Run-Time-Lizenzen oder -Gebühren erforderlich!). Registrierte Benutzer der Vollversion dürfen den Quellcode beliebig verändern. Die Weitergabe des originalen oder geänderten Quellcodes ist jedoch nicht erlaubt! Der registrierte Benutzer der Vollversion hat das Recht, Updateversionen der Toolbox zum Vorzugspreis zu erwerben. Bitte haben Sie Verständnis dafür, daß nicht jeder registrierte Anwender persönlich bei kleineren Änderungen informiert werden kann. Melden Sie sich einfach ab und zu bei mir und erkundigen Sie sich nach dem neuesten Stand des Programmes. Bei entscheidenden Änderungen und Erweiterungen werden Sie selbstverständlich von mir benachrichtigt! Der Autor der Toolbox ist berechtigt, Aktualisierungen der Software nach eigenem Ermessen zu erstellen. Das Programm ist ein mit viel Aufwand hergestelltes Qualitätsprodukt. Unerlaubte Kopierung, Vervielfältigung, Verleih oder Vermietung stellt einen Diebstahl geistigen Eigentums dar und wird zivil- und strafrechtlich verfolgt. Sämtliche Rechte Dritter bleiben unberührt, insbesondere auch die eingetragenen Markenzeichen. Wer sich mit diesen unter Nummer 2.1 oder 2.2 genannten Bedingungen nicht einverstanden erklärt, darf diese Software nicht anwenden, benutzen oder weitergeben. Ausnahmen und Sondervereinbarungen bedürfen zu Ihrer Gültigkeit der schriftlichen Genehmigung. 2.2 Haftung und Gewähr Ich übernehme keine Haftung für die Fehlerfreiheit der Software. Insbesondere übernehme ich keine Gewähr dafür, daß die Software den Anforderungen und Zwecken des Erwerbers genügt oder mit anderen von ihm ausgewählten Programmen zusammenarbeitet. Die Verantwortung für die richtige Auswahl und die Folgen der Benutzung der Software sowie der damit beabsichtigten oder erzielten Ergebnisse trägt der Erwerber. Das gleiche gilt für das die Software begleitende schriftliche Material und die Dokumentationen. Sollte der Datenträger (die Diskette) oder die damit ausgelieferte Hardware fehlerhaft sein, so kann der Erwerber Ersatzlieferung während der Gewährleistungszeit von 6 Monaten ab Lieferung verlangen. Er muß dazu die Diskette, die evtl. mit ihr ausgelieferte Hardware einschl. der Reservekopien und des schriftlichen Materials und einer Kopie der Rechnung/Quittung an mich zurückgeben. Wer sich mit diesen unter Nummer 2.1 oder 2.2 genannten Bedingungen nicht einverstanden erklärt, darf diese Software nicht anwenden, benutzen oder weitergeben. ------ 3. Einleitung -------------------------------------------------------- Im Prinzip bietet jedes Programm eine Reihe von Funktionen an, die je nach Wunsch des Benutzers ausgeführt werden. Es ist die Aufgabe der Benutzeroberfläche, alle Möglichkeiten eines Programmes übersichtlich am Bildschirm darzustellen und eine bedienerfreundliche Auswahlmöglichkeit anzubieten. Bewährt hat sich dabei das Verwenden von Pop-Up- und Pull-Down-Menüs. Nun wäre es unsinnig, eine solche doch recht aufwendige Benutzeroberfläche lediglich für ein einziges Programm zu schreiben. Diese Mühe hätte sich kaum gelohnt. Sinnvoller ist eine universell einsetzbare Toolbox, die zugleich flexible Benutzeroberflächen ermöglicht. Dabei darf auch eine kontext-sensitive Hilfefunktion nicht fehlen. Das Ergebnis meiner Arbeit ist das Programm "WINDOW.C". Da es alleine nicht lauffähig ist, weil es nur Werkzeuge zum Erstellen eigener Benutzeroberflächen bereitstellt, bezeichnet man "WINDOW.C" als Toolbox (= "Werkzeugkiste"). Ursprünglich war die Toolbox lediglich für meinen persönlichen Gebrauch gedacht. Als ich mich jedoch etwas umsah, was es an Toolboxen so alles gibt, mußte ich feststellen, daß weder der Public-Domain-Markt noch der professionelle Markt Tools zu einem günstigen Preis (!) bereitstellt, die inklusive des vollständig dokumentierten Quellcodes ausgeliefert werden. Also setzte ich mich hin und schrieb diese ausführliche Dokumentation. Ich hoffe, daß hierdurch auch andere Programmierer die Möglichkeit haben, qualitativ hochwertige Programme zu erstellen, ohne hierfür viel Geld ausgeben zu müssen. Für Geldspenden als Anerkennung und zur Unterstützung meiner Arbeit bin ich natürlich sehr dankbar. !!! W I C H T I G: !!! Bitte beachten Sie, daß vor der Benutzung der Toolbox die Quick-C-Entwicklungsumgebung entsprechend der unter Kapitel 1.3 genannten Angaben konfiguriert werden muß! ------ 4. Neue Datentypen und Variablen der Toolbox ------------------------- 4.1 Windows Auch wenn die Möglichkeiten der Fenstertechnik bereits relativ alt sind, wurden sie auf dem PC lange Zeit nicht genutzt. Erst in jüngerer Zeit kommen immer mehr Anwenderprogramme auf den Markt, bei denen die Fenstertechnik zum festen Bestandteil der Benutzeroberfläche gehört. Dabei ist es gar nicht so schwer, Fenster in eigene Programme einzubauen. Die Aktivierung eines Windows läuft in den meisten Fällen nach folgendem Schema ab: 1. Speichern des Bildschirmhintergrundes, in dem das Fenster dargestellt werden soll 2. Zeichnen eines Rahmens für das zu öffnende Fenster 3. Ausgabe des gewünschten Fensterinhalts auf dem Bildschirm Der Fensterinhalt kann z. B. eine Liste von Optionen (Menü), eine Arbeitsfläche zur Eingabe eines Textes, ein Hinweis oder sonst etwas sein. Ein weiteres Beispiel ist die kontext-sensitive Hilfe. "Kontext-sensitiv" bedeutet nichts anderes, als daß der Hilfe-Text abhängig von der Situation ist, in der sich Anwender gerade befindet. Es werden also nur Hilfen für die Probleme angezeigt, die beim augenblicklichen Programmstatus auch wirklich auftreten können. Ein großes Problem ist die Textausgabe bei Überschneidungen von mehreren Fenstern. Hier dürfte nur der Text ausgegeben werden, der nicht durch ein anderes Fenster verdeckt ist. Es ist klar, daß der Aufwand an Speicher und Verwaltung irgendwann nicht mehr im Verhältnis zum Resultat steht. Bei der Toolbox wurde deshalb ein Kompromiß geschlossen: Das Problem der Textausgaben liegt ganz allein beim Anwender. Er muß dafür sorgen, daß der Text auch wirklich an der richtigen Stelle landet. Es empfiehlt sich von selbst, Textausgaben nur in das jeweils zuletzt geöffnete Fenster durchzuführen. Auch diese Toolbox bietet die Möglichkeit, Fenster zu verwalten. Dazu werden jedoch einige Informationen über das zu verwaltende Fenster benötigt. Zweckmäßigerweise faßt man diese Informationen in einer C-Struktur zusammen: static struct window { int x, y; /* linke obere Window-Ecke */ int dx, dy; /* Breite und Höhe des Windows */ int wattr; /* Hintergrund-Farbe des Windows */ int rand, rattr; /* Rand-Art und Rand-Farbe */ char *name; /* Zeiger auf Window-Überschrift */ int xpos; /* X-Koordinate der Überschrift */ int nattr; /* Farbe der Überschrift */ struct window *vorher; /* Zeiger auf vorher geöffn. Window */ void *wmalloc; /* Zeiger auf Puffer für Hintergrund */ }; Damit man diese Struktur besser anwenden kann, benennen wir sie einfach um und schaffen somit einen neuen Datentyp: typedef struct window WINDOW; Bitte beachten Sie die Großschreibung! Es folgen nun die Erläuterungen zu den einzelnen Struktur-Mitgliedern: x, y: Gibt die Position der linken oberen Ecke des Fensters am Schirm an. Die Position 0,0 ist die linke obere Bildschirmecke. x-Werte von 0 - 79 y-Werte von 0 - 25 dx, dy: "dx" steht für die gewünschte Breite des Fensters in Textzeichen. "dy" steht entsprechend für die gewünschte Höhe des Fensters. Breite und Höhe verstehen sich inklusive des Rahmens. Das für den Text zur Verfügung stehende Fensterinnere ist somit kleiner! wattr: Neben den Informationen über die Art des Zeichens (ASCII-Code) wird im Bildschirmspeicher einer Grafikkarte auch die Information über die Farbe des Zeichens gespeichert. Grundsätzlich gibt es zwei verschiedene Grafikkarten: Monochrome und Farbgrafik-Karten. Zu den monochromen Grafikkarten gehören z. B. die MDA-, die Herkules- und andere Grafikkarten. Zu den Farbgrafik-Karten gehören u. a. die CGA-, EGA-, VGA-, MCGA- und weitere Grafikkarten. Die Grafikkarten erlauben für jedes Zeichen die zusätzliche Angabe eines Bildschirm-Attributes. Das Attribut bestimmt, wie ein Zeichen dargestellt wird. In "wattr" wird nun die Hintergrund-Farbe des Windows, also das Attribut, gespeichert. Abhängig von der installierten Grafikkarte gibt es zwei Möglichkeiten, wie dieses Attribut aufgebaut ist. Bei Farbgrafik-Karten können verschiedene Farben gleichzeitig dargestellt werden. Das Attributbyte ist deshalb folgendermaßen aufgebaut: ┌───┬───┬───┬───┬───┬───┬───┬───┐ Bit │ 7 │ 6 │ 5 │ 4 │ 3 │ 2 │ 1 │ 0 │ └─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┴─┬─┘ │ └───┼───┘ │ └───┼───┘ │ │ │ │ │ │ │ └─> Farbe des Zeichens │ │ │ │ │ └─> Intensität der Zeichen-Farbe │ │ 0 = normal │ │ 1 = hell │ │ │ └─> Hintergrund-Farbe des Zeichens │ └─> Blinken (bzw. intensive Hintergrundfarbe) 0 = aus 1 = an Bei der monochromen Bildschirmkarte (dazu gehört auch die Herkules-Karte) sieht es etwas anders aus. Zwar kann man jede beliebige Bitkombination in dieses Byte laden, doch werden im Gegensatz zur Farbgrafik-Karte nur die nachfolgenden, fest vorgegebenen Kombinationen erkannt, da keine Farben dargestellt werden können. Damit man diese Bitkombinationen nicht auswendig lernen muß, sind folgende symbolische Konstanten in der Toolbox bereits vordefiniert: NORMAL (Attribut 7) = normale Darstellung HELL ( " 15) = helle Darstellung INVERS ( " 112) = inverse Darstellung UNTERSTRICHEN ( " 1) = unterstrichen UI ( " 9) = unterstrichen und hell Bitte beachten Sie die Großschreibung dieser symbolischen Konstanten. In der Programmiersprache C wird nämlich normalerweise zwischen Groß- und Kleinschreibung unterschieden! Für die Farbgrafik-Karte sind folgende symbolische Konstanten in der Toolbox vordefiniert: SCHWARZ ( Attribut 0 ) BLAU ( " 1 ) GRUEN ( " 2 ) ZYAN ( " 3 ) ROT ( " 4 ) VIOLETT ( " 5 ) BRAUN ( " 6 ) WEISS ( " 7 ) DUNKELGRAU ( " 8 ) HELLBLAU ( " 9 ) HELLGRUEN ( " 10 ) HELLZYAN ( " 11 ) HELLROT ( " 12 ) HELLVIOLETT ( " 13 ) GELB ( " 14 ) HELLWEISS ( " 15 ) Der Hintergrund ist bei diesen Voreinstellungen immer schwarz. Soll der Hintergrund eine andere Farbe haben, muß ein neues Attribut-Byte berechnet werden (siehe Funktion "attribut"; Kapitel 5.6). rand: Dieser Wert gibt an, ob und wenn ja welcher Rahmen um das Window gezeichnet werden soll. Es sind Werte von 0 bis 3 zulässig: 0 = Fenster mit doppeltem Strich als Rahmen 1 = Fenster mit einfachem Strich als Rahmen 2 = komplett ausgefüllter Rahmen (mit dem Zeichen "█") 3 = Rahmen wird waagrecht als doppelter Strich, senkrecht als einfacher Strich dargestellt Wird eine Zahl außerhalb dieses Wertebereichs angegeben, so wird standardmäßig der Rahmen "0" gezeichnet. Soll kein Rahmen gezeichnet werden, nimmt man den Rahmen "2" mit derselben Vordergrundfarbe wie der Hintergrund des Windows dargestellt wird. rattr: Hier wird das Bildschirm-Attribut des Rahmens gespeichert. Der Aufbau dieses Attributs ist derselbe wie der von "wattr". *name: Hier wird der Zeiger auf eine mit einem Null-Byte abgeschlossene Zeichenkette abgelegt. Die Zeichenkette erscheint als Namen des Fensters am oberen Fensterrand. Ist der Zeiger gleich NULL, bleibt das Fenster ohne Namen. xpos: Gibt den horizontalen Offset vom linken Rand des Fensters an, an dem der Name erscheinen soll. "xpos" kann also einen Wert von 0 bis 79 annehmen. Durch Angabe eines passenden Wertes sollte sichergestellt werden, daß der Namen des Windows (die Überschrift) auch wirklich in der Mitte des oberen Fensterrahmens erscheint. Die Zeile, in der die Überschrift erscheinen soll, berechnet die Toolbox automatisch. Wurde keine Überschrift angegeben ("*name" = NULL), so wird dieser Wert ignoriert. nattr: Dies ist das Bildschirm-Attribut des Namens. Der Aufbau entspricht dem von "wattr". *vorher: Die Toolbox verwaltet diese Variable selbständig. Hier wird ein Zeiger auf die Window-Struktur des Fensters abgelegt, das unmittelbar davor geöffnet wurde. Ist der Zeiger gleich NULL, ist das Fenster das erste am Bildschirm. *wmalloc: Hier speichert die Toolbox einen Zeiger ab, der auf die Speicheradresse des geretteten Bildschirm-Hintergrunds zeigt. Enthält diese Variable einen NULL-Zeiger, so ist dieses Window im Augenblick nicht geöffnet. Aus diesem Grund muß der Zeiger mit NULL initialisiert werden, da sonst die Toolbox das Fenster nicht öffnet. Der Zeiger dient auch als Schutzmaßnahme, damit dasselbe Fenster nicht mehrmals geöffnet oder geschlossen wird. 4.2 Menüpunkte Mit dem Öffnen und Schließen von Windows alleine kann man noch wenig anfangen. Man muß innerhalb der Fenster auch bestimmte Daten ein- oder ausgeben können. Dazu gehört z. B. das Anzeigen eines Auswahlmenüs, aus dem der Anwender bestimmte Menüpunkte anwählen kann. Da man auch zum Aufbau und zur Verwaltung eines Menüpunktes eine ganze Menge von Informationen benötigt, ist es sinnvoll, diese ebenfalls in einer C-Struktur zusammenzufassen: static struct menu { int x, y; /* Position des Menüpunktes am Screen */ int nattr; /* Farb-Attribut des Menüpunkt-Namens */ char *name; /* Zeiger auf Namen des Menüpunktes */ int nr; /* Identifikations-Nr. des Menüpunktes */ char page; /* Flag für neue Seite */ struct window *window; /* Zeiger auf vorher zu öffn. Window */ struct menu *sub; /* erster Menüpunkt des Untermenüs */ struct menu *next; /* Zeiger auf nächsten Menüpunkt */ struct menu *prev; /* Zeiger auf vorherigen Menüpunkt */ struct menu *father; /* Zeiger auf Vatermenü des Submenüs */ }; Auch diese Struktur wurde zu einem neuen Datentyp umbenannt: typedef struct menu MENU; Die vielen Daten in dieser Struktur mögen vielleicht als unnötig "aufgebläht" erscheinen, aber diese Struktur ist zur Verwaltung eines einzigen (!) Menüpunktes wirklich notwendig. Die Sache sieht jedoch komplizierter aus, als sie ist. Nicht alle Variablen der Struktur muß der Benutzer selbst initialisieren. Die Toolbox verwaltet diese zum Teil automatisch. Eine andere Variable wird nur benötigt, wenn mit diesem Menüpunkt ein Untermenü verbunden ist. Doch nun zu der Bedeutung der einzelnen Struktur-Elemente: x, y: Gibt die Position des Menüpunktes am Bildschirm an. Die Position 0,0 ist die linke obere Bildschirmecke. x-Werte von 0 - 79 y-Werte von 0 - 25 Um auch die Auswahl aus sehr vielen Optionen zu ermöglichen, können zweidimensionale Menüs verarbeitet werden. "Zweidimensional" bedeutet, daß die einzelnen Menüpunkte sowohl untereinander als AUCH nebeneinander auf dem Bildschirm angeordnet sind. nattr: Dies ist das Bildschirm-Attribut, mit dem der Name des Menüpunktes am Bildschirm angezeigt wird. Der Aufbau entspricht dem von "wattr" im Kapitel 4.1. *name: Hier wird der Zeiger auf eine mit einem Null-Byte abgeschlossene Zeichenkette abgelegt. Die Zeichenkette erscheint als Namen des Menüpunktes an der bei "x" und "y" angegebenen Stelle. Der Zeiger darf nicht gleich NULL sein, da sonst kein Menüpunkt angezeigt wird! nr: Wird bei der Menüauswahl ein Menüpunkt mit der ENTER-Taste angewählt oder die Auswahl mit der ESC-Taste bzw. F1-Taste (Hilfe) abgebrochen, so übergibt die Toolbox der aufrufenden Funktion einen Zeiger auf die entsprechende Menü-Struktur zurück. Es ist jedoch nicht gerade einfach, anhand dieses Zeigers gezielte Aktionen im Hauptprogramm zu veranlassen, da normalerweise nur der Name der Struktur ("*name") Rückschlüsse auf den gewählten Menüpunkt zuläßt. Aus diesem Grund ist es sinnvoll, jede Struktur eines Menüpunktes mit einer Identifikations-Nummer zu versehen, anhand der dann gezielt weitere Aktionen von der aufrufenden Funktion durchgeführt werden können. Die Identifikations-Nummer ist eine beliebige Zahl. Zahlen lassen sich in der Programmiersprache C jedoch einfacher vergleichen als Strings. Insofern stellt die Identifikations-Nummer eine Vereinfachung für den Programmierer dar. Es ist auch denkbar, mehrere Menüs mit der gleichen Nummer zu versehen. Dies wäre z. B. sinnvoll, wenn mehrere Menüpunkte ein und dieselbe Aufgabe zu erfüllen haben. page: Es kommt manchmal vor, daß eine Reihe von zusammengehörigen Menüpunkten nicht auf eine Bildschirm-Seite passen. Möglich ist dies z. B. bei größeren Listen, aus denen der Anwender eine Auswahl treffen soll (siehe auch Funktion "inhalt"). Hier ist es sinnvoll, wenn der Anwender auf dem Bildschirm zwischen mehreren Seiten von Menüpunkten hin und her blättern kann (ähnlich einer Speisekarte). Dafür ist diese Variable zuständig. Zulässige Werte sind: page = 0 -> der Menüpunkt gehört zur bisherigen Seite page <> 0 -> dieser Menüpunkt ist der Anfang einer neuen Seite Besteht ein Auswahlmenü aus mehreren Bildschirmseiten, so kann der Anwender mit den Tasten "PgUp" (Bild hoch) und "PgDn" (Bild unten) zwischen den Seiten hin und her wechseln. Beim Wechseln der Bildschirmseite wird der Inhalt eines evtl. vorhandenen Bildschirmfensters NICHT gelöscht. Man muß deshalb dafür sorgen, daß die Menüpunkte der neuen Seite genau an der gleichen Stelle liegen, an der auch die Menüpunkte der alten Seite sind. In der Regel sollte man auf mehrseitige Menüs verzichten, da sie nicht gerade der Übersichtlichkeit dienen. Sie lassen sich meistens auch durch eine geschickte Aufteilung der Menüs in Haupt- und Untermenüs vermeiden. *window: Wie bereits erwähnt, können alle Punkte eines Menüs an beliebigen Positionen am Schirm erscheinen. Übersichtlicher ist es natürlich, wenn diese untereinander oder nebeneinander angeordnet sind. Um diese Punkte als zusammengehörig zu kennzeichnen, kann automatisch ein Bildschirmfenster um sie gezogen werden. Dies hat auch den Vorteil, daß der alte Bildschirmhintergrund durch die Menüpunkte nicht für immer zerstört wird. Zeigt die Variable "*window" auf eine Window-Struktur, so öffnet die Toolbox zuerst ein Fenster, bevor die zusammengehörigen Menüpunkte auf dem Bildschirm ausgegeben werden. Wurde die Lage und die Größe des Fensters richtig gewählt, landen alle Punkte des Menüs darin. Soll KEIN Fenster geöffnet werden (z. B. zur Ausgabe der Menüzeile am oberen Bildschirmrand bei Pull-Down-Menüs), so muß "*window" mit dem NULL-Zeiger initialisiert werden. WICHTIG: Es wird nur dann ein Window geöffnet, wenn die Variable "*window" des ERSTEN Menüpunktes der ERSTEN Seite eines Haupt- oder Submenüs einen Zeiger auf die entsprechende Menü-Struktur enthält. Bei allen nachfolgenden (zusammengehörigen) Menüpunkten wird die Variable "*window" NICHT beachtet! *sub: Soll beim Anwählen eines Menüpunktes mit der Taste ENTER ein weiteres Menü ("Untermenü") erscheinen, so muß dieser Zeiger auf die Menü-Struktur des ersten Menüpunktes des Untermenüs zeigen. Soll KEIN Untermenü geöffnet werden, muß die Variable "*sub" als Wert den NULL-Zeiger enthalten. Der Zeiger MUSS auf den ersten Menüpunkt des Untermenüs zeigen, wenn das Menü mit der Funktion "PrepareMenu" initialisiert wird, weil es sonst zu einer fehlerhaften Zeigerverkettung und damit einem unbrauchbaren Menü kommt! Erst nach dem Aufruf dieser Funktion darf der Zeiger so "verbogen" werden, daß er auf irgendeinen anderen Menüpunkt des GLEICHEN Untermenüs verweist. In diesem Fall steht der Auswahl-Cursor nach dem Aufruf des Untermenüs auf dem hier angegeben Menüpunkt. Ein Untermenü stellt ein für sich eigenständiges Menü dar, genauso wie das Hauptmenü. Deshalb kann man auch ein Submenü nur mit der ESC-Taste oder durch das Anwählen eines Menüpunktes verlassen. *next, *prev, *father: Eine einzelne Menüstruktur beschreibt lediglich einen einzelnen Menüpunkt. Ein Menü besteht jedoch aus mindestens zwei Menüpunkten. Wie weiß die Toolbox nun, welche Punkte zusammen gehören? Ganz einfach! Die zusammengehörigen Menüpunkte werden zu einer verketteten Liste verbunden, die dann das gesamte Menü bilden. Hierfür sind diese Zeiger notwendig. "*next" zeigt auf die Menü-Struktur des jeweils nachfolgenden Auswahlpunktes. Ist der Zeiger gleich NULL, so folgt kein weiterer Menüpunkt, und die Struktur wird damit als die letzte des Menüs angesehen. "*prev" zeigt jeweils auf den vorhergehenden Menüpunkt. Ist der Zeiger gleich NULL, so ist diese Menü-Struktur der erste Auswahlpunkt des Menüs. Der "*father"-Zeiger verweist auf die Menü-Struktur des "aufrufenden" Menüpunktes. Ist er NULL, so gehört dieser Menüpunkt zum Hauptmenü, ansonsten zu einem Untermenü. Der einzige Zeiger, der von dem Benutzer der Toolbox initialisiert werden muß, ist der "*next"-Zeiger. Die Verkettung mit den "*prev"- und "*father"-Zeigern nimmt die Toolbox automatisch vor, wenn die Benutzung der Menüs mit der Funktion "PrepareMenu" vorbereitet wird. 4.3 Globale Variablen int f0, f1, f2, f3; Jeder Anwender hat andere Wünsche. Dies betrifft insbesondere auch die farbliche Gestaltung von Programmen. Von einem guten Programm erwartet man, daß der Anwender die Farben der Benutzeroberfläche beliebig verändern kann. Dies ist um so mehr erforderlich, als daß es im PC-Bereich keinen einheitlichen Grafikkarten-Standard gibt. Auch die verschiedenen Monitor-Typen (Farbe, Schwarz-Weiß, Bernstein, Grün, LCD usw.) machen es dem Programmierer nicht gerade einfach, eine immer passende farbliche Gestaltung für seine Programme zu finden. Um dieses Problem einigermaßen in den Griff zu bekommen, wurden diese Variablen eingeführt. In jeder dieser vier Variablen ist ein anderes Bildschirm-Attribut-Byte gespeichert. Beim Initialisieren der Toolbox ermittelt diese die Art der angeschlossenen Hardware und belegt die Variablen mit den entsprechenden Farbwerten. Jede Funktion dieser Toolbox, die in irgendeiner Weise ein Bildschirm-Attribut benötigt, greift auf diese Variablen zurück, soweit der Programmierer nicht andere Attribute angegeben hat. Welchen Sinn hat das? - Will der Anwender andere Farben verwenden, so braucht er nur die neuen Farb-Attribute auszuwählen. Das Programm muß die gewählten Werte dann in diesen Variablen abspeichern. Da alle Funktionen der Toolbox auf diese Farb-Variablen zurückgreifen, werden die Farben den Wünschen des Anwenders entsprechend eingesetzt. Die Variablen haben im einzelnen folgende Bedeutung: f0: normale Darstellung f1: erste hervorgehobene Darstellung f2: zweite hervorgehobene Darstellung f3: dritte hervorgehobene Darstellung Beim Öffnen der Toolbox (mit der Funktion "OpenTool") werden die Variablen abhängig von der eingebauten Grafik-Karte mit folgenden Werten belegt: Monochrome Karte: Farbgrafik-Karte: f0: NORMAL WEISS auf BLAUEN Hintergrund f1: HELL GELB auf BLAUEN Hintergrund f2: UNTERSTRICHEN HELLROT auf BLAUEN Hintergr. f3: UI SCHWARZ auf BLAUEN Hintergr. Bei manchen Funktionen der Toolbox kann der Programmierer entscheiden, welches Farb-Attribut verwendet werden soll. Man sollte hier immer eine dieser Farb-Variablen angeben, um das Programm möglichst global an die farblichen Bedürfnisse anpassbar zu halten. Bei der Textausgabe z. B. (mit der Funktion "fastprint") ist es besser, als Farbattribut z. B. "f1" anzugeben als "GELB". Achtung: Die Variablen f0 bis f3 können innerhalb eines Funktionsblockes auch als Farbangabe beim Initialisieren der Window- und Menü-Strukturen verwendet werden (die Strukturen sind somit nur lokal sichtbar). Werden die Variablen vor Aufruf der Funktion "OpenTool" verwendet, so enthalten sie jedoch immer die Attribute für die Farbgrafik-Karte. Dies liegt daran, daß die Toolbox erst beim Öffnen (mit der Funktion "OpenTool") die angeschlossene Grafikkarte ermittelt und die Variablen f0 bis f3 entsprechend initialisiert, die Windows und Menüpunkte aber bereits VOR dem Öffnen der Toolbox definiert werden müssen! Dies läßt sich umgehen, indem man nach dem Öffnen der Toolbox (am besten innerhalb einer Funktion) jedem Window und Menüpunkt erneut den Inhalt dieser Variablen als Farbwert zuweist. Dazu ist es natürlich erforderlich, daß die Window- und Menü-Strukturen als GLOBALE VARIABLEN definiert werden, weil sie sonst innerhalb der Funktion, in der die erneute Farbzuweisung erfolgt, nicht sichtbar (zugänglich) sind. Diese Vorgehensweise hat einen großen Vorteil: Will der Anwender die Farben der Windows und Menüpunkte ändern, so braucht innerhalb des Programms nur diese Funktion aufgerufen zu werden, und schon haben die Fenster und Menüs eine andere Farbe! Das Programm "DEMO.C" arbeitet nach diesem Prinzip. Man sollte sich diesen Quelltext deshalb genauer ansehen und ihn analysieren. Übrigens dürfen bei der Initialisierung der globalen Strukturen (Windows, Menüs etc.) keine anderen globalen Variablen angegeben werden! Das bedeutet, daß die Variablen "f0" bis "f3" noch nicht verwendet werden können. Am besten setzt man deshalb den Pseudowert "0" ein, da die Farben dann später initialisiert werden. unsigned int screen; In dieser Variablen speichert die Toolbox die Segment-Adresse des Bildschirmspeichers ab. Der Programmierer braucht sich allerdings in der Regel nicht um die Verwaltung dieser Variable zu kümmern, sie wird von der Toolbox automatisch belegt. Willkürliche Veränderungen dieses Variablen-Wertes können katastrophale Folgen für den Programmablauf haben! Praktisch alle Funktionen der Toolbox schreiben und lesen die notwendigen Informationen direkt in bzw. aus dem Bildschirmspeicher. Die Adresse des Bildschirmspeichers holen sich die Funktionen aus der Variable "screen". Durch gezielte Veränderungen der Segmentadresse kann man erreichen, daß z. B. eine andere Bildschirmseite verwendet wird oder die Ein-/Ausgaben in einem virtuellen Bildschirmbereich gepuffert werden. Bei monochromen Grafikkarten steht in dieser Variablen der hexadezimale Wert "0xB000". Bei Farbgrafik-Karten enthält sie den Wert "0xB8000". Bei manchen PC's, die nicht 100%-ig kompatibel sind (z. B. einige alte Siemens-PC's), kann der Bildschirmspeicher auch an einer anderen Segment-Adresse liegen. In einem solchen Fall muß in der Variablen "screen" der passende Wert eingetragen werden, nachdem die Funktion "OpenTool" aufgerufen wurde. Für Hinweise, bei welchen PC's meine Toolbox die Segment-Adresse des Bildschirmspeichers falsch ermittelt, bin ich jederzeit dankbar. Bitte geben Sie in diesem Fall auch die neue Segment-Adresse bzw. die notwendigen Änderungen an meiner Toolbox an. Die Anwender werden es Ihnen danken! unsigned int farbe; Diese Variable wird beim Vorbereiten der Toolbox (Funktion "OpenTool") mit folgenden Werten belegt: farbe = 0 -> monochrome Grafikkarte entdeckt farbe = 1 -> Farbgrafik-Karte entdeckt Das Ändern dieser Variablen hat keine Auswirkungen auf die Arbeitsweise der Toolbox. Sie dient lediglich zur Information des Programmierers. In manchen Programmen ist diese Information recht nützlich. int select; Die Funktion "UseMenu" gibt einen sog. Abbruchs-Code zurück, der in dieser Variablen gespeichert wird. Folgende Werte sind möglich: select == 0 -> ENTER-Taste gedrückt select == 1 -> ESC-Taste im Hauptmenü gedrückt select == 2 -> F1-Taste für Hilfe gedrückt select == 3 -> interner Fehler aufgetreten Die Arbeitsweise der Funktion "UseMenu" wird später noch ausführlich erläutert (siehe Kapitel 5.4). int fehler; Die Variable "fehler" wird doppelt verwendet. Einmal benutzt die Funktion "hardfehler" diese Variable, um bei aufgetretenen kritischen Hardware-Fehlern (für Assembler-Programmierer: INT 24h) einen Programmierfehler im Quick-C Compiler (Version 2.0) auszugleichen. Dieser Verwendungszweck ist für den Anwender der Toolbox nicht weiter von Bedeutung. Die zweite und wichtigere Verwendung dieser Variablen ist die Rückgabe eines Fehler-Status bei der Funktion "inhalt". Ist ein Fehler beim Anwenden jener Funktion aufgetreten, gibt sie in dieser Variablen die Art des Fehlers zurück: fehler == 0 -> kein Fehler aufgetreten fehler == 1 -> Abbruch durch Drücken der ESC-Taste fehler == 2 -> Fehler beim Öffnen eines Windows fehler == 3 -> ungültiges Laufwerk angegeben fehler == 4 -> Fehler beim Aufruf von "malloc" fehler == 5 -> Fehler beim Zugriff auf ein Laufwerk fehler == 6 -> sonstige Fehler Auf die genaue Arbeitsweise der Funktion "inhalt" und deren Rückgabe-Werte wird später detailliert eingegangen (siehe Kapitel 5.5). ------ 5. Funktionen der Toolbox -------------------------------------------- Nachdem nun alle wichtigen Strukturen und Variablen beschrieben sind, können wir zu einem nicht weniger wichtigen Teil übergehen, nämlich zu den Funktionen der Toolbox. Die Toolbox wurde weitgehend modular aufgebaut. Der modulare Aufbau hat bekannterweise viele Vorteile: - Erleichterung der Fehlersuche - unabhängiges Austesten der einzelnen Module - einzelne Module müssen nur einmal geschrieben werden und können dann auch von anderen Modulen und Programmen als Baustein benutzt werden - die einzelnen Module lassen sich leicht ändern, erweitern oder austauschen Durch den modularen Aufbau der Toolbox gibt es jedoch viele Funktionen, die der Programmierer überhaupt nicht kennen muß, weil sie nur innerhalb der Toolbox (intern) aufgerufen werden. Diese internen Funktionen werden hier deshalb nicht genauer erwähnt. Sollten trotzdem Informationen hierüber benötigt werden, empfehle ich einen Blick in den kommentierten Quellcode. Hier wird JEDE Funktion ausführlich beschrieben. Einige Funktionen benötigen zusätzlichen Speicherplatz zum Zwischenspeichern von Daten (z. B. die Funktionen "OpenWindow", "inhalt" u. a.). Dieser Speicherplatz wird mit Hilfe der Standard-Funktion "malloc" in den Heap-Speicher gelegt. Durch die dynamische Speicherplatz-Reservierung auf dem Heap wird kein unnötiger Speicherplatz verschwendet. Entsprechend hängen die Extremwerte der Toolbox auch von der Größe des noch zur Verfügung stehenden RAM-Hauptspeichers ab (z. B. die maximale Anzahl der Windows, die gleichzeitig geöffnet werden können). Diese Dokumentation beschreibt nur jene Funktionen, die der Programmierer "im alltäglichen Leben" auch wirklich aufrufen und benutzen wird bzw. kann. Bitte beachten Sie, daß die Namen der Funktionen zum Teil in gemischter Groß- und Kleinschreibung definiert wurden. Dies ist kein Zufall. Hierdurch soll vielmehr verhindert werden, daß der Programmierer zufällig eigene Funktionen mit dem gleichen Namen verwendet, wie sie in der Toolbox vorkommen. Dies würde bei den Programmen zu seltsamen Laufzeitverhalten führen, wenn der Fehler nicht entdeckt wird. Eine alphabetisch sortierte Auflistung aller wichtigen Funktionen der Toolbox finden Sie in der Kurzreferenz dieser Dokumentation (siehe Anhang A). 5.1 Verwaltung der Toolbox int OpenTool() Diese Funktion initialisiert die Toolbox und muß auf jeden Fall einmal aufgerufen werden, bevor irgendeine der anderen Funktionen der Toolbox verwendet werden kann. Am besten ruft man diese Funktion gleich zu Beginn des Programmes auf, also als ersten Befehl in der Funktion main(): ... int main() { /* Variablen werden hier deklariert */ if( OpenTool() == 0 ) /* Fehler aufgetreten? */ return ( 1 ); /* ja, dann beende Hauptprogramm */ ... CloseTool(); } ... Danach braucht diese Funktion während des gesamten Programmablaufes nicht mehr aufgerufen zu werden. "OpenTool()" ermittelt als erstes die aktuelle DOS-Version. Ist diese niedriger als Version 3.0, so gibt die Funktion eine Fehlermeldung aus. Außerdem wird der passende Textmodus ermittelt und eingestellt. Kann kein passender Videomodus gefunden werden, so gibt die Funktion ebenfalls eine Fehlermeldung aus. In der Vollversion prüft die Funktion zusätzlich, ob noch mindestens 20 KB Hauptspeicherplatz für den Heap frei sind. Wenn nicht, gibt die Funktion eine Fehlermeldung aus und bricht ab. Danach werden diverse globale und lokale Variablen initialisiert, u. a. die Variablen "f0, f1, f2, f3, select" und andere. Weiterhin merkt sich die Funktion die momentane Form des Hardware-Cursors und macht diesen dann unsichtbar. Dies ist notwendig, weil der Cursor sonst den Bildschirmaufbau stören würde. Schließlich verbiegt die Funktion noch den Interrupt 24h, der beim Auftreten eines kritischen Hardwarefehlers aufgerufen wird. Dies geschieht mit Hilfe der Toolbox-Internen Funktion "_hardfehler". Das Umleiten des Interrupts 24h ist notwendig, weil sonst z. B. im Falle eines nicht verriegelten Diskettenlaufwerkshebel die DOS-Meldung "(R)etry, (i)gnore or (c)ancel?" erscheinen und den gesamten Bildschirmaufbau zerstören würde. "OpenTool" gibt einen ganzzahligen Ergebniswert zurück. Ist dieser Wert gleich null, so ist irgendein Fehler aufgetreten (falsche DOS-Version, falsche Grafikkarte, zuwenig Speicherplatz frei usw.). In diesem Fall darf die Toolbox nicht verwendet werden. Vielmehr ist das Hauptprogramm zu beenden! void CloseTool() Diese Funktion ist das Gegenstück zu "OpenTool". Sie sollte vor der Beendigung des Hauptprogrammes unbedingt aufgerufen werden. Sie schließt alle noch geöffneten Windows und gibt den reservierten Heap-Speicherplatz frei. Außerdem wird die alte Gestalt des Hardware-Cursors wieder hergestellt, d. h. er wird normalerweise wieder sichtbar. Der verbogene Interrupt 24h (siehe Funktion "OpenTool") wird NICHT wieder auf die alte Routine gesetzt! Dies erledigt DOS automatisch, wenn das Programm beendet ist. Für Assembler-Programmierer: Die Adresse, auf die der INT 24h vorher gezeigt hat, wird von DOS im "Programm Segment Präfix" (PSP) an dem Offset 12h zwischengespeichert. Es wird kein Ergebniswert zurückgeliefert. 5.2 Allgemeine Ein- / Ausgaben beim Bildschirm int set_textmode() Die Funktion ermittelt den besten, zur eingebauten Grafikkarte passenden Videomodus. Dieser Textmodus wird dann eingeschaltet, der Bildschirm gelöscht und die erste Bildschirmseite des Textmodus aktiviert. Außerdem speichert "set_textmode()" in der globalen Variable "farbe" die Art der eingebauten Grafikkarte ab (siehe auch Kapitel 4.3). Ist "farbe" gleich eins, so wurde eine Farbgrafik-Karte entdeckt. Ist "farbe" gleich null, wurde eine monochrome Grafikkarte entdeckt. "set_textmode()" gibt einen Ganzzahlwert (Integer) zurück. Ist dieser Rückgabewert gleich null, so ist irgendein Fehler beim Einstellen des passenden Textmodus aufgetreten (vermutlich ist die Grafikkarte nicht für die Toolbox geeignet oder wird nicht erkannt). Meldet die Funktion einen Wert ungleich null zurück, so wurde sie erfolgreich (ohne Fehler) beendet. Diese Funktion braucht in der Regel nie aufgerufen zu werden, da sie eigentlich nur Toolbox-Intern verwendet wird. Bei manchen Programmen kann es jedoch vorkommen, daß der aktuelle Videomodus verstellt wurde (z. B. bei einer DOS-Shell). In einem solchen Fall sollte man diese Funktion aufrufen, um wieder den zur Toolbox passenden Videomodus zu aktivieren. void fastprint( x, y, attribut, text ) int x, y, attribut char far *text Diese Funktion ermöglicht die Textausgabe auf dem Bildschirm. "text" ist ein far-Zeiger auf eine mit einem Null-Byte abgeschlossene Zeichenkette. Sie können auch einen near-Zeiger übergeben, da bei der Übergabe automatisch eine Typumwandlung durchgeführt wird. "attribut" ist das Bildschirmattribut, in dem der Text erscheinen soll, also dessen Darstellungs-Farbe. Es sind dieselben Attribute wie für den Fensterhintergrund möglich (siehe Kapitel 4.1 "Windows" unter der Struktur-Variable "wattr"). Die Variablen "x" und "y" geben die Spalte und die Zeile an, in der der Text erscheinen soll. Für "x" sind Werte von 0 bis 79, für "y" Werte von 0 bis 24 möglich. Als Steuerzeichen im Text ist lediglich der Code 10 (line feed; "\n") erlaubt. Dieser bewirkt einen Sprung in eine neue Zeile. Dabei steht der Cursor dann wieder in der Spalte, die in der Variablen "x" übergeben wurde. Alle anderen Steuerzeichen werden auf dem Bildschirm ausgegeben. Dies kann absichtlich dazu mißbraucht werden. Auch der Tabulator wird als Sonderzeichen ausgegeben. Die nächste Tabulatorstelle wird jedoch nicht angesprungen! Wird bei der Ausgabe des Textes der rechte Bildschirmrand erreicht (Spalte 80), so wird die Ausgabe in der Spalte eins der nächsten Zeile fortgesetzt. Beispiel: fastprint( 10, 4, f0, "Zeile 4\nSpalte 10" ); "fastprint" schreibt den auszugebenden Text direkt in den Bildschirmspeicher. Dadurch wird die enorm hohe Geschwindigkeit bei der Textausgabe erreicht. Es kann allerdings bei einigen älteren CGA-Karten zum kurzzeitigen Flimmern und Flackern des Bildschirms während der Textausgabe kommen. Bei den Textausgaben liegt die Verantwortung vollständig beim Programmierer, ob der Text auch wirklich an der richtigen Stelle und innerhalb des Windows landet. Die Funktion gibt keine Werte zurück. void string ( x, y, attribut, anzahl, zeichen ) int x, y, attribut, anzahl unsigned char zeichen Diese Funktion gibt das in der Variablen "zeichen" angegebene ASCII-Zeichen sooft auf dem Bildschirm aus wie es in der Variablen "anzahl" angegeben wurde. "attribut" ist das Farbattribut, in dem die Zeichen auf dem Bildschirm erscheinen sollen, also die Darstellungs-Farbe. Es sind dieselben Attribute wie für den Fensterhintergrund möglich (siehe Kapitel 4.1 "Windows" unter der Struktur-Variablen "wattr"). Die Variablen "x" und "y" geben die Spalte und die Zeile an, in der die Zeichen erscheinen sollen. Für "x" sind Werte von 0 bis 79, für "y" Werte von 0 bis 24 möglich. Wird bei der Ausgabe des Zeichens der rechte Bildschirmrand erreicht (Spalte 80), so wird die Ausgabe in der Spalte eins der nächsten Zeile fortgesetzt. Die Funktion liefert keine Werte zurück. void cls( attribut ) int attribut Der gesamte Bildschirm wird mit der angegebenen Attribut-Farbe gelöscht. "attribut" ist das Bildschirmattribut, mit dem der Bildschirm gefüllt werden soll, also dessen Darstellungs-Farbe. Es sind dieselben Attribute wie für den Fensterhintergrund möglich (siehe Kapitel 4.1 "Windows" unter der Struktur-Variable "wattr"). void rahmen( x, y, breite, hoehe, art, attribut ) int x, y, breite, hoehe, art, attribut Diese Funktion zeichnet den angegebenen Rahmen auf dem Bildschirm. Die Variablen "x" und "y" geben die linke obere Ecke des Rahmens an. "x" muß die Spalte, "y" die Zeile der linken oberen Ecke enthalten. Für "x" sind Werte von 0 bis 79, für "y" von 0 bis 24 möglich. "breite" steht für die gewünschte Breite des Rahmens in Textzeichen. "hoehe" steht entsprechend für die gewünschte Höhe des Rahmens. "art" gibt an, welcher Rahmen gezeichnet werden soll. Es sind Werte von 0 bis 3 zulässig: 0 = doppelter Strich als Rahmen 1 = einfacher Strich als Rahmen 2 = komplett ausgefüllter Rahmen (mit dem Zeichen "█") 3 = Rahmen wird waagrecht als doppelter Strich, senkrecht als einfacher Strich dargestellt Wurde eine Zahl außerhalb dieses Wertebereichs angegeben, so wird als Vorgabe der Rahmen "0" gezeichnet. "attribut" ist das Bildschirmattribut, mit dem der Rahmen gezeichnet werden soll, also dessen Darstellungs-Farbe. Es sind dieselben Attribute wie für den Fensterhintergrund möglich (siehe Kapitel 4.1 "Windows" unter der Struktur-Variable "wattr"). Die Funktion liefert keinen Ergebniswert zurück. char *input( x, y, attr, text, cpos ) int x, y, attr char *text int cpos Beim Aufruf dieser Funktion wird der Text angezeigt, den man editieren kann. Besteht der Text aus lauter Leerzeichen, so erwartet die Funktion nur eine Eingabe. Die Variablen "x" und "y" geben an, an welcher Position der zu editierende Text erscheinen bzw. die Eingabe erfolgen soll. "x" gibt die Spalte an, "y" die Zeile auf dem Bildschirm. Für "x" sind Werte von 0 bis 79, für "y" Werte von 0 bis 24 möglich. In "attr" muß das gewünschte Farbattribut angegeben werden, mit dem der zu editierende Text bzw. die Eingabe erfolgen soll (Aufbau des Attributs siehe Kapitel 4.1 unter der Struktur-Variable "wattr"). In der Variable "*text" wird ein Zeiger auf den Speicherplatz übergeben, der für die Eingabe reserviert worden ist. Es können maximal soviele Zeichen eingegeben werden, wie dieser Speicherplatz groß ist (das abschließende Null-Byte, mit dem der Speicherplatz abgeschlossen sein muß, wird nicht mitgezählt!). Der Inhalt dieses Speicherplatzes wird zuerst am Bildschirm angezeigt, danach kann man ihn editieren. Enthält der Speicherplatz nicht lediglich Leerzeichen, so kann man diesen Text editieren. Enthält der Speicherplatz nur Leerzeichen, so wird ein "leerer Text" editiert (was soviel bedeutet wie eine beliebige Eingabe). Wichtig ist, daß der reservierte Speicherplatz durch ein Null-Byte am Ende markiert sein muß, da es sich um einen normalen Textstring handelt! Die Variable "cpos" gibt an, an welcher Stelle innerhalb des zu editierenden Textes sich der Cursor zu Beginn (nach dem Aufruf dieser Funktion) befindet. Für "cpos" sind Werte von null bis zur maximalen Länge des reservierten Speicherplatzes zulässig. Wird ein ungültiger Wert angegeben, so steht der Cursor am Ende des Textes (also an der Stelle ganz rechts, ab der dann nur noch Leerzeichen folgen; besteht der Text nur aus Leerzeichen, steht der Cursor trotzdem an der Stelle null, nämlich ganz links). Man kann natürlich absichtlich einen ungültigen Wert für "cpos" angeben (z. B. "-1"), wenn man den Cursor am Ende des Textes stehen haben möchte. Als Rückgabewert wird ein Zeiger auf den reservierten Speicherplatz zurückgegeben. Ist der zurückgegebene Zeiger der NULL-Zeiger, so wurde die Funktion mit der ESC-Taste abgebrochen! Hinweis: Das Drücken der F1-Taste für Hilfe wird innerhalb dieser Funktion nicht beachtet! Der Cursor kann nicht außerhalb des angegebenen Bildschirmbereichs bewegt werden. Zum Bewegen des Cursors innerhalb des gültigen Bildschirmbereichs sind die Tasten "Cursor links", "Cursor rechts", "POS1" ("HOME") und "END" erlaubt. Mit der Taste "Einfg" ("INS") kann man zwischen dem Einfüge- und dem Überschreibmodus wechseln. Die Taste "DEL" ("Lösch") löscht das Zeichen, auf dem der Cursor gerade steht und schiebt den Text rechts davon um eine Stelle nach links. Die Löschtaste "<-" löscht das Zeichen links vom Cursor und schiebt den Text rechts davon ebenfalls um eine Stelle nach links. Die "ESC"-Taste bricht die Funktion ab. Mit der "ENTER"-Taste wird die Eingabe ordnungsgemäß bestätigt und die Funktion ebenfalls beendet. Der zu editierende Text sollte nicht länger als 79 Zeichen sein, da er sonst nicht mehr in eine Bildschirmzeile paßt. Dadurch wird das Editieren unnötig erschwert, weil die Cursortasten "hoch" und "runter" NICHT verwendet werden dürfen! Sollen nur Zahlenwerte eingegeben werden, so muß man den eingegebenen Text nach Beendigung der Funktion "input" mit der passenden Bibliotheksfunktion in einen Zahlenwert umwandeln und in einer geeigneten numerischen Variablen abspeichern. Dabei ist zu beachten, daß der reservierte Speicherplatz so groß sein muß, daß die größte einzugebende Zahl als Text eingegeben werden kann. Jede Ziffer benötigt eine Textstelle! Beispiel: input( 10, 4, f1, "ändern?", -1 ); Der Text "ändern?" wird in Spalte 10 der Zeile 4 mit dem Farb-Attribut "f1" ausgegeben. Der Cursor steht am Ende des Textes. Der Text kann dann editiert werden. 5.3 Windows void wcls ( x, y, xx, yy, attribut ) int x, y, xx, yy, attribut Diese Funktion löscht einen Bildschirmausschnitt. "attribut" ist das Bildschirmattribut, mit dem der Bildschirmausschnitt gefüllt werden soll, also dessen Darstellungs-Farbe. Es sind dieselben Attribute wie für den Fensterhintergrund möglich (siehe Kapitel 4.1 "Windows" unter der Struktur-Variable "wattr"). Die Variablen "x" und "y" geben die Spalte und die Zeile der linken oberen Ecke an. Für "x" sind Werte von 0 bis 79, für "y" Werte von 0 bis 24 möglich. "xx" und "yy" enthalten die Breite (in Zeichen) und die Höhe (in Zeilen), die der Bildschirmausschnitt groß ist. Abhängig von "x" und "y" sind Werte von 0 bis 79 (für "xx") und 0 bis 24 (für "yy") möglich. Überschreitungen der gültigen Wertbereiche werden nicht abgefangen. Sie können zu unvorhergesehenen Ergebnissen führen! Es werden keine Werte zurückgegeben. int OpenWindow( wi ) WINDOW *wi Durch den Aufruf dieser Funktion wird ein Bildschirm- Fenster (= Window) geöffnet. Der übergebene Zeiger "*wi" muß auf die gewünschte WINDOW-Struktur zeigen (siehe Kapitel 4.1), die bereits vorher mit den entsprechenden Daten initialisiert worden ist. Ein bereits geöffnetes Window wird NICHT nochmal geöffnet! Konnte das Window ohne Fehler geöffnet werden, gibt die Funktion einen Wert ungleich null zurück. Der Wert null als Rückgabewert bedeutet, daß das Window durch irgendwelche Probleme (Speicherplatz, bereits vorher geöffnet etc.) nicht geöffnet werden konnte. int CloseWindow() Diese Funktion schließt dasjenige Window, welches zuletzt geöffnet wurde, also das oberste Fenster. Die Windows müssen in der umgekehrten Reihenfolge geschlossen werden, in der sie geöffnet wurden, damit der Bildschirmhintergrund nicht verändert wird. Es werden keine Parameter benötigt, da die Toolbox automatisch weiß, welches Window das oberste Fenster ist und als nächstes geschlossen werden muß. Gibt die Funktion den Rückgabewert null zurück, so sind bereits alle Windows geschlossen! void CloseAll( void ) Die Funktion "CloseAll" schließt ALLE Windows, die noch offen sind. Es werden keine Eingabe-Parameter erwartet, da die Funktion das Schließen der Fenster selbständig überwacht. Es wird kein Rückgabewert zurückgegeben. void GoMain( item ) MENU *item Diese Funktion schließt solange das oberste Fenster, bis das Window des Hauptmenüs das oberste Fenster ist. In der Variable "item" muß der Zeiger auf die MENU-Struktur irgendeines Menüpunktes übergeben werden. Die Funktion sucht mit Hilfe dieses Zeigers den ersten Menüpunkt des Hauptmenüs heraus. Dort entnimmt sie dann, welches Fenster zum Hauptmenü gehört und schließt solange das oberste Fenster, bis das Window des Hauptmenüs das oberste Fenster ist. Ist das Window des Hauptmenüs nicht geöffnet oder existiert kein Window zu diesem Menü, bricht die Funktion ab, ohne irgendein Fenster zu schließen. Diese Funktion wird dann benötigt, wenn man nicht weiß, welche Windows eines Menüs noch offen sind, man jedoch wieder das Hauptmenü aufrufen will. Dabei würde es nur stören, wenn die Fenster von Submenüs noch offen sind. Es wird kein Rückgabewert zurückgeliefert. 5.4 Menüs void PrepareMenu( first, vater ) MENU *first MENU *vater Diese Funktion bereitet die Benutzung eines kompletten Menüs vor, indem alle notwendigen Menü-Strukturen mit den entsprechenden Zeigern verkettet werden. Die Variable "first" muß auf die "MENU"-Struktur des ERSTEN MENÜPUNKTES des HAUPTMENÜS zeigen! Als Wert für die Variable "vater" sollte man immer den NULL-Zeiger übergeben, da das Hauptmenü nicht gleichzeitig ein Untermenü sein kann! Für jeden einzelnen Menüpunkt muß man eine einzelne "MENU"-Struktur initialisieren. Außerdem muß in jeder "MENU"-Sruktur der "*next"-Zeiger initialisiert werden, damit die Toolbox weiß, welche Menüpunkte zusammengehören und in welcher Reihenfolge die Menüpunkte vom Menü-Cursor zu durchlaufen sind. Die Funktion "PrepareMenu" hangelt sich dann, ausgehend vom übergebenen Menüpunkt "*first", mit Hilfe der "*next"-Zeiger von Punkt zu Punkt und stellt die Verbindung der Menüpunkte und der Submenüs untereinander her (siehe Kapitel 4.2, "*sub"-, "*prev"- und "*father"-Zeiger innerhalb jeder Menü-Struktur). Diese Funktion muß nur ein einziges Mal zu Beginn eines Programmes aufgerufen werden, um ein komplettes Menü für die Benutzung vorzubereiten. Sollen innerhalb eines Programmes mehrere UNABHÄNGIGE Menüs verwendet werden, die nicht irgendwie verbunden sind (z. B. als Submenü), so muß die Funktion "PrepareMenu" für jedes dieser Menüs einzeln aufgerufen werden. Es wird kein Rückgabewert zurückgeliefert. Hinweis: Die Funktion ruft sich selbst rekursiv auf! Sollte es zu Problemen kommen, weil der Stack zu klein ist, muß er im Programm vergrößert werden (siehe Kapitel 1.3). Dieses Problem tritt äußerst selten auf, und zwar nur bei Menüs, die sehr viele (tiefgehende) Untermenüs besitzen (z. B. Submenü "Datei laden" im Submenü "Laden von Diskette" im Submenü "Lesezugriffe" im Submenü "Übertragen" im Hauptmenü "Zugriffe auf Datenträger"...). Im Allgemeinen sollte man auf solche tiefgehenden Submenüs verzichten, weil sie nicht gerade die Übersichtlichkeit und Benutzerfreundlichkeit fördern. void cursor( attr ) int attr Durch den Aufruf dieser Funktion legt man fest, welche Farbe der Auswahl-Cursor bei den Menüpunkten sowie der Cursor bei der "Input"-Funktion haben soll. "attr" ist das Bildschirm-Attribut, das bitweise codiert ist (Aufbau siehe Kapitel 4.1 unter der Struktur-Variablen "wattr"). Enthält "attr" der Wert "-1", so wird der Cursor immer invers zur aktuellen Farbe dargestellt, d. h. die Vorder- und die Hintergrundfarben werden vertauscht. Solange diese Funktion nicht aufgerufen wird, gilt als Vorgabe, daß der Cursor invers dargestellt wird ("attr" gleich "-1" bei Farbgrafik-Karten; bei monochromen Grafikkarten wird der Cursor invers blinkend dargestellt). Die Funktion liefert keine Werte zurück. MENU *UseMenu( item ) MENU *item Diese Funktion bringt ein Menü auf den Bildschirm. Übergeben wird ein Zeiger auf die "MENU"-Struktur des Menüpunktes, auf dem der Auswahl-Cursor (ein besonderer Cursor in Form eines Lichtbalkens, der über die einzelnen Menüpunkte geschoben wird) zu Beginn stehen soll. Das entsprechende Haupt- oder Submenü wird angezeigt, vorher ggf. ein Window geöffnet und der Auswahl-Cursor angezeigt. Die Reihenfolge, in der die Menüpunkte innerhalb eines Menüs durch Betätigen der Cursortasten aufleuchten, wird nicht durch die Position am Bildschirm, sondern durch die Verkettung der einzelnen Menü-Strukturen untereinander bestimmt. Deshalb sollten die Menü-Strukturen so miteinander verkettet werden, daß die Reihenfolge der Verkettung so ist, wie die Menüpunkte am Bildschirm durchlaufen werden sollen. Bei zweidimensionalen Menüs wird allerdings beim Betätigen der Cursortasten "rechts" oder "links" automatisch der Cursor zum nächstgelegenen Nachbarpunkt bewegt. Deshalb müssen nebeneinanderliegende Menüpunkte nicht direkt miteinander verkettet sein. Man sollte bei der Verkettung von zweidimensionalen Menüs vielmehr nach dem Prinzip vorgehen: Zuerst von oben nach unten, dann von der nächsten Spalte rechts wieder von oben nach unten, usw. Einmal kann der Auswahl-Cursor mit den Cursortasten der Zehnertastatur bewegt werden. Auch die Tasten "POS1" ("HOME"), "END" "PgUp" sowie der "PgDn" bewegen den Cursor entsprechend. Die zweite Möglichkeit ist das Drücken einer alphanumerischen Taste, wodurch der Auswahl-Cursor zum nächsten Menüpunkt bewegt wird, dessen Bezeichnung mit diesem Zeichen beginnt. Die Auslösung der Menüfunktion erfolgt in beiden Fällen über die "RETURN"- bzw. "ENTER"-Taste. Gibt es zu dem angewählten Menüpunkt ein Submenü, wird dieses geöffnet und die Auswahl beginnt von neuem. Mit der "ESC"-Taste gelangt man zum vorherigen Menü (Vatermenü) zurück, wenn man sich in einem Submenü befindet. Das Window des Submenüs wird dabei wieder geschlossen. Drückt man die "ESC"-Taste im Hauptmenü, wird die Menü-Auswahl abgebrochen (das Fenster des Hauptmenüs wird jedoch NICHT geschlossen!). Durch Drücken der F1-Taste für Hilfe wird die Menü-Auswahl ebenfalls abgebrochen. Als Rückgabewert erhält man einen Zeiger auf die MENU-Struktur des ausgewählten Menüpunktes. Der NULL-Zeiger wird zurückgegeben, wenn bei der Menü-Auswahl ein schwerer Fehler aufgetreten ist. In der globalen Variablen "select" kann der Grund für die Beendigung der Menü-Auswahl entnommen werden (siehe auch Kapitel 4.3). Folgende Werte für "select" sind möglich: 0 = es wurde ein Menüpunkt mit der "ENTER"-Taste angewählt 1 = es wurde die "ESC"-Taste im Hauptmenü gedrückt 2 = es wurde die "F1"-Taste für Hilfe zu einem Menüpunkt gedrückt (kontext-sensitive Hilfe möglich!) 3 = es ist ein interner Fehler aufgetreten! Hat der Anwender die ESC-Taste im Hauptmenü gedrückt (select = 1), so will er damit ausdrücken, daß er keinen Menüpunkt auswählen wollte. Die Rückgabe eines Zeigers auf den ausgewählten Menüpunkt hat folgenden Grund: Innerhalb der MENU-Struktur des ausgewählten Menüpunktes ist die individuelle Identifikations-Nummer abgespeichert (siehe Kapitel 4.2 unter der Struktur-Variablen "nr"). Mit ihrer Hilfe läßt sich leicht eine entsprechende Programmaktion einleiten, die von dem ausgewählten Menüpunkt abhängig ist. Beispiel: ... MENU *punkt1, *mp; ... mp = UseMenu( punkt1 ); /* Menü anzeigen und benutzen */ if( select == 0 ) /* Menüpunkt mit ENTER gewählt */ switch( mp->nr ) { case 1: ...; case 2: ...; case 3: ...; ... } ... Die Funktion schließt bei Beendigung keine Fenster! Es steht deshalb in der Verantwortung des Programmierers, die noch offenen Windows zu schließen, wann und soweit dies notwendig ist. 5.5 Dateiverwaltung char *inhalt( pfad, maske ) char *pfad char *maske Diese Funktion vereint die Informationen des DOS-Befehls "DIR" mit den DOS-Befehlen "CD", "A:", "B:" usw. Die Funktion ermöglicht innerhalb eines Windows die Auswahl einer Datei aus einer Liste aller Dateien, die sich in dem angegebenen Verzeichnis befinden und die zu der genannten Dateimaske passen. Der Pfad oder das Laufwerk können geändert werden. In der Shareware-Version der Toolbox ist diese Funktion durch einen Hinweis-Bildschirm ersetzt worden. In der Variable "*pfad" muß der kompletten Pfad (einschließlich Laufwerk, z. B. "C:\DOS") OHNE abschließenden Rückwärtsstrich (= Backslash = "\") übergeben werden. Lediglich beim Rootverzeichnis (= Wurzel, z. B. "C:\") muß der abschließende Rückwärtsstrich mit angegeben werden, da hierdurch das Wurzelverzeichnis markiert wird. In der Variable "maske" muß die Vorgabe für die Dateimaske übergeben werden. Die Dateimaske gibt an, welche Dateien angezeigt werden sollen. Es sind die gleichen Stellvertreterzeichen wie beim DIR-Befehl von DOS erlaubt ("?" und "*"). Dabei steht ein "?" für ein einzelnes Zeichen, ein "*" für eine beliebige Anzahl von Zeichen. Mit der Dateimaske "*.*" werden alle Dateien im aktuellen Verzeichnis angezeigt. Die Dateimaske "*.exe" zeigt z. B. nur alle EXE-Dateien im angegebenen Verzeichnis an. In der Regel sollte man als Vorgabe für die Dateimaske "*.*" wählen, da hierdurch alle Dateien angezeigt werden. Als erstes fragt die Funktion "inhalt" den Anwender, ob er mit der Vorgabe-Dateimaske einverstanden ist (Variable "maske"). Auf Wunsch kann der Anwender die vorgegebene Dateimaske ändern. Die Abfrage erfolgt innerhalb eines kleinen Fensters, das mit der aktuellen Farbe der globalen Variable "f1" dargestellt wird. Dann werden alle passenden Dateien aus dem angegebenen Laufwerk und Pfad (Variable "pfad") innerhalb eines Windows angezeigt. Sowohl das Fenster als auch die angezeigten Dateien haben die aktuelle Farbe der globalen Variable "f0". Der Anwender kann nun (vollständig menügesteuert) eine Datei aus dieser Auflistung auswählen. Wahlweise kann der Anwender auch in andere Unterverzeichnisse oder zu anderen Laufwerken wechseln. Hierfür gibt es bestimmte Befehle (z. B. "A:", "CD .." usw.). Die Befehle werden mit der aktuellen Farbe der globalen Variable "f2" angezeigt. Ebenso werden alle Unterverzeichnisse des aktuellen Pfades angezeigt. Die Darstellung erfolgt mit der Farbe der globalen Variable "f3". Durch Anwählen eines Unterzeichnisses wird dorthin verzweigt. Mit der Taste "F1" kann man sich sämtliche Tastenbelegungen und die Bedeutung der verschiedenen Anzeigen ansehen (= Hilfe). Sollte irgendein Fehler auftreten, z. B. keine Diskette im Laufwerk usw., so wird automatisch zum vorherigen Laufwerk (normalerweise Festplatte C:) umgeschaltet. Sollte auch hier ein Fehler auftreten, wird die Funktion abgebrochen. Eine Besonderheit ist bei Computern mit nur einem Diskettenlaufwerk (unabhängig von der Anzahl der Festplatten) zu beachten: Hier simuliert DOS das Laufwerk B:, indem in Wirklichkeit nur das Laufwerk A: verwendet wird. Beim Umschalten zwischen diesen "beiden" Laufwerken wird jedoch eine Meldung angezeigt, die den gesamten Bildschirmaufbau zerstört. Um die zu vermeiden ermittelt die Funktion mit Hilfe des BIOS-Interrupts 11h, ob auch wirklich ein Laufwerk B: (physikalisch) vorhanden ist. Falls nicht, wird das Umschalten auf Laufwerk B: ignoriert. Als Rückgabewert übergibt die Funktion "inhalt" einen Zeiger auf einen Textstring. Dieser String enthält den Dateinamen der ausgewählten Datei inclusive des Laufwerks und des Pfads (z. B. "C:\WORD\WORD.EXE")! Wird der NULL-Zeiger zurückgegeben, so ist irgendein Fehler aufgetreten. In der globalen Variable "fehler" ist dann die Fehler-Ursache zu entnehmen (siehe auch Kapitel 4.3 "Globale Variablen"). Folgende Fehlernummern sind möglich: 0 = kein Fehler aufgetreten 1 = Abbruch der Datei-Auswahl-Funktion mit der ESC-Taste 2 = Fehler beim Öffnen eines Windows 3 = ungültiges Laufwerk/Pfad angegeben 4 = Fehler bei der Speicherreservierung (zuwenig Speicher?) 5 = Fehler beim Zugriff auf ein Laufwerk 6 = sonstiger Fehler Achtung: Der Textstring, auf den der zurückgegebene Zeiger deutet, wurde nur als lokale Variable deklariert. Wird die Funktion "inhalt" erneut aufgerufen, so wird der alte Inhalt des Strings überschrieben. Aus diesem Grund sollte man in der aufrufenden Funktion sofort nach der ordnungsgemäßen Beendigung der Funktion "inhalt" den Textstring in eine eigene Stringvariable kopieren (mit der Bibliotheks- Funktion "strcpy"). Ansonsten kann es zu fatalen Seiteneffekten kommen, weil der Textstring dann plötzlich auf eine ganz andere Datei zeigt! Diese Funktion ist äußerst nützlich. In praktisch jedem größeren Programm ist es notwendig, auf bestimmte Dateien zuzugreifen, die der Anwender ausgewählt hat. So benötigen Textverarbeitungen zum Beispiel den Namen der Datei, die bearbeitet werden soll. Für diese Fälle kann man die Funktion "inhalt" verwenden. Sie spart einem viel Programmier-Arbeit und ist äußerst anwenderfreundlich! Die Funktion kann auch dazu verwendet werden, nur das Inhaltsverzeichnis (= Direktory) eines Laufwerks anzuzeigen. Der Bildschirmhintergrund wird durch diese Funktion nicht verändert. Beispiel: ... textdatei = inhalt( 'C:\\texte\\allgemein', '*.txt' ); ... Innerhalb der Anweisung "inhalt" fällt Ihnen vielleicht auf, daß der Pfad einen doppelten Backslash "\\" enthält. Würden Sie versuchen, den Pfad so zu verwenden, wie er an sich richtig aussieht ("C:\texte\allgemein"), dann würde die Zeichenkombination "\t" als Escapefolge für ein Tabulator-Zeichen interpretiert werden. Um innerhalb der Anführungsstriche eines Strings einen wirklichen Schrägstrich links zu erzielen, müssen Sie dem C-Compiler den doppelten Schrägstrich links geben. Der Grund hierfür liegt in der Tatsache begründet, daß in C der einfache Rückstrich "\" zur Markierung von Escapesequenzen verwendet wird. Aus Speicherplatzgründen können von der Funktion "inhalt" nicht mehr als 209 Dateien und Unterverzeichnisse gleichzeitig angezeigt werden. Sollte ein Verzeichnis mehr Einträge besitzen, werden diese nicht mehr eingelesen und auch nicht angezeigt. Auf dem Bildschirm können nicht mehr als 54 Einträge gleichzeitig angezeigt werden. Mit den Tasten "PgUp" und "PgDn" kann man deshalb zwischen mehreren Anzeige-Seiten wechseln. 5.6 Sonstige int attribut( vg, hg, blinken ) int vg, hg, blinken Sowohl bei den Variablen und Datenstrukturen als auch bei vielen Funktionen der Toolbox muß ein (Farb-) Attribut übergeben werden. Das Attribut gibt an, in welcher Darstellungsart (bei monochromer Grafikkarte) bzw. Darstellungsfarbe (bei Farbgrafik-Karten) eine Bildschirmausgabe erfolgen soll. Das Attribut ist bitweise codiert (siehe Kapitel 4.1 unter der Struktur-Variablen "wattr"). Die Codierung der einzelnen Bits ist jedoch nicht gerade einfach. Auch ist nicht jeder C-Programmierer in der Lage, mit einzelnen Bits umzugehen, obwohl dies in der Programmiersprache C häufig erforderlich ist. Deshalb wurde diese Funktion geschaffen. "attribut" führt die bitweise Codierung der angegebenen Farben zum passenden Attribut-Byte durch. "vg" gibt die Vordergrundfarbe (Textfarbe) an, "hg" muß die Hintergrundfarbe enthalten. Die Variable "blinken" gibt an, ob der Text in diesen Farben blinken soll oder nicht. Ist "blinken" gleich null, so blinkt der Text nicht. Jeder andere Wert als null liefert das Attribut mit blinkender Farbe zurück. Der ganzzahlige Rückgabewert liefert das komplett codierte Attribut zurück, das in dieser Form z. B. in den Funktionen weiter verwendet werden kann. Hinweis: Bei manchen Grafikkarten wird die Hintergrundfarbe aufgehellt, anstatt daß der Text blinkt. Dies ist abhängig von einem Registerwert der Grafikkarte und stellt keinen schwerwiegenden Fehler dar. Auf eine Behebung dieses Problems wird deshalb vorläufig verzichtet! Folgende Parameter sind bei der Funktion "attribut" z. B. erlaubt: ... int farbe; ... farbe = attribut( 7, 0, 0 ); farbe = attribut( ROT, BLAU, 1 ); farbe = attribut( 9, GELB, 100 ); farbe = attribut( GRUEN, 1, -1 ); ... int invert( attr ) int attr Die Funktion "invert" liefert das angegebene Bildschirm-Attribut invertiert zurück. Die Variable "attr" enthält das Bildschirm-Attribut, das invertiert werden soll. Als Rückgabewert wird das invertierte Bildschirm-Attribut zurückgegeben, wobei ein evtles. Blinken ausgeschaltet wurde. Hinweis: Invertieren bedeutet, daß die Vorder- und Hintergrundfarbe vertauscht werden. int alnum( zeichen ) int zeichen Das in der Variable "zeichen" übergebene ASCII-Zeichen wird daraufhin untersucht, ob es ein alphanumerisches Zeichen ist (alphanumerisch bedeutet, daß das Zeichen entweder ein Klein- bzw. Großbuchstabe oder aber eine Ziffer von 0 bis 9 ist). Im Gegensatz zur Bibliotheksfunktion "isalnum" werden auch die deutschen Umlaute ("ä", "ö", "ü", "ß") als alphanumerische Zeichen erkannt. Als Rückgabewert wird "0" zurückgegeben, wenn es sich um KEIN alphanumerisches Zeichen handelt. int lower( zeichen ) int zeichen Das in der Variable "zeichen" angegebene ASCII-Zeichen wird in einen Kleinbuchstaben umgewandelt, wenn es sich um einen Buchstaben handelt. Im Gegensatz zur Bibliotheksfunktion "tolower" werden von der Funktion "lower" auch die deutschen Umlaute "Ä", "Ö" und "Ü" in die entsprechenden Kleinbuchstaben umgewandelt. Lediglich das Zeichen "ß" wird nicht umgewandelt, weil es keine äquivalente Großschreibung besitzt. Als Rückgabewert erhält man das beim Aufruf angegebene ASCII-Zeichen zurück, daß (soweit möglich) in den passenden Kleinbuchstaben umgewandelt wurde. War "zeichen" kein Buchstabe, so wird der ASCII-Wert unverändert zurückgegeben. int color( text ) char *text Die Funktion "color" zeigt in einem Window die Darstellungs-Farben bzw. -Arten aller 256 Bildschirm- Attribute an (siehe auch Kapitel 4.1 unter der Struktur-Variablen "wattr"). Der Anwender kann dann eines dieser Attribute auswählen. Das Window hat die aktuelle Farbe der globalen Variable "f0". In der Shareware-Version der Toolbox ist diese Funktion durch einen Hinweis-Bildschirm ersetzt worden. Die Variable "*text" zeigt auf einen Textstring, der als Window-Überschrift ausgegeben wird (z. B. "Vordergrundfarbe auswählen" usw.). "*text" darf auch den NULL-Zeiger enthalten. In diesem Fall wird keine Fenster-Überschrift angezeigt. Ist die in "*text" angegebene Überschrift länger als 34 Zeichen, so werden nur die ersten 34 Zeichen angezeigt! Man kann diese Funktion verwenden, um den Anwender aus allen möglichen Farben diejenigen auswählen zu lassen, welche er am schönsten findet. Entsprechend farbig kann man dann das Programm gestalten. Weitere Hinweise hierzu finden Sie unter dem Kapitel 4.3 "Globale Variablen" bei den Variablen "f0" bis "f3". Das Drücken der F1-Taste für Hilfe wird innerhalb der Funktion "color" nicht beachtet. Als Rückgabewert liefert die Funktion das ausgewählte (fertig codierte) Bildschirm-Attribut-Byte zurück. Es sind Werte von 0 bis 255 möglich. Sollte der Wert "-1" zurückgegeben werden, so wurde die Funktion durch Drücken der "ESC"-Taste abgebrochen bzw. es ist ein anderer interner Fehler aufgetreten. Der Bildschirmhintergrund wird durch diese Funktion nicht verändert. ------ 6. Beispiele und praktische Hinweise --------------------------------- Hier folgen nun einige Hinweise, wie und vor allem in welcher Reihenfolge eine Menü-Oberfläche mit der Toolbox entworfen werden sollte. Zu beachten ist, daß die Toolbox in der vorliegenden Form als "#include"-Datei ausgelegt worden ist, daß heißt, sie wird vom Hauptprogramm mit Hilfe des Kommandos "#include" in den Source-Text eingebunden und jedesmal mit compiliert. Das hat zur Folge, daß alle globalen Variablen auch im Hauptprogramm verfügbar sind. Es ist genauso möglich, die Toolbox zum inkrementalen Compilieren zu verwenden. Das spart viel Zeit, da sie dadurch nicht jedesmal neu compiliert werden muß. Weil das inkrementale Compilieren jedoch sehr viel mehr an Vorbereitungen erfordert ("extern"-Definitionen usw.), soll an dieser Stelle nicht näher darauf eingegangen werden. Die Vollversion der Toolbox unterstützt jedoch auch das schnelle inkrementale Compilieren. Weitere Informationen hierüber können Sie dem Anhang C dieser Dokumentation und Ihren Quick-C- Handbüchern entnehmen. Beim Entwerfen von neuen Menüs sollte man in folgender Reihenfolge vorgehen: a) Überlegen Sie sich, welche Funktionen Sie von dem Menü aus steuern wollen, verteilen Sie diese sinnvoll in Untermenüs und benennen Sie die einzelnen Menüpunkte schließlich mit selbsterklärenden Bezeichnungen. Am besten fertigt man sich eine Zeichnung an, in der das Hauptmenü und alle Untermenüs mit der annähernden Bildschirmposition vermerkt sind. Überlegen Sie sich auch, ob die Menüpunkte innerhalb eines Windows erscheinen sollen und falls ja, wie groß jedes dieser Windows sein muß. Es ist zu empfehlen, daß die Menüpunkte jedes einzelnen Menüs (Haupt- oder Untermenü) innerhalb eines Windows liegen, damit der darunterliegende Bildschirminhalt nicht zerstört wird. Menüs sollen anwenderfreundlich sein. Es ist deshalb sinnvoll, daß die "Menütiefe" nicht tiefer als drei Stufen reicht. Das bedeutet, daß das Hauptmenü mehrere Untermenüs haben darf. Jedes dieser Untermenüs darf nochmals mehrere Untermenüs besitzen. Weitere Untermenüs innerhalb der "Unter-Untermenüs" sollten jedoch vermieden werden. Grafisch sieht das folgendermaßen aus: ┌──────────────────┐ Tiefe 1: │ Hauptmenü: │ ├──────────────────┤ ┌───────────────│ Datei... │ │ │ Setup... │───────┐ │ │ Suchen │ │ │ │ Ende │ │ │ └──────────────────┘ │ │ │ │ │ │ ┌─────────────────┐ ┌───────────┐ │ Tiefe 2: └──> │ Untermenü │ │ Untermenü │ <──┘ ├─────────────────┤ ├───────────┤ │ Laden │ │ Farben │ │ Sichern │ │ Drucker │ ┌────│ Sichern als... │ │ Tastatur │ │ └─────────────────┘ └───────────┘ │ │ │ │ ┌──────────────────────────┐ Tiefe 3: └──> │ Untermenü │ ├──────────────────────────┤ │ Alte Datei überschreiben │ │ Alte Datei umbenennen │ │ Sicherheitskopie machen │ └──────────────────────────┘ Wie man in der Grafik sieht, kann man anhand des Menüpunktes bereits sehen, ob ein weiteres Untermenü vorhanden ist oder nicht. Dies erkennt man an den drei nachfolgenden Punkten ("..."). Dadurch wird eine Menü-Oberfläche noch anwenderfreundlicher! b) Als nächstes sollte man alle notwendigen Variablen und Strukturen im Programm aufstellen. Am einfachsten und kürzesten geht das, indem man bereits bei der Variablen- und Struktur-Deklaration die entsprechenden Werte zuweist. Beachten Sie dabei die Verkettung der einzelnen Menüpunkte, die über den Zeiger "*next" hergestellt werden muß (siehe Kapitel 4.2). Dies ist problemlos möglich, soweit man dabei folgendes beachtet: Der Zeiger "*next" soll auf den nachfolgenden Menüpunkt verweisen, das heißt seine Adresse enthalten. Die Adresse kann schon während der Strukturdefinition mit Hilfe des Adreßoperators "&" ermittelt werden, jedoch nur für jene Strukturen, die dem Compiler bis zu diesem Zeitpunkt bekannt sind. Das bedeutet: Soll die Adresse der Menü-Struktur des folgenden Menüpunktes mit Hilfe von "&" ermittelt werden, so muß die Struktur des folgenden Menüpunktes bereits bekannt sein, was nur möglich ist, wenn sie VORHER definiert worden ist. Schließlich muß der "next"-Zeiger der letzten Menü-Struktur einer Menüstufe auf "NULL" gesetzt werden, damit die Toolbox den letzten Menüpunkt erkennen kann. !!! Das oben Erklärte bedeutet im Prinzip nichts anderes, als !!! daß die Menüpunkt-Strukturen in umgekehrter Reihenfolge im Programm definiert werden müssen, als wie sie später am ! Bildschirm erscheinen werden. Ähnliches gilt für die Deklaration der Window-Strukturen. Auch hier muß die Window-Struktur bereits bekannt (d. h. deklariert) worden sein, BEVOR sie mit Hilfe des Adreßoperators "&" an eine Menüstruktur übergeben werden kann. Die Reihenfolge, in der die Menüpunkte innerhalb eines Menüs durch Betätigen der Cursortasten aufleuchten, wird nicht durch die Position am Bildschirm, sondern durch die Verkettung der einzelnen Menü-Strukturen untereinander bestimmt! Es ist zu empfehlen, alle Menü- und Window-Strukturen als globale Variablen zu definieren. Dazu müssen Sie außerhalb einer Funktion deklariert werden. Hierzu ein kurzes Programmbeispiel: WINDOW klein = { 5, 5, 20, 8, f1, f1, 1 } MENU punkt3 = { 7, 11, f0, "Punkt Nr. 3", 3, 0, 0, 0, 0, 0, 0 } MENU punkt2 = { 7, 9, f0, "Punkt Nr. 2", 2, 0, 0, 0, &punkt3, 0, 0 } MENU punkt1 = { 7, 7, f0, "Punkt Nr. 1", 1, 0, &klein, 0, &punkt2, 0, 0 } Hier ist die Reihenfolge der Deklaration richtig gewählt. Obwohl der Menüpunkt 3 auf dem Bildschirm in der Reihenfolge nach Menüpunkt 2 und dieser nach Menüpunkt 1 kommt, wurden sie in der umgekehrten Reihenfolge deklariert, so daß die Adresse der Struktur bei der Definition des jeweiligen Menüpunktes bereits dem Compiler bekannt ist und mit "&" ermittelt werden kann. Sollte beim Aufruf von "PrepareMenu" bzw. eines Menüs der Rechner abstürzen oder irgendwelche anderen "seltsamen Vorgänge" passieren, so könnte dies an einer fehlerhaften Verkettung liegen (z. B. wenn der "*next"-Zeiger einer Menü-Struktur auf die eigene Adresse zeigt, der "next"-Zeiger des letzten Menüpunktes nicht mit dem "NULL"-Zeiger markiert wurde usw.). Das hier Erklärte sieht weitaus komplizierter aus, als es in Wirklichkeit ist. Damit sie das hier Erläuterte auch wirklich verstehen, könnten Sie versuchen, verschiedene kleine Menüs zu entwerfen. Vorher sollten Sie jedoch das nun folgende Beispiel-Programm durcharbeiten. Ich empfehle außerdem, daß Sie den C-Quellcode aller auf dieser Diskette befindlichen Beispiel- und Demo-Programme durcharbeiten, analysieren und ein wenig damit experimentieren. ------ 7. Programm-Beispiel ------------------------------------------------- Das folgende Programm-Beispiel verdeutlicht, wie man auf einfachste Art und Weise eine gute Benutzeroberfläche erstellen kann. Das Programm befindet sich auch auf der Diskette unter dem Namen "Beispiel.C". Bei diesem Beispiel kann man sehr gut die oben besprochene, verdrehte Reihenfolge bei den Struktur-Definitionen sowie die Auswertung der Identifikationsnummer der Menüpunkte erkennen. Die Toolbox wird übrigens mit dem "#include"-Befehl eingebunden: #include <window.c> Man kann Quick-C auf zwei Arten mitteilen, wo nach einer Einfügedatei zu suchen ist. Für Dateien in den "Standardverzeichnissen" stellt man den betreffen Dateinamen zwischen Winkelklammern ( <> ). Die Standardverzeichnisse für Quick-C sind die mit INCLUDE (der Variablen des DOS-Environment) bestimmten Verzeichnisse. Eine zweite Variation ist, den Dateinamen in Anführungszeichen einzuschließen: #include "window.c" Diese Schreibweise bewirkt, daß der Compiler im Verzeichnis der gegenwärtigen Quelldatei nach der Einfügedatei zu suchen beginnt. Findet er die Datei dort nicht, wird die Suche in den Standardverzeichnissen fortgesetzt. "WINDOW.C" sollte nach der ersten Methode (mit den Winkelklammern) eingebunden werden. Dadurch verhindert man, daß versehentlich eine andere Datei mit dem gleichen Namen wie die Toolbox eingebunden wird. Hier folgt nun das Programm. Es ist ganze 150 Zeilen klein. Es demonstriert damit die Leistungsfähigkeit der Toolbox. Das Programm ist auch in der ausführbaren Version auf der Diskette enthalten (Datei "Beispiel.EXE"). Wer die Toolbox anhand dieses Programmes besser verstehen lernen will, kann das Programm mit Hilfe der Einzelschritt-Debug-Funktion von Quick-C v2.0 durchgehen. In diesem Beispiel werden die Menüpunkt- und Window-Strukturen nicht global, sondern lokal (also beschränkt sichtbar) definiert. In der Praxis ist es besser, diese Strukturen außerhalb einer Funktion zu deklarieren, damit sie global sichtbar sind. Dadurch sind Änderungen (z. B. an der Farbe; siehe Kapitel 4.3 "globale Variablen" unter der Anmerkung "Achtung:") leichter möglich. /* Beispiel.C --- Erläutert die Anwendung der verschiedenen neuen Funktionen und (Struktur-) Variablen in der Toolbox "Window.C". */ #include <window.c> int main() { int a; /* Hilfsvariablen */ MENU *m1, *m2; /* Definition (= deklaration) der Bildschirmfenster */ WINDOW main = { 33, 3, 17, 8, f1, 0, f1, "> Hauptmenü <", 35, f1, 0, 0 }; WINDOW sub1 = { 20, 9, 20, 7, f0, 1, f0, " Datei ", 26, f0, 0, 0 }; WINDOW sub2 = { 40, 9, 15, 7, f2, 2, f2, " Setup ", 44, f2, 0, 0 }; WINDOW sub3 = { 30, 14, 30, 7, f3, 3, f3, " Sichern als... ", 37, f3, 0, 0 }; WINDOW help = { 10, 10, 60, 5, f0, 4, f0, " Kontextsensitive Hilfe ", 29, f1, 0, 0 }; /* Jetzt folgt die Definition der einzelnen Menüpunkte. Hierbei ist die umgekehrte Reihenfolge der Menüpunkte bei der Deklaration deutlich erkennbar. Auf dem Bildschirm werden die Menüpunkte dagegen in der Reihenfolge durchlaufen, in der sie miteinander verkettet wurden. */ MENU sub3p3 = { 32, 18, f0, " Sicherheitskopie machen ", 33, 0, 0, 0, 0, 0, 0 }; MENU sub3p2 = { 32, 17, f0, " Alte Datei umbenennen ", 32, 0, 0, 0, &sub3p3, 0, 0 }; MENU sub3p1 = { 32, 16, f0, " Alte Datei überschreiben ", 31, 0, &sub3, 0, &sub3p2, 0, 0 }; MENU sub2p3 = { 42, 13, f0, " Farben ", 23, 0, 0, 0, 0, 0, 0 }; MENU sub2p2 = { 42, 12, f0, " Drucker ", 22, 0, 0, 0, &sub2p3, 0, 0 }; MENU sub2p1 = { 42, 11, f0, " Tastatur ", 21, 0, &sub2, 0, &sub2p2, 0, 0 }; MENU sub1p3 = { 22, 13, f0, " Sichern als... ", 13, 0, 0, &sub3p1, 0, 0, 0 }; MENU sub1p2 = { 22, 12, f0, " Sichern ", 12, 0, 0, 0, &sub1p3, 0, 0 }; MENU sub1p1 = { 22, 11, f0, " Laden ", 11, 0, &sub1, 0, &sub1p2, 0, 0 }; MENU mainp4 = { 36, 8, f0, " ENDE ", 04, 0, 0, 0, 0, 0, 0 }; MENU mainp3 = { 36, 7, f0, " Suchen ", 03, 0, 0, 0, &mainp4, 0, 0 }; MENU mainp2 = { 36, 6, f0, " Setup... ", 02, 0, 0, &sub2p1, &mainp3, 0, 0 }; MENU mainp1 = { 36, 5, f0, " Datei... ", 01, 0, &main, &sub1p1, &mainp2, 0, 0 }; /* Damit wären alle notwendigen Variablen und Strukturen deklariert. Als nächstes beginnt die Initialisierung der Toolbox und des kompletten Menüs: */ if( OpenTool() == 0 ) /* Fehler beim Öffnen der Toolbox aufgetreten? */ return( 1 ); /* ja, dann breche das Hauptprg. mit einem Fehlercode ab */ PrepareMenu( &mainp1, NULL ); /* Menü vorbereiten, d. h. alle not- wendigen Zeiger-Verkettungen usw. durchführen */ /* Nun wird das Hauptmenü aufgerufen */ m2 = &mainp1; while( 1 == 1 ) /* Endlosschleife erzeugen */ { m1 = UseMenu( m2 ); /* Hauptmenü aufrufen */ if( select == 1 ) /* ESC im Hauptmenü gedrückt? */ break; /* ja, dann Endlosschleife abbrechen */ if( m1 == NULL ) /* schwerer Fehler aufgetreten? */ { CloseAll(); /* ja, dann alle Windows schließen */ CloseTool(); /* Toolbox schließen */ return( 1 ); /* Programm abbrechen */ } m2 = m1; /* gewählten Menüpunkt beim nächsten mal aufrufen */ if( select == 2 ) /* Hilfe (F1) gedrückt? */ { if( OpenWindow( &help ) == 0 ) /* Fehler beim Öffnen des Hilfe- Fensters aufgetreten? */ { CloseAll(); /* ja, dann schließe alle Windows */ CloseTool(); /* Schließe die Toolbox */ return( 1 ); /* und breche das Programm ab */ } fastprint( 12, 12, f1, "Hier steht normalerweise der Hilfe-Text.\n\\ Bitte eine beliebige Taste drücken..." ); a = getch(); /* warte auf Tastendruck */ CloseWindow(); /* schließe Hilfefenster wieder */ } if( select == 0 ) /* einen Menüpunkt angewählt? */ { if( m1->nr == 23 ) /* Farben-Setup angewählt? */ { color( " Bitte passende Farbe auswählen: " ); continue; /* Endlosschleife von vorne begin. */ } if( m1->nr > 30 && m1->nr < 33 ) /* Laufwerkszugriffe? */ { inhalt( "A:\\", "*.*" ); /* DIR anzeigen... */ continue; /* Endlosschleife fortsetzen */ } /* Hinweis: Die Funktionen "inhalt" und "color" sind in der Shareware-Version der Toolbox NICHT enthalten! */ if( m1->nr == 04 ) /* Menüpunkt "Ende" gewählt? */ break; /* ja, dann beende Endlosschl.*/ printf( "\a" ); /* sonst Signalton ausgeben */ } } /* Wiederholung der Endlosschleife... bis ESC im Hauptmenü zum Beenden des Programms gedrückt wurde! */ if( OpenWindow( &help ) == 0 ) /* Fehler beim Öffnen des Hilfe- Fensters aufgetreten? */ { CloseAll(); /* ja, dann schließe alle Windows */ CloseTool(); /* Schließe die Toolbox */ return( 1 ); /* und breche das Programm ab */ } fastprint( 15, 12, f1, "Zum Ende bitte eine beliebige Taste drücken... " ); a = getch(); /* warte auf Tastendruck */ CloseAll(); /* Schließe dann alle Windows */ CloseTool(); /* Schließe die Toolbox !!! */ /* Programmende */ return( 0 ); /* Beende Programm mit Rückgabewert "OK" */ } ------ 8. Anwenderfreundliche Menüs ------------------------------------------ Das Gebiet der Software-Ergonomie hat in den letzten Jahren einen enormen Aufschwung erlebt. Noch anfang der 80er Jahren war es gang und gebe, daß nach dem Programmstart nur ein kleiner Cursor erschien und sonst nichts! Kein Hinweis war zu finden, um was für ein Programm es sich überhaupt handelt, geschweige denn von einer kurzen Dokumentation. Der Einsatz eines solchen Programmes erforderte vom Anwender oft tiefgehendes Wissen. Noch heute gibt es Programme, die nach diesem Prinzip arbeiten. Hier denke man insbesondere an die sog. externen DOS-Befehle wie "BACKUP", "RESTORE" usw., die nicht einmal eine kurze Hilfe oder eine Befehlsübersicht anbieten, wenn der Anwender einen Fehler macht. Heute hingegen hat ein Programm ohne eine anwenderfreundliche Bedienerführung kaum mehr Chancen, sich gegen die Konkurrenz zu behaupten. Wie aber muß nun eine optimale Benutzeroberfläche aussehen? Diese Frage ist gar nicht so einfach zu beantworten. Die Praxis zeigt nämlich, daß auf dem Markt ein buntes Durcheinander herrscht. Die einen schwören auf Piktogramme nach GEM-Manier, andere empfinden Pull-Down-Menüs oder eine einfache Kommandosprache als optimal. Der Leidtragende dieses Durcheinanders ist letztlich der Anwender, der sich in dem "Dschungel" der Benutzeroberflächen" zurechtfinden muß. Dies ist wohl auch mit ein Grund dafür, daß der Branchenriese IBM das SAA-Konzept (SAA = Systems Application Architecture) eingeführt hat. Das Ziel des SAA-Konzepts ist es, hardware-unabhängige Software entwickeln zu können, die aufgrund ihrer einheitlichen Oberfläche leicht erlernbar ist. Übrigens enthält auch die integrierte Entwicklungsoberfläche von QUICK-C v2.0 viele typische SAA-Elemente. Die Toolbox WINDOW.C unterstützt sowohl Pop-Up- und Pull-Down-Menüs als auch eigene Menükonzepte. Hier erhalten Sie noch einmal einen Überblick, wie sich diese Menüformen unterscheiden: Pop-Up-Menüs: Die Pop-Up-Menüs unterstützen theoretisch eine unendliche Anzahl von senkrecht selektierbaren Einträgen, die innerhalb eines Windows zusammengefaßt sind. Die Anzahl der Einträge ist bei WINDOW.C nur durch den verfügbaren Speicher begrenzt. Pop-Up-Menüs können für jeden Eintrag einen Hilfetext besitzen, müssen es aber nicht. Pull-Down-Menüs: Die Pull-Down-Menüs bestehen aus einer waagrechten Menüleiste am oberen Bildschirmrand und einem, für jeden Eintrag vorhandenen Untermenü mit senkrecht selektierbaren Einträgen. Die Einträge der Untermenüs sind jeweils durch ein Window zusammengefaßt. Pull-Down-Menüs stellen dem Benutzer also eine zweidimensionale Menüschnittstelle zur Verfügung. Sonstige Menüs: Zu den sonstigen Menüs zählen insbesondere die horizontalen Menüs von WORD und LOTUS 1-2-3, aber auch jede andere exotische Anordnungsform von Menü-Einträgen. Doch nun wieder zurück zur Ausgangsfrage: Wie hat eine optimale Benutzeroberfläche auszusehen? Zuerst einmal ist hier die Anzahl der Menüpunkte zu erwähnen. Als optimale Anzahl von Einträgen für ein Menü haben sich fünf bis neun Menüpunkte bewährt. Sobald ein Programm mehr als neun Funktionen anzubieten hat, ist es sinnvoll, diese entsprechend auf Untermenüs aufzuteilen. Bei der Aufteilung der Menüpunkte in die Untermenüs stellt sich zwangsläufig die Frage, nach welchem Ordnungskriteritum dies geschehen soll. Als Faustregel gilt, daß nur die Menüpunkte zusammen in ein Menü aufgenommen werden sollten, die auch durch einen logischen Zusammenhang klar zusammengehören. Der logische Zusammenhang muß für den Anwender eindeutig erkennbar sein! Wenn der Name des aufrufenden Menüpunktes nicht zusammen mit dem Untermenü auf dem Bildschirm zu sehen ist, läßt sich nur schwer ein logischer Zusammenhang erkennen. Deshalb sollte man unbedingt dafür sorgen, daß der Menüpunkt, mit welchem das Untermenü aufgerufen wurde, klar ersichtlich ist. Das läßt sich z. B. dadurch erreichen, daß das Fenster als Überschrift den Namen genau dieses Menüpunktes trägt. Die einzelnen Menüpunkte selbst sollen eindeutig sein. Man muß bereits am Namen des Menüpunktes erkennen können, was für eine Funktion damit ausgeführt wird. Man sollte es unbedingt vermeiden, zweideutige Bezeichnungen zu verwenden. Wenn man beispielsweise einen erstellten Text auf Datenträger speichern möchte, sollte der Menüpunkt nicht etwa "Übertragen" (!?), sondern "Text speichern" heißen. Natürlich darf man bei der Formulierung der Menüpunkte nicht in den absoluten Computerjargon zurückfallen, obwohl das manchmal schwerfällt, weil man damit oft einen Sachverhalt viel präziser formulieren kann. Unbedingt vermeiden sollte man jedoch die Übersetzung von Fachwörtern oder Wortneuschöpfungen. Übrigens wird es allzu oft vergessen, in die Menüführung eine Möglichkeit einzubauen, eine Menüebene zu verlassen, ohne daß eine Auswirkung auf das Programm stattfindet. Gerade ungeübte Anwender werden sich öfter in den Menüs "verlaufen". Kann man dann die aktuelle Menüebene nicht mehr verlassen, ohne irgendeine Programm-Funktion auszuführen, könnte es zu großen Problemen kommen. Ziemlich schnell wird sich der Anwender in eine gute Menüführung eingewöhnen. Doch irgendwann kommt der Zeitpunkt, an dem der Anwender nicht erst mehrere Menüebenen durchwälzen will, bevor er eine Funktion ausführen kann. Hier bietet sich nun die "Hot-Key"-Methode an. Mit dieser Methode wird durch das Drücken einer bestimmten Tastenkombination eine Programm-Funktion direkt ausgeführt. Ein Umweg über die Menüführung wird dadurch vermieden. Als "Hot key" ("heiße Taste") bieten sich die Kombinationen aus einer Sondertaste ("ALT", "CTRL"...) und einer Buchstabentaste an. Von der Verwendung der Funktionstasten wird allerdings dringend abgeraten, weil es einfacher ist, sich einen Buchstaben zu merken, der in Beziehung mit dem Namen eines Menüpunktes steht, als irgendeine Nummer einer Taste. Es wäre z. B. denkbar, die Tastenkombination "CTRL" plus "S" für den Aufruf der Menüfunktion "Speichern" zu verwenden. Damit der Anwender die "hot-keys" schneller lernt, sollten diese zu jedem Menüpunkt mit angezeigt werden, z. B. "Speichern <CTRL> + <S>". Eine optimale Benutzeroberfläche mit anwenderfreundlichen Menüs macht nicht selten einen erheblichen Teil der ganzen Programmierarbeit aus. Die Mühe lohnt sich jedoch. WINDOW.C wird Ihnen dabei helfen, diese Zeit zu verringern und somit eine Menge Entwicklungskosten zu sparen! A n h a n g ============= ------ Anhang A: Kurzreferenz / Zusammenfassung der wichtigsten ------------- globalen Variablen und Funktionen Dieser Anhang beschreibt die Charakteristiken der wichtigsten globalen Variablen und der Funktionen. Die Erörterungen dieses Anhangs geben jedoch nur einen kurzen Überblick. Eine komplette Beschreibung befindet sich an den entsprechenden Stellen der vorangegangenen Dokumentation. Die Variablen- und Funktions-Namen sind alphabetisch sortiert, wodurch das Suchen erleichtert wird. Nach den einzelnen Kategorien sortierte Auflistungen befinden sich ebenfalls in der vorangegangenen Dokumentation. 1. Globale Variablen int f0, f1, f2, f3; In diesen Variablen werden die vier verschiedenen Farb-Attribute für die normale, erste, zweite und dritte hervorgehobene Zeichen-Darstellung gespeichert. Siehe auch Kapitel 4.3 unsigned int farbe; Diese Variable wird beim Vorbereiten der Toolbox (Funktion "OpenTool") mit folgenden Werten belegt: farbe = 0 -> monochrome Grafikkarte entdeckt farbe = 1 -> Farbgrafik-Karte entdeckt Das Ändern dieser Variablen hat keine Auswirkungen auf die Arbeitsweise der Toolbox. Sie dient lediglich zur Information des Programmierers. In manchen Programmen ist diese Information recht nützlich. int fehler; Gibt bei Beendigung der Funktion "inhalt" den Fehler-Status zurück: fehler == 0 -> kein Fehler aufgetreten fehler == 1 -> Abbruch durch Drücken der ESC-Taste fehler == 2 -> Fehler beim Window-Öffnen fehler == 3 -> ungültiges Laufwerk angegeben fehler == 4 -> Fehler beim Aufruf von "malloc" fehler == 5 -> Fehler beim Laufwerks-Zugriff fehler == 6 -> sonstige Fehler MENU: Dieser neue Datentyp dient der zusammengefaßten Speicherung aller Informationen, die zum Verwalten eines einzelnen Menüpunktes notwendig sind: static struct menu { int x, y /* Position des Menüpunktes am Bildschirm */ int nattr; /* Farb-Attribut des Menüpunkt-Namens */ char *name; /* Zeiger auf Namen des Menüpunktes */ int nr; /* Identifikationsnummer des Menüpunktes */ char page; /* Flag für neue Seite (<> 0: 1. MP der Seite) */ struct window *window; /* Zeiger auf vorher zu öffnendes Window */ struct menu *sub; /* Zeiger auf ersten Menüpunkt des Untermenüs */ struct menu *next; /* Zeiger auf nächsten Menüpunkt */ struct menu *prev; /* Zeiger auf vorherigen Menüpunkt */ struct menu *father; /* Zeiger auf Vatermenü des Submenüs */ }; typedef struct menu MENU; unsigned int screen; In dieser Variablen speichert die Toolbox die Segment-Adresse des Bildschirmspeichers ab. Der Programmierer braucht sich allerdings in der Regel nicht um die Verwaltung dieser Variable zu kümmern, sie wird von der Toolbox automatisch belegt. Willkürliche Veränderungen dieses Variablen-Wertes können katastrophale Folgen für den Programmablauf haben! Siehe auch Kapitel 4.3 int select; Diese Variable enthält einen Abbruchscode, der angibt, aus welchem Grund die Funktion "UseMenu" beendet wurde: select == 0 -> ENTER-Taste gedrückt select == 1 -> ESC-Taste gedrückt select == 2 -> F1-Taste für Hilfe gedrückt select == 3 -> interner Fehler aufgetreten WINDOW: Dieser neu erzeugte Datentyp dient der Speicherung aller Informationen, die zur Verwaltung eines einzelnen Windows notwendig sind. static struct window { int x, y; /* linke obere Window-Ecke */ int dx, dy; /* Breite und Höhe des Windows */ int wattr; /* Hintergrund-Farbe des Windows */ int rand, rattr; /* Rand-Art und Rand-Farbe */ char *name; /* Zeiger auf Window-Überschrift (Namen) */ int xpos; /* X-Koordinate der Überschrift */ int nattr; /* Farbe der Überschrift */ struct window *vorher; /* Zeiger auf vorher geöffnetes Window */ void *wmalloc; /* Zeiger auf Puffer-Speicher für Hintergrund */ }; typedef struct window WINDOW; Für den Rand sind folgende Zahlenwerte gültig: 0 = doppelter Strich als Rahmen 1 = einfacher Strich als Rahmen 2 = komplett ausgefüllter Rahmen (Zeichen "█") 3 = Rahmen wird waagrecht als doppelter Strich, senkrecht als einfacher Strich dargestellt 2. Funktionen int alnum( int zeichen ) Prüft, ob das angegebene ASCII-Zeichen zum alphanumerischen Bereich gehört (A-Z, a-z, 0-9, deutsche Umlaute). Ergibt einen Wert ungleich null, wenn das Zeichen zum alphanum. Bereich gehört. Siehe auch Kapitel 5.6 int attribut( int vg, int hg, int blinken ) Berechnet das Farb-Attribut-Byte mit der Vordergrundfarbe "vg", der Hintergrundfarbe "hg" und evtl. mit Blinken (wenn Variable "blinken" ungleich null ist). Ergibt das bitweise codierte Attribut. Siehe auch Kapitel 5.6 void CloseAll( void ) Schließt ALLE noch offenen Windows. Keine Parameter. Siehe auch Kapitel 5.3 void CloseTool( void ) Bereitet die Rückkehr zum Betriebssystem vor, indem die alten Voreinstellungen wiederhergestellt werden. Ergibt keinen Rückgabewert. Siehe auch Kapitel 5.1 int CloseWindow() Schließt das zuletzt geöffnete Fenster wieder. Ergibt den Wert null, wenn kein Window mehr offen ist. Siehe auch Kapitel 5.3 void cls( int attr ) Löscht den gesamten Bildschirm mit der angegebenen Farbe. Keine Rückgabewerte. Siehe auch Kapitel 5.2 int color( char *text ) Zeigt in einem Window alle 256 Farb-Attribute an und ermöglicht die Auswahl eines dieser Attribute. Ergibt das gewählte Farb-Attribut. Wird der Wert "-1" zurückgegeben, so wurde die Funktion durch Drücken der ESC-Taste abgebrochen. Siehe auch Kapitel 5.6 Diese Funktion ist in der Shareware-Version nicht enthalten! void cursor( int attr ) Legt die Farbe des Input- und Menü-Cursors fest. Bei "attr" gleich "-1" wird der Cursor immer invers dargestellt. Ergibt keinen Rückgabewert. Siehe auch Kapitel 5.4 void fastprint( int x, int y, int attribut, char far *text ) Gibt einen Text auf dem Bildschirm aus. Keine Rückgabewerte. Siehe auch Kapitel 5.2 void GoMain( MENU *item ) Schließt solange das oberste Fenster, bis das Window des Hauptmenüs das oberste ist. Ergibt keinen Rückgabewert. Siehe auch Kapitel 5.3 char * inhalt( char *pfad, char *maske1 ) Diese Funktion ermöglicht die Auswahl einer Datei innerhalb eines Windows aus einer Liste aller Dateien des angegebenen Verzeichnisses. Wechsel des Pfades und des Laufwerks sind möglich. Ergibt einen Zeiger auf den String des kompletten Pfades und des Dateinamens der ausgewählten Datei. Wird der NULL-Zeiger zurückgegeben, ist irgendein Fehler aufgetreten. In der globalen Variable "fehler" steht dann die Fehler-Ursache. Siehe auch Kapitel 5.5 Diese Funktion ist in der Shareware-Version nicht enthalten! char * input( int x, int y, int attr, char *text, int cpos ) Der angegebene Text wird angezeigt und kann editiert (bearbeitet) werden. Ergibt den Zeiger "*text" auf den reservierten Speicherplatz. Wird stattdessen der NULL-Zeiger zurückgegeben, so hat der Anwender die Funktion mit der ESC-Taste abgebrochen. Siehe auch Kapitel 5.2 int invert( int attr ) Invertiert das angegebene Farb-Attribut. Ergibt das invertierte Attribut. Siehe auch Kapitel 5.6 int lower( int zeichen ) Wandelt das angegebene ASCII-Zeichen in den entsprechenden Kleinbuchstaben um, wobei auch die deutschen Umlaute (ä, ö, ü) berücksichtigt werden. Ergibt das umgewandelte Zeichen. Siehe auch Kapitel 5.6 int OpenTool( void ) Bereitet die Toolbox zur Verwendung vor. Diese Funktion muß einmal aufgerufen worden sein, bevor irgendeine andere Funktion der Toolbox aufgerufen werden darf. Ergibt den Wert null, wenn ein Fehler aufgetreten ist. Die Toolbox darf in diesem Fall nicht verwendet werden! Siehe auch Kapitel 5.1 int OpenWindow( WINDOW *wi ) Öffnet ein Bildschirmfenster. Ergibt den Wert null, wenn das Window nicht geöffnet werden konnte (Fehler...) oder bereits offen ist. Siehe auch Kapitel 5.3 void PrepareMenu( MENU *first, MENU *vater ) Bereitet die Benutzung eines kompletten Menüs vor, indem alle notwendigen Initialisierungs- arbeiten durchgeführt werden. Als "vater"-zeiger muß immer der "NULL"-Zeiger übergeben werden. Keine Rückgabewerte. Siehe auch Kapitel 5.4 void rahmen( int x, int y, int breite, int hoehe, int art, int attribut ) Zeichnet den angegebenen Rahmen auf dem Bildschirm. Ergibt keinen Rückgabewert. "art" gibt an, welcher Rahmen gezeichnet werden soll. Es sind Werte von 0 bis 3 zulässig: 0 = doppelter Strich als Rahmen 1 = einfacher Strich als Rahmen 2 = komplett ausgefüllter Rahmen (Zeichen "█") 3 = Rahmen wird waagrecht als doppelter Strich, senkrecht als einfacher Strich dargestellt Siehe auch Kapitel 5.2 int set_textmode() Ermittelt den besten Textmodus zur vorhandenen Hardware, stellt diesen ein und löscht den Bildschirm. Ergibt den Wert null, wenn irgendein Fehler aufgetreten ist. Siehe auch Kapitel 5.2 void string( int x, int y, int attribut, int anzahl, unsigned char zeichen ) Gibt das ASCII-Zeichen "zeichen" sooft nebeneinander auf dem Bildschirm aus, wie es in der Variablen "anzahl" angegeben wurde. Ergibt keinen Rückgabewert. Siehe auch Kapitel 5.2 MENU * UseMenu( MENU *item ) Aktiviert das angegebene Menü. Der Anwender kann dann einen Menüpunkt auswählen, Hilfe anfordern oder Abbrechen. Ergibt den Zeiger auf den gewählten Menüpunkt. Die globale Variable "select" enthält den Grund für die Beendigung der Funktion. Siehe auch Kapitel 5.4 void wcls( int x, int y, int xx, int yy, int attribut ) Diese Funktion löscht einen Bildschirmausschnitt. Kein Rückgabewert! Siehe auch Kapitel 5.3 3. Einfügedateien innerhalb der Toolbox Die Toolbox benötigt eine Reihe von Einfügedateien. Quick-C v2.0 wird bereits mit einer beachtlichen Anzahl von Einfügedateien ausgeliefert. Davon bindet die Toolbox "WINDOW.C" nachfolgende Einfügedateien ein. Der Programmierer muß in seinem Hauptprogramm diese Dateien nicht erneut einbinden. Das doppelte Einbinden von Einfügedateien hat nur eine Nebenwirkung: Es verschwendet unnötig viel Zeit zum Compilieren! #include <bios.h> #include <conio.h> #include <ctype.h> #include <dos.h> #include <graph.h> #include <malloc.h> #include <stdio.h> #include <stdlib.h> #include <string.h> Bitte beachten Sie, daß die aufgeführten Einfügedateien beim inkrementalen Compilieren für Ihr Programm nicht mehr sichtbar sind! Das bedeutet, daß Sie sich in diesem Fall wieder selbst um die benötigten Einfügedateien kümmern müssen (mit "#include" selbst einfügen). Siehe auch Anhang C ------ Anhang B: Evtl. auftretende Probleme und deren Lösung ---------------- Problem: In den Speichermodellen "small" oder "medium" stürzt das Programm ab oder läuft inkorrekt. -> Die Toolbox verwendet die Macros "FP_OFF" und "FP_SEG". Dadurch dürfen in diesen beiden kleinen Speichermodellen keine Funktionen und Daten als "far" deklariert werden (weitere Informationen hierüber: innerhalb der Quick-C-Entwicklungsumgebung mit der F1-Taste Hilfe zu diesen beiden Macros anzeigen lassen). Am besten löst man dieses Problem, indem man ein anderes Speichermodell verwendet oder keine "far"-Elemente definiert. Problem: Das ausführbare Programm läuft nicht (Rechner-Absturz oder Endlosschleife). -> Wahrscheinlich haben Sie einen Fehler bei der Menüverkettung gemacht. Alle notwendigen Menüstrukturen müssen miteinander durch Zeiger verbunden werden. Wurde hier ein Zeiger auf eine falsche Struktur oder Speicherstelle gesetzt, so stürzt der Rechner normalerweise ab. Genauere Informationen hierüber siehe Kapitel 6 Buchstabe b. Natürlich kann der Absturz auch viele andere Ursachen haben. Im Einzelfall empfehle ich einen Einzelschrittdurchlauf mit dem Debugger, falls die Ursache nicht sofort gefunden werden kann. Problem: Beim Compilieren tritt (manchmal) die Warnung "Warnung: 'funktion' neu definiert" (Warnung Nr. C4414) auf. -> Diese Warnung kann ignoriert werden. Sie tritt auf, weil in der Toolbox nicht alle Funktionen am Anfang des Quelltextes mit einem Prototypen vordefiniert wurden. Problem: Es tritt der Laufzeitfehler "-Stapelüberlauf" (Laufzeitfehler "R6000") auf. -> Der Stapel (Stack) für das ausführbare Programm ist zu klein. Bitte vergewissern Sie sich, daß der Stapel gemäß Kapitel 1.3 dieser Dokumentation vergrößert wurde. Sollte der Fehler auch bei der ordnungsgemäßen Stapelgröße von acht Kilobyte auftreten so muß dieser zusätzlich vergrößert werden (Menü "Optionen -> Make... -> Linker-Marken" unter dem Punkt Stapelgröße). Dieser Fehler tritt meistens nur bei den Programmen auf, die viel Gebrauch von rekursiven Funktionen machen. Problem: Es tritt der Laufzeitfehler "-Unzulässiger Far-Zeiger" auf (Laufzeitfehler "R6013"). -> Die Toolbox greift mit Hilfe von Far-Zeigern direkt auf den Bildschirmspeicher zu. Dieser liegt außerhalb des Programm-Bereichs. Es handelt sich hier um keinen "echten" Fehler, weil die Bereichsüberschreitung so gewollt ist. Normalerweise tritt dieser Fehler nur auf, wenn die Zeigerprüfung aktiv ist. Die Toolbox schaltet die Zeigerprüfung automatisch aus. Irgendwie wurde die Zeigerprüfung jedoch wieder aktiviert. Dieser Fehler läßt sich beheben, indem man im Menü "Optionen -> Make... -> Compiler-Marken" die Option "Zeigerprüfung" ausschaltet oder den Quelltext erneut mit Hilfe des Pragmas "#pointer_check( off )" compiliert. Problem: Auf dem Bildschirm sind keine Bildschirmausgaben zu sehen (u. U. ist er mit einer einheitlichen Farbe gelöscht) und es erscheint auch kein Text, keine Windows und keine Menüs. -> Vermutlich werden die Bildschirmausgaben in den falschen Bildschirmspeicherbereich geschrieben. In der Variablen "screen" speichert die Toolbox die Segment-Adresse des Bildschirmspeichers ab. Der Programmierer braucht sich in der Regel nicht um die Verwaltung dieser Variable zu kümmern, sie wird von der Toolbox automatisch belegt. Bei manchen PC's, die nicht 100%-ig kompatibel sind (z. B. einige alte Siemens-PC's), kann der Bildschirmspeicher auch an einer anderen Segment-Adresse liegen. In einem solchen Fall muß in der Variablen "screen" der passende Wert eingetragen werden, nachdem die Funktion "OpenTool" aufgerufen wurde. Diese Änderung muß im Quellcode des Programmes erfolgen. Das somit entstandene ausführbare Programm ist dadurch mit ziemlicher Sicherheit nur noch auf Computern dieses gleichen Typs lauffähig. Es ist auch möglich, die Funktion "OpenTool" so zu ändern, daß sie den "seltsamen" PC erkennt und automatisch die richtige Segmentadresse ermittelt. Dadurch wäre das erzeugte Programm wieder auf allen PC's lauffähig. Weitere Hinweise können Sie beim Kapitel 4.3 unter der Variable "screen" entnehmen. Problem: In den kleinen Speichermodellen (Small, Medium und Compakt) wird die Warnung C4060 ("Umwandlung langer Adresse zu kurzer Adresse") oder die Warnung C4062 ("near/far-Fehler im Argument: Umwandlung durchgeführt") gemeldet. -> Diese Warnungen können ignoriert werden. Sie kommen zustande, weil die Toolbox von far-Zeigern (32 statt 16 Bits!) Gebrauch macht. Die kleinen Speichermodelle können jedoch nur near-Zeiger und -Adressen verarbeiten (16 Bits). Aus diesem Grund muß eine Umwandlung durchgeführt werden. Soweit bisher bekannt ist, haben diese Warnungen auf die Programmausführung keinen Einfluß. Problem: Bei globalen Strukturen (z. B. Windows und Menüs), die gleichzeitig mit der Deklaration initialisiert werden, tritt der Fehler C2098 "Ausdruck ist keine Adresse" oder der Fehler C2097 "Unzulässige Initialisierung" auf. -> Bei globalen Variablen und Strukturen dürfen nur Zahlenwerte angegeben werden, keinesfalls jedoch Variablen! Wahrscheinlich haben Sie versucht, einer globalen Struktur oder einer Variable gleich bei der Deklaration mit dem Wert einer anderen globalen Variable zu initialisieren, wie z. B. so: WINDOW hier = { 1, 1, 10, 5, f0, 1, f2, ... } Bei diesem Beispiel wurden bereits die globalen Farb-Variablen "f0" und "f2" angegeben. Dies ist verboten! Sie müssen hier stattdessen einen Pseudowert (z. B. "0") einsetzen und später eine Funktion aufrufen, die dem Window die entsprechenden Farben zuweist, z. B. so: ... hier->wattr = f0; hier->rattr = f2; ... Weitere Hinweise können Sie unter dem Kapitel 4.3 "Globale Variablen" bei der Erklärung der Variablen "f0" bis "f3", Zwischenüberschrift "Achtung" entnehmen. Problem: Die Toolbox "Window.C" arbeitet nicht in Verbindung mit anderen Toolboxen (Rechnerabstürze, falsch arbeitende Funktionen usw.). -> Die Toolbox "Window.C" wurde so programmiert, daß sie auch zu anderen Toolboxen kompatibel sein müßte. Der einzige "Schwachpunkt" ist das Umleiten des INT 24h mit Hilfe der Funktion "_harderr" von Quick-C. Dadurch wird bei einem evtl. auftretenden schweren Fehler sofort die Toolbox-interne Funktion "hardfehler" aufgerufen. Sollte eine andere Toolbox ebenfalls den Interrupt 24h verbiegen, wird es zu größeren Problemen kommen. Dieses Problem läßt sich nur durch eine Änderung der Toolbox lösen. Am besten wenden Sie sich direkt an mich. Bitte geben Sie sowohl die Versionsnummer der Toolbox "Window.C" als auch den Namen und die Version der anderen Toolbox an. ------ Anhang C: Inkrementales Compilieren ---------------------------------- Der Compiler von Quick-C Version 2.0 wurde gegenüber der Version 1.0 vollständig überarbeitet. So compiliert er jetzt bei jedem neuen Lauf nur die Teile eines Quelltextes, die sich seit der letzten Compilation verändert haben. Dadurch ergibt sich eine unglaubliche Geschwindigkeitssteigerung. Diese Form des Compilierens nennt man "inkrementales Compilieren". Zum inkrementalen Compilieren ist es allerdings erforderlich, daß das Programm in mehrere Teile aufgespalten und getrennt abgespeichert wird. Es gibt verschiedene Gründe für das Teilen einer Datei in mehrere Module. Neben der Wiederverwendbarkeit von einzelnen Programmteilen in anderen Programmen (sog. Toolboxen) erleichtert das Teilen auch die Bearbeitung und Wartung von Programmen. Auch die Toolbox "WINDOW.C" kann zum inkrementalen Compilieren verwendet werden, wodurch das Compilieren sehr viel rascher abläuft. Hierzu sind jedoch einige Vorbereitungen erforderlich. Nachfolgend wird nun beschrieben, wie man innerhalb der Entwicklungsumgebung seine eigenen Programme zusammen mit der Toolbox inkremental compiliert. Zur leichteren Erklärung nehmen wir im folgenden an, Sie wollen Ihr Programm namens "SCHULE.C" inkremental compilieren. Die wichtigste Änderung ist folgende: Statt der Datei "WINDOW.C" müssen Sie nun die Header-Datei "WINDOW.H" in ihr Programm (SCHULE.C) einfügen (#include <window.H> statt #include <window.C>). In dieser Header-Datei sind alle notwendigen Strukturen, Variablen und Funktionen als "extern" deklariert. Als nächstes müssen Sie für das Programm, daß inkremental !!! compiliert werden soll, eine neue Programmliste erstellen: Öffnen Sie das Menü "Make" und wählen Sie "Programmliste bestimmen" (nur bei eingeschaltetem vollständigen Menü möglich!). Schreiben Sie dann den Namen Ihres Programmes mit der Extension ".MAK" als Namen für die Datei, welche die Programmliste enthalten soll (also "SCHULE.MAK"; die Erweiterung "MAK" wird für Beschreibungsdateien verwendet) und drücken Sie die Eingabetaste. Es erscheint dann ein Dialogfeld. Hier fügen Sie nun die Datei "WINDOW.C" und den Dateinamen Ihres Programmes (SCHULE.C) der Programmliste zu. Unter Umständen müssen Sie dabei den Pfad !!! oder gar das Laufwerk wechseln, weil sich die Datei "WINDOW.C" in dem Verzeichnis der Headerdateien befindet (siehe auch Kapitel 1.4). Sobald beide Programme in der Programmliste erscheinen, klicken Sie zur Sicherung der ".MAK"-Datei das Befehlsfeld "Liste speichern" an. Diese Programmliste informiert Quick-C nun beim Compilieren daran, daß mehrere Quelldateien in einem Programm zu vereinen sind. Wollen Sie außerdem weitere Programm-Module mitcompilieren, müssen auch diese in die Programmliste aufgenommen werden. Beachten Sie bitte, daß der Basisname der Programmliste dem Dateinamen Ihres Programmes gleichen sollte (SCHULE.C und SCHULE.MAK). Dadurch fragt Quick-C beim Laden Ihres Programmes automatisch, ob Sie die Programmliste verwenden wollen. Ab sofort wird Ihr Programm nun inkremental compiliert. Hinweis: Inkrementales Compilieren ist nur mit der Vollversion der Toolbox möglich, da hierzu die Headerdatei "WINDOW.H" benötigt wird (diese wird in der Shareware- Version nicht mitgeliefert!). Bitte beachten Sie außerdem folgendes: Die im Anhang A unter dem Kapitel 3 aufgeführten Einfügedateien sind durch das inkrementale Compilieren für Ihr Programm nicht mehr sichtbar! Das bedeutet, daß Sie nun wieder alle Einfügedateien selbst mit "#include" einfügen müssen, soweit sie diese benötigen. Weiterhin sind die Toolbox-internen Funktionen beim inkrementalen Compilieren NICHT mehr sichtbar, d. h. man kann auf sie nicht mehr zugreifen! Sollte dies dennoch erwünscht sein, muß man in die Headerdatei "Window.H" den Prototypen der gewünschten internen Funktion mit dem Vorsatz "extern" einfügen. Will man z. B. die interne Funktion "_locate" verwenden, muß man folgende Zeile in die Headerdatei einfügen: extern unsigned int _locate( int x, int y );