4.7 Number

4.7.1 Grundlegende Eigenschaften
4.7.2 Display-Format
4.7.3 Angepasstes Aussehen und Sliders
4.7.4 Weitere Hinweise zur Arbeit mit Number-Objekten
4.7.5 Number-Objekte im Delayed Mode

Objekte der Klasse Number (engl.: Zahl) dienen dazu, Zahlen darzustellen oder einzugeben. Obwohl sie sehr einfach zu verwenden sind, verfügen Sie über einen hohen Grad an "Eigenintelligenz".

Die folgenden Ausführungen gehen zunächst grundsätzlich davon aus, dass das Number-Objekt im normalen Modus (nicht im sogenannten "Delayed Mode") arbeitet. Das ist der Normalfall, wenn man nicht spezielle Hints setzt, um in den Delayed Mode zu kommen. Dieser "Delayed Mode" ist ausführlich im Kapitel 3.4.2 (Delayed Mode und Status-Message) dieses Handbuchs beschrieben.

Abstammung:

Spezielle Instance-Variablen:

Variable Syntax im UI-Code Im BASIC-Code

value value = numWert lesen, schreiben

minVal minVal = numWert lesen, schreiben

maxVal maxVal = numWert lesen, schreiben

incVal incVal = numWert lesen, schreiben

ApplyHandler ApplyHandler = <Handler> nur schreiben

StatusHandler StatusHandler = <Handler> nur schreiben

modified modified modified = TRUE | FALSE lesen, schreiben

NavigateToNextFieldOnReturn NavigateToNextFieldOnReturn --

displayFormat displayFormat = numWert lesen, schreiben

decimal decimal = numWert lesen, schreiben

look look = numWert lesen, schreiben

sliderShowIntervals sliderShowIntervals = main [, sub ] lesen, schreiben

SliderNoDigitalDisplay SliderNoDigitalDisplay --

SliderShowMinMax SliderShowMinMax --

Methoden:

Methode Aufgabe

Increment value-Wert um incVal erhöhen

Decrement value-Wert um incVal verringern

Apply Apply-Handler aufrufen

SendStatus Status-Handler aufrufen

Action-Handler-Typen:

Handler-Typ Parameter

NumberAction (sender as object, value as real)

^

4.7.1 Grundlegende Eigenschaften

R-BASIC Number-Objekte speichern eine Zahl im Wertebereich von -32768 ... +32767 mit einer Genauigkeit von 4 Stellen nach dem Komma. Das gilt für die Instance-Variablen value, minVal, maxVal und incVal. Um Kommastellen darstellen zu können muss die Instance-Variable displayFormat auf einen passenden Wert gesetzt werden (siehe Kapitel 4.7.2), per Default werden ganze Zahlen dargestellt.

Der Zahlenwert

value	value = numWert	lesen, schreiben
minVal	minVal = numWert	lesen, schreiben
maxVal	maxVal = numWert	lesen, schreiben
incVal	incVal = numWert	lesen, schreiben

value

Die Instance-Variable value enthält die vom Number-Objekt dargestellte Zahl. Sie sollten den Wert auf die notwendige Anzahl von Stellen runden (R-BASIC Befehl ROUND), wenn Sie ihn vom Number-Objekt lesen, da ein Number-Objekt eine begrenzte Genauigkeit in der internen Zahlendarstellung aufweist.

Syntax UI-Code: value = numWert
         Lesen: <numVar> = <obj>.value   
     Schreiben: <obj>.value = numWert

minVal

Die Instance-Variable minVal enthält den unteren Grenzwert für die Instance-Variable value. Das Number-Objekt sorgt selbständig dafür, dass dieser Grenzwert nicht unterschritten wird. Der Defaultwert für minVal beträgt 0.

Syntax UI-Code: minVal = numWert
         Lesen: <numVar> = <obj>.minVal
     Schreiben: <obj>.minVal = numWert

maxVal

Die Instance-Variable maxVal enthält den oberen Grenzwert für die Instance-Variable value. Das Number-Objekt sorgt selbständig dafür, dass dieser Grenzwert nicht überschritten wird. Der Defaultwert für maxVal beträgt 32766.

