GAMBAS BOOK 3.18.2

This class implements a button - a button. A button can display a text, an image or both:

Figure 16.3.1: Three buttons in the GeoMap → project Chapter 17.15.1

• If you use a & sign in the caption (property Text or synonymously Caption), then you insert a so-called ShortCut. The key combination ALT+letter, which follows the & character, triggers the action that would have been triggered even if the button had been clicked.
• A button in a program window can be defined as the default button with the property Button. The default button is automatically activated when the RETURN button is pressed.
• If the property Button.Cancel is set to True for a button, then pressing the ESC key will automatically activate this button!

tablelayout

Table 16.3.1.1: Selected button properties

For a button, the click event is the dominant event. It is triggered when the user clicks on the button with the mouse.

' This function returns the names of the classes with the required property in a matrix.
 
Private Function SearchClasses(sProperty As String) As String[]
  Dim hClass As Class
  Dim aNamesMatrix As New String[]
 
  For Each hClass In Classes
      If hClass.Symbols.Exist(sProperty, gb.IgnoreCase) Then aNamesMatrix.Add(hClass.Name)
  Next
  Return aNamesMatrix.Sort() ' Return of the sorted array of names
 
End ' Function SearchClasses(..)
 
Public Sub btnAnzeigeLast_Click()
  Dim sElement As String
 
  TextArea.Clear
  For Each sElement In SearchClasses("PopupMenu")
      TextArea.Insert(sElement & ", ")
  Next
 
End ' btnAnzeigeLast_Click()

Extensions exist if the properties Button. Default, Button. Cancel or Button. Value are set to the value True? properties.

Example 1 shows a button with which three different actions (start, stop and reset) can be triggered. The pivotal point here is the use of the tag property. A process is started and the time duration in seconds is displayed hexadecimal. After stopping, the time can be read off and finally the start state can be set with reset:

Figure 16.3.3.1: Short-time measurement with hexadecimal display

The source code contains only the relevant sections of a larger project:

[1] ...
[2] 
[3] Private sSecond As Integer
[4] 
[5] Public Sub Form_Open() 
[6]   ... 
[7]   
[8]   btnStartStop.Tag = "start" 
[9]   btnStartStop.Picture = Picture["icon:/16/play"] 
[10]   btnStartStop.Caption = "  Starten" 
[11]   Timer1.Delay = 1000 
[12]   LCDNumber1.Mode = 2 ' Hexadecimal 
[13]   
[14]   ... 
[15]  End ' Form_Open() 
[16] 
[17] Public Sub btnStartStop_Click() 
[18] 
[19]   Select Case btnStartStop.Tag 
[20]     Case "start" 
[21]       btnStartStop.Picture = Picture["icon:/16/stop"] 
[22]       btnStartStop.Tag = "stop" 
[23]       btnStartStop.Caption = "  Stoppen" 
[24]       Timer1.Start ' Aktion starten 
[25]     Case "stop" 
[26]       btnStartStop.Picture = Picture["icon:/16/redo"] 
[27]       btnStartStop.Tag = "reset" 
[28]       btnStartStop.Caption = "  Reset" 
[29]       Timer1.Stop ' Aktion stoppen 
[30]     Case "reset" 
[31]       btnStartStop.Picture = Picture["icon:/16/play"] 
[32]       btnStartStop.Tag = "start" 
[33]       btnStartStop.Caption = "  Starten" 
[34]       sSecond = 0 
[35]       LCDNumber1.Value = 0 
[36]   End Select ' btnStartStop.Tag 
[37] 
[38] End ' btnStartStop_Click() 
[39] 
[40] Public Sub Timer1_Timer() 
[41]   
[42]   Inc sSecond 
[43]   LCDNumber1.Value = sSecond 
[44] 
[45] End ' Timer1_Timer()

Example 2 shows the project to demonstrate the component gb. map for displaying maps from openstreetmap. org. However, the focus is not on the display of the maps, but rather the use of properties, methods and the click event for the three buttons on the form Figure 16.3.4.2.

