Event Handling in the YaST2 UI

Author: Stefan Hundhammer <sh@suse.de>

Event Reference

Contents

Event Maps in General

Use WaitForEvent() to get full information about a YaST2 UI event. UserInput() only returns a small part of that information, the ID field of the event map.

The event map returned by WaitForEvent() always contains at least the following elements:
Map Key Value Type Valid Values Description
EventType string WidgetEvent
MenuEvent
TimeoutEvent
CancelEvent
KeyEvent
DebugEvent

The type of this event.

Use this for general event classification.

ID any The ID (a widget ID for WidgetEvents) that caused the event.
This is what UserInput() returns.
EventSerialNo integer >= 0 The serial number of this event.
Intended for debugging.

Event Types

WidgetEvent

All WidgetEvents have these map fields in common:
Map Key Value Type Valid Values Description
EventType string WidgetEvent (constant)
EventReason string Activated
ValueChanged
SelectionChanged
The reason for this event. This is something like an event sub-type. Use this to find out what the user really did with the widget.
ID any The ID of the widget that caused the event.
This is what UserInput() returns.
WidgetID any The ID of the widget that caused the event. This is nothing but an alias for "ID", but with this alias you can easily find out if this is a widget event at the same time as you retrieve the widget ID: No other events than WidgetEvent have this field.
WidgetClass string PushButton
SelectionBox
Table
CheckBox
...
The class (type) of the widget that caused the event.
WidgetDebugLabel string

The label (more general: the widget's shortcut property) of the widget that caused the event - in human readable form without any shortcut markers ("&"), maybe abbreviated to a reasonable length.

This label is translated to the current locale (the current user's language).

This is intended for debugging so you can easily dump something into the log file when you get an event.

Wigets that don't have a label don't add this field to the event map, so make sure you use a reasonable default when using a map lookup for this field: Don't use nil, use "" (the emtpy string) instead.

Activated WidgetEvent

Map Key Value Type Valid Values Description
EventReason string Activated (constant)

An Activated WidgetEvent is sent when the user explicitly wishes to activate an action.

Traditionally, this means clicking on a PushButton or activating it with some other means like pressing its shortcut key combination, moving the keyboard focus to it and pressing space.

Some other widgets (Table, SelectionBox, Tree) can also trigger this kind of event if they have the notify option set.

User interface style hint: YCP applications should use this to do the "typical" operation of that item - like editing an entry if the dialog has an "Edit" button. Use this Activated WidgetEvent only as a redundant way (for "power users") of invoking an action. Always keep that "Edit" (or similar) button around for novice users; double-clicks are by no way obvious. The user shouldn't need to experiment how to get things done.


Widget Type Widget Options Action to Trigger the Event
PushButton (none)
  • Single click on the button (Qt).
  • Press space on the button.
  • Press return anywhere in the dialog. This activates the dialog's default button if it has any and if the respective UI can handle default buttons.
Table `opt(`notify )
  • Double click on an item (Qt).
  • Press space on an item.
SelectionBox `opt(`notify )
  • Double click on an item (Qt).
  • Press space on an item.
Tree `opt(`notify )
  • Double click on an item (Qt).

    Note: This will also open or close items that have children!

  • Press space on an item.

Note that MenuButton and RichText don't ever send WidgetEvents. They send MenuEvents instead.

ValueChanged WidgetEvent

Map Key Value Type Valid Values Description
EventReason string ValueChanged (constant)

A ValueChanged WidgetEvent is sent by most interactive widgets that have a value that can be changed by the user. They all require the notify option to be set to send this event.

Widgets that have the concept of a "selected item" like SelectionBox, Table, or Tree don't send this event - they send a SelectionChanged WidgetEvent instead. One exception to this rule is the MultiSelectionBox which can send both events, depending on what the user did.

Widget Type Widget Options Action to Trigger the Event
MultiSelectionBox `opt(`notify ) Toggle an item's on/off state:
  • Click on an item's checkbox (Qt).
  • Press space on an item.
