docs/events.rst
author Radek Brich <radek.brich@devl.cz>
Wed, 30 Jan 2013 20:21:08 +0100
changeset 73 85a282b5e4fc
parent 45 43b2279b06e1
permissions -rw-r--r--
Add mousehover event (only SDL).
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
45
43b2279b06e1 Clean up Emitter class, simplify event handling. Fix Container.focusnext() method. Add events test (handler auto-registration, order).
Radek Brich <radek.brich@devl.cz>
parents: 38
diff changeset
     1
Events
43b2279b06e1 Clean up Emitter class, simplify event handling. Fix Container.focusnext() method. Add events test (handler auto-registration, order).
Radek Brich <radek.brich@devl.cz>
parents: 38
diff changeset
     2
======
9
7175ed629a76 Added ComboBox, HorizontalLayout, TreeNode, TreeModel, TreeView. Widget is now descendant of EventSource. Improved color management (color prefixes).
Radek Brich <radek.brich@devl.cz>
parents:
diff changeset
     3
36
caf927c3f10b Update docs.
Radek Brich <radek.brich@devl.cz>
parents: 9
diff changeset
     4
Draw event
caf927c3f10b Update docs.
Radek Brich <radek.brich@devl.cz>
parents: 9
diff changeset
     5
----------
caf927c3f10b Update docs.
Radek Brich <radek.brich@devl.cz>
parents: 9
diff changeset
     6
caf927c3f10b Update docs.
Radek Brich <radek.brich@devl.cz>
parents: 9
diff changeset
     7
Draw event is generating for all widgets in top down order - top window is drawn first, then its children etc.
caf927c3f10b Update docs.
Radek Brich <radek.brich@devl.cz>
parents: 9
diff changeset
     8
See TopWindow.draw(), Container.draw(), Widget.draw() - these methods control the draw event propagation.
caf927c3f10b Update docs.
Radek Brich <radek.brich@devl.cz>
parents: 9
diff changeset
     9
Normal widgets should implement only on_draw() method, which is called from draw().
caf927c3f10b Update docs.
Radek Brich <radek.brich@devl.cz>
parents: 9
diff changeset
    10
9
7175ed629a76 Added ComboBox, HorizontalLayout, TreeNode, TreeModel, TreeView. Widget is now descendant of EventSource. Improved color management (color prefixes).
Radek Brich <radek.brich@devl.cz>
parents:
diff changeset
    11
38
c6e170452c7f Documentation, fix names of focus methods.
Radek Brich <radek.brich@devl.cz>
parents: 36
diff changeset
    12
Keypress event
c6e170452c7f Documentation, fix names of focus methods.
Radek Brich <radek.brich@devl.cz>
parents: 36
diff changeset
    13
--------------
36
caf927c3f10b Update docs.
Radek Brich <radek.brich@devl.cz>
parents: 9
diff changeset
    14
caf927c3f10b Update docs.
Radek Brich <radek.brich@devl.cz>
parents: 9
diff changeset
    15
Keyboard events go in top down order, from top window to focused widget in each level. When implementing on_keypress method,
caf927c3f10b Update docs.
Radek Brich <radek.brich@devl.cz>
parents: 9
diff changeset
    16
add super().on_keypress(). Anything before that will be executed in top down walk, anything after in bottom up. Return True if you want to stop
caf927c3f10b Update docs.
Radek Brich <radek.brich@devl.cz>
parents: 9
diff changeset
    17
the walk.
caf927c3f10b Update docs.
Radek Brich <radek.brich@devl.cz>
parents: 9
diff changeset
    18
caf927c3f10b Update docs.
Radek Brich <radek.brich@devl.cz>
parents: 9
diff changeset
    19
::
9
7175ed629a76 Added ComboBox, HorizontalLayout, TreeNode, TreeModel, TreeView. Widget is now descendant of EventSource. Improved color management (color prefixes).
Radek Brich <radek.brich@devl.cz>
parents:
diff changeset
    20
36
caf927c3f10b Update docs.
Radek Brich <radek.brich@devl.cz>
parents: 9
diff changeset
    21
  before  after
caf927c3f10b Update docs.
Radek Brich <radek.brich@devl.cz>
parents: 9
diff changeset
    22
  1       7      top window
caf927c3f10b Update docs.
Radek Brich <radek.brich@devl.cz>
parents: 9
diff changeset
    23
  2       6        window