From the source code (complete) only lines 1 to 33 are relevant for the topic button. The source code is then commented:

[1] ' Gambas class file
[2] 
[3] Public Sub Form_Open()  
[4]   FMain.Center
[5]   FMain.Caption = "GeoMap - Daten von OpenStreetMap ©"
[6]   
[7]   btnShowMap.Picture = Picture["icon:/16/internet"]
[8]   btnShowMap.Text = "  Anzeige GeoMap"
[9]   btnShowMap.Default = True
[10]   btnShowMap.SetFocus
[11] 
[12]   btnClose.Caption = "&Beenden"
[13] 
[14]   btnShowHelp.Text = Null
[15]   btnShowHelp.Tooltip = "Hinweise zur Nutzung von GeoMap"
[16]   btnShowHelp.Picture = Picture["icon:/16/help"]
[17]   
[18] End ' Form_Open()
[19] 
[20] Public Sub btnShowMap_Click()    
[21]   If btnShowHelp.Tag = Null Then
[22]      btnShowHelp.Value = True
[23]      btnShowHelp.Tag = 1
[24]   Endif ' btnHelp.Tag = Null ?
[25]   ShowMap()  
[26] End ' btnShowMap_Click()
[27] 
[28] Public Sub btnShowHelp_Click()
[29]   HelpMessage()
[30] End ' btnShowHelp_Click()
[31] 
[32] Public Sub btnClose_Click()
[33]   FMain.Close
[34] End ' btnClose_Click()
[35] 
[36] '************************************************************************
[37] Private Sub ShowMap()
[38]   Dim iZoom As Integer
[39]   Dim fLatitude, fLongitude As Float
[40]   Dim sCacheName, sTileName, sTilePattern As String
[41]   Dim cArguments As New Collection
[42]   
[43]   iZoom = 13
[44]   fLatitude = 52.78631   ' °Breite Osterburg
[45]   fLongitude = 11.73872  ' °Länge  Osterburg
[46]   sTileName = "OpenStreetMap"
[47]   sTilePattern = "85.30.190.241/{z}/{x}/{y}.png"
[48]   cArguments = Null
[49]   sCacheName = Null
[50]   MapView1.Map.AddTile(sTileName, sTilePattern, cArguments, sCacheName)
[51]   MapView1.AllowEffect = False
[52]   MapView1.Map[sTileName].Visible = True
[53]   MapView1.Map.Center = MapPoint(fLatitude, fLongitude)
[54]   MapView1.Map.Zoom = iZoom
[55]     
[56] End ' ShowMap
[57] 
[58] Private Sub HelpMessage()
[59]   Dim sMessage As String
[60]  
[61]   sMessage = "<hr><b>Hinweise zum Einsatz der Komponente Map</b><hr>"
[62]   sMessage &= "» Verschieben der Karte mit der linken Maustaste"
[63]   sMessage &= "<br>» Zoomen mit dem Maus-Rad>"  
[64]   sMessage &= "<br>» Original-Zoom mit 'Anzeige GeoMap'<hr>"  
[65]   sMessage &= "» Enter-Taste setzt Standard-Anzeige (Original-Zoom)"  
[66]   sMessage &= "<br>» Tastenkombination ALT+b beendet das Programm<hr>"  
[67]   sMessage &= "▪ Entwickler der Komponente gb.map ist Fabien Bodard"  
[68]   sMessage &= "<br>▪ EMail: gambix@users.sourceforge.net<hr>"  
[69]   Message.Info(sMessage)    
[70] End ' HelpMessage()

Comments:

