Referenzliste Window Library -blättern- Referenzliste Utility Library

Inhalt | Start

Die Utility Library

5. Utility Library
Referenzliste Utility Library




In diesem Kapitel finden Sie weitere EasyGem Befehle, die Ihnen bei der Programmierung Ihres Computer helfen, aber nicht direkt mit Menüs, Dialogboxen oder Fenstern zu tun haben.


Get_Mouse R Mouse_X,R Mouse_Y[,R Mouse_But]
Mausposition in globalen Koordinaten und Mausknopf-Zustand abfragen.

Diese Prozedur liefert die Position der Maus auf dem realen Bildschirm, entspricht also den BASIC-Funktionen MOUSEX und MOUSEY. Die Position wird allerdings immer in globalen Koordinaten angegeben, während die BASIC-Funktionen die Position der Maus in lokalen Koordinaten des gerade aktiven Omikron Basic Ausgabefensters liefern. Wenn keine Omikron Basic Ausgabefenster angelegt wurden, sind beide Werte natürlich identisch.
Optional kann gleichzeitig auch noch der Zustand des Mausknopfes ermittelt werden. Der in Mouse_But zurückgelieferte Wert hat dabei die gleiche Bedeutung wie bei der BASIC-Funktion MOUSEBUT.
Nun ist es bisweilen auch erforderlich, die Position der Maus in lokalen Koordinaten zum gerade aktiven Fenster zu kennen. Zwar könnte man diese auch leicht selbst ausrechnen; um Ihnen die Arbeit zu erleichtern, stellt EasyGem hierfür aber eine eigene Prozedur zur Verfügung. Sie funktioniert ganz analog zu Get_Mouse, liefert aber eben die Mausposition in lokalen Koordinaten des gerade aktiven Fensters. Der Nullpunkt ist dabei die innere linke obere Ecke des Fensters. Bitte beachten Sie, dass eine eventuell vorhandene Infozeile bereits zum Fensterinneren gehört.


Get_Mouse_Local R Mouse_X,R Mouse_Y[,R Mouse_But]
Mausposition in lokalen Koordinaten und Mausknopf-Zustand abfragen.

Sicher haben Sie bei anderen Programmen schon beobachtet, daß sich die Form des Mauscursors bei bestimmten Anwendungen ändert (z.B. Kreuz oder Armbanduhr statt Pfeil). Dafür gibt es den EasyGem Befehl:


Set_Cursor Cursor_No
Form des Mauscursors einstellen.

In Cursor_No können Sie eine Zahl zwischen 0 und 4 oder 128 und 255 übergeben, die folgenden Formen entsprechen:


0 Der standardmäßige Arrow-Cursor.
1 Der sogenannte I-Beam-Cursor. Diese Form wird normalerweise für Textverarbeitung benutzt.
2 Der Cross-Cursor. Er besteht aus einem kleinen Kreuz und findet üblicherweise in Grafikprogrammen Verwendung.
3 Der Plus-Cursor. Wie der Name schon vermuten läßt, ähnelt dieses Cursorsymbol einem Pluszeichen. Man sollte ihn immer dann verwenden, wenn es darum geht, Bereiche zu selektieren.
4 Der Watch-Cursor hat die Form einer Armbanduhr und signalisiert, daß eine Operation ausgeführt wird, die ein wenig Zeit benötigt.
128-255 Diese Zahlen entsprechen einer Cursorform, die sich als Resource vom Typ "crsr" in der Resourcefork Ihres Programms befindet. Der Wert 128 ist standardmäßig mit dem Berkhan-Cursor belegt, den Sie schon vom Omikron Basic her kennen.
Mit einem Resourceeditor (z.B. ResEdit von Apple) können Sie daran aber auch Änderungen vornehmen oder weitere Cursorformen mit höheren Nummern definieren.


Easy_Alert Defaultbutton,Boxstring$[,R Button]  
Alert_Box darstellen.

Diese Prozedur entspricht dem BASIC-Befehl FORM_ALERT. Möglicherweise wird Easy_Alert in zukünftigen EasyGem Versionen mit verbesserten Eigenschaften (z.B. Titelzeile zum Verschieben) ausgestattet. Wir möchten Ihnen deshalb empfehlen, schon jetzt immer Easy_Alert anstelle von FORM_ALERT zu verwenden.


