4.13 DocumentGuardian

4.13.1 Konfiguration

4.13.2 Verwalten von Dokumenten

4.13.3 Services

DocumentGuardian-Objekte sind dafür ausgelegt mit der Library "DocumentTools" zusammenzuarbeiten. Diese Library bietet z.B. die zur Dateiarbeit nötigen Dialogboxen wie "Öffnen" und "Speichern unter" an. Im Handbuch "Spezielle Themen", Kapitel 15, ("Implementieren eines Dokument-Interfaces") finden Sie eine ausführliche Beschreibung wie man die Arbeit mit Dokumenten unter Verwendung der DocumentTools Library und eines DocumentGuardian-Objekts organisiert. Bitte lesen Sie dort nach, wenn Sie ausführliche Beispiele oder weitergehende Erklärungen benötigen.

Zur Vereinfachung kann der gesamte Dokument-Interface Code über ein R-BASIC Menu in ihr Programm eingebaut werden. Dazu verwenden Sie das Menü "Extras" -> "Code Bausteine" -> "Dokument-Interface". Dort können Sie auch festlegen, welche Teile des Dokumentinterfaces Sie unterstützen wollen, z.B. ob Sie Musterdokumente unterstützen wollen oder nicht.

Im Prinzip läuft die Arbeit mit DocumentGuardian-Objekten so ab:

• Vereinbaren Sie ein DocumentGuardian-Objekt im UI-Code oder erzeugen Sie sein oder mehrere DocumentGuardian-Objekte zur Laufzeit (mit CreateObject).

• Initialisieren Sie das Objekt durch Belegen der Instancevariablen configData und ButtonHandler.

• Öffnen Sie ein vorhandenes Dokument mit der Methode OpenDocument oder erzeugen Sie ein neues Dokument mit CreateNewDocument.

• Um Daten aus der Dokument-Datei zu lesen oder in die Datei zu schreiben benötigen Sie das FILE Handle der Datei. Das bekommen Sie über die Instancevariable documentHandle.

  Wichtig: Das FILE Handle der Dokumentendatei kann sich im Laufe der Zeit ändern, z.B. wenn die Datei umbenannt (Menüpunkte "Speichern unter" oder "Umbenennen") oder verschoben wird (Menüpunkt "Verschieben nach"). Deswegen sollten Sie das FILE Handle nicht irgendwo zwischenspeichern.

• Wenn Sie Informationen über den Zustand der Datei wissen oder ändern wollen, können Sie die Instancevariable documentState und die Methode SetDocumentState verwenden. Insbesondere sollten Sie SetDocumentState rufen, wenn Sie die Datei als geändert markieren wollen.

• Weitere wichtige Informationen über die offene Datei speichern die Instancevariablen documentName$ und documentPath$. DocumentUserData können Sie verwenden, um beliebige weitere Informationen über die Datei abzulegen.

• Um ein Dokument zu schließen verwenden Sie die Methode CloseDocument.

• Wenn GEOS herunterfährt bzw. wieder neu startet übernehmen die Methoden HandleShutdown und HandleRestart alle notwendigen Schritte um die Datei zu schließen und beim Neustart automatisch wieder zu öffnen.

Objekte der Klasse DocumentGuardian sind per Default nicht sichtbar (visible = FALSE). Sie können in den generic Tree eingebunden werden. Werden sie auf visible = TRUE gesetzt verhalten sie sich wie eine Group. Die unterstützen das Geometriemanagement und können Children haben.

Spezielle Instance-Variablen:

Variable	Syntax im UI-Code	Im BASIC-Code
ButtonHandler	ButtonHandler = <Handler>	nur schreiben
configData	--	lesen, schreiben
documentState	--	nur lesen
documentHandle	--	nur lesen
documentName$	--	nur lesen
documentPath$	--	nur lesen
documentUserData	--	lesen, schreiben

Methoden:

Methode	Aufgabe
SetDocumentState	Informationen über das Dokument ändern
CreateNewDocument	Neues Dokument anlegen
OpenDocument	Vorhandenes Dokument öffnen
CloseDocument	Aktuelles Dokument schließen
HandleShutdown	System-Shutdown behandeln
HandleRestart	System Neustart behandeln