• After assigning an icon from the Gambas collection to the btnShowMap button in lines 7 and 8 and specifying the labeling, the button btnShowMap is declared the default button in line 9 and automatically activated at runtime if you press the RETURN key. Whether you press the return key or press the button btnShowMap shows the same effect - a geographical map is displayed.
• In line 12 a ShortCut is defined, so that also the key combination ALT+b terminates the program - just like a click on the button btnClose.
• The tag property of the btnShowMap button is used in lines 21 to 24 to give the user a one-time presentation of the' Notes on using the Map' component before the first display of a map.
• The (automatic) display of the help text is realized in line 22, because the property Value gets the value True by assigning btnShowMap. value = True. The click event is simulated. Alternatively, you could have entered btnShowMap_Click () in line 22.
• After the first display of the help text, the value of the tag property of the btnShowMap button changes from zero to 1 in line 23. btnShowMap prevents further displays of the help text by clicking on the btnShowMap button, because the query always returns false in line 21.

Figure 16.3.4.1: Program help

Figure 16.3.4.2: Project GeoMap

Hint:

• The first key is always the default button.
• The last button is always the Cancel button? Escape button.

If the function is called with only one argument, then there is only the “OK” button.

Diese Klasse implementiert einen Button – eine Taster-Schaltfläche. Ein Button kann einen Text, ein Bild oder beides anzeigen:

Abbildung 16.3.1: Drei Button im Projekt GeoMap → Kapitel 17.15.1

• Verwendet man in der Beschriftung (Eigenschaft Text oder synonym Caption) ein &-Zeichen, dann fügt man einen so genannten ShortCut ein. Die Tastenkombination ALT+Buchstabe, der dem &-Zeichen folgt, löst die Aktion aus, die auch bei einem Klick auf den Button ausgelöst worden wäre.
• Ein Button in einem Programm-Fenster kann über die Eigenschaft Button.Default = True als Default-Button definiert werden. Der Default-Button wird automatisch aktiviert, wenn die RETURN-Taste gedrückt wird.
• Wenn für einen Button die Eigenschaft Button.Cancel auf True gesetzt wird, dann wird das Drücken der ESC-Taste diesen Button automatisch aktivieren.

Tabelle 16.3.1.1: Ausgewählte Button-Eigenschaften

Für einen Button ist das Klick-Ereignis das dominante Ereignis. Es wird ausgelöst, wenn der Benutzer mit der Maus auf den Button klickt.

' Diese Funktion liefert die Namen der Klassen mit der gesuchten Eigenschaft in einer Matrix
 
Private Function SearchClasses(sProperty As String) As String[]
  Dim hClass As Class
  Dim aNamesMatrix As New String[]
 
  For Each hClass In Classes
      If hClass.Symbols.Exist(sProperty, gb.IgnoreCase) Then aNamesMatrix.Add(hClass.Name)
  Next
  Return aNamesMatrix.Sort() ' Rückgabe des sortierten Arrays der Namen
 
End ' Function SearchClasses(..)
 
Public Sub btnAnzeigeLast_Click()
  Dim sElement As String
 
  TextArea.Clear
  For Each sElement In SearchClasses("PopupMenu")
      TextArea.Insert(sElement & ", ")
  Next
 
End ' btnAnzeigeLast_Click()

Erweiterungen existieren, wenn die Eigenschaften Button.Default, Button.Cancel oder Button.Value auf den Wert True gesetzt worden sind → Eigenschaften.

Beispiel 1 zeigt einen Button, mit dem drei unterschiedliche Aktionen (Starten, Stoppen und Reset) ausgelöst werden können. Dreh- und Angelpunkt ist hier die Verwendung der Tag-Eigenschaft. Ein Vorgang wird gestartet und die Zeit-Dauer in Sekunden hexadezimal angezeigt. Nach dem Stoppen kann die Zeit abgelesen werden und abschließend mit Reset der Startzustand gesetzt werden:

Abbildung 16.3.3.1: Kurzzeit-Messung mit hexadezimaler Anzeige

Der Quelltext enthält nur die relevanten Abschnitte aus einem größeren Projekt:

