GAMBAS BOOK 3.18.2

If you want to interactively read in an integer from an interval[min… max] in a program, you can use the SpinBox component, whose most important properties and its use are described in this chapter.

The Spinbox is a text field with two small keys (up/down), which can be used to increase or decrease the current value with a freely selectable step size in the interval[min… max]. You can also enter an integer value directly into the spinbox. To accept this value, you must press the Enter key. You can only enter integers because all other entries are not accepted without a response. You can assign a defined start value to each spinbox. Since all values in a spinbox are of the integer type, you may have to convert these values for your program, for example, if you want to map the interval from [3… 10] to the interval [0,0… 3,5].

If the maximum or minimum value has been reached, this can be recognized at runtime by the Spinbox's appearance, because one of the up/down keys is grayed out. The SpinBox has a repeat function for the up/down keys.

You can add a context menu (PopupMenu) to the component SpinBox which replaces the standard context menu of the spinbox. The menu has to be declared beforehand - for example in the menu editor - so that you can select the corresponding menu in the properties window and assign it to the SpinBox. Alternatively, you can also make the assignment at runtime. Detailed information on this path can be found in chapter 13.4' Context menu'.

You can assign the following values (data type integer) for selected properties of a spinbox at the program start, otherwise the default values are set:

• Minimum value → standard = 0
• Maximum value → standard = 100
• Step size → standard = 1
• Start value → standard = 0

In the following example, a spinbox is used to set the zoom factor for the image of a function f (x). The zoom factor can be changed in a range of [20%… 300%]. The step size is set to 5(%) and the zoom start value is set to 50(%).

Figure 16.12.1: Function plotter with zoom function

The source code is only specified in those parts that demonstrate the conversion of the above-mentioned concept for a zoom function:

Public Sub Form_Open()
  FMain.Center
  FMain.Resizable = False
  …
  spinboxZoom.MinValue = 20 ' 4 starting values
  spinboxZoom.MaxValue = 300
  spinboxZoom.Step = 5
  spinboxZoom.Value = 50
  fZoom = spinboxZoom.Value ' Initialize the zoom
  spinboxZoom.Tooltip = "Zoom-Bereich 20...300"
' mnu0Einstellungen.Visible = False ' optional
' spinboxZoom.PopupMenu = "mnu0Einstellungen" ' optionaly
  spinboxZoom.SetFocus
  …
End ' Form_Open
 
Public Sub spinboxZoom_Change()
 
  fZoom = spinboxZoom.Value
  KS_RP_G_Zeichnen(fZoom)
 
End ' spinboxZoom_Change()

The procedure spinboxZoom_Change() of the spinboxZoom component reacts to the change event. The variable fZoom (data type float) is then assigned the current value of the spinbox. This value is the parameter value of the procedure KS_RP_G_Draw (fZoom) which draws the coordinate system, the raster points and finally the graph of the given function f(x) with the current zoom factor.

The use of the three buttons with the labels +, - and 1 shows as an optional extension another way to realize a zoom function, where the Spinbox is used to display the current zoom factor:

Public Sub btnZoomNormal_Click()
  fZoom = 50 ' Angabe in %
  spinboxZoom.Value = fZoom
  KS_RP_G_Zeichnen(fZoom) ' Koordinatensystem, Rasterpunkte und Graph
End ' btnZoomNormal_Click()
 
Public Sub btnZoomG_Click()
  If fZoom < 300 Then 
     fZoom += 5
     spinboxZoom.Value = fZoom
     KS_RP_G_Zeichnen(fZoom)
  Endif ' fZoom < 300
End ' btnZoomG_Click()
 
Public Sub btnZoomK_Click()
  If fZoom > 20 Then
     fZoom -= 5 
     spinboxZoom.Value = fZoom
     KS_RP_G_Zeichnen(fZoom)
  Endif ' fZoom > 20
End ' btnZoomK_Click()

Digression

For example, in order to linearly map the interval of [3… 10] to the interval [0,0… 3,5], you need the linear function with the two points P0(3|0] and P1(10|3,5). The (general) approach for a linear equation (y-y0)-(x1-x0) = (y1-y0)-(x-x0) leads to k(x) = 0.5·x - 1.5 with x ∈ N in the restricted definition range 3 ≤ x ≤ 10.

Public Function k(x As Integer) As Float
  Return 0.5 * x - 1.5
End ' Function k(x)

The general approach to determine the interval [a….b] to the interval [p….q] leads to the linear equation (y-y0)·(x1-x0) = (y1-y0)·(x-x0) → (y-p)·(b-a) = (q-p)·(x-a) with a ≠ b. Converting to y results in the general equation for the conversion function k(x) with x ∈ N in the restricted definition range a ≤ x ≤ b.

Wenn Sie in einem Programm eine ganze Zahl aus einem Intervall [min…max] interaktiv einlesen wollen, dann steht Ihnen dafür auch die Komponente SpinBox zur Verfügung, deren wichtigste Eigenschaften und ihr Einsatz in diesem Kapitel beschrieben werden.

Die Spinbox ist ein Textfeld mit zwei kleinen Tasten (up/down), durch die der aktuelle Wert mit einer frei wählbaren Schrittweite im Intervall [min…max] erhöht oder verringert werden kann. Sie können einen ganzzahligen Wert auch direkt in die Spinbox eingeben. Um diesen Wert zu übernehmen, müssen Sie die Entertaste drücken. Sie können nur Zahlen vom Typ Integer eingeben, weil alle anderen Eingaben – ohne eine Reaktion – nicht akzeptiert werden. Jeder Spinbox können Sie einen definierten Startwert zuweisen. Da alle Werte in einer Spinbox vom Typ Integer sind, müssen Sie für Ihr Programm diese Werte u.U. umrechnen → Exkurs, wenn Sie zum Beispiel das Intervall von [3…10] auf das Intervall [0,0…3,5] abbilden wollen.