Syntax UI-Code: maxVal = numWert
         Lesen: <numVar> = <obj>.maxVal
     Schreiben: <obj>.maxVal = numWert

incVal

Die Instance-Variable incVal enthält den Wert, um den die Instance-Variable value erhöht bzw. erniedrigt wird, wenn man auf einen der Pfeile neben dem Zahlenwert klickt. Der Defaultwert für incVal beträgt 1.

Syntax UI-Code: incVal = numWert
         Lesen: <numVar> = <obj>.incVal
     Schreiben: <obj>.incVal = numWert

Anwenden der Änderungen

ApplyHandler ApplyHandler = <Handler> nur schreiben

modified modified = TRUE | FALSE lesen, schreiben

NavigateToNextFieldOnReturn NavigateToNextFieldOnReturn --

ApplyHandler

Die Instance-Variable ApplyHandler enthält den Namen des ActionHandlers, der aufgerufen wird, wenn das Number-Objekt seinen Wert "anwenden" will (engl. to apply: Anwenden). Dieser muss als NumberAction vereinbart sein. Der Apply-Handler wird üblicherweise aufgerufen, wenn der Nutzer auf die Pfeile des Number-Objekts klickt, nach Eingabe eines Wertes auf "Enter" drückt oder einen Slider "zieht". Sliders werden im Kapitel 4.7.3 besprochen.

Der Wert für den ApplyHandler wird üblicherweise im UI-Code gesetzt. Bei Bedarf kann er auch zur Laufzeit (im BASIC-Code) gesetzt, aber nicht gelesen werden.

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

Beispiel: Ein typisches Number-Objekt

Number testNumber
  Caption$ = "Value = "
  ApplyHandler = numberApply
  incVal = 5
  value = 280
  minVal = -105
  maxVal = 300
  END Object

BASIC-Code des Apply-Handlers:

NumberAction numberApply
  Print ROUND(value)
  END Action

Beachten Sie die Verwendung der R-BASIC Funktion ROUND( ), um sicherzustellen, dass der ausgegeben Wert ganzzahlig ist. Auch wenn das Number-Objekt eine Ganze Zahl darstellt kann es trotzdem intern eine Zahl mit Nachkommastellen gespeichert haben.

Hinweis: Es ist möglich den ApplyHandler des Number-Objekts manuell (vom BASIC-Code aus) zu aktivieren. Dazu wird die von der GenericClass geerbte Methode Apply verwendet. Da ApplyHandler nur ausgelöst werden, wenn das Objekt "modified" ist, muss es vorher als "modified" markiert werden. Alternativ könnte man dem Objekt auch den Hint ApplyEvenIfNotModified geben.

Beispiel:

 testNumber.modified = TRUE
 testNumber.Apply

Eine ausführliche Beschreibung dazu finden Sie im Kapitel 3.4 (Die "Apply"-Message) dieses Handbuchs.

modified

Die Instance-Variable modified enthält die Information, ob der vom Number-Objekt dargestellte Wert seit dem letzten Aufruf des Apply-Handlers geändert wurde (modified = TRUE) oder nicht (modified = FALSE).

Beachten Sie, dass ein Verändern des Objekts vom BASIC-Code aus (z.B. Belegen der Instance-Variable value), das Objekt nicht als "modified" markiert, d.h. der Wert der Instance-Variablen modified wird nicht verändert. Sie können dies bei Bedarf selbst machen, indem Sie die Anweisung "<obj>.modified = TRUE" verwenden.

Syntax UI-Code: modified = TRUE | FALSE
         Lesen: <numVar> = <obj>.modified
     Schreiben: <obj>.modified = TRUE | FALSE

Wenn Sie die Instance Variable modified lesen, werden Sie feststellen, dass sie Null enthält, es sei denn, Sie haben sie explizit auf einen anderen Wert gesetzt. Ändert der Nutzer nämlich den Zahlenwert, so passiert intern folgendes:

Die Instance-Variable modified wird mit TRUE belegt.
Es wird geprüft ob ein ApplyHandler vorhanden ist und dieser wird ggf. aufgerufen.
Die Instance-Variable modified wird zurückgesetzt (mit FALSE belegt).

Hinweis: Im sogenannten Delayed Mode (siehe entsprechendes Kapitel weiter unten) werden die letzten beiden Schritte nicht ausgeführt, so dass die Instance-Variable modified eine eigene Bedeutung erhält.