[1] ...
[2] 
[3] Private sSecond As Integer
[4] 
[5] Public Sub Form_Open() 
[6]   ... 
[7]   
[8]   btnStartStop.Tag = "start" 
[9]   btnStartStop.Picture = Picture["icon:/16/play"] 
[10]   btnStartStop.Caption = "  Starten" 
[11]   Timer1.Delay = 1000 
[12]   LCDNumber1.Mode = 2 ' Hexadecimal 
[13]   
[14]   ... 
[15]  End ' Form_Open() 
[16] 
[17] Public Sub btnStartStop_Click() 
[18] 
[19]   Select Case btnStartStop.Tag 
[20]     Case "start" 
[21]       btnStartStop.Picture = Picture["icon:/16/stop"] 
[22]       btnStartStop.Tag = "stop" 
[23]       btnStartStop.Caption = "  Stoppen" 
[24]       Timer1.Start ' Aktion starten 
[25]     Case "stop" 
[26]       btnStartStop.Picture = Picture["icon:/16/redo"] 
[27]       btnStartStop.Tag = "reset" 
[28]       btnStartStop.Caption = "  Reset" 
[29]       Timer1.Stop ' Aktion stoppen 
[30]     Case "reset" 
[31]       btnStartStop.Picture = Picture["icon:/16/play"] 
[32]       btnStartStop.Tag = "start" 
[33]       btnStartStop.Caption = "  Starten" 
[34]       sSecond = 0 
[35]       LCDNumber1.Value = 0 
[36]   End Select ' btnStartStop.Tag 
[37] 
[38] End ' btnStartStop_Click() 
[39] 
[40] Public Sub Timer1_Timer() 
[41]   
[42]   Inc sSecond 
[43]   LCDNumber1.Value = sSecond 
[44] 
[45] End ' Timer1_Timer()

Das Beispiel 2 zeigt das Projekt zur Demonstration der Komponente gb.map zur Anzeige von Karten von openstreetmap.org. Es steht aber nicht die Anzeige der Karten im Fokus, sondern der Einsatz von Eigenschaften, Methoden und des Klick-Ereignisses für die drei Button auf dem Formular → Abbildung 16.3.4.2.

Vom Quelltext (komplett) sind nur die Zeilen 1 bis 33 relevant für das Thema Button. Der Quelltext wird anschließend kommentiert:

[1] ' Gambas class file
[2] 
[3] Public Sub Form_Open()  
[4]   FMain.Center
[5]   FMain.Caption = "GeoMap - Daten von OpenStreetMap ©"
[6]   
[7]   btnShowMap.Picture = Picture["icon:/16/internet"]
[8]   btnShowMap.Text = "  Anzeige GeoMap"
[9]   btnShowMap.Default = True
[10]   btnShowMap.SetFocus
[11] 
[12]   btnClose.Caption = "&Beenden"
[13] 
[14]   btnShowHelp.Text = Null
[15]   btnShowHelp.Tooltip = "Hinweise zur Nutzung von GeoMap"
[16]   btnShowHelp.Picture = Picture["icon:/16/help"]
[17]   
[18] End ' Form_Open()
[19] 
[20] Public Sub btnShowMap_Click()    
[21]   If btnShowHelp.Tag = Null Then
[22]      btnShowHelp.Value = True
[23]      btnShowHelp.Tag = 1
[24]   Endif ' btnHelp.Tag = Null ?
[25]   ShowMap()  
[26] End ' btnShowMap_Click()
[27] 
[28] Public Sub btnShowHelp_Click()
[29]   HelpMessage()
[30] End ' btnShowHelp_Click()
[31] 
[32] Public Sub btnClose_Click()
[33]   FMain.Close
[34] End ' btnClose_Click()
[35] 
[36] '************************************************************************
[37] Private Sub ShowMap()
[38]   Dim iZoom As Integer
[39]   Dim fLatitude, fLongitude As Float
[40]   Dim sCacheName, sTileName, sTilePattern As String
[41]   Dim cArguments As New Collection
[42]   
[43]   iZoom = 13
[44]   fLatitude = 52.78631   ' °Breite Osterburg
[45]   fLongitude = 11.73872  ' °Länge  Osterburg
[46]   sTileName = "OpenStreetMap"
[47]   sTilePattern = "85.30.190.241/{z}/{x}/{y}.png"
[48]   cArguments = Null
[49]   sCacheName = Null
[50]   MapView1.Map.AddTile(sTileName, sTilePattern, cArguments, sCacheName)
[51]   MapView1.AllowEffect = False
[52]   MapView1.Map[sTileName].Visible = True
[53]   MapView1.Map.Center = MapPoint(fLatitude, fLongitude)
[54]   MapView1.Map.Zoom = iZoom
[55]     
[56] End ' ShowMap
[57] 
[58] Private Sub HelpMessage()
[59]   Dim sMessage As String
[60]  
[61]   sMessage = "<hr><b>Hinweise zum Einsatz der Komponente Map</b><hr>"
[62]   sMessage &= "» Verschieben der Karte mit der linken Maustaste"
[63]   sMessage &= "<br>» Zoomen mit dem Maus-Rad>"  
[64]   sMessage &= "<br>» Original-Zoom mit 'Anzeige GeoMap'<hr>"  
[65]   sMessage &= "» Enter-Taste setzt Standard-Anzeige (Original-Zoom)"  
[66]   sMessage &= "<br>» Tastenkombination ALT+b beendet das Programm<hr>"  
[67]   sMessage &= "▪ Entwickler der Komponente gb.map ist Fabien Bodard"  
[68]   sMessage &= "<br>▪ EMail: gambix@users.sourceforge.net<hr>"  
[69]   Message.Info(sMessage)    
[70] End ' HelpMessage()