caf927c3f10b Update docs.
Radek Brich <radek.brich@devl.cz>
parents: 9
diff changeset
    24
  3       5          container
caf927c3f10b Update docs.
Radek Brich <radek.brich@devl.cz>
parents: 9
diff changeset
    25
  4       4            edit box
caf927c3f10b Update docs.
Radek Brich <radek.brich@devl.cz>
parents: 9
diff changeset
    26
38
c6e170452c7f Documentation, fix names of focus methods.
Radek Brich <radek.brich@devl.cz>
parents: 36
diff changeset
    27
Focus
c6e170452c7f Documentation, fix names of focus methods.
Radek Brich <radek.brich@devl.cz>
parents: 36
diff changeset
    28
-----
c6e170452c7f Documentation, fix names of focus methods.
Radek Brich <radek.brich@devl.cz>
parents: 36
diff changeset
    29
c6e170452c7f Documentation, fix names of focus methods.
Radek Brich <radek.brich@devl.cz>
parents: 36
diff changeset
    30
Basics:
c6e170452c7f Documentation, fix names of focus methods.
Radek Brich <radek.brich@devl.cz>
parents: 36
diff changeset
    31
 * Only one node in hierarchy can have focus.
c6e170452c7f Documentation, fix names of focus methods.
Radek Brich <radek.brich@devl.cz>
parents: 36
diff changeset
    32
 * All parent containers have focus, so they can relay events to focused child.
c6e170452c7f Documentation, fix names of focus methods.
Radek Brich <radek.brich@devl.cz>
parents: 36
diff changeset
    33
 * Top container has always focus.
c6e170452c7f Documentation, fix names of focus methods.
Radek Brich <radek.brich@devl.cz>
parents: 36
diff changeset
    34
c6e170452c7f Documentation, fix names of focus methods.
Radek Brich <radek.brich@devl.cz>
parents: 36
diff changeset
    35
Each container maintains its focus child and allows to cycle focus between children (See Container.focus_next). Focus cycling works throughout
36
caf927c3f10b Update docs.
Radek Brich <radek.brich@devl.cz>
parents: 9
diff changeset
    36
container levels - if focus was on last child and would go to the first, 'tab' key is not handled thus allowing parent level to cycle focus.
caf927c3f10b Update docs.
Radek Brich <radek.brich@devl.cz>
parents: 9
diff changeset
    37
caf927c3f10b Update docs.
Radek Brich <radek.brich@devl.cz>
parents: 9
diff changeset
    38
When focus changes, two events are generated: focus on new widget, unfocus on previous one.
caf927c3f10b Update docs.
Radek Brich <radek.brich@devl.cz>
parents: 9
diff changeset
    39
Mousedown causes focus change when allowed (Widget.allow_focus).
caf927c3f10b Update docs.
Radek Brich <radek.brich@devl.cz>
parents: 9
diff changeset
    40
38
c6e170452c7f Documentation, fix names of focus methods.
Radek Brich <radek.brich@devl.cz>
parents: 36
diff changeset
    41
 * Use grab_focus() on widget to make it receive keyboard events. This will clean old focus and set focus to this child.
c6e170452c7f Documentation, fix names of focus methods.
Radek Brich <radek.brich@devl.cz>
parents: 36
diff changeset
    42
 * Global shortcuts can be handled in keypress event from top widget. All keyboard events go through there.
c6e170452c7f Documentation, fix names of focus methods.
Radek Brich <radek.brich@devl.cz>
parents: 36
diff changeset
    43
 * Tab key changes focus to next widget. Shift-tab changes back to previous widget (FIXME: not implemented).
c6e170452c7f Documentation, fix names of focus methods.
Radek Brich <radek.brich@devl.cz>
parents: 36
diff changeset
    44
 * Hide on focused widget causes focus change like if tab key was pressed.
36
caf927c3f10b Update docs.
Radek Brich <radek.brich@devl.cz>
parents: 9
diff changeset
    45
38
c6e170452c7f Documentation, fix names of focus methods.
Radek Brich <radek.brich@devl.cz>
parents: 36
diff changeset
    46
See Container.trap_focus, Widget.can_focus(), Widget.has_focus(), Widget.set_focus() for more information.
9
7175ed629a76 Added ComboBox, HorizontalLayout, TreeNode, TreeModel, TreeView. Widget is now descendant of EventSource. Improved color management (color prefixes).
Radek Brich <radek.brich@devl.cz>
parents:
diff changeset
    47