NavigateToNextFieldOnReturn

Drückt der Nutzer in Eingabefeld eines Number-Objekts die Enter-Taste bleibt der Cursor üblicherweise dort stehen. Der Hint NavigateToNextFieldOnReturn bewirkt, dass der Cursor stattdessen zum nächsten Eingabefeld weiterrückt.

Syntax UI-Code: NavigateToNextFieldOnReturn

Methoden

Increment value-Wert um incVal erhöhen

Decrement value-Wert um incVal verringern

Increment

Die Methode Increment bewirkt, dass der Instance-Wert value um incVal erhöht wird, genau so, als ob der Nutzer auf den entsprechenden Pfeil des Number-Objekts geklickt hat.

Syntax BASIC-Code: <obj>.Increment

Decrement

Die Methode Decrement bewirkt, dass der Instance-Wert value um incVal vermindert wird, genau so, als ob der Nutzer auf den entsprechenden Pfeil des Number-Objekts geklickt hat.

Syntax BASIC-Code: <obj>.Decrement

^

4.7.2 Display-Format

displayFormat displayFormat = numWert lesen, schreiben

decimal decimal = numWert lesen, schreiben

Grundsätzlich gilt: Number-Objekte speichern Zahlen im Wertebereich von -32768 ... +32767 mit einer Genauigkeit von 4 Stellen nach dem Komma. Diese Zahl kann aber von einem Number-Objekt auf verschieden Weise dargestellt werden. Das wird über die Instance-Variablen displayFormat und decimal gesteuert.

decimal

Die Instance-Variable decimal stellt die Anzahl der angezeigten Nachkommastellen ein. Voraussetzung ist, dass das mit displayFormat eingestellte Anzeigeformat auch Nachkommastellen zulässt. Das ist bei allen Formaten außer DF_INTEGER der Fall. Der Default-Wert für decimal ist 3, der Maximalwert ist 4.

Syntax UI-Code: decimal = numWert
         Lesen: <numVar> = <obj>.decimal
     Schreiben: <obj>.decimal = numWert

displayFormat

Die Instance-Variable displayFormat stellt ein, auf welche Weise die vom Number-Objekt gespeicherte Zahl dargestellt wird. Der Default-Wert für displayFormat ist DF_INTEGER.

Syntax UI-Code: displayFormat = numWert
         Lesen: <numVar> = <obj>.displayFormat 
     Schreiben: <obj>.displayFormat = numWert

Das Number-Objekt rechnet dabei den internen Wert in die das gewünschte Format um. Intern geht das Number-Objekt davon aus, das der intern gespeicherte Wert in US-Points vorliegt. Es stehen die folgenden Formate zur Verfügung:

Konstante Wert Darstellung (Beispiele)

DF_INTEGER 0 Ganzzahlig, z.B. 12

DF_DECIMAL 1 Mit Dezimalstellen, z.B. 28,6

DF_POINTS 2 US-Point 720 Pt

DF_INCHES 3 Inches 18,9 in

DF_CENTIMETERS 4 Zentimeter 12,3 cm

DF_MILLIMETERS 5 Millimeter 534 mm

DF_PICAS 6 Picas 60 pt

DF_EUR_POINTS 7 Europäische Points 98 ep

DF_CICEROS 8 Ciceros 78,9 ci

DF_POINTS_OR_MILLIMETERS 9 72 Pt oder 25,4 mm

DF_INCHES_OR_CENTIMETERS 10 1,5 in oder 3,81 cm

Anmerkungen zu einigen der Konstanten

DF_INTEGER: Der Wert wird ganzzahlig ohne Einheit dargestellt. Ist intern ein nicht ganzzahliger Wert gespeichert, so wird der dargestellte Wert gerundet.
DF_DECIMAL: Der Wert wird zur Darstellung auf den durch die Instance-Variable decimal vorgegebene Genauigkeit gerundet.
DF_POINTS_OR_MILLIMETERS, DF_INCHES_OR_CENTIMETERS: Auf Systemen, deren lokalen Einstellungen auf "US-Einheiten" basieren, wird der Wert in Points oder Inches dargestellt, sind die Einheiten auf "Metrisch" gestellt, erfolgt die Darstellung in mm bzw. cm.