Easy_Fsel R Fsspec$,R Reply$,Titel$,R Sel
Dateiauswahlbox darstellen.

Der Befehl Easy_Fsel bringt eine Dateiauswahlbox auf den Bildschirm, so wie der BASIC-Befehl FILESELECT. Da auch für diesen Befehl Erweiterungen in zukünftigen EasyGem Versionen zu erwarten sind, sollten Sie statt FILESELECT besser immer gleich Easy_Fsel verwenden.


Die Variablen bedeuten im einzelnen:
Fsspec$ Im Falle von StandardPutFile (Sel=1) kann in Fsspec$ ein Filename übergeben werden, der dann in der Fileselectbox als Defaultname eingetragen wird.
Nach dem Verlassen der Box befindet sich in
Fsspec$ der FileSpecificationRecord der ausgewählten Datei.
Reply$ Im Falle von StandardGetFile (Sel=0) kann in Reply$ eine Filetyp-Liste übergeben werden (z.B. "TEXTPICT"). Dann werden nur die in dieser Liste angegebenen Filetypen überhaupt angezeigt.
Nach der Rückkehr von
Easy_Fsel enthält diese Variable immer den FileReplyRecord, dem Sie zusätzliche Informationen (z.B. den Filetyp), über das ausgewählte File entnehmen können. Siehe auch im Omikron Basic Handbuch das Kapitel über die wichtigsten Datenstrukturen des MacOS.

Achtung: Wenn System 8.5 oder höher installiert ist, wird ein geänderter FileRelpyRecord zurückgeliefert (wie bei Easy_Fnav).
Titel$ Im Falle von StandardPutFile (Sel=1) können Sie in Titel$ eine Überschrift über dem Dateinamen definieren. Bei StandardGetFile (Sel=0) hat diese Variable keine Bedeutung.
Sel Mit dieser Variablen legen Sie zum einen fest, ob Sie eine Datei laden (Sel=0) oder speichern (Sel=1) wollen, zum anderen erhalten Sie Informationen darüber, ob die Fileselectbox mit 'Abbruch' verlassen wurde. Dann ist nämlich Sel=0 und sonst Sel=1.

Wenn Sie System 8.5 oder höher installiert haben, sollten Sie besser die File-Navigation-Services verwenden, da diese erheblich erweiterte Möglichkeiten bieten, um Dateien, Ordner,Volumes oder beliebige Objekte auszuwählen. Es ist damit sogar möglich, mehrere Dateien gleichzeitig zu öffnen. Ausserdem verfügt die dargestellte Fileselectbox standardmässig über einen Schiebebalken und kann über einen Sizer in der rechten unteren Ecke in der Grösse verändert werden. Die File-Navigation-Services merken sich diese Einstellungen individuell für jedes Programm, so dass die Box bei einem erneuten Öffnen gleich wieder in der richtigen Einstellung dargestellt wird. Mit dieser Fileselectbox ist es auch möglich, auf andere Programme umzuschalten, während die Box geöffnet ist.


Ab EasyGem 4.0 können Sie die File-Navigation-Services mit folgendem Befehl ansprechen:


Easy_Fnav R Fsspec$,R Reply$,Prompt$[,Titel$[,X,Y]],R Sel
Neue Dateiauswahlbox darstellen.

Dabei haben die einzelnen Variablen folgende Bedeutung:
Fsspec$ Beim Aufruf kann in diesem String ein FileSpecificationRecord übergeben werden. Damit wird dann festgelegt, welcher Ordnerinhalt beim Öffnen der Box angezeigt wird. Fsspec$="" bewirkt, dass der beim letzten Aufruf mit der gleichen Sel - Nummer verwendete Pfad angezeigt wird. Ist die Pfadinformation in Fsspec$ ungültig, wird der Desktop als Default-Pfad benutzt.