Wurde der Maximal- oder Minimalwert erreicht, dann erkennt man das zur Laufzeit am Erscheinungsbild der Spinbox, weil einer der up/down-Tasten grau dargestellt wird. Die SpinBox besitzt für die up/down-Tasten eine Repeat-Funktion.

Der Komponente SpinBox kann man ein Kontext-Menü (PopupMenu) mitgeben, welches dann das Standard-Kontext-Menü der Spinbox ersetzt. Das Menü muss vorher – zum Beispiel im Menüeditor – deklariert werden, damit man das entsprechende Menü im Eigenschaften-Fenster auswählen und der SpinBox zuordnen kann. Alternativ kann man die Zuordnung auch zur Laufzeit des Programms vornehmen. Ausführliche Informationen für diesen Weg erhalten Sie im Kapitel 13.4 'Kontext-Menü'.

Die folgenden Werte (Datentyp Integer) für ausgewählte Eigenschaften einer Spinbox können Sie bereits beim Programmstart zuweisen, sonst werden die Standardwerte gesetzt:

• Minimaler Wert → Standard = 0
• Maximaler Wert → Standard = 100
• Schrittweite → Standard = 1
• Startwert → Standard = 0

Im folgenden Beispiel wird eine Spinbox eingesetzt, um für das das Bild einer Funktion f(x) den Zoom-Faktor festzulegen. Der Zoom-Faktor ist in einem Bereich von [20%…300%] veränderbar. Die Schrittweite wird auf 5 (%) eingestellt und der Startwert für den Zoom auf 50 (%).

Abbildung 16.12.1: Funktionsplotter mit Zoom-Funktion

Der Quelltext wird nur in den Teilen angegeben, welche die Umsetzung des o.a. Konzepts für eine Zoom-Funktion demonstrieren:

Public Sub Form_Open()
  FMain.Center
  FMain.Resizable = False
  …
  spinboxZoom.MinValue = 20 ' 4 Startwerte
  spinboxZoom.MaxValue = 300
  spinboxZoom.Step = 5
  spinboxZoom.Value = 50
  fZoom = spinboxZoom.Value ' Zoom initialisieren
  spinboxZoom.Tooltip = "Zoom-Bereich 20...300"
' mnu0Einstellungen.Visible = False ' optional
' spinboxZoom.PopupMenu = "mnu0Einstellungen" ' optional
  spinboxZoom.SetFocus
  …
End ' Form_Open
 
Public Sub spinboxZoom_Change()
 
  fZoom = spinboxZoom.Value
  KS_RP_G_Zeichnen(fZoom)
 
End ' spinboxZoom_Change()

In der Prozedur spinboxZoom_Change() der Komponente spinboxZoom wird auf das Change-Ereignis reagiert. Der Variablen fZoom (Datentyp Float) wird dann der aktuelle Wert der Spinbox zugewiesen. Dieser Wert ist Parameterwert der Prozedur KS_RP_G_Zeichnen(fZoom), die das Koordinatensystem, die Rasterpunkte und abschließend den Graphen der gegebenen Funktion f(x) mit dem aktuellen Zoom-Faktor zeichnet.

Die Nutzung der drei Button mit den Beschriftungen +, - und 1 zeigt als optionale Erweiterung einen anderen Weg, um eine Zoom-Funktion zu realisieren, bei der die Spinbox u.a zur Anzeige des aktuellen Zoom-Faktors genutzt wird:

Public Sub btnZoomNormal_Click()
  fZoom = 50 ' Angabe in %
  spinboxZoom.Value = fZoom
  KS_RP_G_Zeichnen(fZoom) ' Koordinatensystem, Rasterpunkte und Graph
End ' btnZoomNormal_Click()
 
Public Sub btnZoomG_Click()
  If fZoom < 300 Then 
     fZoom += 5
     spinboxZoom.Value = fZoom
     KS_RP_G_Zeichnen(fZoom)
  Endif ' fZoom < 300
End ' btnZoomG_Click()
 
Public Sub btnZoomK_Click()
  If fZoom > 20 Then
     fZoom -= 5 
     spinboxZoom.Value = fZoom
     KS_RP_G_Zeichnen(fZoom)
  Endif ' fZoom > 20
End ' btnZoomK_Click()

Den Wert der Eigenschaft Spinbox.Text (Datentyp String) können Sie nur auslesen und sofort zur Anzeige des aktuellen Wertes der Spinbox in einer geeigneten Komponente verwenden.

Exkurs

Um zum Beispiel das Intervall von [3…10] auf das Intervall [0,0…3,5] linear abzubilden, benötigt man die lineare Funktion durch die beiden Punkte P0(3|0] und P1(10|3,5). Der (allgemeine) Ansatz für eine lineare Gleichung (y-y0)·(x1-x0) = (y1-y0)·(x-x0) führt auf k(x) = 0,5·x – 1,5 mit x ∈ N im eingeschränkten Definitionsbereich 3 ≤ x ≤ 10.

Public Function k(x As Integer) As Float
  Return 0.5 * x - 1.5
End ' Function k(x)

Der allgemeine Ansatz, um das Intervall [a…b] auf das Intervall [p…q] abzubilden, führt auf die lineare Gleichung (y-y0)·(x1-x0) = (y1-y0)·(x-x0) → (y-p)·(b-a) = (q-p)·(x-a) mit a ≠ b. Das Umstellen nach y ergibt die allgemeine Gleichung für die Konvertierungsfunktion k(x) mit x ∈ N im eingeschränkten Definitionsbereich a ≤ x ≤ b.