3.0 Die Generic Class

Die meisten Objekte in R-BASIC stammen von der GenericClass ab. In diesem Abschnitt finden Sie die Instance-Variablen, die allen diesen Objekten gemeinsam sind.
3.1 Caption: Die Objekt-Beschriftung

3.1.1 Text-Captions

3.1.2 Grafische Captions

3.1.3 Die Caption-Ausrichtung

^

3.1 Caption: Die Objekt-Beschriftung

Unter 'Caption' (engl. caption = Überschrift, Titel) versteht man in R-BASIC die 'Beschriftung' eines Objekts. Das kann ein Text oder eine kleine (!) Grafik sein. Im Primary befindet er sich der Caption-Text in der Titelzeile, bei Buttons ist es die Aufschrift und bei anderen Objekten ist er über oder neben dem Objekt angeordnet um die Funktion oder Bedeutung des Objekts zu beschreiben. Text-Captions weisen Sie mit der Instancevariablen Caption$ zu. Für grafische Captions stehen Ihnen - je nachdem, wo die Grafik herkommt, die Methoden CaptionIcon, CaptionPicture, CaptionImage und CaptionGString zur Verfügung. Mit der Instancevariablen justifyCaption können Sie in vielen Fällen festlegen, wie die Caption relativ zum Objekt positioniert wird.

Variable Syntax im UI-Code Im BASIC-Code
Caption$ Caption$ = "Text" [, n ] lesen, schreiben
CaptionIcon CaptionIcon = "tchr" , manufID [, flags ] nur schreiben
CaptionPicture CaptionPicture = "PictureName" nur schreiben
CaptionImage CaptionImage = [stdPath, ] "File" [, num] nur schreiben
CaptionGS -- nur schreiben
justifyCaption justifyCaption = numWert lesen, schreiben
kbdShortcut kbdShortcut = numWert lesen, schreiben
kbdSearchPath kbdSearchPath = TRUE | FALSE lesen, schreiben

Bitte beachten Sie, dass Captions im gleichen Speicherblock gespeichert werden, wie das Objekt selbst. Speicherblöcke können unter GEOS nicht größer als 64 kByte werden, meistens gibt es schon viel früher Probleme ('Hauptspeicher voll'). Grafische Captions sollten deshalb nicht größer als 4 kByte sein. Bei Text-Captions (Caption$) Captions aus der TokenDatabase (CaptionIcon) und GString-Captions (CaptionGString) ist das im Allgemeinen erfüllt. Normale Grafikbefehle wie Line, Rectangle, FillEllipse usw. erfordern jeweils 10 bis 15 Byte. Texte erfordern pro Zeichen 1 Byte.

Problematisch können Captions sein, die eine Bitmap enthalten und mit zur Laufzeit zugewiesen werden, da dies der Compiler nicht prüfen kann. Bei der Zuweisung im UI-Code führt R-BASIC bei Bitmaps eine Größenkontrolle aus und warnt bei einem Speicherbedarf von mehr als 4 kByte. Captions mit mehr als 12 kByte lassen sich nicht zuweisen.

Der Speicherbedarf einer Bitmap setzt sich aus den Bitmapdaten und einer eventuell vorhandenen Maske (Transparenz) zusammen. Für die Bitmapdaten gilt die Formel 'Breite x Höhe x Farbtiefe (in Bit pro Pixel) / 8'. Für die Maske kommen je Zeile noch 'Breite/8' Bytes hinzu, wobei jeweils auf ganze Bytes aufgerundet (!) werden muss.

Beispiele (jeweils eine Transparenzmaske vorausgesetzt)

Abmessungen (Pixel) Farbtiefe (Bit pro Pixel) Speicherbedarf (Byte)
48 x 30 4 900
32 x 32 8 1152
32 x 32 24 3200
64 x 64 8 4608
128 x 128 8 51200

