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'