7175ed629a76 Added ComboBox, HorizontalLayout, TreeNode, TreeModel, TreeView. Widget is now descendant of EventSource. Improved color management (color prefixes).
Radek Brich <radek.brich@devl.cz>
parents:
diff changeset
    48
7175ed629a76 Added ComboBox, HorizontalLayout, TreeNode, TreeModel, TreeView. Widget is now descendant of EventSource. Improved color management (color prefixes).
Radek Brich <radek.brich@devl.cz>
parents:
diff changeset
    49
Other event propagation
7175ed629a76 Added ComboBox, HorizontalLayout, TreeNode, TreeModel, TreeView. Widget is now descendant of EventSource. Improved color management (color prefixes).
Radek Brich <radek.brich@devl.cz>
parents:
diff changeset
    50
-----------------------
36
caf927c3f10b Update docs.
Radek Brich <radek.brich@devl.cz>
parents: 9
diff changeset
    51
caf927c3f10b Update docs.
Radek Brich <radek.brich@devl.cz>
parents: 9
diff changeset
    52
Normal events are propagated in top down order, to all children in each level, in order of child addition.
caf927c3f10b Update docs.
Radek Brich <radek.brich@devl.cz>
parents: 9
diff changeset
    53
Some events choose one or more of children for event propagation. In case of mouse events, child is chosen based on mouse cursor position.
caf927c3f10b Update docs.
Radek Brich <radek.brich@devl.cz>
parents: 9
diff changeset
    54
73
85a282b5e4fc Add mousehover event (only SDL).
Radek Brich <radek.brich@devl.cz>
parents: 45
diff changeset
    55
85a282b5e4fc Add mousehover event (only SDL).
Radek Brich <radek.brich@devl.cz>
parents: 45
diff changeset
    56
Standard events
85a282b5e4fc Add mousehover event (only SDL).
Radek Brich <radek.brich@devl.cz>
parents: 45
diff changeset
    57
---------------
85a282b5e4fc Add mousehover event (only SDL).
Radek Brich <radek.brich@devl.cz>
parents: 45
diff changeset
    58
85a282b5e4fc Add mousehover event (only SDL).
Radek Brich <radek.brich@devl.cz>
parents: 45
diff changeset
    59
* mousedown
85a282b5e4fc Add mousehover event (only SDL).
Radek Brich <radek.brich@devl.cz>
parents: 45
diff changeset
    60
  - report button press (left, mdiddle, right)
85a282b5e4fc Add mousehover event (only SDL).
Radek Brich <radek.brich@devl.cz>
parents: 45
diff changeset
    61
* mouseup
85a282b5e4fc Add mousehover event (only SDL).
Radek Brich <radek.brich@devl.cz>
parents: 45
diff changeset
    62
  - report button released
85a282b5e4fc Add mousehover event (only SDL).
Radek Brich <radek.brich@devl.cz>
parents: 45
diff changeset
    63
* mousemove
85a282b5e4fc Add mousehover event (only SDL).
Radek Brich <radek.brich@devl.cz>
parents: 45
diff changeset
    64
  - report mouse position change (only when button pressed)
85a282b5e4fc Add mousehover event (only SDL).
Radek Brich <radek.brich@devl.cz>
parents: 45
diff changeset
    65
  - for use in combination with mousedown, mouseup
85a282b5e4fc Add mousehover event (only SDL).
Radek Brich <radek.brich@devl.cz>
parents: 45
diff changeset
    66
* mousehover
85a282b5e4fc Add mousehover event (only SDL).
Radek Brich <radek.brich@devl.cz>
parents: 45
diff changeset
    67
  - report mouse position change (only when all buttons released)
85a282b5e4fc Add mousehover event (only SDL).
Radek Brich <radek.brich@devl.cz>
parents: 45
diff changeset
    68
* mousewheel
85a282b5e4fc Add mousehover event (only SDL).
Radek Brich <radek.brich@devl.cz>
parents: 45
diff changeset
    69
  - report wheel up, down (as buttons)
85a282b5e4fc Add mousehover event (only SDL).
Radek Brich <radek.brich@devl.cz>
parents: 45
diff changeset
    70