Mit
Easy_Fnav ist es möglich, mehr als eine Datei gleichzeitig auszuwählen (Sel=0 oder Sel=2). Darum enthält Fsspec$ in diesem Fall nach der Rückkehr eine Kette aus FileSpecificationRecords. Dabei ist jeder einzelne FileSpecificationRecord genau 70 Byte lang. Wenn nichts ausgewählt wurde, ist Fsspec$="".
Reply$ Im Falle von Sel=0 oder Sel=2 kann in diesem String eine Filetyp-Liste übergeben werden, mit der Sie festlegen können, welche Dateitypen in der Box angezeigt werden sollen. Z.B. würden bei Reply$="TEXTPICTOBAS" nur Textdateien, Bilder vom Typ 'PICT' und Omikron Basic Token-Code Dateien angezeigt. Wenn Reply$="" ist, werden alle Dateitypen angezeigt.

Hinweis: Über ein Popup-Menü in der Fileselectbox können Sie die Anzeige nach dem Öffnen noch verändern.

Bei
Sel=1 können Sie in Reply$ einen Defaultnamen übergeben, unter dem die Datei gespeichert werden soll. Dieser Name wird in die Easy_Fnav Box eingetragen, kann aber vom Anwender noch geändert werden.

Für die anderen
Easy_Fnav Typen hat der Wert von Reply$ bei der Eingabe keine Bedeutung.

Nach der Rückkehr enthält
Reply$ den FileReplyRecord. Dieser ist bei Easy_Fnav anders aufgebaut als bei Easy_Fsel. Für normale Anwendungen benötigen Sie den FileReplyRecord nicht. Wer trotzdem mehr darüber erfahren möchte, kann die genaue Bedeutung in "Inside Macintosh, Programming with Navigation Services" nachlesen.
Prompt$ Dies ist ein String, der in der Fileselectbox ausgegeben wird.
Titel$ Fenstertitel der Fileselectbox.
X X-Position der linken oberen Ecke der Fileselectbox.
Y Y-Position der linken oberen Ecke der Fileselectbox.
Sel Bei der Eingabe muss in dieser Variablen ein Wert zwische 0 und 6 übergeben werden. Damit wird festgelegt, welcher Boxtyp geöffnet wird. Die einzelnen Werte haben dabei die folgende Bedeutung:

0 : Öffnen einer oder mehrerer Dateien gleichzeitig
1 : Speichern einer Datei
2 : Auswählen einer oder mehrerer Dateien gleichzeitig
3 : Auswählen eines Volumes
4 : Auswählen eines Ordners
5 : Auswählen eines beliebigen Objektes
6 : Anlegen eines neuen Ordners

Nach der Rückkehr enthält die Variable den Wert 0, wenn die Box mit [Abbruch] verlassen wurde, sonst die Anzahl der ausgewählten Objekte.

Bitte beachten Sie auch das Programm "Easy_Fnav.BAS" im DEMO-Ordner. Es zeigt Ihnen, wie die verschiedenen Varianten aufgerufen und nach der Rückkehr die ausgewählten Objekte ermittelt werden können.
Sind die File-Navigation-Services nicht vorhanden, so wird automatisch die alte Fileselectbox dargestellt.

Achtung: Die File-Navigation-Services funktionieren nur dann korrekt, wenn Sie Ihrem Programm eine Signatur geben (COMPILER "Signature XXXX"). Dies gilt auch für Easy_Fsel, wenn System 8.5 oder höher installiert ist, da in diesem Fall Easy_Fsel automatisch auf Easy_Fnav umgeleitet wird.

Da moderne Computer standardmäßig farbige Bildschirmdarstellungen ermöglichen, steht man als Programmierer häufig vor dem Problem, dem Anwender eine einfache Möglichkeit zu bieten, um eine spezielle Farbe (z.B. für einen Text oder den Zeichenstift) auszuwählen. EasyGem bietet mit dem folgenden Befehl die Möglichkeit, eine Dialogbox aufzurufen, die eine einfache Farbauswahl ermöglicht.


Pick_Color X,Y,Prompt$,Color_In,Color_Out,R Button
Farbauswahlbox darstellen.