Kommentare:

• Nach dem in den Zeilen 7 und 8 dem Button btnShowMap ein Icon aus dem Bestand von Gambas zugewiesen und die Beschriftung festgelegt wurde, wird in der Zeile 9 der Button btnShowMap zum Default-Button erklärt und zur Programmlaufzeit automatisch aktiviert, wenn Sie die RETURN-Taste drücken würden. Ob Sie die Return-Taste drücken oder auf den Button btnShowMap drücken zeigt die gleiche Wirkung – es wird eine geografischen Karte angezeigt.
• In der Zeile 12 wird ein ShortCut definiert, so dass auch die Tastenkombination ALT+b das Programm beendet – genauso wie ein Klick auf den Button btnClose.
• Die Tag-Eigenschaft des Buttons btnShowMap wird in den Zeilen 21 bis 24 genutzt, um dem Benutzer bereits vor der ersten Anzeige einer Karte die 'Hinweise zum Einsatz der Komponente Map' einmalig zu präsentieren.
• Die (automatische) Anzeige des Hilfetextes wird in der Zeile 22 realisiert, weil die Eigenschaft Value durch die Zuweisung btnShowMap.Value = True den Wert True erhält. Das Klick-Ereignis wird simuliert. Alternativ hätten Sie in der Zeile 22 auch btnShowMap_Click() eintragen können.
• Nach der ersten Anzeige des Hilfe-Textes ändert sich der Wert der Tag-Eigenschaft des Button btnShowMap in der Zeile 23 vom Wert Null auf 1. Damit werden weitere Anzeigen des Hilfe-Textes bei einem Klick auf den Button btnShowMap sicher unterbunden, weil die Abfrage in der Zeile 21 dann stets False liefert.

Abbildung 16.3.4.1: Programm-Hilfe

Abbildung 16.3.4.2: Projekt GeoMap

Hinweis:

Alle Message-Boxen als (Unter-)Programmfenster können bis zu drei Button besitzen. Dabei gilt:

• Die erste Taste ist immer der Default-Button → Return-Taste.
• Der letzte Button ist immer der Cancel-Button → Escape-Taste.

Wenn die Funktion nur mit einem Argument aufgerufen, dann gibt es nur den “OK”-Button.