1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
|
.. _Actions:
Actions
=======
*Actions* provide small, specific, isolated functionality like creating a search filter
or adding a tag to a selected item.
The advantage of Actions is their lightweight implementation, so that the code can be reused easily, and added or removed to the application on demand.
For example, a feature that introduces large dependencies could be isolated in this manner, only being offered if the dependencies are met.
Or, the user can configure the appearance and button toolbars.
Triggers and execution
----------------------
An action is triggered by some event like a key press or a touch event.
Implementation-wise, touch triggers are implemented via kivy's default `on_touch_down` functionality.
Key events are handled by overwriting the `tagit.action.Action.ktrigger` method.
It is supposed to return a boolean that indicates whether or not the key event triggers
the action. The `tagit.widget.Binding` class helps you to check if a specific key event
matches your default binding.
Note that the binding needs not to be unique, i.e., multiple actions may be triggered
by the same key event. You can use this to your advantage, but should carefully regard
other actions when adding new default bindings.
Once triggered, the `tagit.action.Action.apply` function of the action is invoked.
Actions are automatically linked to the root window (*self.root*) and can use
*widget contexts* to query or manipulate them.
See the following snipped as an example::
from tagit import config
from tagit.actions.action import Action
from tagit.utils import clamp
from tagit.widgets import Binding
class NextPage(Action):
"""Scroll one page downwards without moving the cursor."""
def ktrigger(self, evt):
"""Check if *evt* matches the configured key binding for this action (PGDN)."""
return Binding.check(evt, self.cfg('bindings', 'browser', 'page_next'))
def apply(self):
"""Execute the NextPage action."""
with self.root.browser as browser:
browser.offset = clamp(browser.offset + browser.page_size, browser.max_offset)
config.declare(('bindings', 'browser', 'page_next'),
config.Keybind(), Binding.simple(Binding.PGDN))
Action appearance
-----------------
The action appearance is normally defined in a respective *.kv* file.
Any actions may be displayed as text and/or as image, hence you should provide both options.
The `tagit.actions.Action` base class provides the configuration flags to control the
display style. The configuration is usually specified by the parent element like a widget,
or a dock (e.g., `tagit.widgets.dock.ButtonDock`).
The following snipped defines the appearance of the *NextPage* action::
#:import resource_find kivy.resources.resource_find
<NextPage>:
source: resource_find('atlas://browser/next_page')
text: 'Next Page'
.. EOF ..
|