Falls Sie vorhaben, zur Laufzeit grafische Captions zuzuweisen, die deutlich größer sind als die zur Compilezeit zugewiesenen, sollten Sie der Verteilung der Objekte auf die Objektblöcke Aufmerksamkeit widmen. Details dazu finden Sie im Kapitel 2.1.4 (Beeinflussung der Objektblöcke im UI-Code).

^

3.1.1 Text-Captions

Caption$

Caption$ ist der Text auf oder neben dem Objekt. Im Gegensatz zu den grafischen Captions kann Caption$ auch gelesen werden und es kann ein 'Navigationsbuchstabe' definiert werden, der eine Tastaturnavigation durch die Menüs ermöglicht. 
Syntax UI-Code: Caption$ = "Text" [, n]
        "Text": Aufschrift
             n: Nummer des hervorgehobenen Buchstaben für
                Tastatur-Navigation.
                0 = 1. Buchstabe, 1 = zweiter Buchstabe usw.
         Lesen: <stringVar> = <obj>. Caption$
                Liefert den Text. Der Navigationsbuchstabe
                kann nicht gelesen werden.
     Schreiben: <obj>. Caption$ = "Text" [, n]
Beispiele UI Code: 
Button OKButton
    Caption$ = " OK "   ...
    ActionHandler = ....
    END Object

Button MyButton
    Caption$ = "Press mich!", 0   ...
    ActionHandler = ....
    END Object
Beispiel BASIC-Code: 
DIM c$
    c$ = MyButton.Caption$        
    OKButton.Caption$ = " JA! "    ...
    MyButton.Caption$ = "yes!", 2    ...

^

3.1.2 Grafische Captions

CaptionIcon

Weist dem Objekt ein Token aus der Token-Database als Caption zu. CaptionIcon kann im UI Code und im BASIC Code (Schreiben) verwendet werden. Lesen im BASIC-Code ist nicht möglich. 
Syntax UI-Code: CaptionIcon = "tchr" , manufID [, flags ] 
  Syntax BASIC: <obj>.CaptionIcon = "tchr" , manufID [, flags ] 
        "tchr": Tokenchars des Icons. Genau 4 Zeichen
       manufID: ManufacturerID des Icons. Datentyp WORD
         flags: Icon-Flags. Siehe unten.
Das passende Bild aus der Tokendatabase Datei wird beim Aufruf von CaptionIcon in den Speicherblock des Objekts kopiert.

Gültige Werte für 'flags':

Konstante Wert Bedeutung
TOOL_ICON 1 Tool-Icon (15 x 15 Pixel) verwenden.
TINY_ICON 1 Synonym für TOOL_ICON
SMALL_ICON 2 Kleineres Icon verwenden (oft 32x20 Pixel)
BIG_ICON 4 Größeres Icon verwenden (oft 64x40 Pixel)
GRAY_ICON 8 Schwarz-Weiß Icon verwenden
RGB_ICON 16 True-Color Icon verwenden

Wird keines der Flags angegeben wird das 'Standard'-Icon (meist 48 x 30 Pixel, 16 Farben oder 256 Farben) verwendet.

Hinweise:

  • Ist die entsprechend den Flagbits angeforderte Kombination nicht vorhanden sucht das System ein 'möglichst passendes' Icon aus. Das Flag 'TOOL_ICON' hat dabei Vorrang vor allen anderen Flags.

  • Sollte zum gegebenen Token ('TCHR', manufID) kein grafisches Icon vorhanden sein wird ein Text verwendet.

  • Findet sich das Token nicht in der TokenDB zeigt R-BASIC ein Ersatzbild ('unbekanntes Icon'). R-BASIC Icons enthalten nur zwei Bilder: ein Standard- und ein Tool-Icon.
Beispiel: Das GeoWrite-Datei-Icon 'WDAT, 0' enthält Normal, Small und Big Icons. 
Button Button1
    CaptionIcon = "WDAT", 0, TOOL_ICON
End OBJECT