CheckBox `opt(`notify ) Toggle the on/off state:
  • Single click the widget (Qt).
  • Press space on the widget.
RadioButton `opt(`notify ) Set this RadioButton to on:
  • Single click the widget (Qt).
  • Press space on the widget.
No event is sent when the button's status is set to off because another RadioButton of the same RadioButtonGroup is set to on to avoid generating a lot of useless events: Only the on case is relevant for most YCP applications.
TextEntry
MultiLineEdit
`opt(`notify ) Enter text.
ComboBox `opt(`notify )
  • Select another value from the drop-down list:
    • Open the drop-down list and click on one of its items (Qt).
    • Open the drop-down list, use the cursor keys to move the selection and press space or return to actually accept that item.

      Simply opening the drop-down list and moving the cursor around in it (i.e. changing its selection) does not trigger this event.

  • Enter text (with `opt(`editable ) ).
IntField `opt(`notify ) Change the numeric value:
  • Enter a number.
  • Click on the up button (Qt).
  • Click on the down button (Qt).
  • Press cursor up in the widget (NCurses).
  • Press cursor down in the widget (NCurses).
Slider `opt(`notify )
  • Move the slider.
  • Enter a number in the embedded IntField.
  • Use one of the embedded IntField's up / down button.
PartitionSplitter `opt(`notify )
  • Move the slider.
  • Enter a number in one of the embedded IntFields.
  • Use one of the embedded IntFields' up / down button.

SelectionChanged WidgetEvent

Map Key Value Type Valid Values Description
EventReason string SelectionChanged (constant)

A SelectionChanged WidgetEvent is sent by most widgets that have the concept of a "selected item" like SelectionBox, Table, or Tree when the selected item changes.

Note that the MultiSelectionBox widget can send a SelectionChanged event, but also a ValueChanged WidgetEvent depending on what the user did. This is one reason to keep SelectionChanged and ValueChanged two distinct events: Widgets can have both concepts which may be equally important, depending on the YCP application.

The ComboBox never sends a SelectionChanged event. It only sends ValueChanged WidgetEvents.

The rationale behind this is that merely opening the drop-down list without actually accepting one of its items is just a temporary operation in a separate pop-up window (the drop-down list) that should not affect the YCP application or other widgets in the same dialog until the user actually accepts a value - upon which event a ValueChanged WidgetEvent is sent.
Widget Type Widget Options Action to Trigger the Event
SelectionBox
Qt: `opt(`notify )
NCurses: `opt(`notify, `immediate )
Select another item:
  • Click on an item (Qt).
  • Press cursor up in the widget.
  • Press cursor down in the widget.
Table
`opt(`notify, `immediate ) Select another item:
  • Click on an item (Qt).
  • Press cursor up in the widget.
  • Press cursor down in the widget.
Tree
`opt(`notify ) Select another item:
  • Click on an item (Qt).
  • Press cursor up in the widget.
  • Press cursor down in the widget.
MultiSelectionBox `opt(`notify ) Select another item:
  • Click on an item's text (not on the checkbox) (Qt).
  • Press cursor up in the widget.
  • Press cursor down in the widget.

MenuEvent

Map Key Value Type Valid Values Description
EventType string MenuEvent (constant)
ID any

The ID of the menu item the user selected or the href target (as string) for hyperlinks in RichText widgets.

Notice:This is not the widget ID, it is a menu item or hyperlink ID inside that MenuButton or RichText widget!

A MenuEvent is sent when the user activates a menu entry in a MenuButton or a hyperlink in a RichText widget.

Since the ID of the MenuButton or RichText widget is irrelevant in either case, this is not another subclass of WidgetEvent; the ID field has different semantics - and remember, the ID field is the only thing what UserInput() returns so this is particularly important.

For most YCP applications this difference is purely academic. Simply use the ID and treat it like it were just another button's ID.

No notify option is necessary for getting this event. Both MenuButton and RichText deliver MenuEvents right away.

TimeoutEvent