^

4.13.1 Konfiguration

ConfigData

noDocumentString$

NoDocumentString$ enthält den Text, den die Methode DocumentName$ zurückgeben soll, wenn kein Dokument geöffnet ist. Ein typischer Wert wäre "kein Dokument".

templateFolder$

TemplateFolder$ enthält den Unterordner im SP_TEMPLATE-Verzeichnis, in dem das Programm Templates ("Muster-Dateien") speichert. Das DocumentGuardian-Objekt stellt sicher, dass der Ordner existiert.

nameForNew$

NameForNew$ enthält den Kerntext, aus dem das DocumentGuardian-Objekt durch Hinzufügen einer Zahl von 1 bis 99 einen Namen für eine neue Datei bilden soll.

NameForNew$ hat das Format "core*.ext" oder "core".

Beispiele:

Aus "LEER*.RBF" wird "LEER1.RBF", "LEER2.RBF" bis "LEER99.RBF"
Aus "NEU*" wird "NEU2", "NEU2" bis "NEU99"
Aus "namenlos " wird "namenlos 1", "namenlos 2" bis "namenlos 99"

Wichtig: Sie sind selbst dafür zuständig, dass der nach dem oben genannten Schema gebildete Name zum Dateityp passt, für DOS-Dateien also das Format 8+3 eingehalten wird.

fileType

FileType enthält den Typ der Dokumentendatei. Gültige Werte sind GFT_VM, GFT_DATA und GFT_NOT_GEOS_FILE. Erfahrene Programmierer sollten VM-Dateien (GFT_VM) verwenden, für alle anderen empfiehlt sich GFT_DATA (GEOS-Daten-Dateien). Diese unterstützen wie die VM-Dateien die Geos-Attribute wie Token und CreatorToken. DOS-Dateien (GFT_NOT_GEOS_FILE) sollten Sie nur dann verwenden, wenn Sie einen wirklich guten Grund dafür haben.

token, creatorToken

Token und CreatorToken enthalten das Token und das CreatorToken der Datei für GEOS-Daten- und VM-Dateien. Beim Anlegen einer neuen Datei setzt das DocumentGuardian-Objekt Token und CreatorToken automatisch.

matchMask$, matchFlags

MatchMask$ und matchFlags werden vom DocumentGuardian-Objekt nicht selbst verwendet, sondern sind zur Arbeit der DocumentTools-Library notwendig. MatchFlags enthält die Information, welche Eigenschaften der Datei der im "Öffnen"-Dialog angezeigte FileSelector zum Filtern der Dateien verwenden soll. MatchMask$ enthält die Dateimaske, die verwendet wird, falls das entsprechende Bit in MatchFlags gesetzt ist.

reserved

Diese 10 Bytes sind für eventuelle spätere Erweiterungen vorgesehen. Sie dürfen diese Werte nicht verwenden.

ButtonHandler

Syntax UI-Code: ButtonHandler = <Handler>
     Schreiben: <obj>.ButtonHandler = <Handler>

4.13.2 Verwalten von Dokumenten

CreateNewDocument

• Der Name der neuen Datei wird aus configData.nameForNew und einer Zahl gebildet.

• Der Dateityp (DOS-, GEOS-Daten- oder GEOS-VM-Datei) wird von configData.fileType bestimmt.

• Für GEOS-Daten- und VM-Dateien wird Token (configData.token) und CreatorToken (configData.creatorToken) gesetzt.

• VM-Dateien werden so initialisiert, dass sie mit der "VMFiles" Library verwendet werden können. Details zur Arbeit mit VM-Dateien finden Sie Im Handbuch der "VMFiles" Library

• Achtung! Sollte das DocumentGuardian-Objekt noch eine Dokument-Datei offen haben wird sie ohne Nachfragen geschlossen.

OpenDocument

Syntax BASIC-Code: <obj>.OpenDocument "name" [, forceRO ]
           "name": Dateiname der zu öffnenden Datei
          forceRO: FALSE: normal öffnen (Default)
                    TRUE: schreibgeschützt öffnen

CloseDocument