Beachten Sie, dass mit displayFormat wirklich nur das Anzeige-Format geändert und der Wert zur Anzeige umgerechnet wird. Das bedeutet konkret, dass der in der Instance-Variablen value gespeicherte Wert bei den meisten Formaten nicht mit dem Zahlenwert in der Anzeige identisch ist. Wie oben schon erwähnt geht das Number-Objekt davon aus, das der intern gespeicherte Wert in US-Points vorliegt.

Dabei gelten die folgenden Umrechnungen:

Hinweis Bernd: Das "fast gleich"-Zeichen ließ sich im GEOS-Browser nicht darstellen, daher stattdessen in der Tabelle die Kombi aus Gleichheitszeichen und Sternchen =*

Konstante Definition Umrechnung zu US-Point (Pt)

DF_INTEGER keine Umrechnung nötig

DF_DECIMAL keine Umrechnung nötig

DF_POINTS keine Umrechnung nötig

DF_INCHES 1 in = 72 Pt 1 Pt = 1/72 in

DF_CENTIMETERS 1 in = 2.54 cm 1 cm =* 28.246 Pt 1 Pt =* 0.03278 cm

DF_MILLIMETERS 10 mm = 1 cm 1 mm =* 2.8246 Pt 1 Pt =* 0.3278 mm

DF_PICAS 1 pt = 1/6 in 1 pt = 12 Pt 1 Pt = 1/12 pt

DF_EUR_POINTS 1 ep =* 1.0656 Pt 1 Pt = 0.93844 ep

DF_CICEROS 1 ci = 12 ep 1 ci = 12 ep 1 ci =* 12,7872 Pt 1 Pt =* 0,078203 ci

Beispiel: value steht auf 72 (Pt), das sind 2,54 cm

Number testnumber
  Caption$ = "Abstand = "
  displayFormat = DF_CENTIMETERS 
  value = 72
  incVal = 36
  maxVal = 3000
  END Object

Beachten Sie, dass beim Lesen der Instance-Variable value natürlich der dort gespeicherte Wert gelesen wird. Im Beispiel ist das 72, und nicht etwa 2,54!

^

4.7.3 Angepasstes Aussehen und Sliders

Variable Syntax im UI-Code Im BASIC-Code

look look = numWert lesen, schreiben

sliderShowIntervals sliderShowIntervals = main [, sub ] lesen, schreiben

SliderNoDigitalDisplay SliderNoDigitalDisplay --

SliderShowMinMax SliderShowMinMax --

look

Das Aussehen eine Number-Objekts kann mit der Instance-Variable look angepasst werden (engl. look : Aussehen, äußere Erscheinung).

Syntax UI-Code: look = numWert
         Lesen: <numVar> = <obj>.look 
     Schreiben: <obj>.look = numWert

Dabei stehen die folgenden Werte zur Verfügung:

Konstante Wert Aussehen

LOOK_NORMAL 0 komplett "normal"

LOOK_NOT_DIGITALLY_EDITABLE 1 Eingabefeld read-only

LOOK_NOT_INCREMENTABLE 2 keine Pfeile

LOOK_X_SLIDER 3 Schieberegler, horizontal

LOOK_Y_SLIDER 4 Schieberegler, vertikal

LOOK_NORMAL

LOOK_NOT_DIGITALLY_EDITABLE

LOOK_NOT_INCREMENTABLE

LOOK_X_SLIDER

LOOK_Y_SLIDER

Für Sliders gibt es weitere Möglichkeiten, das Aussehen anzupassen. Sie sollten die folgenden Hints nur anwenden, wenn die Instance-Variable look auf einen der SLIDER-Werte gesetzt ist.

sliderShowIntervals

Dieser Hint versieht den Slider mit Intervall-Marken. Sie können angeben, wie viele Hauptintervalle gezeichnet und ob diese noch unterteilt werden sollen.

Syntax UI-Code: sliderShowIntervals = main [ , sub ]
         Lesen: <numVar> = <obj>.sliderShowIntervals ( n )
                n = 0: main-Wert lesen
                n = 1: sub-Wert lesen
     Schreiben: <obj>.sliderShowIntervals = main [ , sub ]
               <obj>.sliderShowIntervals = 0 löscht den Hint aus den Instance-Daten, d.h. die Intervalle werden entfernt.