Die Variablen bedeuten im einzelnen:
X,Y Damit legen Sie fest, wo auf dem Bildschirm die Dialogbox erscheinen soll. X und Y definieren die linke obere Ecke der Dialogbox. Ist X=0 und Y=0, so wird die Dialogbox zentriert dargestellt.
Prompt$ In diesem Parameter können Sie einen Prompt übergeben. Das ist ein kurzer Text, der oben in der Dialogbox dargestellt wird (z.B. "Wählen Sie eine Farbe").
Color_In
Color_Out
In diesen Parametern müssen Farbindizes (eine Zahl zwischen 0 und 255) übergeben werden. Color_In enthält dabei den Index der Eingabefarbe. Der zugehörige Farbton wird in der Dialogbox oben rechts dargestellt. In Color_Out wird die ausgewählte Farbe eingetragen, falls die Box mit 'OK' verlassen wurde, andernfalls wird die Farbe von Color_Out nicht verändert.
Button Diese Variable ist null, wenn Pick_Color mit 'Abbruch' verlassen wurde und sonst ungleich null.


Die Color-Picker Dialogbox ermöglicht es dem Anwender, die Auswahl der gewünschten Farbe in verschiedenen Farbräumen vorzunehmen (z.B. RGB, CYMK, HLS usw.) und stellt damit eine sehr professionelle Möglichkeit der Farbauswahl dar. Bedenken Sie aber bitte, daß abhänging von der eingestellten Farbtiefe nicht jede gewünschte Farbe auch tatsächlich auf dem Bildschirm realisierbar ist.


Besonders bei wissenschaftlichen Anwendungen steht man häufig vor der Aufgabe, einen in einem zweidimensionalen Feld vorliegenden Datensatz (aus Messungen oder Berechnungen) farblich darzustellen, da dadurch die Meßwerte wesentlich besser interpretiert werden können. Diese Aufgabe wird mit der folgenden Prozedur zu einem Kinderspiel.


Display_Data &Dat(,),Dat_W,Dat_S,&Col(),Ix,Iy,Iw,Ih,X,Y,W,H
Datensatz darstellen.

Die Parameter bedeuten im einzelnen:
Dat(,) Dieses Feld muß die gemessenen oder berechneten Werte, die Sie visualisieren möchten, enthalten. Es muß sich dabei um ein Integer-Feld handeln (Byte, Short oder Long), da die Werte ja als Index in einer Farbtabelle interpretiert werden und darum nur ganze Zahlen dafür in Frage kommen.
Für die meisten Anwendungen reichen Byte-Felder völlig aus. Damit sind 256 unterschiedliche Farben möglich. In einigen Spezialfällen kann es aber auch vorteilhaft sein, Short-Integer (bis 32768 Farben) oder Long-Integer (praktisch beliebig viele Farben) zu verwenden. Wenn Ihre Quelldaten in einem Fließkomma-Feld vorliegen, müssen Sie diese vorher in ein Integer-Feld übertragen und dabei so renormieren, daß nur positive Zahlen in einem Intervall vorkommen, für das Sie die Farbtabelle in
Col() definiert haben.
Dat_W Das ist die Breite einer Reihe, also der Wert des ersten Index, auf den Sie das Feld Dat(,) dimensioniert haben, plus eins. Zum Beispiel: DIM Dat(639,399):Dat_W=640
Dat_S Dieser Parameter gibt an, wieviele Bytes ein Feldelement belegt. Bei Byte-Feldern muß hier 1 übergeben werden, bei Short-Integer Feldern 2 und bei Long-Interger Feldern 4.
Col() Dies muß ein Feld vom Typ Long-Integer sein, das die Farben als RGB-Werte enthält. Jedes Feldelement belegt vier Bytes. Das erste Byte ist frei. Bei 256 oder weniger Farben können Sie hier z.B. einen Index eintragen. In dem zweiten Byte befindet sich der Rotanteil, in dem dritten der Grünanteil und in dem vierten der Blauanteil der zu dem entsprechenden Index gehörenden Farbe (jeweils 0 bis $FF).

Wichtig: Für jeden Wert in Dat(,) muß eine Farbe in Col() definiert sein. Col() muß also mindestens auf den größten der in Dat(,) enthaltenen Werte dimensioniert sein und mit sinnvollen Farbwerten gefüllt werden.
Ix,Iy,Iw,Ih Mit diesen vier Parametern bestimmen Sie, welcher Teil des in Dat(,) übergebenen Feldes dargestellt werden soll. Die Werte sind als Feld-Indizes aufzufassen. Wenn sich die Daten z.B. in einer Matrix Dat(639,399) befinden und Sie für Ix=160 und für Iw=320 angeben, so würden die Feldelemente, deren erster Index größer oder gleich 160 und kleiner 480 ist, für die Darstellung verwendet. Entsprechend bestimmen Iy und Ih das Intervall für den zweiten Index.
X,Y,W,H Diese vier Parameter definieren das Zielgebiet auf dem gerade aktiven Bildschirm (Mit Gwin_Activate, Win_Activate oder GRAF_PORT eingestellt). Wenn Iw<>W oder Ih<>H ist, wird das Bild entsprechend verformt, so daß es genau ins Zielgebiet paßt.

