5. Arbeit mit der Zwischenablage
^
5.1 Überblick
Zugriff auf die Zwischenablage
Die Arbeit mit der Zwischenablage (auch Clipboard genannt) ist unter PC/GEOS auf zwei Arten möglich. Zum einen weiß jedes Objekt, z.B. ein Memo-Objekt, ob es mit der Zwischenablage zusammenarbeiten kann und wie es Daten (z.B. einen Text oder eine Grafik) in die Zwischenablage kopiert oder aus ihr herausholt. Zusätzlich unterstützt PC/GEOS den direkten Zugriff auf die Zwischenablage, d.h. eine Applikation kann ihre eigenen Daten in einem eigenen Format in die Zwischenablage kopieren bzw. von dort lesen. R-BASIC bietet ebenfalls beide Wege an. Auf Objektebene stehen die Methoden (Objektanweisungen) ClpTestCopy, ClpTestPaste, ClpCopy und ClpPaste zur Verfügung. Das Programm selbst kann mit den Befehlen ClipboardTest, ClipboardPut, ClipboardGet, ClipboardPutGS, ClipboardGetGS, ClipboardPutBitmap und ClipboardGetBitmap direkt auf die Zwischenablage zugreifen. Die globale Variable clipboardError wird auf TRUE gesetzt, wenn es ein Problem bei der Arbeit mit der Zwischenablage gab.Überwachung der Zwischenablage
Ein R-BASIC Programm kann sich bei Bedarf über Änderungen des Inhalts der Zwischenablage informieren lassen. Jedes Mal wenn irgendein Programm (z.B. GeoWrite) Änderungen an der Zwischenablage vornimmt wird vom Application-Objekt ein spezieller Handler (OnClpChange-Handler) gerufen.Das ClipboardFormat
Will ein Programm oder Objekt z.B. einen Text aus der Zwischenablage entnehmen, so muss es sicher sein, dass sich auch ein Text in der Zwischenablage befindet. Deshalb muss beim Kopieren irgendwelcher Daten in die Zwischenablage immer eine Information mit abgespeichert werden, worum es sich handelt. Diese Information heißt ClipboardFormat und besteht aus zwei WORD-Werten, der Manufacturer-ID und der FormatNummer. Der erste Wert, die Manufacturer-ID, frei übersetzt die "Hersteller-Kennung", beschreibt, wer die Software, die Daten ins Clipboard kopiert, geschrieben hat. Der zweite Wert, die FormatNummer, ist einfach eine laufende Nummer, die verschiedene Clipboardformate der gleiche Softwareschmiede unterscheiden soll.Standardformate
Bei allen von PC/GEOS selbst definierten Formaten (z.B. Text, Bitmap, Graphic String) ist die Manufacturer-ID Null. Null ist die Herstellerkennung von GeoWorks. BreadBox hat die Nummer 16431 und der Programmierer von R-BASIC hat die Nummer 16480. GeoWorks hat einige grundlegende Formate z.B. Text (FormatNr. 0), Graphic String (Folge von Grafikbefehlen, Nr. 1) und Bitmap (Nr. 7) sowie einige mehr definiert. Diese werden als Standardformate bezeichnet und sind teilweise im PC/GEOS-SDK dokumentiert. Unter R-BASIC ist ein Zugriff auf die Formate Text, Graphic String und Bitmap über einige R-BASIC Objekte möglich. Ein BitmapContent-Objekt kann z.B. sowohl eine Bitmap als auch einen Graphic String aus dem Clipboard lesen und Textobjekte (Memo, InputLine) können selbstverständlich mit Texten im Clipboard umgehen.
Weiter unten wird beschrieben, wie sie selbst zu einer Manufacturer-ID kommen, falls sie eine benötigen.
Mehrere Formate im Clipboard
Unter PC/GEOS können die Daten in der Zwischenablage in mehr als einem Format gleichzeitig abgelegt werden. Beispielsweise speichert GeoDraw seine Grafiken immer sowohl als editierbare GeoDraw-Objekte als auch als Graphic String (der z.B. von GeoWrite oder vom R-BASIC Bitmap-Objekt gelesen werden kann). Der Grafikbetrachter Gonzo und auch das R-BASIC BitmapContent Objekt kopiert Bilder sowohl als reine Bitmap als auch als Graphic String in die Zwischenablage. Wenn Sie in R-BASIC eigene Clipboardformate verwenden, können Sie allerdings nur genau ein Format gleichzeitig in die Zwischenablage kopieren.^
5.2 Clipboardoperationen
Aus dem Bearbeiten-Menü kennen Sie die Clipboardoperationen "Kopieren", "Einfügen" und "Ausschneiden". Diese sind unter PC/GEOS auf ganz elementarer Ebene und für alle Objekte definiert - auch wenn die meisten Objekte (z.B. ein Button) gar nicht mit dem Clipboard zusammenarbeiten können. R-BASIC übernimmt das und deswegen sind die Clipboardoperationen auch unter R-BASIC für alle Objekte erlaubt. Sehr viele, wie z.B. ein Button, ignorieren die entsprechenden Anweisungen aber. Bei denjenigen Objekten, die mit dem Clipboard arbeiten können, z.B. BitmapContent und Textobjekte, finden Sie bei der Beschreibung dieser Objekte die entsprechenden Detailinformationen.
Das Kopieren von Daten ins Clipboard wird als Copy-Operation bezeichnet (engl. to copy: etwas kopieren), das Einfügen von Daten aus dem Clipboard in ein Objekt wird als Paste-Operation bezeichnet (engl. to paste: etwas einkleben, etwas einfügen). Die Operation "Ausschneiden" wird von R-BASIC nicht direkt unterstützt. Sie ist identisch mit "Kopieren ins Clipboard" und anschließendem Löschen der Daten aus dem Objekt. Das lässt sich bei Bedarf sehr leicht manuell implementieren.
clipboardError
Es ist möglich, wenn auch extrem unwahrscheinlich, dass in der kurzen Zeitspanne zwischen den Prüfen der Zwischenablage mit ClpTest bzw. ClipboardTest und der Verwendung der Daten mit ClpPaste bzw. ClipboardGet eine andere Applikation den Inhalt der Zwischenablage verändert hat. Die Clipboard "Lese" Operationen ClipboardGet und ClpPaste setzen deswegen die globale Variable clipboardError auf TRUE (Fehler) oder FALSE (OK), je nachdem ob sie erfolgreich waren oder nicht.ClpTestCopy, ClpCopy
Die Methode ClpTestCopy weist das Objekt an zu prüfen, ob es Daten ins Clipbord kopieren kann. Die Methode liefert den Wert TRUE (-1, entspricht ja) oder FALSE (Null, entspricht nein). Objekte, die nicht mit dem Clipboard arbeiten können liefern hier immer Null, also nein. Die globale Variable clipboardError wird von ClpTestCopy nicht verändert.- Syntax BASIC-Code: <numVar> = <obj>.ClpTestCopy
- Liefert:
- TRUE: Daten zum Kopieren vorhanden
- FALSE: Kann keine Daten kopieren
Die Methode ClpCopy weist das Objekt an, seine Daten ins Clipboard zu kopieren. Ist es dazu nicht in der Lage, entweder weil das Objekt gar nicht mit dem Clipboard arbeiten kann oder weil gerade keine Daten verfügbar sind, wird die Anweisung ignoriert und die globale Variable clipboardError wird auf TRUE gesetzt.
Syntax BASIC-Code: <obj>.ClpCopy
Beispiel:
DIM n
n = QuestionBox ("Text kopieren?")
IF n = YES then
DemoText.ClpCopy
end if
ClpTestPaste, ClpPaste
Mit der Methode ClpTestPaste können Sie erfahren, ob sich Daten im Clipboard befinden, die vom Objekt akzeptiert werden. Dazu prüft das Objekt, ob sich ein geeignetes Format im Clipboard befindet. Objekte, die nicht mit dem Clipboard arbeiten können liefern hier immer FALSE (Wert Null, bedeutet nein). Die globale Variable clipboardError wird von ClpTestPaste nicht verändert.- Syntax BASIC-Code: <numVar> = <obj>.ClpTestPaste
- Liefert:
- TRUE: Daten zum Einfügen gefunden
- FALSE: Kann nichts einfügen
Die Methode ClpPaste weist das Objekt an, Daten aus dem Clipboard bei sich selbst "einzufügen". Ob das ein "Hinzufügen" oder ein "Ersetzen" ist hängt vom Objekt ab. Ist das Objekt nicht in der Lage, die Clipboarddaten einzufügen, entweder weil das Objekt gar nicht mit dem Clipboard arbeiten kann oder weil es ein Problem gibt, wird die Anweisung ignoriert. Je nach Objekt und Situation kann es eine Fehlermeldung geben oder auch nicht. Die meisten Objekte (mit Ausnahme der Textobjekte) setzen die globale Variable clipboardError auf TRUE bzw. auf FALSE.
Syntax BASIC-Code: <obj>.ClpPaste
Beispiel:
IF DemoBitmap.ClpTestPaste THEN DemoBitmap.ClpPaste else MsgBox "Keine Grafik im Clipboard" end if
^
5.3 Das Clipboard überwachen
Um in R-BASIC z.B. ein "Bearbeiten" Menü zu implementieren müssen Sie wissen wenn jemand etwas ins Clipboard kopiert und was es ist. Dann können Sie z.B. einen "Einfügen" Schalter enablen oder disablen. Für dieses Zweck verfügt das Application Objekt (und nur dieses) über einen speziellen Actionhandler, der immer dann aufgerufen wird, wenn sich im Clipboard etwas tut.
Der OnClpChange Handler wird automatisch immer dann aufgerufen wenn sich die Daten im Clipboard ändern. Die übergebenen Parameter sind hier ohne Bedeutung und sollten ignoriert werden. Wenn die Instancevariable OnClpChange erstmalig belegt wird, meldet sich das Applicationobjekt beim System für die Clipboardüberwachung an und erhält fortan automatisch die entsprechenden Informationen. Erstmalig wird der Handler bereits gerufen, wenn sich das Applicationobjekt anmeldet. Da OnClpChange üblicherweise im UI-Code belegt wird erfolgt der erstmalige Aufruf schon beim Programmstart. Damit ist das BASIC Programm stets über den Stand des Clipboards informiert.
Das folgende Beispiel zeigt das Fragment einer typischen Implementation. Der "Einfügen" Button ist nur dann aktiv wenn sich auch eine Grafik im Clipboard befindet.
Im UI Code:
Application DemoApplication Children = DemoPrimary OnClpChange = ClpChangeHandler END Object BitmapContent DemoBitmap .... END Object Button PasteButton Caption$="Einfügen" enabled = FALSE ' sicherheitshalber ActionHandler = PasteImageHandler END Object
'
' Der Handler enabled oder disabled den Einfügen Button
'
SYSTEMACTION ClpChangeHandler
DIM ok
ok = DemoBitmap.ClpTestPaste
IF ok THEN
PasteButton.enabled = TRUE
ELSE
PasteButton.enabled = FALSE
END IF
END Action
'
' Der Button Handler ist sehr simpel
'
BUTTONACTION PasteImageHandler
DemoBitmap.ClpPaste
END Action
^
5.4 Eigene Formate verwenden
Bei komplexen Anwendungen kann es sinnvoll oder nötig sein, eigene Daten von R-BASIC aus ins Clipboard zu kopieren und die wieder von dort zu lesen. Ein einfacher Fall wäre das Kopieren von Inhalten von einem Dokument in ein anderes. R-BASIC unterstützt das über die drei Befehle: ClipboardTest, ClipboardPut und ClipboardGet sowie mit der globalen Variaben clipboardError. Dabei wird jeweils der Inhalte einer Strukturvariablen ins Clipboard kopiert bzw. von dort gelesen. Sie sollten daher mit den Grundlagen der Verwendung von Strukturen (Schlüsselwort STRUCT) vertraut sein um die folgenden Abschnitte vollständig zu verstehen.clipboardError
Enthält im Fehlerfall TRUE, sonst FALSE. Details siehe Abschnitt "Clipboardoperationen".ClipboardTest
ClipboardTest prüft, ob sich Daten mit einem bestimmten Format im Clipboard befinden. Das Format kann ein GEOS Standardformat oder eine eigenes Format sein. Die globale Variable clipboardError wird nicht verändert.- Syntax BASIC Code: <numVar> = ClipboardTest ( manufID, formatNr)
- manufID: Manufacturer-ID des Formats
- formatNr: Nummer des Formats
- Return: TRUE: Format gefunden
- manufID: Manufacturer-ID des Formats
- FALSE: Format nicht im Clipboard
Die folgenden Tabelle enthält eine Auswahl der von GeoWorks definierten Clipboardformate. Einige dieser Formate sind im PC/GEOS-SDK dokumentiert, andere nicht.
Unter R-BASIC ist ein Zugriff auf die Formate Text, Graphic String und Bitmap über R-BASIC Objekte möglich.
ClipboardPut
Mit ClipboardPut können Sie den Inhalt einer Strukturvariablen (Strukturausdrücke sind auch erlaubt) ins Clipboard kopieren. Dazu müssen Sie ein eigenes ClipboardFormat "definieren" indem sie eine eindeutige Kombination von Manufacturer-ID und Formatnummer verwenden. ClipboardPut kann nicht fehlschlagen, die globale Variable clipboardError wird immer auf FALSE gesetzt.Syntax BASIC Code: ClipboardPut <structExpr>, manufID, formatNr
<structExpr> Struktur Variable oder Ausdruck
manufID: Manufacturer-ID ihres Formats
formatNr: Nummer ihres Formats
ClipboardPut erkennt alle sonstigen nötigen Daten wie Größe der Struktur automatisch. Es kopiert die Struktur 1:1 ins Clipboard und legt als ClipboardFormat die Kombination aus manufID und formatNr fest.
Beispiel
STRUCT Mydata x, y AS INTEGER r,g,b AS BYTE text$ AS STRING(60) info$ AS STRING(30) END STRUCT DIM dat AS Mydata ... ' hier dat mit Werten belegen ClipboardPut dat, 16480, 12 ' RABE-Soft ID + Nr.12
Falls Sie noch keine eigene Manufacturer-ID besitzen sollten Sie sich bei BreadBox eine besorgen. Wenn sie das wirklich nicht wollen ist die Sache komplizierter. Sie müssen sich dann eine "ausdenken" - was unter (wenn auch sehr unwahrscheinlichen) Umständen zu Konflikten führen kann. Lesen Sie dazu bitte den Abschnitt 3.4 (Über die Manufacturer ID) im R-BASIC Benutzer Handbuch.
ClipboardGet
Mit ClipboardGet können Sie den Inhalt des Clipboards in eine Strukturvariable kopieren. ClipboardGet prüft dabei, ob sich das ClipboardFormat, dass Sie mit den Parametern manufID und formatNr spezifiziert haben, auch wirklich im Clipboard befindet. Sollte das nicht der Fall sein liefert ClipboardGet eine "leere" Struktur (alles Nullen) zurück. Es erfolgt keine weitere Fehlermeldung. Verwenden Sie vorher ClipboardTest, und prüfen Sie auch die globale Variabe clipboardError ab, wenn Sie sicher sein wollen.Syntax BASIC Code: <structVar> = ClipboardGet ( manufID, formatNr)
<structVar> Struktur-Variable
manufID: Manufacturer-ID ihres Formats
formatNr: Nummer ihres Formats
ClipboardGet erkennt alle sonstigen nötigen Daten wie Größe der Struktur automatisch.
Achtung! ClipboardGet führt keine weiteren Prüfungen aus! Wenn das ClipboardFormat 'manufID' + 'formatNr' gefunden wurde, wird versucht die Daten zu kopieren. Das heißt z.B.
- Wenn Sie statt ihres gewünschten Formats zufällig ein Format spezifiziert haben, dass sich im Clipboard befindet, greift ClipboardGet darauf zu. Im günstigsten Fall erhalten Sie Müll, im schlechtesten crasht das System.
- Wenn der Typ der Strukturvariablen links vom Gleichheitszeichen nicht mit dem Type der Variablen, die bei ClipboardPut verwendet wurde, übereinstimmt, erhalten Sie Müll.
Beispiel
DIM dat AS Mydata ' Siehe ClipboardPut dat = ClipboardGet (16480, 12)
^
5.5 Bitmaps und GStrings
R-BASIC kann sowohl auf Bitmapdaten (ManufacturerID = 0, formatNr = 7) als auch auf Graphic Strings (ManufacturerID = 0, formatNr = 1) im Clipboard direkt zugreifen bzw. diese ins Clipboard kopieren. Dabei werden die Bitmap bzw. der GString über Handles referenziert.
Um zu prüfen, ob sich das richtige Format im Clipboard befindet können Sie die Routine ClipboardTest (siehe oben) verwenden. Um zu prüfen, ob die Operation erfolgreich war können Sie die globale Variable clipboardError abfragen.