Button Button2
    CaptionIcon = "WDAT", 0, SMALL_ICON
End OBJECT
...
Button Button3
    CaptionIcon = "WDAT", 0
End OBJECT

Button Button4
    CaptionIcon = "WDAT", 0, BIG_ICON
End OBJECT

CaptionPicture

CaptionPicture weist einem Objekt eine grafische 'Aufschrift' zu. Die Grafik steht in der Picture-List des Programms (oder der Library). Die Picture-List enthält Grafiken, die über ihren Namen angesprochen werden und in der Code-Datei selbst gespeichert sind. Sie kann über das Menü 'Extras' -> 'Picture-List' verwaltet werden. Details dazu finden Sie im Kapitel 2.8.6.2 (Verwendung der Picture-List) des R-BASIC Programmierhandbuchs. 
Syntax UI-Code: CaptionPicture = "PictureName"
  Syntax BASIC: <obj>.CaptionPicture = "PictureName"
 "PictureName": Name der Grafik in der Picture-List
Das Bild wird beim Aufruf von CaptionPicture in den Speicherblock des Objekts kopiert. Beachten Sie den Hinweis am Anfang des Kapitels 3.1. Zu große Caption-Bilder können zum Systemabsturz führen!

Hinweise:

  • Wird CaptionPicture im BASIC-Code gerufen setzt es die globale Variable fileError - entweder auf Null (das Bild wurde gefunden) oder auf einen Fehlerwert (das Bild wurde nicht gefunden).

  • Wenn CaptionPicture im Code einer Library gerufen wird bezieht sich der Name des Bildes auf die Picture-List der Library. Das ermöglicht es unter anderem Bilder in die Picture-List von Libraries auszulagern.

Beispiel: In der Picture-List befinden sich zwei kleine Bilder mit dem Namen 'Radioactive' und 'Formel'. Die Grafik "Formel" wurde mit GeoDraw erstellt und dann über die Zwischenablage in die Picture-List aufgenommen. 

Button MyButton
    CaptionPicture = "Radioactive"    
End OBJECT
Die Zuweisung der zweiten Grafik kann z.B. im Basic Code erfolgen. 
    MyButton.CaptionPicture = "Formel"

CaptionImage

CaptionImage weist einem Objekt eine grafische 'Aufschrift' zu die aus einer externen Datei gelesen wird. Sollte die Datei mehr als ein Bild enthalten (z.B. *.GIF, *.ICO) können Sie mit dem Parameter pictNum bestimmen, welches Bild ausgelesen wird. Das erste Bild hat immer die Nummer Null. 
Syntax UI-Code: CaptionImage = [stdPath, ] "Path+File" [, pictNum]
  Syntax BASIC: <obj>.CaptionImage = [stdPath, ] "Path+File" [,pictNum]
       stdPath: Optional: Standardpfad Konstante, z.B. SP_TOP
   "Path+File": Dateiname, Pfade sind zulässig
       pictNum: Optional: Nummer des Bildes in der Datei


CaptionImage öffnet und schließt die Datei automatisch. Das Bild wird in den Speicherblock des Objekts kopiert. Beachten Sie den Hinweis am Anfang des Kapitels 3.1. Zu große Caption-Bilder können zum Systemabsturz führen!

Folgende Dateiformate werden unterstützt: JPG, BMP, ICO, PCX, GIF, TGA, RLE, DIB, SCR , FLC, FLI und GEOS Hintergrunddateien.

Wird CaptionImage im UI-Code verwendet so gilt:

  • Wird kein Standardpfad angegeben wird die Datei im Ordner 'USERDATA\R-BASIC\IMAGES' gesucht.

  • Das Bild wird in die Code-Datei kopiert, d.h. die externe Datei muss nicht in das R-App Paket aufgenommen werden.
