4.3 Button

Ein Button ist eine Schaltfläche, die mit der Maus angeklickt oder mit der Tastatur aktiviert werden kann.

Buttons werden für Menü-Einträge oder als alleinstehende Schalter verwendet.

Abstammung:

Spezielle Instance-Variablen:

Variable Syntax im UI-Code Im BASIC-Code

ActionHandler ActionHandler = <Handler>
ActionHandler = BringUpHelp nur schreiben
--

actionData actionData = numWert lesen, schreiben

interactionCommand interactionCommand = numWert lesen, schreiben

BringsUpWindow BringsUpWindow --

IsDestructive IsDestructive --

unhandledEvents -- nur lesen

Methoden:

Methode Aufgabe

Activate Auslösen des Buttons, als ob darauf geklickt wurde

Action-Handler-Typen:

Handler-Typ Parameter

ButtonAction (sender as object, actionData as integer)

ActionHandler

Die Instance-Variable ActionHandler enthält den Namen des aufzurufenden Actionhandlers. Dieser muss als ButtonAction vereinbart sein. Der Wert wird üblicherweise im UI-Code gesetzt.

Bei Bedarf kann er auch zur Laufzeit (im BASIC-Code) gesetzt, aber nicht gelesen werden.

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

Beispiel: siehe unten

Syntax UI-Code: ActionHandler = BringUpHelp

Diese spezielle Syntax weist dem Button den von R-BASIC vordefinierten "Öffne die Hilfe" Handler zu. Wenn der Nutzer auf den Button klickt durchsucht der Handler den generic Tree nach einem Help Context und dem Namen einer Hilfedatei. Dazu durchsucht er zunächst den Button und dann der Reihe nach sein Parent, dessen Parent usw. Abschließend öffnet er die entsprechende Seite der Hilfe. Sehr oft hat daher der Button selbst einen Help Context gesetzt während die Hilfedatei vom Application Objekt bezogen wird. Dieses Verhalten kann man nutzen um ein Hilfemenü aufzubauen, dass spezielle Hilfeseiten direkt über Menüeinträge anzuspringen.

Button HelpButton
  Caption$="Hilfe zu irgend etwas"
  ActionHandler = BringUpHelp
  helpContext$ ="Help1"
  End Object

Natürlich kann man jedem Button auch eine eigene Hilfedatei zuordnen (helpFile$=..), wenn man das will.

actionData

Die Instance-Variable actionData enthält einen Integer-Wert, der bei Bedarf zur Identifizierung des Buttons oder sonstigen Zwecken herangezogen werden kann. Der Standard-Fall ist jedoch, dass der actionData-Wert nicht benutzt wird.

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

ButtonAction

Action-Handler für Buttons müssen als ButtonAction definiert werden.

Parameter:

sender: Das Button-Objekt, das den Handler aktiviert hat
actionData: actionData-Wert des Buttons. Null, falls der Wert nicht gesetzt ist.

Beispiel 1: einfacher Button

UI-Code:

Button MyButton
  Caption$ = "OK", 0
  ActionHandler = OKPressed
END Object

BASIC-Code:

ButtonAction OKPressed
  < .. diverser Code ..>
  MsgBox "Operation erfolgreich."
END ACTION

Beispiel 2: Verwendung des actionData-Wertes

UI-Code:

Button TestButton
  Caption$ = "Press mich"
  actionData = 255
  ActionHandler = Handler1
END OBJECT

BASIC-Code:

ButtonAction Handler1
DIM x, y as word
  x = actionData/2
  y = actionData + 12
  MsgBox "Gefundene Werte:"+ Str$(actionData)+ Str$(x) + Str$(y)
END ACTION

interactionCommand

Sehr häufig müssen Buttons in einer Dialogbox standardisierte Aktionen auslösen, wie z.B. das Schließen des Dialogs. Oder es ist nötig, dass eine Dialogbox einen Wert zurückgibt, z.B. ob der Nutzer auf "Ja", "Nein" oder "Abbrechen" geklickt hat. Für diesen Zweck kann man einem Button einen "Interactions-Kommando" - Wert (einen WORD-Wert) zuordnen, so dass das GEOS-System automatisch weiß, was es zu tun hat.

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

Da die Verwendung von interactionCommand-Werten nur im Zusammenhang mit Dialogboxen sinnvoll ist, werden sie dort ausführlich besprochen. Zur Vereinfachung finden Sie unten trotzdem eine Tabelle der verfügbaren Interaction-Command-Werte. Beachten Sie, dass ein Button nur entweder einen action-Handler oder ein interactionCommand haben kann. Die Zuweisung des Einen im BASIC-Code löscht jeweils das Andere.

interactionCommand Wert Bedeutung

IC_CLOSE 1 Dialog schließen

IC_APPLY 3 Änderungen anwenden

IC_RESET 4 Dialog zurücksetzen

IC_OK 5 Verwendet für "OK"

IC_YES 6 Verwendet für "Ja"

IC_NO 7 Verwendet für "Nein"

IC_STOP 8 Verwendet für "Stop" oder "Abbrechen"

IC_HELP 10 Button ersetzt den "Hilfe" Button

BringsUpWindow

Dieser Hint platziert eine Ellipse "..." hinter dem Button-Text um anzuzeigen, dass der Button eine Dialogbox oder ähnliches auf den Schirm bringt. Damit sieht ein Menüeintrag genau so aus, als sei die Dialogbox das direkte Child des Menüs.

Syntax UI-Code: BringsUpWindow

IsDestructive

Ähnlich wie der Hint CannotBeDefault für Groups soll IsDestructive verhindern, dass der Nutzer den Button als "Default-Aktion" per Enter- oder Leertaste aktiviert. Verwenden Sie diesen Hint, wenn der Button eine potentiell gefährliche (destruktive) Aktion auslöst.

Syntax UI-Code: IsDestructive

unhandledEvents

Enthält, wie oft der Button "aktiviert" wurde (z.B. durch Anklicken mit der Maus), ohne dass der zugehörige ActionHandler aufgerufen werden konnte. Dass passiert i.A. wenn noch ein anderer ActionHandler läuft, während der Button aktiviert wurde. Da alle ActionHandler nacheinander (im gleichen Thread) abgearbeitet werden sie in der Reihenfolge abgearbeitet in der sie auftreten, ohne sich gegenseitig zu unterbrechen.

Achtung! Die Instancevariable unhandledEvents enthält immer den Wert Null, wenn dem Button kein ActionHandler zugewiesen wurde.

Sie können diese Instancevariable benutzen, wenn Sie einen lang andauernden Prozess vorzeitig abbrechen wollen, aber dafür keinen Progress-Dialog (siehe Kapitel 4.6.6.4) einsetzen möchten. Bedenken Sie aber, dass die entsprechenden Ereignisse bereits in der Ereigniswarteschlage (Event queue) abgelegt sind und daher auf jeden Fall später noch abgearbeitet werden.

Syntax BASIC-Code: <numVar> = <obj>.unhandledEvents

Activate

Diese Methode bewirkt, dass der Button aktiviert wird, so als ob der User direkt darauf geklickt hat. Der Action-Handler oder das InteractionCommand des Buttons wird ausgeführt.

Syntax BASIC-Code: <obj>.Activate

Beispiel:

  IF x > 0 THEN MyButton.Activate

^

Weiter...