Author: Stefan Hundhammer <sh@suse.de>
Prev: Event-related UI builtins | Top: Event Handling Index | Next: (none) |
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. |
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. |
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) |
|
Table | `opt(`notify ) |
|
SelectionBox | `opt(`notify ) |
|
Tree | `opt(`notify ) |
|
Note that MenuButton and RichText don't ever send WidgetEvents. They send MenuEvents instead.
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:
|
CheckBox | `opt(`notify ) |
Toggle the on/off state:
|
RadioButton | `opt(`notify ) |
Set this RadioButton to on:
|
TextEntry MultiLineEdit |
`opt(`notify ) | Enter text. |
ComboBox | `opt(`notify ) |
|
IntField | `opt(`notify ) |
Change the numeric value:
|
Slider | `opt(`notify ) |
|
PartitionSplitter | `opt(`notify ) |
|
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 |
|
Select another item:
|
||||
Table |
`opt(`notify, `immediate ) |
Select another item:
|
||||
Tree |
`opt(`notify ) |
Select another item:
|
||||
MultiSelectionBox | `opt(`notify ) |
Select another item:
|
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.
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.
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!
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.
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.
Prev: Event-related UI builtins | Top: Event Handling Index | Next: (none) |
$Id: event-reference.html,v 1.7 2003/11/11 18:12:03 sh Exp $