Wird CaptionImage im BASIC-Code verwendet so gilt:
  • Wird kein Standardpfad angegeben wird die Datei im aktuellen Verzeichnis gesucht.

  • Die externe Datei wird zur Laufzeit geöffnet, d.h. sie muss unbedingt in das R-App Paket aufgenommen werden oder es muss auf andere Weise sichergestellt sein, dass sie existiert.

  • Wird pictNum nicht angegeben so wird immer das erste Bild ausgelesen.

  • Die globale Variable fileError wird gesetzt - entweder auf Null (das Bild wurde gefunden) oder auf einen Fehlerwert (die Datei wurde nicht gefunden oder sie enthält kein Bild).
Beispiel: Das PC/GEOS Icon "GWICON5.ICO" verwenden, dass sich im PC/GEOS Hauptverzeichnis befindet. 
Button MyButton
    CaptionImage = SP_TOP, "GWICON5.ICO"    
End OBJECT

CaptionGString

CaptionGString weist dem Objekt eine grafische Caption zu, die vorher in einen GString geschrieben wurde. Die Verwendung von CaptionGString ist eine der Möglichkeiten für ein Objekt (häufig ein Button oder eine Group) zur Laufzeit die grafische Caption zu ändern. CaptionGString wird verwendet, wenn die Grafik nicht als vordefiniertes Bild vorliegt, sondern zur Laufzeit des Programms gezeichnet werden muss (oder kann). Eine komplette Beschreibung der Arbeit mit GStrings finden Sie im Kapitel 2.8.5 (Arbeit mit Graphic Strings) des R-BASIC Programmierhandbuchs. 
Syntax BASIC: <obj>.CaptionGString = <gsHandle> 
              <gsHandle>: Handle auf einen Graphic String.
Der GString wird beim Aufruf von CaptionGString in den Speicherblock des Objekts kopiert. Daher sollten Sie nicht vergessen den GString nach Verwendung wieder freizugeben. Beachten Sie den Hinweis am Anfang des Kapitels 3.1. Zu große Caption-Bilder können zum Systemabsturz führen!

Beispiel: 

SUB SetNewCaption ( )
DIM gsHan AS HANDLE

    gsHan = StartRecordGS ( )
    FillEllipse 0, 0, 32, 32, LIGHT_RED  ' Farbig
    Ellipse 0, 0, 32, 32                 ' Schwarz
    FillRect 9, 8, 24, 24, YELLOW
    EndRecordGS gsHan
    MyObj.CaptionGString = gsHan    

    FreeGS gsHan                         ' Nicht vergessen!
End SUB

^

3.1.3 Die Caption-Ausrichtung

justifyCaption

Die Instance-Variable justifyCaption bestimmt, wo bzw. wie die Beschriftung (Caption~) des Objekts angeordnet wird. Die folgende Tabelle enthält die zulässigen Werte. Häufig verwendet wird die Kombination J_TOP + J_CENTER, bei Buttons auch J_CENTER alleine.

Konstante Wert Bedeutung
J_CENTER 1 Caption zentrieren
J_LEFT 2 Caption nach links
J_RIGHT 4 Caption nach rechts
J_TOP 8 Caption nach oben

Wird justifyCaption nicht gesetzt, ist es dem Objekt überlassen, wo die Beschriftung angeordnet wird. In vielen Fällen entspricht dies J_LEFT. Einige Objekte akzeptieren nicht jeden Wert, da justifyCaption als Hint implementiert ist; z.B. ignorieren Buttons alles außer J_CENTER. Hier hilft nur ausprobieren.

Beachten Sie, dass nur die in der Tabelle oben aufgeführten Konstanten für justifyCaption akzeptiert werden. Andere J_-Konstanten, die z.B. für justifyChildren (siehe Kapitel Geometriemanagement) definiert sind, werden ignoriert.

Beispiel 

View MyView
    Caption$ = "Vorschau"
    justifyCaption = J_TOP + J_CENTER    ' Mittig über dem Objekt
    < .. weitere instances .. >
    END Object

^

Weiter...