Dies ist eine sehr mächtige Prozedur, die Ihnen sehr viel Arbeit abnehmen kann. Bei der Übergabe von falschen Parametern können Sie damit aber auch leicht Ihren ganzen Computer zum Absturz bringen. Achten Sie besonders darauf, daß Dat(,) keine negativen Werte enthält, daß Dat_W und Dat_S korrekt sind und daß Col() ausreichend dimensioniert wurde.
Da die verwendeten Felder meist sehr groß sein müssen, um eine detailreiche Darstellung auf dem Bildschirm zu erzielen, müssen Sie mit
COMPILER "BAS_MEM X" genügend BASIC-Speicher dafür reservieren. Alternativ können Sie auch direkt vom Mac OS Speicher anfordern und dort Ihre Daten wie in einem zweidimensionalen Feld ablegen. Verwenden Sie dafür den Befehl MAC_OS Handle;1,"NewHandle",Size. Diese Funktion gibt das Handle (Pointer auf einen Pointer) des angeforderten Speichers zurück. Dieses Handle können Sie dann anstelle von &Dat(,) der Prozedur Display_Data übergeben. Vergessen Sie aber nicht, den Speicherbereich mit MAC_OS ;1,"HLock",Handle zu sperren, bevor Sie Ihn verwenden. Der Vorteil dieser Methode besteht darin, daß der Speicher nicht aus dem begrenzten BASIC-Memory stammen muß, sondern aus dem Application-Heap oder auch einem beliebigen freien Speicherstück stammen kann. Eine genaue Beschreibung der für diesen Zweck erforderlichen Mac OS Funktionen finden Sie in "Inside Macintosh, Memory".
Eine Verwendungsmöglichkeit für die Prozedur
Display_Data zeigt das Programm EasyFractal.BAS im DEMO-Ordner.


Manchmal ist es vorteilhaft, zwischen verschiedenen Programmen Daten auszutauschen oder ein Programm von einem anderen aus zu beeinflussen. Zum Beispiel könnte der Anwender eine Datei öffnen wollen, die das eigene Programm nicht interpretieren kann. Dann könnte man einfach einem anderen geeigneten Programm die Botschaft schicken, die gewünschte Datei zu öffnen. Diese Kommunikation zwischen verschiedenen Programmen ist nicht leicht zu programmieren, da man dafür recht komplizierte Datenstrukturen benötigt. Wer alle Möglichkeiten ausschöpfen möchte und sich eine C++ ähnliche Programmierung zutraut, sollte mal einen Blick in "Inside Macintosh, Interapplication Communication" werfen. Für alle anderen haben wir in die EasyGem Library einen Befehl eingebaut, mit dem man immerhin andere Programme starten, diesen Dateien zum Öffnen übergeben und die fremden Programme auch wieder beenden kann.

Die Prozedur dafür lautet:


Event_Send Signature,Event_Type,Fsspec$,R Oserr
Event senden.

Dabei haben die einzelnen Variablen folgende Bedeutung:
Signature Die Signatur eines Programms ist eine 32-Bit Zahl, in der normalerweise eine Folge aus 4 Buchstaben codiert ist. Zum Beispiel hat Omikron Basic die Signatur CVIL("OmBa") und der Finder hat CVIL("MACS"). Mit Signature bestimmen Sie also den Empfänger der Botschaft. Das Programm muss bereits laufen, sonst kann es die Meldung ja nicht empfangen.

