# This file is part of MyPaint. # Copyright (C) 2008-2014 by Martin Renold # # This program is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by # the Free Software Foundation; either version 2 of the License, or """Canvas input modes API: stack, and base classes for modes.""" ## Imports import logging logger = logging.getLogger(__name__) import gtk2compat import buttonmap import lib.command from lib.observable import event import math import gobject import gtk from gtk import gdk from gtk import keysyms from gettext import gettext as _ ## Module constants # Actions it makes sense to bind to a button. (HACK). # Notably, tablet pads tend to offer many more buttons than the usual 3... BUTTON_BINDING_ACTIONS = [ "ShowPopupMenu", "Undo", "Redo", "Bigger", "Smaller", "MoreOpaque", "LessOpaque", "PickContext", "Fullscreen", "ToggleSubwindows", "BrushChooserPopup", "ColorChooserPopup", "ColorDetailsDialog", "ColorHistoryPopup", "PalettePrev", "PaletteNext", ] ## Behaviour flags class Behavior: """Broad classification of what a mode's handler methods do These flags are assigned to devices in `gui.device` to allow the user to limit what devices are allowed to do. Mode instances expose their behaviour by defining their pointer_behavior and scroll_behavior properties. """ NONE = 0x00 #: the mode does not perform any action PAINT_FREEHAND = 0x01 #: paint freehand brushstrokes PAINT_CONSTRAINED = 0x02 #: non-freehand painting: lines, or filling EDIT_OBJECTS = 0x04 #: move and adjust objects on screen CHANGE_VIEW = 0x08 #: move the viewport around # Useful masks NON_PAINTING = EDIT_OBJECTS | CHANGE_VIEW ALL_PAINTING = PAINT_FREEHAND | PAINT_CONSTRAINED ALL = NON_PAINTING | ALL_PAINTING ## Metaclass for all modes class ModeRegistry (type): """Lookup table for interaction modes and their associated actions Operates as the metaclass for `InteractionMode`, so all you need to do to create the association for a mode subclass is to define an ``ACTION_NAME`` entry in the class's namespace containing the name of the associated `gtk.Action` defined in ``resources.xml``. """ action_name_to_mode_class = {} mode_classes = set() # (Special-cased @staticmethod) def __new__(cls, name, bases, dict): """Creates and records a new (InteractionMode) class. :param cls: this metaclass :param name: name of the class under construction :param bases: immediate base classes of the class under construction :param dict: class dict for the class under construction :rtype: the constructed class, a regular InteractionMode class object If it exists, the ``ACTION_NAME`` entry in `dict` is recorded, and can be used as a key for lookup of the returned class via the ``@classmethod``s defined on `ModeRegistry`. """ action_name = dict.get("ACTION_NAME", None) mode_class = super(ModeRegistry, cls).__new__(cls, name, bases, dict) if action_name is not None: action_name = str(action_name) cls.action_name_to_mode_class[action_name] = mode_class cls.mode_classes.add(mode_class) return mode_class @classmethod def get_mode_class(cls, action_name): """Looks up a registered mode class by its associated action's name. :param action_name: a string containing an action name (see this metaclass's docs regarding the ``ACTION_NAME`` class variable) :rtype: an InteractionMode class object, or `None`. """ return cls.action_name_to_mode_class.get(action_name, None) @classmethod def get_action_names(cls): """Returns all action names associated with interaction. :rtype: an iterable of action name strings. """ return cls.action_name_to_mode_class.keys() ## Mode base classes class InteractionMode (object): """Required base class for temporary interaction modes. Active interaction mode objects process input events, and can manipulate document views (TiledDrawWidget), the document model data (lib.document), and the mode stack they sit on. Interactions encapsulate state about their particular kind of interaction; for example a drag interaction typically contains the starting position for the drag. Event handler methods can create new sub-modes and push them to the stack. It is conventional to pass the current event to the equivalent method on the new object when this transfer of control happens. Subclasses may nominate a related `GtkAction` instance in the UI by setting the class-level variable ``ACTION_NAME``: this should be the name of an action defined in `gui.app.Application.builder`'s XML file. """ ## Class configuration #: All InteractionMode subclasses register themselves. __metaclass__ = ModeRegistry #: See the docs for `gui.mode.ModeRegistry`. ACTION_NAME = None #: True if the mode supports live update from the brush editor IS_LIVE_UPDATEABLE = False #: Timeout for Document.mode_flip_action_activated_cb(). How long, in #: milliseconds, it takes for the controller to change the key-up action #: when activated with a keyboard "Flip" action. Set to zero #: for modes where key-up should exit the mode at any time, and to a larger #: number for modes where the behaviour changes. keyup_timeout = 500 ## Defaults for instances (sue me, I'm lazy) #: The `gui.document.Document` this mode affects: see enter() doc = None #: Broad description of what result clicking, moving the pointer, #: or dragging has in this mode. See `Behavior`. pointer_behavior = Behavior.NONE #: Broad description of what result scrolling a mouse scroll-wheel #: does in this mode. See `Behavior`. scroll_behavior = Behavior.NONE #: True if the mode supports switching to another mode based on #: combinations of pointer buttons and modifier keys. supports_button_switching = True #: Optional whitelist of the names of the modes which this mode can #: switch to. If the iterable is empty, all modes are possible. permitted_switch_actions = () ## Status message info @classmethod def get_name(cls): """Returns a short human-readable description of the mode. :rtype: unicode This is used for status bar messages, and potentially elsewhere before the mode has been instantiated. All concrete subclasses should override this. By default the (non-localized) class name is returned. When capitalizing, use whatever style the GNOME HIG specifies for menu items. In English, this is currently "header", or title case (first word capitalized, all other words capitalized except closed-class words). Do not use trailing punctuation. """ return unicode(cls.__name__) def get_usage(self): """Returns a medium-length usage message for the mode. :rtype: unicode This is used for status bar messages. All concrete subclasses should override this. The default return value is an empty string. The usage message should be a short, natural-sounding explanation to the user detailing what the current mode is for. Note that the usage message is typically displayed after the mode's name or explanatory icon, so there is no need to repeat that. Brevity is important because space is limited. When capitalizing, use whatever style the GNOME HIG specifies for tooltips. In English, this is currently sentence case. Use one complete sentence, and always omit the the trailing period. """ return u"" def __unicode__(self): return self.get_name() ## Associated action def get_action(self): """Returns any app action associated with the mode.""" if self.doc and hasattr(self.doc, "app"): if self.ACTION_NAME: return self.doc.app.find_action(self.ACTION_NAME) ## Mode icon def get_icon_name(self): """Returns the icon to use when representing the mode. If there's an associated action, this method returns the icon associated with the action. """ icon_name = None action = self.get_action() if action: icon_name = action.get_icon_name() if not icon_name: return 'missing-icon' return icon_name ## Mode stacking interface def stackable_on(self, mode): """Tests whether the mode can usefully stack onto an active mode. :param mode: another mode object :rtype: bool This method should return True if this mode can usefully be stacked onto another mode when switching via toolbars buttons or other actions. """ return False def enter(self, doc, **kwds): """Enters the mode: called by `ModeStack.push()` etc. :param doc: the `gui.document.Document` this mode should affect. A reference is kept in `self.doc`. This is called when the mode becomes active, i.e. when it becomes the top mode on a ModeStack, and before input is sent to it. Note that a mode may be entered only to be left immediately: mode stacks are cleared by repeated pop()ing. """ self.doc = doc assert not hasattr(super(InteractionMode, self), "enter") def leave(self): """Leaves the mode: called by `ModeStack.pop()` etc. This is called when an active mode becomes inactive, i.e. when it is no longer the top mode on its ModeStack. It should commit any uncommitted work to the undo stack, just as `checkpoint()` does. """ self.doc = None assert not hasattr(super(InteractionMode, self), "leave") def checkpoint(self, **kwargs): """Commits any of the mode's uncommitted work This is called on the active mode at various times to signal that pending work should be committed to the command stack now, so that the Undo command would be able to undo it if it were called next. The mode continues to be active. This method is not automatically invoked when changing modes: leave() should manage that transition. """ assert not hasattr(super(InteractionMode, self), "checkpoint") ## Event handler defaults (no-ops) def button_press_cb(self, tdw, event): """Handler for ``button-press-event``s.""" assert not hasattr(super(InteractionMode, self), "button_press_cb") def motion_notify_cb(self, tdw, event): """Handler for ``motion-notify-event``s.""" assert not hasattr(super(InteractionMode, self), "motion_notify_cb") def button_release_cb(self, tdw, event): """Handler for ``button-release-event``s.""" assert not hasattr(super(InteractionMode, self), "button_release_cb") def scroll_cb(self, tdw, event): """Handler for ``scroll-event``s. """ assert not hasattr(super(InteractionMode, self), "scroll_cb") def key_press_cb(self, win, tdw, event): """Handler for ``key-press-event``s. The base class implementation does nothing. Keypresses are received by the main window only, but at this point it has applied some heuristics to determine the active doc and view. These are passed through to the active mode and are accessible to keypress handlers via `self.doc` and the `tdw` argument. """ assert not hasattr(super(InteractionMode, self), "key_press_cb") return True def key_release_cb(self, win, tdw, event): """Handler for ``key-release-event``s. The base class implementation does nothing. See `key_press_cb` for details of the additional arguments. """ assert not hasattr(super(InteractionMode, self), "key_release_cb") return True ## Drag sub-API (FIXME: this is in the wrong place) # Defined here to allow mixins to provide behaviour for both both drags and # regular events without having to derive from DragMode. Really these # buck-stops-here definitions belong in DragMode, so consider moving them # somewhere more sensible. def drag_start_cb(self, tdw, event): assert not hasattr(super(InteractionMode, self), "drag_start_cb") def drag_update_cb(self, tdw, event, dx, dy): assert not hasattr(super(InteractionMode, self), "drag_update_cb") def drag_stop_cb(self, tdw): assert not hasattr(super(InteractionMode, self), "drag_stop_cb") ## Internal utility functions def current_modifiers(self): """Returns the current set of modifier keys as a Gdk bitmask. See: gui.document.Document.get_current_modifiers() """ doc = self.doc if self.doc is None: modifiers = gdk.ModifierType(0) else: modifiers = self.doc.get_current_modifiers() return modifiers def current_position(self): """Returns the current client pointer position on the main TDW For use in enter() methods: since the mode may be being entered by the user pressing a key, no position is available at this point. Normal event handlers should use their argument GdkEvents to determing position. """ disp = self.doc.tdw.get_display() mgr = disp.get_device_manager() dev = mgr.get_client_pointer() win = self.doc.tdw.get_window() underwin, x, y, mods = win.get_device_position(dev) return x, y class ScrollableModeMixin (InteractionMode): """Mixin for scrollable modes. Implements some immediate rotation and zoom commands for the scroll wheel. These should be useful in many modes, but perhaps not all. """ # Hack conversion factor from smooth scroll units to screen pixels. _PIXELS_PER_SMOOTH_SCROLL_UNIT = 25.0 # Could also use the viewport-page-sized approximation that # Gtk.ScrolledWindow uses internally: # https://git.gnome.org/browse/gtk+/tree/gtk/gtkscrolledwindow.c?h=gtk-3-14#n2416 def __reset_delta_totals(self): self.__total_dx = 0.0 self.__total_dy = 0.0 def enter(self, doc, **kwds): self.__reset_delta_totals() return super(ScrollableModeMixin, self).enter(doc, **kwds) def button_press_cb(self, tdw, event): self.__reset_delta_totals() return super(ScrollableModeMixin, self).button_press_cb(tdw, event) def button_release_cb(self, tdw, event): self.__reset_delta_totals() return super(ScrollableModeMixin, self).button_release_cb(tdw, event) def scroll_cb(self, tdw, event): """Handles scroll-wheel events. Normal scroll wheel events: whichever of {panning, scrolling} the device is configured to do. With Ctrl or Alt: invert scrolling and zooming. With shift, if smooth scroll events are being sent, constrain the zoom or scroll in appropriate chunks. """ doc = self.doc direction = event.direction dev_mon = doc.app.device_monitor dev = event.get_source_device() dev_settings = dev_mon.get_device_settings(dev) scroll_action = dev_settings.scroll # Invert scrolling and zooming if Ctrl or Alt is held import gui.device if event.state & (gdk.MOD1_MASK | gdk.CONTROL_MASK): if scroll_action == gui.device.ScrollAction.ZOOM: scroll_action = gui.device.ScrollAction.PAN elif scroll_action == gui.device.ScrollAction.PAN: scroll_action = gui.device.ScrollAction.ZOOM # Force incremental scrolling or zooming when shift is held. constrain_smooth = (event.state & gdk.SHIFT_MASK) if direction == gdk.SCROLL_SMOOTH: self.__total_dx += event.delta_x self.__total_dy += event.delta_y # Handle zooming (the old default) # We don't rotate any more though. Srsly, that was awful. if scroll_action == gui.device.ScrollAction.ZOOM: if direction == gdk.SCROLL_SMOOTH: if constrain_smooth: # Needs to work in an identical fashion to old-style # zooming. while self.__total_dy > 1: self.__total_dy -= 1.0 doc.zoom(doc.ZOOM_OUTWARDS) while self.__total_dy < -1: self.__total_dy += 1.0 doc.zoom(doc.ZOOM_INWARDS) else: # Smooth scroll zooming is intended to resemble what # gui.viewmanip.ZoomViewMode does, minus the # panning. In other words, simple zooming at the # cursor. dx = event.delta_x dy = event.delta_y dx *= self._PIXELS_PER_SMOOTH_SCROLL_UNIT dy *= self._PIXELS_PER_SMOOTH_SCROLL_UNIT # Don't pan: that's because the cursor generally does # not move during scroll events. # tdw.scroll(-dx, 0) # not for now dy *= -1 tdw.zoom( math.exp(dy/100.0), center = (event.x, event.y), ongoing = True, ) tdw.renderer.update_cursor() self.__reset_delta_totals() # Need to send the notifications here if not # callling doc methods. # https://github.com/mypaint/mypaint/issues/313 doc.notify_view_changed() # Old-style zooming elif direction == gdk.SCROLL_UP: doc.zoom(doc.ZOOM_INWARDS) self.__reset_delta_totals() elif direction == gdk.SCROLL_DOWN: doc.zoom(doc.ZOOM_OUTWARDS) self.__reset_delta_totals() # Handle scroll panning. elif scroll_action == gui.device.ScrollAction.PAN: if direction == gdk.SCROLL_SMOOTH: if constrain_smooth: # Holding shift to constrain the pan works like # discrete panning below. while self.__total_dy > 1: self.__total_dy -= 1.0 doc.pan(doc.PAN_DOWN) while self.__total_dy < -1: self.__total_dy += 1.0 doc.pan(doc.PAN_UP) while self.__total_dx > 1: self.__total_dx -= 1.0 doc.pan(doc.PAN_RIGHT) while self.__total_dx < -1: self.__total_dx += 1.0 doc.pan(doc.PAN_LEFT) else: # Smooth panning is *nice*. It should work identically to # gui.viewmanip.PanViewMode. # No inertia here. Too many touchpads already # emulate that, some by default and others not. dx = event.delta_x dy = event.delta_y dx *= self._PIXELS_PER_SMOOTH_SCROLL_UNIT dy *= self._PIXELS_PER_SMOOTH_SCROLL_UNIT tdw.scroll(dx, dy, ongoing=True) doc.notify_view_changed() self.__reset_delta_totals() # Discrete panning. elif direction == gdk.SCROLL_UP: doc.pan(doc.PAN_UP) self.__reset_delta_totals() elif direction == gdk.SCROLL_DOWN: doc.pan(doc.PAN_DOWN) self.__reset_delta_totals() elif direction == gdk.SCROLL_LEFT: doc.pan(doc.PAN_LEFT) self.__reset_delta_totals() elif direction == gdk.SCROLL_RIGHT: doc.pan(doc.PAN_RIGHT) self.__reset_delta_totals() return super(ScrollableModeMixin, self).scroll_cb(tdw, event) class PaintingModeOptionsWidgetBase (gtk.Grid): """Base class for the options widget of a generic painting mode""" _COMMON_SETTINGS = [ #TRANSLATORS: "Brush radius" for the options panel. Short. ('radius_logarithmic', _("Size:")), #TRANSLATORS: "Brush opacity" for the options panel. Short. ('opaque', _("Opaque:")), #TRANSLATORS: "Brush hardness/sharpness" for the options panel. Short. ('hardness', _("Sharp:")), #TRANSLATORS: "Additional pressure gain" for the options panel. Short. ('pressure_gain_log', _("Gain:")), ] def __init__(self): gtk.Grid.__init__(self) self.set_row_spacing(6) self.set_column_spacing(6) from application import get_app self.app = get_app() self.adjustable_settings = set() #: What the reset button resets row = self.init_common_widgets(0) row = self.init_specialized_widgets(row) row = self.init_reset_widgets(row) def init_common_widgets(self, row): for cname, text in self._COMMON_SETTINGS: label = gtk.Label() label.set_text(text) label.set_alignment(1.0, 0.5) label.set_hexpand(False) self.adjustable_settings.add(cname) adj = self.app.brush_adjustment[cname] scale = gtk.HScale(adj) scale.set_draw_value(False) scale.set_hexpand(True) self.attach(label, 0, row, 1, 1) self.attach(scale, 1, row, 1, 1) row += 1 return row def init_specialized_widgets(self, row): return row def init_reset_widgets(self, row): align = gtk.Alignment(0.5, 1.0, 1.0, 0.0) align.set_vexpand(True) self.attach(align, 0, row, 2, 1) button = gtk.Button(_("Reset")) button.connect("clicked", self.reset_button_clicked_cb) align.add(button) row += 1 return row def reset_button_clicked_cb(self, button): app = self.app bm = app.brushmanager parent_brush = bm.get_parent_brush(brushinfo=app.brush) if parent_brush: parent_binf = parent_brush.get_brushinfo() for cname in self.adjustable_settings: parent_value = parent_binf.get_base_value(cname) adj = self.app.brush_adjustment[cname] adj.set_value(parent_value) app.brushmodifier.normal_mode.activate() class BrushworkModeMixin (InteractionMode): """Mixin for modes using brushes This mixin adds the ability to paint undoably to the current layer with proper atomicity and handling of checkpoints, and time-based automatic commits. Classes using this mixin should use `stroke_to()` to paint, and then may use the `brushwork_commit()` method to commit completed segments atomically to the command stack. If a subclass needs greater control over new segments, `brushwork_begin()` can be used to start them recording. The `leave()` and `checkpoint()` methods defined here cooperatively commit all outstanding brushwork. """ def __init__(self, abrupt_start=False, **kwds): """Cooperative init (this mixin initializes some private fields) :param bool abrupt_start: Make the 1st brushwork_begin() abrupt :param bool \*\*kwds: Passed through to other __init__s. Starting the first segment of brushwork abruptly makes the first segment cleaner in a (very limited) number of cases. See https://github.com/mypaint/mypaint/issues/11. """ super(BrushworkModeMixin, self).__init__(**kwds) self.__abrupt_start = abrupt_start self.__active_brushwork = {} # {model: Brushwork} def brushwork_begin(self, model, description=None, abrupt=False): """Begins a new segment of active brushwork for a model :param lib.document.Document model: The model to begin work on :param unicode description: Optional description of the work :param bool abrupt: Fake a zero-pressure "stroke_to()" at start Passing ``None`` for the description is suitable for freehand drawing modes. This method will be called automatically with the default options by `stroke_to()` if needed, so not all subclasses need to use it. """ # Commit any previous work for this model cmd = self.__active_brushwork.get(model) if cmd is not None: self.brushwork_commit(model, abrupt=abrupt) # New segment of brushwork layer_path = model.layer_stack.current_path cmd = lib.command.Brushwork( model, layer_path, description=description, abrupt_start=(abrupt or self.__abrupt_start), ) self.__abrupt_start = False cmd.__last_pos = None self.__active_brushwork[model] = cmd def brushwork_commit(self, model, abrupt=False): """Commits any active brushwork for a model to the command stack :param lib.document.Document model: The model to commit work to :param bool abrupt: End with a faked zero pressure "stroke_to()" This only makes a new entry on the command stack if the currently active brushwork segment made any changes to the model. See also `brushwork_rollback()`. """ cmd = self.__active_brushwork.pop(model, None) if cmd is None: return if abrupt and cmd.__last_pos is not None: x, y, xtilt, ytilt = cmd.__last_pos pressure = 0.0 dtime = 0.0 cmd.stroke_to(dtime, x, y, pressure, xtilt, ytilt) changed = cmd.stop_recording(revert=False) if changed: model.do(cmd) def brushwork_rollback(self, model): """Rolls back any active brushwork for a model :param lib.document.Document model: The model to roll back This restores the model's appearance and state to how it was when the current segment of brushwork started. For input patterns where this makes sense, your calls to `stroke_to()` should have ``auto_split=False``. See also `brushwork_commit()`. """ cmd = self.__active_brushwork.pop(model, None) if cmd is None: return cmd.stop_recording(revert=True) def brushwork_commit_all(self, abrupt=False): """Commits all active brushwork""" for model in list(self.__active_brushwork.keys()): self.brushwork_commit(model, abrupt=abrupt) def brushwork_rollback_all(self): """Rolls back all active brushwork""" for model in list(self.__active_brushwork.keys()): self.brushwork_rollback(model) def stroke_to(self, model, dtime, x, y, pressure, xtilt, ytilt, auto_split=True): """Feeds an updated stroke position to the brush engine :param lib.document.Document model: model on which to paint :param float dtime: Seconds since the last call to this method :param float x: Document X position update :param float y: Document Y position update :param float pressure: Pressure, ranging from 0.0 to 1.0 :param float xtilt: X-axis tilt, ranging from -1.0 to 1.0 :param float ytilt: Y-axis tilt, ranging from -1.0 to 1.0 :param bool auto_split: Split ongoing brushwork if due During normal operation, succesive calls to `stroke_to()` record an ongoing sequence of `lib.command.Brushwork` commands on the undo stack, stopping and committing the currently recording command when it becomes due. """ cmd = self.__active_brushwork.get(model, None) desc0 = None if auto_split and cmd and cmd.split_due: desc0 = cmd.description # retain for the next cmd self.brushwork_commit(model, abrupt=False) assert model not in self.__active_brushwork cmd = None if not cmd: self.brushwork_begin(model, description=desc0, abrupt=False) cmd = self.__active_brushwork[model] cmd.stroke_to(dtime, x, y, pressure, xtilt, ytilt) cmd.__last_pos = (x, y, xtilt, ytilt) def leave(self, **kwds): """Leave mode, committing outstanding brushwork as necessary The leave action defined here is careful to tail off strokes cleanly: certain subclasses are geared towards fast capture of data and queued delivery of stroke information, so we have to reset the brush engine's idea of pressure fast. If we don't, an interrupted queued stroke can result in a *huge* sequence of dabs from the last processed position to wherever the cursor is right now. This leave() knows about the mode stack, and only commits if it knows it isn't still stacked. That's to allow temporary view manipulation modes to work without disrupting `gui.inktool`'s mode, which normally has a lot pending. """ logger.debug("BrushworkModeMixin: leave()") still_stacked = False for mode in self.doc.modes: if mode is self: still_stacked = True break if not still_stacked: self.brushwork_commit_all(abrupt=True) super(BrushworkModeMixin, self).leave(**kwds) def checkpoint(self, **kwargs): """Commit any outstanding brushwork Like `leave()`, this commits the currently recording Brushwork command for each known model; however we do not attempt to tail off brushstrokes cleanly because that would make Freehand mode discontinuous when the user changes the brush color. """ logger.debug("BrushworkModeMixin: checkpoint()") super(BrushworkModeMixin, self).checkpoint(**kwargs) self.brushwork_commit_all(abrupt=False) class SingleClickMode (InteractionMode): """Base class for non-drag (single click) modes""" #: The cursor to use when entering the mode # FIXME: Use Gdk.Cursor.new_for_display; read-only property cursor = gdk.Cursor.new(gdk.CursorType.ARROW) def __init__(self, ignore_modifiers=False, **kwds): super(SingleClickMode, self).__init__(**kwds) self._button_pressed = None def enter(self, doc, **kwds): super(SingleClickMode, self).enter(doc, **kwds) assert self.doc is not None self.doc.tdw.set_override_cursor(self.cursor) def leave(self, **kwds): if self.doc is not None: self.doc.tdw.set_override_cursor(None) super(SingleClickMode, self).leave(**kwds) def button_press_cb(self, tdw, event): if event.button == 1 and event.type == gdk.BUTTON_PRESS: self._button_pressed = 1 return False else: return super(SingleClickMode, self).button_press_cb(tdw, event) def button_release_cb(self, tdw, event): if event.button == self._button_pressed: self._button_pressed = None self.clicked_cb(tdw, event) return False else: return super(SingleClickMode, self).button_press_cb(tdw, event) def clicked_cb(self, tdw, event): assert not hasattr(super(SingleClickMode, self), "clicked_cb") class DragMode (InteractionMode): """Base class for drag activities. Dragm modes can be entered when the button is pressed, or not yet pressed. If the button is pressed when the mode is entered. the initial position will be determined from the first motion event. Drag modes are normally "spring-loaded", meaning that when a drag mode is first entered, it remembers which modifier keys were held down at that time. When these keys are released, the mode will exit. """ # FIXME: Use Gdk.Cursor.new_for_display; read-only property inactive_cursor = gdk.Cursor.new(gdk.CursorType.ARROW) active_cursor = None #: If true, exit mode when initial modifiers are released SPRING_LOADED = True def __init__(self, ignore_modifiers=False, **kwds): """Construct, possibly ignoring initial modifiers. :param ignore_modifiers: If True, ignore initial modifier keys. Drag modes can be instructed to ignore the initial set of modifiers when they're entered. This is appropriate when the mode is being entered in response to a keyboard shortcut. Modifiers don't mean the same thing for keyboard shortcuts. Conversely, toolbar buttons and mode-switching via pointer buttons should use the default behaviour. In practice, it's not quite so clear cut. Instead we have keyboard-friendly "Flip*" actions which allow the mode to be toggled off with a second press. These actions use the `ignore_modifiers` behaviour, and coexist with a secondary layer of radioactions which don't do this, but which reflect the state prettily. """ super(DragMode, self).__init__(**kwds) self._tdw_grab_broken_conninfo = None self._reset_drag_state() self.initial_modifiers = None #: Ignore the initial modifiers (FIXME: bad name, maybe not public?) self.ignore_modifiers = ignore_modifiers def _reset_drag_state(self): self.last_x = None self.last_y = None self.start_x = None self.start_y = None self._start_keyval = None self._start_button = None self._grab_widget = None if self._tdw_grab_broken_conninfo is not None: tdw, connid = self._tdw_grab_broken_conninfo tdw.disconnect(connid) self._tdw_grab_broken_conninfo = None def _stop_drag(self, t=gdk.CURRENT_TIME): # Stops any active drag, calls drag_stop_cb(), and cleans up. if not self.in_drag: return tdw = self._grab_widget tdw.grab_remove() gdk.keyboard_ungrab(t) gdk.pointer_ungrab(t) self._grab_widget = None self.drag_stop_cb(tdw) self._reset_drag_state() def _start_drag(self, tdw, event): # Attempt to start a new drag, calling drag_start_cb() if successful. if self.in_drag: return if hasattr(event, "x"): self.start_x = event.x self.start_y = event.y else: last_t, last_x, last_y = self.doc.get_last_event_info(tdw) self.start_x = last_x self.start_y = last_y tdw_window = tdw.get_window() event_mask = (gdk.BUTTON_PRESS_MASK | gdk.BUTTON_RELEASE_MASK | gdk.POINTER_MOTION_MASK) cursor = self.active_cursor if cursor is None: cursor = self.inactive_cursor # Grab the pointer grab_status = gdk.pointer_grab(tdw_window, False, event_mask, None, cursor, event.time) if grab_status != gdk.GRAB_SUCCESS: logger.warning("pointer grab failed: %r", grab_status) logger.debug("gdk_pointer_is_grabbed(): %r", gdk.pointer_is_grabbed()) # There seems to be a race condition between this grab under # PyGTK/GTK2 and some other grab - possibly just the implicit grabs # on color selectors: https://gna.org/bugs/?20068 Only pointer # events are affected, and PyGI+GTK3 is unaffected. # # It's probably safest to exit the mode and not start the drag. # This condition should be rare enough for this to be a valid # approach: the irritation of having to click again to do something # should be far less than that of getting "stuck" in a drag. self._bailout() # Sometimes a pointer ungrab is needed even though the grab # apparently failed to avoid the UI partially "locking up" with the # stylus (and only the stylus). Happens when WMs like Xfwm # intercept an Button combination for window management # purposes. Results in gdk.GRAB_ALREADY_GRABBED, but this line is # necessary to avoid the rest of the UI becoming unresponsive even # though the canvas can be drawn on with the stylus. Are we # cancelling an implicit grab here, and why is it device specific? gdk.pointer_ungrab(event.time) return # We managed to establish a grab, so watch for it being broken. # This signal is disconnected when the mode leaves. connid = tdw.connect("grab-broken-event", self._tdw_grab_broken_cb) self._tdw_grab_broken_conninfo = (tdw, connid) # Grab the keyboard too, to be certain of getting the key release event # for a spacebar drag. grab_status = gdk.keyboard_grab(tdw_window, False, event.time) if grab_status != gdk.GRAB_SUCCESS: logger.warning("Keyboard grab failed: %r", grab_status) self._bailout() gdk.pointer_ungrab(event.time) return # GTK too... tdw.grab_add() self._grab_widget = tdw # Drag has started, perform whatever action the mode needs. self.drag_start_cb(tdw, event) def _bailout(self): """Attempt to exit this mode safely, via an idle routine The actual task is handled by an idle callback to make this method safe to call during a mode's enter() or leave() methods. Modes on top of the one requesting bailout will also be ejected. """ from application import get_app app = get_app() if self not in app.doc.modes: logger.debug( "bailout: cannot bail out of %r: " "mode is not in the mode stack", self, ) return logger.debug("bailout: starting idler to safely bail out of %r", self) gobject.idle_add(self._bailout_idle_cb, app.doc.modes) def _bailout_idle_cb(self, modestack): """Bail out of this mode if it's anywhere in the mode stack""" while self in modestack: logger.debug("bailout idler: leaving %r", modestack.top) modestack.pop() logger.debug("bailout idler: done") return False def _tdw_grab_broken_cb(self, tdw, event): # Cede control as cleanly as possible if something else grabs either # the keyboard or the pointer while a grab is active. # One possible cause for https://gna.org/bugs/?20333 logger.debug("grab-broken-event on %r", tdw) logger.debug(" send_event : %r", event.send_event) logger.debug(" keyboard : %r", event.keyboard) logger.debug(" implicit : %r", event.implicit) logger.debug(" grab_window : %r", event.grab_window) self._bailout() return True @property def in_drag(self): return self._grab_widget is not None def enter(self, doc, **kwds): """Enter the mode, recording the held modifier keys the 1st time The attribute `self.initial_modifiers` is set the first time the mode is entered. """ super(DragMode, self).enter(doc, **kwds) assert self.doc is not None self.doc.tdw.set_override_cursor(self.inactive_cursor) if self.SPRING_LOADED: if self.ignore_modifiers: self.initial_modifiers = 0 return old_modifiers = getattr(self, "initial_modifiers", None) if old_modifiers is not None: # Re-entering due to an overlying mode being popped if old_modifiers != 0: # This mode started with modifiers held modifiers = self.current_modifiers() if (modifiers & old_modifiers) == 0: # But none of them are held any more, # so queue a further pop. gobject.idle_add(self.__pop_modestack_idle_cb) else: # This mode is being entered for the first time; # record modifiers modifiers = self.current_modifiers() self.initial_modifiers = self.current_modifiers() def __pop_modestack_idle_cb(self): # Pop the mode stack when this mode is re-entered but has to leave # straight away because its modifiers are no longer held. Doing it in # an idle function avoids confusing the derived class's enter() method: # a leave() during an enter() would be strange. if self.initial_modifiers is not None: if self.doc and (self is self.doc.modes.top): self.doc.modes.pop() return False def leave(self, **kwds): self._stop_drag() if self.doc is not None: self.doc.tdw.set_override_cursor(None) super(DragMode, self).leave(**kwds) def button_press_cb(self, tdw, event): if event.type == gdk.BUTTON_PRESS: if self.in_drag: if self._start_button is None: # Doing this allows single clicks to exit keyboard # initiated drags, e.g. those forced when handling a # keyboard event somewhere else. self._start_button = event.button else: self._start_drag(tdw, event) if self.in_drag: # Grab succeeded self.last_x = event.x self.last_y = event.y self._start_button = event.button return super(DragMode, self).button_press_cb(tdw, event) def button_release_cb(self, tdw, event): if self.in_drag: if event.button == self._start_button: self._stop_drag() return super(DragMode, self).button_release_cb(tdw, event) def motion_notify_cb(self, tdw, event): # We might be here because an Action manipulated the modes stack # but if that's the case then we should wait for a button or # a keypress to initiate the drag. if self.in_drag: if self.last_x is not None: dx = event.x - self.last_x dy = event.y - self.last_y self.drag_update_cb(tdw, event, dx, dy) self.last_x = event.x self.last_y = event.y return True # Fall through to other behavioral mixins, just in case return super(DragMode, self).motion_notify_cb(tdw, event) def key_press_cb(self, win, tdw, event): if self.in_drag: # Eat keypresses in the middle of a drag no matter how # it was started. return True elif event.keyval == keysyms.space: # Start drags on space if event.keyval != self._start_keyval: self._start_keyval = event.keyval self._start_drag(tdw, event) return True # Fall through to other behavioral mixins return super(DragMode, self).key_press_cb(win, tdw, event) def key_release_cb(self, win, tdw, event): if self.in_drag: if event.keyval == self._start_keyval: self._stop_drag() self._start_keyval = None return True if self.SPRING_LOADED: if event.is_modifier and self.in_drag: return False if self.initial_modifiers: modifiers = self.current_modifiers() if modifiers & self.initial_modifiers == 0: if self is self.doc.modes.top: self.doc.modes.pop() return True # Fall through to other behavioral mixins return super(DragMode, self).key_release_cb(win, tdw, event) class OneshotDragMode (DragMode): """Drag modes that can exit immediately when the drag stops These are utility modes which allow the user to do quick, simple tasks with the canvas like pick a color from it or pan the view. """ def __init__(self, unmodified_persist=True, temporary_activation=True, **kwargs): """ :param bool unmodified_persist: Stay active if entered without modkeys :param bool \*\*kwargs: Passed through to other __init__s. If unmodified_persist is true, and drag mode is spring-loaded, the tool will stay active if no modifiers were held initially. This means tools will not deselect themselves after one use if activated from, say, the toolbar. """ DragMode.__init__(self) self.unmodified_persist = unmodified_persist self.temporary_activation = temporary_activation def stackable_on(self, mode): """Oneshot modes return to the mode the user came from on exit""" return not isinstance(mode, OneshotDragMode) def drag_stop_cb(self, tdw): if not hasattr(self, "initial_modifiers"): # Always exit at the end of a drag if not spring-loaded. if self is self.doc.modes.top: self.doc.modes.pop() elif self.initial_modifiers != 0: # If started with modifiers, keeping the modifiers held keeps # spring-loaded modes active. If not, exit the mode. if (self.initial_modifiers & self.current_modifiers()) == 0: if self is self.doc.modes.top: self.doc.modes.pop() else: # No modifiers were held when this mode was entered. if self.temporary_activation or (not self.unmodified_persist): if self is self.doc.modes.top: self.doc.modes.pop() return super(OneshotDragMode, self).drag_stop_cb(tdw) ## Mode stack class _NullMode (InteractionMode): """A mode that does nothing (placeholder only)""" class ModeStack (object): """A stack of InteractionModes. The top mode is the active one. Mode stacks can never be empty. If the final element is popped, it will be replaced with a new instance of its ``default_mode_class``, instantiated with ``**default_mode_kwargs``. """ def __init__(self, doc): """Initialize for a particular controller :param doc: Controller instance :type doc: gui.document.CanvasController The main MyPaint app uses an instance of `gui.document.Document` as `doc`. Simpler drawing canvases can use a basic CanvasController and a simpler `default_mode_class`. """ object.__init__(self) self._stack = [] self._doc = doc self._syncing_pending_changes = False if hasattr(doc, "model"): doc.model.sync_pending_changes += self._sync_pending_changes_cb #: Class to instantiate if stack is empty: callable with 0 args. default_mode_class = _NullMode #: Keyword parameters for default_mode_class. default_mode_kwargs = {} def _sync_pending_changes_cb(self, model, **kwargs): """Syncs pending changes with the model :param lib.document.Document model: the requesting model :param \*\*kwargs: passed through to checkpoint() This issues a `checkpoint()` on the current InteractionMode. """ if self._syncing_pending_changes: return self._syncing_pending_changes = True self.top.checkpoint(**kwargs) self._syncing_pending_changes = False @event def changed(self, old, new): """Event: emitted when the active mode changes :param old: The previous active mode :param new: The new `top` (current) mode This event is emitted after the ``enter()`` method of the new mode has been called, and therefore after the ``leave()`` of the old mode too. On occasion, the old mode may be null. Context-aware pushes call this only once, with the old active and newly active mode only regardless of how many modes were skipped. """ @property def top(self): """The top node on the stack""" # Perhaps rename to "active()"? new_mode = self._check() if new_mode is not None: new_mode.enter(doc=self._doc) self.changed(None, new_mode) return self._stack[-1] def context_push(self, mode): """Context-aware push. :param mode: mode to be stacked and made active :type mode: `InteractionMode` Stacks a mode onto the topmost element in the stack it is compatible with, as determined by its ``stackable_on()`` method. Incompatible top modes are popped one by one until either a compatible mode is found, or the stack is emptied, then the new mode is pushed. """ # Pop until the stack is empty, or the top mode is compatible old_mode = None if len(self._stack) > 0: old_mode = self._stack[-1] while len(self._stack) > 0: if mode.stackable_on(self._stack[-1]): break self._stack.pop(-1).leave() if len(self._stack) > 0: self._stack[-1].enter(doc=self._doc) # Stack on top of any remaining compatible mode if len(self._stack) > 0: self._stack[-1].leave() self._stack.append(mode) mode.enter(doc=self._doc) self.changed(old=old_mode, new=mode) def pop(self): """Pops a mode, leaving the old top mode and entering the exposed top. """ old_mode = None if len(self._stack) > 0: old_mode = self._stack.pop(-1) old_mode.leave() top_mode = self._check() if top_mode is None: top_mode = self._stack[-1] # No need to checkpoint user activity here: leave() was already called top_mode.enter(doc=self._doc) self.changed(old=old_mode, new=top_mode) def push(self, mode): """Pushes a mode, and enters it. :param mode: Mode to be stacked and made active :type mode: InteractionMode """ old_mode = None if len(self._stack) > 0: old_mode = self._stack[-1] old_mode.leave() # No need to checkpoint user activity here: leave() was already called self._stack.append(mode) mode.enter(doc=self._doc) self.changed(old=old_mode, new=mode) def reset(self, replacement=None): """Clears the stack, popping the final element and replacing it. :param replacement: Optional mode to go on top of the cleared stack. :type replacement: `InteractionMode`. """ old_top_mode = None if len(self._stack) > 0: old_top_mode = self._stack[-1] while len(self._stack) > 0: old_mode = self._stack.pop(-1) old_mode.leave() if len(self._stack) > 0: self._stack[-1].enter(doc=self._doc) top_mode = self._check(replacement) assert top_mode is not None self.changed(old=old_top_mode, new=top_mode) def _check(self, replacement=None): """Ensures that the stack is non-empty :param replacement: Optional replacement mode instance. :type replacement: `InteractionMode`. Returns the new top mode if one was pushed. """ if len(self._stack) > 0: return None if replacement is not None: mode = replacement else: mode = self.default_mode_class(**self.default_mode_kwargs) self._stack.append(mode) mode.enter(doc=self._doc) return mode def __repr__(self): """Plain-text representation.""" s = '