Source code for enable.constraints_container

# (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!
from collections import deque

# traits imports
from traits.api import (

# local imports
from .container import Container
from .coordinate_box import CoordinateBox
from .layout.layout_helpers import expand_constraints
from .layout.layout_manager import LayoutManager
from .layout.utils import (

[docs]class ConstraintsContainer(Container): """ A Container which lays out its child components using a constraints-based layout solver. """ # A read-only symbolic object that represents the left boundary of # the component contents_left = Property(fget=get_from_constraints_namespace) # A read-only symbolic object that represents the right boundary # of the component contents_right = Property(fget=get_from_constraints_namespace) # A read-only symbolic object that represents the bottom boundary # of the component contents_bottom = Property(fget=get_from_constraints_namespace) # A read-only symbolic object that represents the top boundary of # the component contents_top = Property(fget=get_from_constraints_namespace) # A read-only symbolic object that represents the width of the # component contents_width = Property(fget=get_from_constraints_namespace) # A read-only symbolic object that represents the height of the # component contents_height = Property(fget=get_from_constraints_namespace) # A read-only symbolic object that represents the vertical center # of the component contents_v_center = Property(fget=get_from_constraints_namespace) # A read-only symbolic object that represents the horizontal # center of the component contents_h_center = Property(fget=get_from_constraints_namespace) # The layout constraints for this container. # This can either be a list or a callable. If it is a callable, it will be # called with a single argument, the ConstraintsContainer, and be expected # to return a list of constraints. layout_constraints = Either(List, Callable) # A boolean which indicates whether or not to allow the layout # ownership of this container to be transferred to an ancestor. # This is False by default, which means that every container # get its own layout solver. This improves speed and reduces # memory use (by keeping a solver's internal tableaux small) # but at the cost of not being able to share constraints # across Container boundaries. This flag must be explicitly # marked as True to enable sharing. share_layout = Bool(False) # Sharing related private traits _owns_layout = Bool(True) _layout_owner = Any # The contents box constraints for this container _contents_constraints = Property # The user-specified layout constraints, with layout helpers expanded _layout_constraints = Property # A dictionary of components added to this container _component_map = Dict # The kiwi solver _layout_manager = Instance(LayoutManager, allow_none=True) _offset_table = List _layout_table = List # ------------------------------------------------------------------------ # Public methods # ------------------------------------------------------------------------
[docs] def do_layout(self, size=None, force=False): """ Make sure child components get a chance to refresh their layout. """ for component in self.components: component.do_layout(size=size, force=force)
[docs] def refresh(self): """ Re-run the constraints solver in response to a resize or constraints modification. """ if self._owns_layout: if self._layout_manager is None: return mgr_layout = self._layout_manager.layout offset_table = self._offset_table width_var = self.layout_width height_var = self.layout_height width, height = self.bounds def layout(): running_index = 1 for offset_index, item in self._layout_table: dx, dy = offset_table[offset_index] nx, ny = item.left.value(), item.bottom.value() item.position = (nx - dx, ny - dy) item.bounds = ( item.layout_width.value(), item.layout_height.value(), ) offset_table[running_index] = (nx, ny) running_index += 1 mgr_layout(layout, width_var, height_var, (width, height)) self.invalidate_draw() else: self._layout_owner.refresh()
[docs] def relayout(self): """ Explicitly regenerate the container's constraints and refresh the layout. """ if not self.share_layout: self._init_layout() self.refresh() elif self._layout_owner is not None: self._layout_owner.relayout()
# ------------------------------------------------------------------------ # Layout Sharing # ------------------------------------------------------------------------
[docs] def transfer_layout_ownership(self, owner): """ A method which can be called by other components in the hierarchy to gain ownership responsibility for the layout of the children of this container. By default, the transfer is allowed and is the mechanism which allows constraints to cross widget boundaries. Subclasses should reimplement this method if different behavior is desired. Parameters ---------- owner : ConstraintsContainer The container which has taken ownership responsibility for laying out the children of this component. All relayout and refresh requests will be forwarded to this component. Returns ------- results : bool True if the transfer was allowed, False otherwise. """ if not self.share_layout: return False self._owns_layout = False self._layout_owner = owner self._layout_manager = None return True
[docs] def will_transfer(self): """ Whether or not the container expects to transfer its layout ownership to its parent. This method is predictive in nature and exists so that layout managers are not senslessly created during the bottom-up layout initialization pass. It is declared public so that subclasses can override the behavior if necessary. """ cls = ConstraintsContainer if self.share_layout: if self.container and isinstance(self.container, cls): return True return False
# ------------------------------------------------------------------------ # Traits methods # ------------------------------------------------------------------------ def _bounds_changed(self, old, new): """ Run the solver when the container's bounds change. """ super()._bounds_changed(old, new) self.refresh() def _layout_constraints_changed(self): """ Refresh the layout when the user constraints change. """ self.relayout() def _get__contents_constraints(self): """ Return the constraints which define the content box of this container. """ add_symbolic_contents_constraints(self._constraints_vars) return [ self.contents_left == self.left, self.contents_bottom == self.bottom, self.contents_right == self.left + self.layout_width, self.contents_top == self.bottom + self.layout_height, ] def _get__layout_constraints(self): """ React to changes of the user controlled constraints. """ if self.layout_constraints is None: return [] if callable(self.layout_constraints): new = self.layout_constraints(self) else: new = self.layout_constraints # Expand any layout helpers return [cns for cns in expand_constraints(self, new)] def __components_items_changed(self, event): """ Make sure components that are added can be used with constraints. """ # Remove stale components from the map for item in event.removed: item.observe( self._handle_changed_component_size_hint, "layout_size_hint", remove=True, ) del self._component_map[] # Check the added components self._check_and_add_components(event.added) def __components_changed(self, new): """ Make sure components that are added can be used with constraints. """ # Clear the component maps for key, item in self._component_map.items(): item.observe( self._handle_changed_component_size_hint, "layout_size_hint", remove=True, ) self._component_map = {} # Check the new components self._check_and_add_components(new) def _handle_changed_component_size_hint(self, event): """ Refresh the size hint contraints for a child component """ self.relayout() # ------------------------------------------------------------------------ # Protected methods # ------------------------------------------------------------------------ def _build_layout_table(self): """ Build the layout and offset tables for this container. A layout table is a pair of flat lists which hold the required objects for laying out the child widgets of this container. The flat table is built in advance (and rebuilt if and when the tree structure changes) so that it's not necessary to perform an expensive tree traversal to layout the children on every resize event. Returns ------- result : (list, list) The offset table and layout table to use during a resize event. """ # The offset table is a list of (dx, dy) tuples which are the # x, y offsets of children expressed in the coordinates of the # layout owner container. This owner container may be different # from the parent of the widget, and so the delta offset must # be subtracted from the computed geometry values during layout. # The offset table is updated during a layout pass in breadth # first order. # # The layout table is a flat list of (idx, updater) tuples. The # idx is an index into the offset table where the given child # can find the offset to use for its layout. The updater is a # callable provided by the widget which accepts the dx, dy # offset and will update the layout geometry of the widget. zero_offset = (0, 0) offset_table = [zero_offset] layout_table = [] queue = deque((0, child) for child in self._component_map.values()) # Micro-optimization: pre-fetch bound methods and store globals # as locals. This method is not on the code path of a resize # event, but it is on the code path of a relayout. If there # are many children, the queue could potentially grow large. push_offset = offset_table.append push_item = layout_table.append push = queue.append pop = queue.popleft CoordinateBox_ = CoordinateBox Container_ = ConstraintsContainer isinst = isinstance # The queue yields the items in the tree in breadth-first order # starting with the immediate children of this container. If a # given child is a container that will share its layout, then # the children of that container are added to the queue to be # added to the layout table. running_index = 0 while queue: offset_index, item = pop() if isinst(item, CoordinateBox_): push_item((offset_index, item)) push_offset(zero_offset) running_index += 1 if isinst(item, Container_): if item.transfer_layout_ownership(self): for child in item._component_map.values(): push((running_index, child)) return offset_table, layout_table def _check_and_add_components(self, components): """ Make sure components can be used with constraints. """ for item in components: key = if len(key) == 0: msg = "Components added to a {0} must have a valid 'id' trait." name = type(self).__name__ raise ValueError(msg.format(name)) elif key in self._component_map: msg = "A Component with id '{0}' has already been added." raise ValueError(msg.format(key)) elif key == msg = "Can't add a Component with the same id as its parent." raise ValueError(msg) self._component_map[key] = item item.observe( self._handle_changed_component_size_hint, "layout_size_hint" ) # Update the layout self.relayout() def _generate_constraints(self, layout_table): """ Creates the list of kiwi Constraint objects for the widgets for which this container owns the layout. This method walks over the items in the given layout table and aggregates their constraints into a single list of kiwi Constraint objects which can be given to the layout manager. Parameters ---------- layout_table : list The layout table created by a call to _build_layout_table. Returns ------- result : list The list of kiwi Constraint instances to pass to the layout manager. """ user_cns = self._layout_constraints user_cns_extend = user_cns.extend # The list of raw kiwi constraints which will be returned # from this method to be added to the kiwi solver. raw_cns = self._hard_constraints + self._contents_constraints raw_cns_extend = raw_cns.extend isinst = isinstance Container_ = ConstraintsContainer # The first element in a layout table item is its offset index # which is not relevant to constraints generation. for _, child in layout_table: raw_cns_extend(child._hard_constraints) if isinst(child, Container_): if child.transfer_layout_ownership(self): user_cns_extend(child._layout_constraints) raw_cns_extend(child._contents_constraints) else: raw_cns_extend(child._size_constraints) else: raw_cns_extend(child._size_constraints) return raw_cns + user_cns def _init_layout(self): """ Initializes the layout for the container. """ # Layout ownership can only be transferred *after* this init # layout method is called, since layout occurs bottom up. So, # we only initialize a layout manager if we are not going to # transfer ownership at some point. if not self.will_transfer(): offset_table, layout_table = self._build_layout_table() cns = self._generate_constraints(layout_table) # Initializing the layout manager can fail if the objective # function is unbounded. We let that failure occur so it can # be logged. Nothing is stored until it succeeds. manager = LayoutManager() manager.initialize(cns) self._offset_table = offset_table self._layout_table = layout_table self._layout_manager = manager