Der Parameter main gibt die Anzahl der Hauptintervalle an. Der Parameter sub ist optional und legt fest, in wie viele Unterintervalle die Hauptintervalle zu unterteilen sind. Die Sub-Intervallstriche sind etwas kürzer als die der Hauptintervalle. Die Einteilung in Intervalle erfolgt völlig unabhängig vom dargestellten Zahlenbereich. Beispiel: siehe unten

SliderNoDigitalDisplay

Dieser Hint entfernt den Zahlenwert, der üblicherweise über bzw. neben dem Slider erscheint.

Syntax UI-Code: SliderNoDigitalDisplay

Beispiel: siehe unten

SliderShowMinMax

Dieser Hint fügt die Anzeige des Minimal- und Maximal-Wertes (minVal und maxVal) zum Slider hinzu. Die Werte werden in dem durch die Instance-Variable displayFormat spezifizierten Format angezeigt.

Syntax UI-Code: SliderShowMinMax

Beispiel: Ein Slider mit 4 Intervallen, die in je 2 Unterintervalle geteilt sind. Die Anzeige des aktuellen Digitalwertes ist deaktiviert, die Anzeige des Minimum- und Maximum-Wertes ist aktiviert.

Number QualitySlider
  Caption$ = "Quality:"
  justifyCaption = J_TOP
  ApplyHandler = numberApply
  value = 30
  incVal = 10
  minVal = 0
  maxVal = 100
  look = LOOK_X_SLIDER 
  sliderShowIntervals = 4, 2
  SliderNoDigitalDisplay
  SliderShowMinMax
  END Object

Beachten Sie, dass Number-Objekte von der GenericClass abstammen und daher alle Eigenschaften und Fähigkeiten dieser Klasse erben. Insbesondere gilt das für die Geometrie-Hints sowie die Möglichkeit sie auf "enabled = FALSE" oder "readOnly = TRUE" zu setzen.

Die Bilder zeigen "readOnly = TRUE" Objekte, links einen Slider mit dem Hint SliderNoDigitalDisplay gesetzt und rechts ein "normales" Objekt.

^

4.7.4 Weitere Hinweise zur Arbeit mit Number-Objekten

Die Instance-Variablen value, minVal, maxVal und incVal sind aus der Sicht von R-BASIC vom Datentyp REAL. Intern verwenden Number-Objekte zur Speicherung der Werte den Datentyp WWFixed. Er besteht aus einem Integer-Wert (Wertebereich von -32768 bis +32767) für den ganzzahligen Teil und einem WORD für den gebrochenen Teil.
Daraus ergeben sich die folgenden Einschränkungen:
- Die Werte für value, minVal, maxVal und incVal können in einem Bereich von -32768 bis +32767 liegen.
- Die Genauigkeit ist auf 4 Stellen nach dem Komma begrenzt.
- Es muss "minVal - incVal >= -32768" und "minVal + incVal <= 32767" gelten.
Setzen Sie den Wert für value zur Laufzeit, prüft das Number-Objekt, ob er im Bereich von minVal bis maxVal liegt. Ist das nicht der Fall, so passt das Number-Objekt den Wert ohne Warnmeldung an. Fehlerhafte Werte für minVal bzw. maxVal werden auf den größtmöglichen bzw. kleinstmöglichen Wert gesetzt.
Das Number-Objekt rundet den internen Wert auf die zur Anzeige notwendige Stellenzahl. Sie daher sollten den value-Wert auch auf die notwendige Anzahl von Stellen runden (R-BASIC Befehl ROUND), wenn Sie ihn vom Number-Objekt lesen oder einen Number-Action-Handler programmieren. Wegen der begrenzten Genauigkeit in der internen Zahlendarstellung weicht der intern dargestellte Wert oft geringfügig vom angezeigten Wert ab.
Die Geometrie-Hints ExpandWidth, ExpandHeight, DivideWidthEqually und DivideHeightEqually werden nur in den ~_SLIDER - Looks unterstützt. Bei Bedarf packen Sie das Number-Objekt (mit den anderen Looks) in eine Group, die die entsprechenden Hints gesetzt hat.