Syntax BASIC-Code: <obj>.CloseDocument 
                   <obj>.CloseDocument FALSE

DocumentHandle

Syntax Lesen: <fh> = <obj>.documentHandle 
              <fh>: Variable vom Typ FILE

DocumentName$

Syntax Lesen: <stringVar> = <obj>.documentName$ 
              <stringVar>: Variable vom Typ String

DocumentPath$

Syntax Lesen: <stringVar> = <obj>.documentPath$ 
  <stringVar>: String-Variable, die 200 Zeichen aufnehmen kann.

documentState, SetDocumentState

Konstante	Wert	Bedeutung
DOCS_OPEN	1	Es ist ein Dokument offen
DOCS_MODIFIED	2	Das Dokument wurde geändert. (*)
DOCS_UNTITLED	4	Das Dokument ist neu und hat noch keinen vom Nutzer vergebenen Namen.
DOCS_READ_ONLY	8	Das Dokument ist schreibgeschützt
DOCS_EDIT_TEMPLATE	16	Es ist ein Muster in Bearbeitung (**)

(*) Das Bit DOCS_MODIFIED wird vom DocumentGuardian-Objekt weder automatisch gesetzt noch zurückgesetzt. Es wird von der "DocumentTools" Library benötigt. Deswegen muss der Programmierer es auf dem aktuellen Stand halten.

(**) Das Bit DOCS_EDIT_TEMPLATE wird vom DocumentGuardian-Objekt nicht automatisch gesetzt. Es wird benutzt um sicherzustellen, dass der nächste "Öffnen"-Dialog den Dokument-Ordner anzeigt, und nicht dem der aktuell offenen Datei (den Template-Ordner). Der Programmierer sollte es setzen, wenn er ein Muster zum Bearbeiten öffnet. Es wird beim Schließen dieser Datei automatisch zurückgesetzt.

Die Instancevariable documentState kann nur gelesen werden. Um sie zu ändern verwenden Sie die Methode SetDocumentState. Sie erwartet zwei Parameter: die Bits, die zu setzen sind und die Bits, die zu löschen sind. Das vereinfacht die Verwaltung des Dokumentstatus wesentlich. SetDocumentState kann nur die Bits DOCS_MODIFIED, DOCS_UNTITLED und DOCS_EDIT_TEMPLATE ändern. Wenn kein Dokument offen ist können diese Bits nicht gesetzt werden.

Syntax BASIC-Code: <numVar> = <obj>.documentState

Syntax BASIC-Code: <obj>.SetDocumentState bitsToSet, bitsToClear

4.13.3 Services

HandleShutdown, HandleRestart

Syntax BASIC-Code: <obj>.HandleShutdown
                   <obj>.HandleRestart

documentUserData

Eine andere Anwendung wäre, wenn Sie ein Programm schreiben, dass mit mehreren offenen Dokumenten gleichzeitig umgehen kann, wobei jedes offene Dokument sein eigenes DocumentGuardian-Objekt hat. DocumentUserData könnte dann die Dokument-spezifischen Daten enthalten.

DocumentUserData ist zuweisungskompatibel mit jeder Art von Strukturvariablen. Beim Schreiben müssen Sie allerdings die Größe der Struktur extra angeben. Beim Lesen müssen Sie selbst darauf achten, dass die Strukturen kompatibel sind, R-BASIC führt weder eine Typ- noch eine Größenprüfung aus. Aber es ist sichergestellt, dass niemals mehr Bytes kopiert werden, als die Variable auf der linken Seite der Zuweisung aufnehmen kann.

Es ist zulässig mehrfach hintereinander Strukturen verschiedenen Typs und verschiedener Größe in die Instancevariable zu schreiben. R-BASIC optimiert jedes Mal den verwendeten Speicher, so dass kein Platz verschwendet wird.

Syntax Schreiben: <obj>.documentUserData = <struct>, size
        <struct>: Strukturausdruck beliebigen Typs
            size: Größe der Struktur
           Lesen: <sturctVar> = <obj>.documentUserData 
     <structVar>: Strukturvariable des Typs,
                  der beim Schreiben verwendet wurde.