Source code for enable.component

# (C) Copyright 2005-2022 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 the Component class """

from uuid import uuid4

# Enthought library imports
from traits.api import (
    Any, Bool, Delegate, Enum, Float, Instance, Int, List, Property, Str, Union
from kiva.api import FILL, STROKE

# Local relative imports
from .colors import black_color_trait, white_color_trait
from .coordinate_box import CoordinateBox
from .enable_traits import LineStyle, bounds_trait, coordinate_trait
from .interactor import Interactor

coordinate_delegate = Delegate("inner", modify=True)

[docs]class Component(CoordinateBox, Interactor): """ Component is the base class for most Enable objects. In addition to the basic position and container features of Component, it also supports Viewports and has finite bounds. Since Components can have a border and padding, there is an additional set of bounds and position attributes that define the "outer box" of the components. These cannot be set, since they are secondary attributes (computed from the component's "inner" size and margin-area attributes). """ # ------------------------------------------------------------------------ # Basic appearance traits # ------------------------------------------------------------------------ # Is the component visible? visible = Bool(True) # Does the component use space in the layout even if it is not visible? invisible_layout = Bool(False) # Fill the padding area with the background color? fill_padding = Bool(False) # ------------------------------------------------------------------------ # Object/containment hierarchy traits # ------------------------------------------------------------------------ # Our container object container = Any # Instance("Container") # A reference to our top-level Enable Window. This is stored as a shadow # attribute if this component is the direct child of the Window; otherwise, # the getter function recurses up the containment hierarchy. window = Property # Instance("Window") # The list of viewport that are viewing this component viewports = List(Instance("enable.viewport.Viewport")) # ------------------------------------------------------------------------ # Layout traits # ------------------------------------------------------------------------ # Dimensions that this component is resizable in. For resizable # components, get_preferred_size() is called before their actual # bounds are set. # # * 'v': resizable vertically # * 'h': resizable horizontally # * 'hv': resizable horizontally and vertically # * '': not resizable # # Note that this setting means only that the *parent* can and should resize # this component; it does *not* mean that the component automatically # resizes itself. resizable = Enum("hv", "h", "v", "") # The ratio of the component's width to its height. This is used by # the component itself to maintain bounds when the bounds are changed # independently, and is also used by the layout system. aspect_ratio = Union(None, Float) # When the component's bounds are set to a (width,height) tuple that does # not conform to the set aspect ratio, does the component center itself # in the free space? auto_center = Bool(True) # A read-only property that returns True if this component needs layout. # It is a reflection of both the value of the component's private # _layout_needed attribute as well as any logical layout dependencies with # other components. layout_needed = Property # If the component is resizable, this attribute can be used to specify the # amount of space that the component would like to get in each dimension, # as a tuple (width, height). This attribute can be used to establish # relative sizes between resizable components in a container: if one # component specifies, say, a fixed preferred width of 50 and another one # specifies a fixed preferred width of 100, then the latter component will # always be twice as wide as the former. fixed_preferred_size = Union(None, bounds_trait) # ------------------------------------------------------------------------ # Overlays and underlays # ------------------------------------------------------------------------ # A list of underlays for this plot. By default, underlays get a chance to # draw onto the plot area underneath plot itself but above any images and # backgrounds of the plot. underlays = List # [AbstractOverlay] # A list of overlays for the plot. By default, overlays are drawn above # the plot and its annotations. overlays = List # [AbstractOverlay] # Listen for changes to selection metadata on # the underlying data sources, and render them specially? use_selection = Bool(False) # ------------------------------------------------------------------------ # Tool and interaction handling traits # ------------------------------------------------------------------------ # An Enable Interactor that all events are deferred to. controller = Any # Events are *not* automatically considered "handled" if there is a handler # defined. Overrides an inherited trait from Enable's Interactor class. auto_handle_event = False # ------------------------------------------------------------------------ # Padding-related traits # Padding in each dimension is defined as the number of pixels that are # part of the component but outside of its position and bounds. Containers # need to be aware of padding when doing layout, object collision/overlay # calculations, etc. # ------------------------------------------------------------------------ # The amount of space to put on the left side of the component padding_left = Int(0) # The amount of space to put on the right side of the component padding_right = Int(0) # The amount of space to put on top of the component padding_top = Int(0) # The amount of space to put below the component padding_bottom = Int(0) # This property allows a way to set the padding in bulk. It can either be # set to a single Int (which sets padding on all sides) or a tuple/list of # 4 Ints representing the left, right, top, bottom padding amounts. When # it is read, this property always returns the padding as a list of four # elements even if they are all the same. padding = Property # Readonly property expressing the total amount of horizontal padding hpadding = Property # Readonly property expressing the total amount of vertical padding vpadding = Property # Does the component respond to mouse events over the padding area? padding_accepts_focus = Bool(True) # ------------------------------------------------------------------------ # Position and bounds of outer box (encloses the padding and border area) # All of these are read-only properties. To set them directly, use # set_outer_coordinates() or set_outer_pos_bounds(). # ------------------------------------------------------------------------ # The x,y point of the lower left corner of the padding outer box around # the component. Setting this position will move the component, but # will not change the padding or bounds. # This returns a tuple because modifying the returned value has no effect. # To modify outer_position element-wise, use set_outer_position(). outer_position = Property # The number of horizontal and vertical pixels in the padding outer box. # Setting these bounds will modify the bounds of the component, but # will not change the lower-left position (self.outer_position) or # the padding. # This returns a tuple because modifying the returned value has no effect. # To modify outer_bounds element-wise, use set_outer_bounds(). outer_bounds = Property outer_x = Property outer_x2 = Property outer_y = Property outer_y2 = Property outer_width = Property outer_height = Property # ------------------------------------------------------------------------ # Rendering control traits # ------------------------------------------------------------------------ # The order in which various rendering classes on this component are drawn. # Note that if this component is placed in a container, in most cases # the container's draw order is used, since the container calls # each of its contained components for each rendering pass. # Typically, the definitions of the layers are: # # #. 'background': Background image, shading, and (possibly) borders # #. 'mainlayer': The main layer that most objects should draw on # #. 'border': A special layer for rendering the border on top of the # component instead of under its main layer (see **overlay_border**) # #. 'overlay': Legends, selection regions, and other tool-drawn visual # elements draw_order = Instance(list, args=(DEFAULT_DRAWING_ORDER,)) # If True, then this component draws as a unified whole, # and its parent container calls this component's _draw() method when # drawing the layer indicated by **draw_layer**. # If False, it tries to cooperate in its container's layer-by-layer # drawing. Its parent container calls self._dispatch_draw() with the name # of each layer as it goes through its list of layers. unified_draw = Bool(False) # If **unified_draw** is True for this component, then this attribute # determines what layer it will be drawn on. This is used by containers # and external classes, whose drawing loops call this component. # If **unified_draw** is False, then this attribute is ignored. draw_layer = Str("mainlayer") # Draw the border as part of the overlay layer? If False, draw the # border as part of the background layer. overlay_border = Bool(True) # Draw the border inset (on the plot)? If False, draw the border # outside the plot area. inset_border = Bool(True) # ------------------------------------------------------------------------ # Border and background traits # ------------------------------------------------------------------------ # The width of the border around this component. This is taken into # account during layout, but only if the border is visible. border_width = Int(1) # Is the border visible? If this is false, then all the other border # properties are not used. border_visible = Bool(False) # The line style (i.e. dash pattern) of the border. border_dash = LineStyle # The color of the border. Only used if border_visible is True. border_color = black_color_trait # The background color of this component. By default all components have # a white background. This can be set to "transparent" or "none" if the # component should be see-through. bgcolor = white_color_trait # ------------------------------------------------------------------------ # Backbuffer traits # ------------------------------------------------------------------------ # Should this component do a backbuffered draw, i.e. render itself to an # offscreen buffer that is cached for later use? If False, then # the component will *never* render itself backbuffered, even if asked # to do so. use_backbuffer = Bool(False) # Should the backbuffer extend to the pad area? backbuffer_padding = Bool(True) # If a draw were to occur, whether the component would actually change. # This is useful for determining whether a backbuffer is valid, and is # usually set by the component itself or set on the component by calling # _invalidate_draw(). It is exposed as a public trait for the rare cases # when another component wants to know the validity of this component's # backbuffer. draw_valid = Bool(False) # drawn_outer_position specifies the outer position this component was # drawn to on the last draw cycle. This is used to determine what areas of # the screen are damaged. drawn_outer_position = coordinate_trait # drawn_outer_bounds specifies the bounds of this component on the last # draw cycle. Used in conjunction with outer_position_last_draw drawn_outer_bounds = bounds_trait # The backbuffer of this component. In most cases, this is an # instance of GraphicsContext, but this requirement is not enforced. _backbuffer = Any # ------------------------------------------------------------------------ # New layout/object containment hierarchy traits # These are not used yet. # ------------------------------------------------------------------------ # A list of strings defining the classes to which this component belongs. # These classes will be used to determine how this component is styled, # is rendered, is laid out, and receives events. There is no automatic # management of conflicting class names, so if a component is placed # into more than one class and that class classes = List # The element ID of this component. id = Str # ------------------------------------------------------------------------ # Private traits # ------------------------------------------------------------------------ # Shadow trait for self.window. Only gets set if this is the top-level # enable component in a Window. _window = Any # Instance("Window") # Whether or not component itself needs to be laid out. Some times # components are composites of others, in which case the layout # invalidation relationships should be implemented in layout_needed. _layout_needed = Bool(True) # ------------------------------------------------------------------------ # Abstract methods # ------------------------------------------------------------------------ def _do_layout(self): """ Called by do_layout() to do an actual layout call; it bypasses some additional logic to handle null bounds and setting **_layout_needed**. """ pass def _draw_selection(self, gc, view_bounds=None, mode="normal"): """ Renders a selected subset of a component's data. This method is used by some subclasses. The notion of selection doesn't necessarily apply to all subclasses of PlotComponent, but it applies to enough of them that it is defined as one of the default draw methods. """ pass # ------------------------------------------------------------------------ # Public methods # ------------------------------------------------------------------------ def __init__(self, **traits): # The 'padding' trait sets 4 individual traits in bulk. Make sure that # it gets set first before other explicit padding traits get set so # they may override the bulk default. padding = traits.pop("padding", None) padding_traits = {} padding_names = [ "padding_top", "padding_bottom", "padding_left", "padding_right", ] for name in padding_names: try: padding_traits[name] = traits.pop(name) except KeyError: pass if "container" in traits: # After the component is otherwise configured, make sure our # container gets notified of our being added to it. container = traits.pop("container") super().__init__(**traits) self._set_padding_traits(padding, padding_traits) container.add(self) else: super().__init__(**traits) self._set_padding_traits(padding, padding_traits)
[docs] def draw(self, gc, view_bounds=None, mode="default"): """ Draws the plot component. Parameters ---------- gc : Kiva GraphicsContext The graphics context to draw the component on view_bounds : 4-tuple of integers (x, y, width, height) of the area to draw mode : string The drawing mode to use; can be one of: 'normal' Normal, antialiased, high-quality rendering 'overlay' The plot component is being rendered over something else, so it renders more quickly, and possibly omits rendering its background and certain tools 'interactive' The plot component is being asked to render in direct response to realtime user interaction, and needs to make its best effort to render as fast as possible, even if there is an aesthetic cost. """ if self.layout_needed: self.do_layout() self._draw(gc, view_bounds, mode)
[docs] def draw_select_box(self, gc, position, bounds, width, dash, inset, color, bgcolor, marker_size): """ Renders a selection box around the component. Subclasses can implement this utility method to render a selection box around themselves. To avoid burdening subclasses with various selection-box related traits that they might never use, this method takes all of its required data as input parameters. Parameters ---------- gc : Kiva GraphicsContext The graphics context to draw on. position : (x, y) The position of the selection region. bounds : (width, height) The size of the selection region. width : integer The width of the selection box border dash : float array An array of floating point values specifying the lengths of on and off painting pattern for dashed lines. inset : integer Amount by which the selection box is inset on each side within the selection region. color : 3-tuple of floats between 0.0 and 1.0 The R, G, and B values of the selection border color. bgcolor : 3-tuple of floats between 0.0 and 1.0 The R, G, and B values of the selection background. marker_size : integer Size, in pixels, of "handle" markers on the selection box """ with gc: gc.set_line_width(width) gc.set_antialias(False) x, y = position x += inset y += inset width, height = bounds width -= 2 * inset height -= 2 * inset rect = (x, y, width, height) gc.set_stroke_color(bgcolor) gc.set_line_dash(None) gc.draw_rect(rect, STROKE) gc.set_stroke_color(color) gc.set_line_dash(dash) gc.draw_rect(rect, STROKE) if marker_size > 0: gc.set_fill_color(bgcolor) half_y = y + height / 2.0 y2 = y + height half_x = x + width / 2.0 x2 = x + width marker_positions = ( (x, y), (x, half_y), (x, y2), (half_x, y), (half_x, y2), (x2, y), (x2, half_y), (x2, y2), ) gc.set_line_dash(None) gc.set_line_width(1.0) for pos in marker_positions: gc.rect( pos[0] - marker_size / 2.0, pos[1] - marker_size / 2.0, marker_size, marker_size, ) gc.draw_path()
[docs] def get_absolute_coords(self, *coords): """ Given coordinates relative to this component's origin, returns the "absolute" coordinates in the frame of the top-level parent Window enclosing this component's ancestor containers. Can be called in two ways: get_absolute_coords(x, y) get_absolute_coords( (x,y) ) Returns a tuple (x,y) representing the new coordinates. """ if self.container is not None: offset_x, offset_y = self.container.get_absolute_coords( *self.position ) else: offset_x, offset_y = self.position return (offset_x + coords[0], offset_y + coords[1])
[docs] def get_relative_coords(self, *coords): """ Given absolute coordinates (where the origin is the top-left corner of the frame in the top-level parent Window) return coordinates relative to this component's origin. Can be called in two ways: get_relative_coords(x, y) get_relative_coords( (x,y) ) Returns a tuple (x,y) representing the new coordinates. """ if self.container is not None: offset_x, offset_y = self.container.get_relative_coords( *self.position ) else: offset_x, offset_y = self.position return (coords[0] - offset_x, coords[1] - offset_y)
[docs] def request_redraw(self): """ Requests that the component redraw itself. Usually this means asking its parent for a repaint. """ for view in self.viewports: view.request_redraw() self._request_redraw()
[docs] def invalidate_draw(self, damaged_regions=None, self_relative=False): """ Invalidates any backbuffer that may exist, and notifies our parents and viewports of any damaged regions. Call this method whenever a component's internal state changes such that it must be redrawn on the next draw() call.""" self.draw_valid = False if damaged_regions is None: damaged_regions = self._default_damaged_regions() if self_relative: damaged_regions = [ [region[0] + self.x, region[1] + self.y, region[2], region[3]] for region in damaged_regions ] for view in self.viewports: view.invalidate_draw( damaged_regions=damaged_regions, self_relative=True, view_relative=True, ) if self.container is not None: self.container.invalidate_draw( damaged_regions=damaged_regions, self_relative=True ) if self._window is not None: self._window.invalidate_draw( damaged_regions=damaged_regions, self_relative=True )
[docs] def invalidate_and_redraw(self): """ Convenience method to invalidate our contents and request redraw """ self.invalidate_draw() self.request_redraw()
[docs] def is_in(self, x, y): # A basic implementation of is_in(); subclasses should provide their # own if they are more accurate/faster/shinier. if self.padding_accepts_focus: bounds = self.outer_bounds pos = self.outer_position else: bounds = self.bounds pos = self.position return ( (x >= pos[0]) and (x < pos[0] + bounds[0]) and (y >= pos[1]) and (y < pos[1] + bounds[1]) )
[docs] def cleanup(self, window): """When a window viewing or containing a component is destroyed, cleanup is called on the component to give it the opportunity to delete any transient state it may have (such as backbuffers)."""
[docs] def set_outer_position(self, ndx, val): """ Since self.outer_position is a property whose value is determined by other (primary) attributes, it cannot return a mutable type. This method allows generic (i.e. orientation-independent) code to set the value of self.outer_position[0] or self.outer_position[1]. """ if ndx == 0: self.outer_x = val else: self.outer_y = val
[docs] def set_outer_bounds(self, ndx, val): """ Since self.outer_bounds is a property whose value is determined by other (primary) attributes, it cannot return a mutable type. This method allows generic (i.e. orientation-independent) code to set the value of self.outer_bounds[0] or self.outer_bounds[1]. """ if ndx == 0: self.outer_width = val else: self.outer_height = val
# ------------------------------------------------------------------------ # Layout-related concrete methods # ------------------------------------------------------------------------
[docs] def do_layout(self, size=None, force=False): """ Tells this component to do layout at a given size. Parameters ---------- size : (width, height) Size at which to lay out the component; either or both values can be 0. If it is None, then the component lays itself out using **bounds**. force : Boolean Whether to force a layout operation. If False, the component does a layout on itself only if **_layout_needed** is True. The method always does layout on any underlays or overlays it has, even if *force* is False. """ if self.layout_needed or force: if size is not None: self.bounds = size self._do_layout() self._layout_needed = False for underlay in self.underlays: if underlay.visible or underlay.invisible_layout: underlay.do_layout() for overlay in self.overlays: if overlay.visible or overlay.invisible_layout: overlay.do_layout()
[docs] def get_preferred_size(self): """ Returns the size (width,height) that is preferred for this component. When called on a component that does not contain other components, this method just returns the component bounds. If the component is resizable and can draw into any size, the method returns a size that is visually appropriate. (The component's actual bounds are determined by its container's do_layout() method.) """ if self.fixed_preferred_size is not None: return self.fixed_preferred_size else: size = [0, 0] outer_bounds = self.outer_bounds if "h" not in self.resizable: size[0] = outer_bounds[0] if "v" not in self.resizable: size[1] = outer_bounds[1] return size
# ------------------------------------------------------------------------ # Protected methods # ------------------------------------------------------------------------ def _set_padding_traits(self, padding, padding_traits): """ Set the bulk padding trait and all of the others in the correct order. Parameters ---------- padding : None, int or list of ints The bulk padding. padding_traits : dict mapping str to int The specific padding traits. """ if padding is not None: self.trait_set(padding=padding) self.trait_set(**padding_traits) def _request_redraw(self): if self.container is not None: self.container.request_redraw() elif self._window: self._window.redraw() def _default_damaged_regions(self): """ Returns the default damaged regions for this Component. This consists of the current position/bounds, and the last drawn position/bounds """ return [ list(self.outer_position) + list(self.outer_bounds), list(self.drawn_outer_position) + list(self.drawn_outer_bounds), ] def _draw(self, gc, view_bounds=None, mode="default"): """ Draws the component, paying attention to **draw_order**, including overlays, underlays, and the like. This method is the main draw handling logic in plot components. The reason for implementing _draw() instead of overriding the top-level draw() method is that the Enable base classes may do things in draw() that mustn't be interfered with (e.g., the Viewable mix-in). """ if not self.visible: return if self.layout_needed: self.do_layout() self.drawn_outer_position = list(self.outer_position[:]) self.drawn_outer_bounds = list(self.outer_bounds[:]) # OpenGL-based graphics-contexts have a `gl_init()` method. We # test for this to avoid having to import the OpenGL # GraphicsContext just to do an isinstance() check. is_gl = hasattr(gc, "gl_init") if self.use_backbuffer and (not is_gl): if self.backbuffer_padding: x, y = self.outer_position width, height = self.outer_bounds else: x, y = self.position width, height = self.bounds if not self.draw_valid: # get a reference to the GraphicsContext class from the object GraphicsContext = gc.__class__ # Some pixels are bigger than others pixel_scale = self.window.base_pixel_scale size = (int(width * pixel_scale), int(height * pixel_scale)) if hasattr(GraphicsContext, "create_from_gc"): # For some backends, such as the mac, a much more efficient # backbuffer can be created from the window gc. bb = GraphicsContext.create_from_gc(gc, size) else: bb = GraphicsContext(size) # Always scale by base_pixel_scale here bb.scale_ctm(pixel_scale, pixel_scale) # if not fill_padding, then we have to fill the backbuffer # with the window color. This is the only way I've found that # it works- perhaps if we had better blend support we could set # the alpha to 0, but for now doing so causes the backbuffer's # background to be white if not self.fill_padding: with bb: bb.set_antialias(False) bb.set_fill_color(self.window.bgcolor_) bb.draw_rect((x, y, width, height), FILL) # Fixme: should there be a +1 here? bb.translate_ctm(-x + 0.5, -y + 0.5) # There are a couple of strategies we could use here, but we # have to do something about view_bounds. This is because # if we only partially render the object into the backbuffer, # we will have problems if we then render with different view # bounds. for layer in self.draw_order: if layer != "overlay": self._dispatch_draw(layer, bb, view_bounds, mode) self._backbuffer = bb self.draw_valid = True # Blit the backbuffer and then draw the overlay on top gc.draw_image(self._backbuffer, (x, y, width, height)) self._dispatch_draw("overlay", gc, view_bounds, mode) else: for layer in self.draw_order: self._dispatch_draw(layer, gc, view_bounds, mode) def _dispatch_draw(self, layer, gc, view_bounds, mode): """ Renders the named *layer* of this component. This method can be used by container classes that group many components together and want them to draw cooperatively. The container iterates through its components and asks them to draw only certain layers. """ # Don't render the selection layer if use_selection is false. This # is mostly for backwards compatibility. if layer == "selection" and not self.use_selection: return if self.layout_needed: self.do_layout() handler = getattr(self, "_draw_" + layer, None) if handler: handler(gc, view_bounds, mode) def _draw_border(self, gc, view_bounds=None, mode="default", force_draw=False): """ Utility method to draw the borders around this component The *force_draw* parameter forces the method to draw the border; if it is false, the border is drawn only when **overlay_border** is True. """ if not self.border_visible: return if self.overlay_border or force_draw: if self.inset_border: self._draw_inset_border(gc, view_bounds, mode) else: border_width = self.border_width rect = ( self.x - border_width / 2.0, self.y - border_width / 2.0, self.width + 2 * border_width - 1, self.height + 2 * border_width - 1, ) with gc: gc.set_line_width(border_width) gc.set_line_dash(self.border_dash_) gc.set_stroke_color(self.border_color_) gc.draw_rect(rect, STROKE) def _draw_inset_border(self, gc, view_bounds=None, mode="default"): """ Draws the border of a component. Unlike the default Enable border, this one is drawn on the inside of the plot instead of around it. """ if not self.border_visible: return border_width = self.border_width rect = ( self.x + border_width / 2.0 - 0.5, self.y + border_width / 2.0 - 0.5, self.width - border_width / 2.0, self.height - border_width / 2.0, ) with gc: gc.set_line_width(border_width) gc.set_line_dash(self.border_dash_) gc.set_stroke_color(self.border_color_) gc.set_antialias(0) gc.draw_rect(rect, STROKE) # ------------------------------------------------------------------------ # Protected methods for subclasses to implement # ------------------------------------------------------------------------ def _draw_background(self, gc, view_bounds=None, mode="default"): """ Draws the background layer of a component. """ if self.bgcolor not in ("clear", "transparent", "none"): if self.fill_padding: r = tuple(self.outer_position) + ( self.outer_width - 1, self.outer_height - 1, ) else: r = tuple(self.position) + (self.width - 1, self.height - 1) with gc: gc.set_antialias(False) gc.set_fill_color(self.bgcolor_) gc.draw_rect(r, FILL) # Call the enable _draw_border routine if not self.overlay_border and self.border_visible: # Tell _draw_border to ignore the self.overlay_border self._draw_border(gc, view_bounds, mode, force_draw=True) def _draw_overlay(self, gc, view_bounds=None, mode="normal"): """ Draws the overlay layer of a component. """ for overlay in self.overlays: if overlay.visible: overlay.overlay(self, gc, view_bounds, mode) def _draw_underlay(self, gc, view_bounds=None, mode="normal"): """ Draws the underlay layer of a component. """ for underlay in self.underlays: # This method call looks funny but it's correct - underlays are # just overlays drawn at a different time in the rendering loop. if underlay.visible: underlay.overlay(self, gc, view_bounds, mode) def _get_visible_border(self): """ Helper function to return the amount of border, if visible """ if self.border_visible: if self.inset_border: return 0 else: return self.border_width else: return 0 # ------------------------------------------------------------------------ # Tool-related methods and event dispatch # ------------------------------------------------------------------------
[docs] def dispatch(self, event, suffix): """ Dispatches a mouse event based on the current event state. If the component has a **controller**, the method dispatches the event to it, and returns. Otherwise, the following objects get a chance to handle the event: 1. The component's active tool, if any. 2. Any overlays, in reverse order that they were added and are drawn. 3. The component itself. 4. Any underlays, in reverse order that they were added and are drawn. 5. Any listener tools. If any object in this sequence handles the event, the method returns without proceeding any further through the sequence. If nothing handles the event, the method simply returns. Parameters ---------- event : an Enable MouseEvent A mouse event. suffix : string The name of the mouse event as a suffix to the event state name, e.g. "_left_down" or "_window_enter". """ # Maintain compatibility with .controller for now if self.controller is not None: self.controller.dispatch(event, suffix) return if self._active_tool is not None: self._active_tool.dispatch(event, suffix) if event.handled: return # Dispatch to overlays in reverse of draw/added order for overlay in self.overlays[::-1]: overlay.dispatch(event, suffix) if event.handled: break if not event.handled: self._dispatch_stateful_event(event, suffix) if not event.handled: # Dispatch to underlays in reverse of draw/added order for underlay in self.underlays[::-1]: underlay.dispatch(event, suffix) if event.handled: break # Now that everyone who might veto/handle the event has had a chance # to receive it, dispatch it to our list of listener tools. if not event.handled: for tool in tool.dispatch(event, suffix)
def _get_active_tool(self): return self._active_tool def _set_active_tool(self, tool): # Deactivate the existing active tool old = self._active_tool if old == tool: return self._active_tool = tool if old is not None: old.deactivate(self) if tool is not None and hasattr(tool, "_activate"): tool._activate() self.invalidate_and_redraw() def _get_layout_needed(self): return self._layout_needed def _tools_items_changed(self): self.invalidate_and_redraw() # ------------------------------------------------------------------------ # Event handlers # ------------------------------------------------------------------------ def _id_default(self): """ Generate a random UUID for the ID. """ # The first 32bits is plenty. return uuid4().hex[:8] def _aspect_ratio_changed(self, old, new): if new is not None: self._enforce_aspect_ratio() def _enforce_aspect_ratio(self, notify=True): """ This method adjusts the width and/or height of the component so that the new width and height match the aspect ratio. It uses the current width and height as a bounding box and finds the largest rectangle of the desired aspect ratio that will fit. If **notify** is True, then fires trait events for bounds and position changing. """ ratio = self.aspect_ratio old_w, old_h = self.bounds if ratio is None: return elif ratio == 0: self.width = 0 return elif old_h == 0: return elif int(old_w) == int(ratio * old_h): return old_aspect = old_w / float(old_h) new_pos = None if ratio > old_aspect: # desired rectangle is wider than bounding box, so use the width # and compute a smaller height new_w = old_w new_h = new_w / ratio if self.auto_center: new_pos = self.position[:] new_pos[1] += (old_h - new_h) / 2.0 else: # desired rectangle is taller than bounding box, so use the height # and compute a smaller width new_h = old_h new_w = new_h * ratio if self.auto_center: new_pos = self.position[:] new_pos[0] += (old_w - new_w) / 2.0 self.trait_set(bounds=[new_w, new_h], trait_change_notify=notify) if new_pos: self.trait_set(position=new_pos, trait_change_notify=notify) def _bounds_changed(self, old, new): self._enforce_aspect_ratio(notify=True) if self.container is not None: self.container._component_bounds_changed(self) def _bounds_items_changed(self, event): self._enforce_aspect_ratio(notify=True) if self.container is not None: self.container._component_bounds_changed(self) def _container_changed(self, old, new): # We don't notify our container of this change b/c the # caller who changed our .container should take care of that. if new is None: self.position = [0, 0] def _position_changed(self, *args): if self.container is not None: self.container._component_position_changed(self) def _position_items_changed(self, *args): if self.container is not None: self.container._component_position_changed(self) def _visible_changed(self, old, new): if new: self._layout_needed = True def _get_window(self): if self._window is not None: return self._window elif self.container is not None: return self.container.window else: return None def _set_window(self, win): self._window = win # ------------------------------------------------------------------------ # Position and padding setters and getters # ------------------------------------------------------------------------ def _get_x(self): return self.position[0] def _set_x(self, val): self.position[0] = val def _get_y(self): return self.position[1] def _set_y(self, val): self.position[1] = val def _get_padding(self): return [ self.padding_left, self.padding_right, self.padding_top, self.padding_bottom, ] def _set_padding(self, val): old_padding = self.padding if type(val) == int: self.padding_left = ( self.padding_right ) = self.padding_top = self.padding_bottom = val self.trait_property_changed("padding", old_padding, [val] * 4) else: # assume padding is some sort of array type if len(val) != 4: raise RuntimeError( "Padding must be a 4-element sequence " "type or an int. Instead, got" + str(val) ) self.padding_left = val[0] self.padding_right = val[1] self.padding_top = val[2] self.padding_bottom = val[3] self.trait_property_changed("padding", old_padding, val) def _get_hpadding(self): return ( 2 * self._get_visible_border() + self.padding_right + self.padding_left ) def _get_vpadding(self): return ( 2 * self._get_visible_border() + self.padding_bottom + self.padding_top ) # ------------------------------------------------------------------------ # Outer position setters and getters # ------------------------------------------------------------------------ def _get_outer_position(self): border = self._get_visible_border() pos = self.position return ( pos[0] - self.padding_left - border, pos[1] - self.padding_bottom - border, ) def _set_outer_position(self, new_pos): border = self._get_visible_border() self.position = [ new_pos[0] + self.padding_left + border, new_pos[1] + self.padding_bottom + border, ] def _get_outer_x(self): return self.x - self.padding_left - self._get_visible_border() def _set_outer_x(self, val): self.position[0] = val + self.padding_left + self._get_visible_border() def _get_outer_x2(self): return self.x2 + self.padding_right + self._get_visible_border() def _set_outer_x2(self, val): self.x2 = val - self.padding_right - self._get_visible_border() def _get_outer_y(self): return self.y - self.padding_bottom - self._get_visible_border() def _set_outer_y(self, val): self.position[1] = ( val + self.padding_bottom + self._get_visible_border() ) def _get_outer_y2(self): return self.y2 + self.padding_top + self._get_visible_border() def _set_outer_y2(self, val): self.y2 = val - self.padding_top - self._get_visible_border() # ------------------------------------------------------------------------ # Outer bounds setters and getters # ------------------------------------------------------------------------ def _get_outer_bounds(self): bounds = self.bounds return (bounds[0] + self.hpadding, bounds[1] + self.vpadding) def _set_outer_bounds(self, bounds): self.bounds = [bounds[0] - self.hpadding, bounds[1] - self.vpadding] def _get_outer_width(self): return self.outer_bounds[0] def _set_outer_width(self, width): self.bounds[0] = width - self.hpadding def _get_outer_height(self): return self.outer_bounds[1] def _set_outer_height(self, height): self.bounds[1] = height - self.vpadding