Source code for traitsui.key_bindings

# (C) Copyright 2004-2023 Enthought, Inc., Austin, TX
# All rights reserved.
# This software is provided without warranty under the terms of the BSD
# license included in LICENSE.txt and may be redistributed only under
# the conditions described in the aforementioned license. The license
# is also available online at
# Thanks for using Enthought open source!

""" Defines KeyBinding and KeyBindings classes, which manage the mapping of
    keystroke events into method calls on controller objects that are supplied
    by the application.

from traits.api import (
from traits.trait_base import SequenceTypes

from .editors.key_binding_editor import KeyBindingEditor
from .editors.list_editor import ListEditor
from .group import HGroup
from .handler import ModelView
from .item import Item
from .toolkit import toolkit
from .view import View

#: Trait definition for key bindings
Binding = Str(editor=KeyBindingEditor())

[docs]class KeyBinding(HasStrictTraits): """Binds one or two keystrokes to a method.""" # ------------------------------------------------------------------------- # Trait definitions: # ------------------------------------------------------------------------- #: First key binding binding1 = Binding #: Second key binding binding2 = Binding #: Description of what application function the method performs description = Str() #: Name of controller method the key is bound to method_name = Str() #: KeyBindings object that "owns" the KeyBinding owner = Instance("KeyBindings")
[docs] def match(self, binding): return any(binding == x for x in {self.binding1, self.binding2})
[docs] def clear_binding(self, binding): if binding == self.binding1: self.binding1 = self.binding2 self.binding2 = "" if binding == self.binding2: self.binding2 = ""
# ------------------------------------------------------------------------- # Traits view definitions: # ------------------------------------------------------------------------- traits_view = View( HGroup( Item("binding1"), Item("binding2"), Item("description", style="readonly"), show_labels=False, ) )
[docs]class KeyBindings(HasPrivateTraits): """A set of key bindings.""" # ------------------------------------------------------------------------- # Trait definitions: # ------------------------------------------------------------------------- #: Set of defined key bindings (redefined dynamically) bindings = List(Instance(KeyBinding)) #: Optional prefix to add to each method name prefix = Str() #: Optional suffix to add to each method name suffix = Str() # -- Private Traits ------------------------------------------------------- #: The (optional) list of controllers associated with this KeyBindings #: object. The controllers may also be provided with the 'do' method: controllers = List(transient=True) #: The 'parent' KeyBindings object of this one (if any): parent = Instance("KeyBindings", transient=True) #: The root of the KeyBindings tree this object is part of: root = Property(observe="parent") #: The child KeyBindings of this object (if any): children = List(transient=True) # ------------------------------------------------------------------------- # Traits view definitions: # ------------------------------------------------------------------------- def __init__(self, *bindings, **traits): # initialize bindings if len(bindings) == 1 and isinstance(bindings[0], SequenceTypes): bindings = bindings[0] traits.setdefault("bindings", list(bindings)) for binding in traits["bindings"]: binding.owner = self super().__init__(**traits)
[docs] def do(self, event, controllers=[], *args, **kw): """Processes a keyboard event.""" if isinstance(controllers, dict): controllers = list(controllers.values()) elif not isinstance(controllers, SequenceTypes): controllers = [controllers] else: controllers = list(controllers) return self._do( toolkit().key_event_to_name(event), controllers, args, kw.get("recursive", False), )
[docs] def merge(self, key_bindings): """Merges another set of key bindings into this set.""" binding_dic = {} for binding in self.bindings: binding_dic[binding.method_name] = binding for binding in key_bindings.bindings: binding2 = binding_dic.get(binding.method_name) if binding2 is not None: binding2.binding1 = binding.binding1 binding2.binding2 = binding.binding2
[docs] def clone(self, **traits): """Returns a clone of the KeyBindings object.""" return self.__class__(*self.bindings, **traits).trait_set( **self.trait_get("prefix", "suffix") )
[docs] def dispose(self): """Dispose of the object.""" if self.parent is not None: self.parent.children.remove(self) del self.controllers del self.children del self.bindings self.parent = self._root = None
[docs] def edit(self): """Edits a possibly hierarchical set of KeyBindings.""" model_view = KeyBindingsHandler(model=self) ui = model_view.edit_traits()
# -- Property Implementations --------------------------------------------- @cached_property def _get_root(self): root = self while root.parent is not None: root = root.parent return root # -- Event Handlers ------------------------------------------------------- @observe('bindings:items:[binding1,binding2]') def _binding_updated(self, event): if != "": for a_binding in self._match_binding(, skip={event.object}): a_binding.clear_binding( @observe("children.items") def _children_modified(self, event): """Handles child KeyBindings being added to the object.""" # the full children list is changed if isinstance(event.object, KeyBindings): for item in item.parent = self # the contents of the children list are changed else: for item in event.added: item.parent = self # -- Private Methods ------------------------------------------------------ def _get_bindings(self, bindings): """Returns all of the bindings of this object and all of its children.""" bindings.extend(self.bindings) for child in self.children: child._get_bindings(bindings) return bindings def _do(self, key_name, controllers, args, recursive): """Process the specified key for the specified set of controllers for this KeyBindings object and all of its children. """ # Search through our own bindings for a match: for binding in self._match_binding(key_name): method_name = "%s%s%s" % ( self.prefix, binding.method_name, self.suffix, ) for controller in controllers + self.controllers: method = getattr(controller, method_name, None) if method is not None: result = method(*args) if result is not False: return True if binding.method_name == "edit_bindings": self.edit() return True # If recursive, continue searching through a children's bindings: if recursive: for child in self.children: if child._do(key_name, controllers, args, recursive): return True # Indicate no one processed the key: return False def _match_binding(self, binding, skip=frozenset()): """Return all KeyBinding instances that match the given binding. """ return ( a_binding for a_binding in self.bindings if a_binding not in skip and a_binding.match(binding) )
[docs]class KeyBindingsHandler(ModelView): bindings = List(Instance(KeyBinding))
[docs] def key_binding_for(self, binding, key_name): """Returns the current binding for a specified key (if any).""" if key_name != "": for a_binding in self._match_binding(key_name, skip={binding}): return a_binding return None
def _match_binding(self, binding, skip=frozenset()): """Return all KeyBinding instances that match the given binding. """ return ( a_binding for a_binding in self.bindings if a_binding not in skip and a_binding.match(binding) ) def _bindings_default(self): bindings = list(set(self.model.root._get_bindings([]))) bindings.sort(key=lambda x: (x.binding1[-1:], x.binding1)) return bindings traits_view = View( [ Item( "bindings", style="readonly", show_label=False, editor=ListEditor(style="custom"), ), "|{Click on an entry field, then press the key to " "assign. Double-click a field to clear it.}<>", ], title="Update Key Bindings", kind="livemodal", resizable=True, width=0.4, height=0.4, )