Interne Details

Der von Number-Objekten zur Speicherung von Zahlen verwendete Datentyp WWFixed wird im GEOS System sehr häufig, unter anderem für alle grafischen Berechnungen, verwendet. Das liegt daran, dass sie einen sehr guten Kompromiss aus guter Genauigkeit (Nachkommastellen) und sehr hoher Rechengeschwindigkeit ermöglicht. Die oben genannte Begrenzung des Wertebereichs ergibt sich aus der Verwendung eine Integer-Wertes für den ganzzahligen Teil. Der Nachkommateil kann als Anzahl der 1/65536 interpretiert werden, die auf den ganzzahligen Teil zu addieren ist. Da 1/65536 _ 0,000015 ist, kann der Nachkommawert nur in dieser Abstufung geändert werden. Eine Genauigkeit von 5 Nachkommastellen ist damit nicht mehr erreichbar. Selbst 4 Stellen sind mit Vorsicht zu genießen, da 0,0001 intern bereits als 7/65536 dargestellt werden muss, was aber eigentlich 0,0001068 ist. R-BASIC begrenzt den Wert für decimal daher auf 4.

Die Bedingungen "minVal - incVal >= -32768" und "minVal + incVal <= 32767" haben folgenden Grund: Erhöht oder Erniedrigt das Number-Objekt seinen value-Wert um den durch incVal gegebenen Wert (klicken Sie z.B. auf den Hoch- bzw. Runter-Pfeil), so nutzt es dazu Ganzzahl-Arithmetik. Daher kann es zu einer Wertebereichsüberschreitung (Übertrag) kommen, die vom GEOS-System aus Performance-Gründen nicht behandelt wird. R-BASIC beachtet diese Bedingungen beim Compilieren des UI-Codes, aber - ebenfalls aus Performance-Gründen - nicht zur Laufzeit. Sie können daher gegen diese beiden Bedingungen verstoßen, wenn Sie die Instance-Variablen zur Laufzeit setzen. Sie werden schon sehen, was Sie davon haben.

Wenn Sie eine höhere Genauigkeit wünschen oder den Integer-Wertebereich verlassen müssen, können Sie zur Eingabe einer Zahl einer der Befehle INPUT oder InputBox oder ein Text-Objekt (z.B. Memo oder InputLine) und ggf. die BASIC-Funktionen VAL, ValLocal bzw. Str$ verwenden.

^

4.7.5 Number-Objekte im Delayed Mode

Ein Number-Objekt kann im "Delayed Mode" (engl.: verzögerter Modus) arbeiten. Dazu muss man dem Objekt selbst bzw. einem seiner Parents im UI-Code den Hint MakeDelayedApply geben oder man bindet das Objekt als Child in einem Dialog ein, dessen dialogType Instance Variable auf DT_DELAYED_APPLY gesetzt ist. Dieser "Delayed Mode" ist ausführlich im Kapitel 3.4.2 (Delayed Mode und Status-Message) dieses Handbuchs beschrieben, eine Beschreibung des Dialog-Objekts im Delayed Mode finden Sie im Kapitel 4.6.6.5.

Instance Variable Syntax im UI-Code Im BASIC-Code

StatusHandler StatusHandler = <Handler> nur schreiben

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

Der StatusHandler wird im Delayed Mode statt des ApplyHandlers gerufen, wenn der Nutzer auf die Pfeile des Number-Objekt klickt, nach Eingabe eines Wertes auf "Enter" drückt oder einen Slider "zieht". Der ApplyHandler hingegen wird erst auf Anforderung gerufen (siehe Kapitel 3.4.2).

Die Instance-Variable modified kann TRUE enthalten, nämlich dann, wenn das Objekt vom User modifiziert wurde, der ApplyHandler aber noch nicht gerufen wurde. Der Aufruf des ApplyHandlers setzt auch im Delayed Mode den modified-Status zurück.

Methode Aufgabe

SendStatus Status-Handler aufrufen

Syntax BASIC-Code: <obj>.SendStatus

Die Methode SendStatus fordert das Objekt auf, seinen StatusHandler aufzurufen (d.h. seine Status-Message zu senden).

^

Weiter...