Hinweis: Wenn Sie erreichen wollen, dass eine Datei von einem anderen Programm geöffnet wird und Sie nicht wissen, ob dieses Programm bereits gestartet wurde, empfiehlt es sich, die Message an den Finder zu schicken (Signature = CVIL("MACS")), da dieser ja auf jeden Fall läuft. Der Finder sucht dann den Creator dieser Datei, startet Ihn gegebenenfalls und veranlasst die Öffnung Ihrer Datei.
Event_Type Mit dem Event-Typ legen Sie fest, was geschehen soll. Dabei gibt es 3 grundlegende Möglichkeiten, die von jedem anderen Programm verstanden werden sollten:

Event_Type =
CVIL("odoc")
: Dokument öffnen.
CVIL("pdoc") : Dokument drucken.
CVIL("quit") : Programm beenden.

Hinweis: Wenn Sie ein anderes Programm nur starten wollen, ohne gleich eine Datei zum Öffnen zu übergeben, können Sie dies mit einem "odoc" Event erreichen, indem Sie das Programmfile selbst als Dokument spezifizieren und die Message an den Finder schicken.
Fsspec$ Mit diesem FileSpecificationRecord wird festgelegt, welche Datei geöffnet bzw. gedruckt werden soll. Sie sollten hier immer einen vollständigen FileSpecificationRecord übergeben, da das Empfängerprogramm nicht wissen kann, in welchem Ordner sich die Datei befindet.
Oserr In dieser Variablen wird eine Fehlernummer zurückgeliefert, wenn die Botschaft nicht verschickt werden konnte. Die häufigsten Fehler sind:

-609 : Signatur existiert nicht.
-903 : Empfanger hat keine 'SIZE' Resource (Diese ist erforderlich, damit ein Programm High-Level-Events empfangen kann). Die 'SIZE' Resource wird vom Omikron Basic Compiler automatisch angelegt.

Eine Beschreibung aller möglichen Fehlermeldungen finden Sie in "Inside Macintosh, Interapplication Communication".

Bitte beachten Sie auch das Programm "Event_Send.BAS" im DEMO-Ordner.
Nach dem Starten dieses Programms öffnet sich eine nichtmodale Dialogbox, die drei Buttons und ein Popup-Menü enthält.
Mit dem obersten Button wählen Sie den Empfänger aus. In der Standardeinstellung ist es der Finder. Wenn Sie diesen Button anklicken, öffnet sich ein Fileselectbox, mit der Sie auch ein beliebiges anderes Programm als Empfänger bestimmen können. Das Programm muss aber bereits gestartet sein, damit es die Botschaft empfangen kann.
Mit dem Popup-Menü können Sie einen von drei Event-Typen auswählen.
Der Button unter dem Popup-Menü funktioniert genauso wie der erste Button. Damit bestimmen Sie das Objekt, das an den Empfänger geschickt werden sollen. In der Standardeinstellung ist hier eine Textdatei "DummyText.TXT" ausgewählt.

Ändern Sie an den Einstellungen erstmal nichts und klicken Sie einfach auf 'Senden'. Dann wird dem Finder mitgeteilt, dass er die Datei "DummyText.TXT" öffnen soll. Da dies eine "SimpleText" Datei ist, startet der Finder zunächst das Programm "SimpleText" und veranlasst dieses dann, die Datei "DummyText.TXT" zu öffnen. Auf dem Bildschirm sollte sich jetzt also ein Fenster mit dem Beispieltext öffnen.

Klicken Sie jetzt auf den oberen Button in der Dialogbox und wählen Sie das Programm "SimpleText" als Empfänger aus. Sie finden das Programm auf der Macintosh HD im Ordner "Apple Extras:SimpleText". Wählen Sie über das Popup-Menü jetzt 'Anwendung beenden' als Eventtyp aus ("quit" Event). Klicken Sie auf 'Senden'. SimpleText erhält jetzt die Botschaft, sich zu beenden.

Warnung: Schicken Sie niemals einen "quit" Event an den Finder. Dann wird dieser nämlich beendet und alle Icons und Finder-Fenster verschwinden vom Desktop. Auch das Finder-Menü ist nicht mehr erreichbar, so dass Sie keine Dateioperationen mehr durchführen können, keine Programme starten usw.. Im schlimmsten Fall müssen Sie Ihren Computer dann neu starten.




Referenzliste Window Library -blättern- Referenzliste Utility Library

Inhalt | Start



© 1998-2000 Berkhan-Software
www.berkhan.de | Online bestellen