Map Key Value Type Valid Values Description
EventType string TimeoutEvent (constant)
ID symbol `timeout (constant)

A TimeoutEvent is sent when the timeout specified at WaitForEvent() or TimeoutUserInput() is expired and there is no other event pending (i.e. there is no other user input).

PollInput() never returns a TimeoutEvent; it simply returns nil if there is no input.

CancelEvent

Map Key Value Type Valid Values Description
EventType string CancelEvent (constant)
ID symbol `cancel (constant)

A CancelEvent is an event that is sent when the user performs a general "cancel" action that is usually not part of the YCP application.

For the Qt UI, this means he used the window manager close button or a special key combination like Alt-F4 to close the active dialog's window. For the NCurses UI, this means he hit the ESC key.

User interface style hint: It is usually a good idea for each dialog to provide some kind of "safe exit" anyway. Most popup dialogs (at least those that have more than just a simple "OK" button) should provide a "Cancel" button. If you use the widget ID `cancel for that button, CancelEvents integrate seamlessly into your YCP application.

"Main window" type dialogs should have an "Abort" button or something similar. If you don't use the widget ID `cancel for that button, don't forget to handle `cancel or "CancelEvent" like that "Abort" button. The user should always have a safe way out of a dialog - preferably one that doesn't change anything. Don't forget to add a confirmation popup before you really exit if there are unsaved data that might get lost!

KeyEvent

KeyEvents are specific to the NCurses UI. They are not intended for general usage. The idea is to use them where the default keyboard focus handling is insufficient - for example, when the logical layout of a dialog is known and the keyboard focus should be moved to the logically right widget upon pressing the cursor right key.

Widgets deliver KeyEvents if they have `opt( keyEvent ) set. This is independent of the notify option.

It is completely up to the UI what key presses are delivered as key events. Never rely on each and every key press to be delivered.
Map Key Value Type Valid Values Description
EventType string KeyEvent (constant)
ID string CursorRight
CursorDown
F1
a
A
...
The key symbol of this event in human readable form.
This is what UserInput() returns.
KeySymbol string CursorRight
CursorDown
F1
a
A
...
The key symbol of this event in human readable form.
This is nothing but an alias for "ID", but with this alias you can easily find out if this is a key event at the same time as you retrieve the key symbol: No other events than KeyEvent have this field.
FocusWidgetID any The ID of the widget that currently has the keyboard focus.
Unlike a WidgetEvent, this is not the same as "ID".
FocusWidgetClass string TextEntry
SelectionBox
...
The class (type) of the widget that has the keyboard focus.
FocusWidgetDebugLabel string

The label (more general: the widget's shortcut property) of the focus widget - in human readable form without any shortcut markers ("&"), maybe abbreviated to a reasonable length.

This label is translated to the current locale (the current user's language).

This is intended for debugging so you can easily dump something into the log file when you get an event.

Wigets that don't have a label don't add this field to the event map, so make sure you use a reasonable default when using a map lookup for this field: Don't use nil, use "" (the emtpy string) instead.

Even though at first glance the KeyEvent map looks very much like the WidgetEvent's map, it is different in how the "ID" field is used: A KeyEvent uses it to return the key symbol, while a WidgetEvent returns the widget ID. This is intended to integrate more seamlessly with common usage of UserInput(): A YCP application can simply use UserInput() and check for a return value "CursorRight" etc. - which should not cause any trouble unless somebody uses this as a (badly chosen) widget ID.

DebugEvent

Map Key Value Type Valid Values Description
EventType string DebugEvent (constant)
ID symbol `debugHotkey (constant)

A DebugEvent is an event type especially intended for debugging YCP code. It is sent when the user presses a special key combination.

For the Qt UI, this event is sent upon pressing Alt-Ctrl-Shift-D. There is currently no such key combination in the NCurses UI.

Use DebugEvents event to dump additional data to the log file or to open special debugging popup dialogs - but never do anything with it that might turn out to be a security hazard. Remember, even though the key combination is really awkward, sooner or later some users will get to know it, and they will experiment.




$Id: event-reference.html,v 1.7 2003/11/11 18:12:03 sh Exp $