#------------------------------------------------------------------------------- # # Adds a 'connect' feature to DockWindow which allows users to dynamically # connect (i.e. synchronize) traits on one object with another. To make an # object 'connectable' the developer must specify the 'connect' metadata on # any trait that can be connected to another object's trait. The value of the # 'connect' metadata should be: 'to|from|both[:[:]description]', indicating # the direction of synchronization supported (i.e. to, from or both), as # well as an optional description to display in the feature's tooltip. If # a double colon (i.e. ::) precedes the description, then the description is # also used as a type, meaning that both ends of the connection must specify # the same type information. This is useful when using simple trait types # list Str or File, and you want to add an additional level of type checking # to the connection. # # Written by: David C. Morrill # # Date: 07/04/2006 # # (c) Copyright 2006 by David C. Morrill # #------------------------------------------------------------------------------- #------------------------------------------------------------------------------- # Imports: #------------------------------------------------------------------------------- from enthought.traits.api \ import HasTraits, HasPrivateTraits, Any, List, Str, Dict, Instance, Enum from enthought.traits.ui.menu \ import Menu, Action from enthought.pyface.dock.api \ import DockWindowFeature from enthought.pyface.image_resource \ import ImageResource from enthought.developer.api \ import get_pickle, set_pickle #------------------------------------------------------------------------------- # Constants: #------------------------------------------------------------------------------- no_connections_image = ImageResource( 'no_connections_feature' ) connections_image = ImageResource( 'connections_feature' ) # Menu to display when there are no available connections/disconnections: no_connections = Menu( Action( name = 'No connections available', enabled = False ), name = 'popup' ) PermanentConnections = 'enthought.pyface.dock.features.ConnectFeature.' \ 'permanent_connections' #------------------------------------------------------------------------------- # Filter for extracting traits which support the 'connect' protocol: #------------------------------------------------------------------------------- supported_protocols = ( 'to', 'from', 'both' ) def can_connect ( value ): if isinstance( value, str ): col = value.find( ':' ) if col >= 0: value = value[ : col ].strip() return (value in supported_protocols) return False #------------------------------------------------------------------------------- # 'ConnectFeature' class: #------------------------------------------------------------------------------- class ConnectFeature ( DockWindowFeature ): #--------------------------------------------------------------------------- # Class variables: #--------------------------------------------------------------------------- # The user interface name of the feature: feature_name = 'Connect' #--------------------------------------------------------------------------- # Trait definitions: #--------------------------------------------------------------------------- # Set of 'connectable' object traits: connectable_traits = Any # Dict( name, trait ) # Set of current connections that have been made: connections = Dict # ( name, Connection ) # The current image to display on the feature bar: image = ImageResource( 'no_connections_feature' ) # The tooltip to display when the mouse is hovering over the image: tooltip = 'Click to make or break connections to other views.' #-- DockWindowFeature Methods -------------------------------------------------- #--------------------------------------------------------------------------- # Returns the object to be dragged when the user drags feature image: #--------------------------------------------------------------------------- def drag ( self ): """ Returns the object to be dragged when the user drags feature image. """ return self #--------------------------------------------------------------------------- # Handles the user dropping a specified object on the feature image: #--------------------------------------------------------------------------- def drop ( self, object ): """ Handles the user dropping a specified object on the feature image. """ new_connections = [] connects = {} self.get_available_connections( object, connects, new_connections ) # If only one possible connection, just go ahead and make it: if len( new_connections ) == 1: self.make_connection( new_connections[0] ) # Else let the user pick which one they want: else: self.pop_connection_menu( connects, new_connections, [] ) #--------------------------------------------------------------------------- # Returns whether a specified object can be dropped on the feature image: #--------------------------------------------------------------------------- def can_drop ( self, object ): """ Returns whether a specified object can be dropped on the feature image. """ if isinstance( object, ConnectFeature ): connections = [] self.get_available_connections( object, {}, connections ) if len( connections ) > 0: return True return False #--------------------------------------------------------------------------- # Handles the user right clicking on the feature image: #--------------------------------------------------------------------------- def right_click ( self ): """ Handles the user right clicking on the feature image. """ self.click() #--------------------------------------------------------------------------- # Handles the user left clicking on the feature image: #--------------------------------------------------------------------------- def click ( self ): """ Handles the user left clicking on the feature image. """ new_connections = [] connects = {} # Iterate over all other DockControls in the same window: for dc in self.dock_control.dock_controls: # Then find those which have objects supporting the 'connect' # protocol: for feature2 in dc.features: if isinstance( feature2, ConnectFeature ): self.get_available_connections( feature2, connects, new_connections ) break # If there are no actions that can be taken, then display empty menu: connections = self.connections if (len( connects ) == 0) and (len( connections ) == 0): self.popup_menu( no_connections ) else: # Else display pop-up menu of available connections/disconnections: self.pop_connection_menu( connects, new_connections, connections ) #--------------------------------------------------------------------------- # Performs any clean-up needed when the feature is being removed: #--------------------------------------------------------------------------- def dispose ( self ): """ Performs any clean-up needed when the feature is being removed. """ self.dock_control.on_trait_change( self.activate, 'activated', remove = True ) #-- ConnectFeature Methods ----------------------------------------------------- #--------------------------------------------------------------------------- # Returns the connections that can be made between two ConnectFeatures: #--------------------------------------------------------------------------- def get_available_connections ( self, feature2, connects, new_connections ): """ Returns the connections that can be made between two ConnectFeatures. """ connectable_traits = feature2.connectable_traits dc = feature2.dock_control label2 = dc.name object2 = dc.object object1 = self.dock_control.object label1 = self.dock_control.name no_name1 = (len( self.connectable_traits ) == 1) no_name2 = (len( connectable_traits ) == 1) connections = self.connections for name1, trait1 in self.connectable_traits.items(): connect1, type1, ui_name1 = self.parse_connect( trait1.connect, name1 ) if no_name1: ui_name1 = '' actions = [] for name2, trait2 in connectable_traits.items(): # Only allow a connection that hasn't already been made: for connection in connections.get( name1, [] ): if ((name2 == connection.name2) and (label2 == connection.label2)): break else: # Determine if a connection will actually work: connect2, type2, ui_name2 = self.parse_connect( trait2.connect, name2 ) if no_name2: ui_name2 = '' if (((connect1 == 'both') or (connect2 == 'both') or (connect1 != connect2)) and (((type1 == '') and (type2 == '')) or (type1 == type2))): if (connect1 == 'to') or (connect2 == 'from'): try: trait1.validate( object1, name1, getattr( object2, name2 ) ) except: continue else: try: trait2.validate( object2, name2, getattr( object1, name1 ) ) except: continue # Establish the type of connection to make: connect = connect1 if connect1 != connect2: if connect1 == 'both': connect = 'to' if connect2 == 'to': connect = 'from' # Add the action to connect it: actions.append( ( ui_name1, ui_name2, dc.name, len( new_connections ) ) ) # Create the corresponding Connection object: new_connections.append( Connection( object1 = object1, name1 = name1, ui_name1 = ui_name1, feature1 = self, label1 = label1, object2 = object2, name2 = name2, ui_name2 = ui_name2, feature2 = feature2, label2 = label2, connection = connect ) ) # If there are any actions, then add them to the list: if len( actions ) > 0: if name1 not in connects: connects[ name1 ] = [] connects[ name1 ].extend( actions ) #--------------------------------------------------------------------------- # Parses a 'connect' string into the connection type and an optional user # friendly name: #--------------------------------------------------------------------------- def parse_connect ( self, connect, name ): """ Parses a 'connect' string into the connection type and an optional user friendly name. """ col = connect.find( ':' ) if col < 0: return ( connect, '', name ) connection = connect[ : col ].strip() has_type = (connect[ col + 1: col + 2 ] == ':') if has_type: col += 1 name = connect[ col + 1: ].strip() type = '' if has_type: type = name return ( connection, type, name ) #--------------------------------------------------------------------------- # Returns a list of Actions for a list of potential connections: #--------------------------------------------------------------------------- def connect_actions ( self, actions ): """ Returns a list of Actions for a list of potential connections. """ force = (len( actions ) == 1) result = [] for ui_name1, ui_name2, dc_name, index in actions: if (not force) and (ui_name2 != ''): result.append( Action( name = 'to the %s in the %s' % ( ui_name2, dc_name ), action = "self.connect(%d)" % index ) ) else: result.append( Action( name = 'to the %s' % dc_name, action = "self.connect(%d)" % index ) ) return result #--------------------------------------------------------------------------- # Returns a list of Actions for a list of potential disconnects: #--------------------------------------------------------------------------- def disconnect_actions ( self, connections ): """ Returns a list of Actions for a list of potential disconnects. """ force = (len( connections ) == 1) actions = [] for i, connection in enumerate( connections ): if connection.feature1 is self: ui_name2 = connection.ui_name2 if (not force) and (ui_name2 != ''): actions.append( Action( name = 'from the %s in the %s' % ( ui_name2, connection.label2 ), action = "self.disconnect('%s',%d)" % ( connection.name1, i ) ) ) else: actions.append( Action( name = 'from the %s' % connection.label2, action = "self.disconnect('%s',%d)" % ( connection.name1, i ) ) ) else: ui_name1 = connection.ui_name1 if (not force) and (ui_name1 != ''): actions.append( Action( name = 'from the %s in the %s' % ( ui_name1, connection.label1 ), action = "self.disconnect('%s',%d)" % ( connection.name2, i ) ) ) else: actions.append( Action( name = 'from the %s' % connection.label1, action = "self.disconnect('%s',%d)" % ( connection.name2, i ) ) ) return actions #--------------------------------------------------------------------------- # Makes a connection specified by index: #--------------------------------------------------------------------------- def connect ( self, index ): """ Makes a connection specified by index. """ self.make_connection( self._new_connections[ index ] ) #--------------------------------------------------------------------------- # Makes a specified connection: #--------------------------------------------------------------------------- def make_connection ( self, connection, permanent = True ): """ Makes a specified connection. """ # Add the connection to our list of connections: self.add_connection( connection.name1, connection ) # Add the connection to the other ConnectFeature's list of connections: connection.feature2.add_connection( connection.name2, connection ) # Make the connection: connection.connect() # Persist the connection: if permanent: ConnectFeature.add_permanent_connection( connection ) #--------------------------------------------------------------------------- # Adds a new connection to our list of connections: #--------------------------------------------------------------------------- def add_connection ( self, name, connection ): """ Adds a new connection to our list of connections. """ # If this is our first connection, change the feature image: connections = self.connections if len( connections ) == 0: self.image = connections_image self.refresh() # Add the connection to our list of connections: if name not in connections: connections[ name ] = [] connections[ name ].append( connection ) #--------------------------------------------------------------------------- # Disconnects a specified connection: #--------------------------------------------------------------------------- def disconnect ( self, name, index ): """ Disconnects a specified connection. """ # Get the connection to be broken: connection = self.connections[ name ][ index ] # Remove the connection from our list: self.remove_connection( name, connection ) # Remove the connection from the other ConnectFeature's list: if connection.feature1 is self: connection.feature2.remove_connection(connection.name2, connection) else: connection.feature1.remove_connection(connection.name1, connection) # Break the connection: connection.disconnect() # Unpersist the connection: ConnectFeature.remove_permanent_connection( connection ) #--------------------------------------------------------------------------- # Removes a specified connection: #--------------------------------------------------------------------------- def remove_connection ( self, name, connection ): """ Removes a specified connection. """ connections = self.connections[ name ] connections.remove( connection ) if len( connections ) == 0: del self.connections[ name ] if len( self.connections ) == 0: self.image = no_connections_image self.refresh() #--------------------------------------------------------------------------- # Displays the pop-up connection menu for a specified set of connections: #--------------------------------------------------------------------------- def pop_connection_menu ( self, connects, new_connections, old_connections ): """ Displays the pop-up connection menu for a specified set of connections. """ # Create the list for holding the main menu actions: actions = [] # Create the 'connect' submenus: if len( connects ) > 0: names = connects.keys() if len( names ) == 1: sub_menus = self.connect_actions( connects[ names[0] ] ) else: names.sort() sub_menus = [] for name in names: items = connects[ name ] sub_menus.append( Menu( name = items[0][0], *self.connect_actions( items ) ) ) actions.append( Menu( name = 'Connect', *sub_menus ) ) # Create the 'disconnect' submenus: disconnects = [] n = len( old_connections ) if n > 0: names = old_connections.keys() if n == 1: sub_menus = self.disconnect_actions( old_connections[names[0]] ) else: names.sort() sub_menus = [] for name in names: sub_menus.append( Menu( name = name, *self.disconnect_actions( old_connections[ name ] ) ) ) actions.append( Menu( name = 'Disconnect', *sub_menus ) ) # Display the pop-up menu: self._new_connections = new_connections self.popup_menu( Menu( name = 'popup', *actions ) ) self._new_connections = None #-- Event Handlers ------------------------------------------------------------- #--------------------------------------------------------------------------- # Handles the 'dock_control' trait beinch changed: #--------------------------------------------------------------------------- def _dock_control_changed ( self, dock_control ): """ Handles the 'dock_control' trait beinch changed. """ dock_control.on_trait_change( self.activate, 'activated' ) #--------------------------------------------------------------------------- # Handles the associated DockControl being activated by the user: #--------------------------------------------------------------------------- def activate ( self ): """ Handles the associated DockControl being activated by the user. """ dock_control = self.dock_control regions = [ dock_control.parent ] controls = [ dock_control ] queue = [] # Add to the work queue all of our connections: for connections in self.connections.values(): for connection in connections: queue.append( ( dock_control, connection ) ) # Loop until we've processed all reachable connections: while len( queue ) > 0: # Get the next connection to analyze: dock_control, connection = queue.pop() # Only process the connection if it is 'downstream' from this one: if dock_control is connection.feature1.dock_control: if connection.connection == 'to': continue feature2 = connection.feature2 elif connection.connection == 'from': continue else: feature2 = connection.feature1 # Only process it if we haven't already visited it before: dock_control2 = feature2.dock_control if dock_control2 in controls: continue controls.append( dock_control2 ) # Add all of its connections to the work queue: for connections2 in feature2.connections.values(): for connection2 in connections2: queue.append( ( dock_control2, connection2 ) ) # Only activate it if we haven't already activated something in the # same notebook: region = dock_control2.parent if region in regions: continue regions.append( region ) # OK, passed all tests...activate it: dock_control2.activate( False ) #-- Class Attributes ----------------------------------------------------------- #--------------------------------------------------------------------------- # Class attributes: #--------------------------------------------------------------------------- # The list of permanent, persisted connections: permanent_connections = [] # Have the permanent connections been loaded yet? permanent_loaded = False #-- Overidable Class Methods --------------------------------------------------- #--------------------------------------------------------------------------- # Returns a new feature object for a specified DockControl (or None if the # feature does not apply to it): #--------------------------------------------------------------------------- def feature_for ( cls, dock_control ): """ Returns a new feature object for a specified DockControl (or None if the feature does not apply to it). """ object = dock_control.object if isinstance( object, HasTraits ): connectable_traits = object.traits( connect = can_connect ) if len( connectable_traits ) > 0: result = cls( dock_control = dock_control, connectable_traits = connectable_traits ) # Restore permanent connections list (if necessary): cls.check_permanent_connections() # Restore any permanent connections this feature may be in: name1 = dock_control.name dock_controls = dock_control.dock_controls for c in cls.permanent_connections: if (name1 == c.label1) or (name1 == c.label2): for dc in dock_controls: for feature2 in dc.features: if isinstance( feature2, ConnectFeature ): break else: continue name2 = dc.name if name2 == c.label1: feature2.make_connection( c.clone().set( feature1 = feature2, object1 = dc.object, feature2 = result, object2 = object ), False ) elif name2 == c.label2: result.make_connection( c.clone().set( feature2 = feature2, object2 = dc.object, feature1 = result, object1 = object ), False ) return result return None feature_for = classmethod( feature_for ) #--------------------------------------------------------------------------- # Makes sure that the permanent connections have been loaded: #--------------------------------------------------------------------------- def check_permanent_connections ( cls ): if not cls.permanent_loaded: cls.permanent_loaded = True cls.permanent_connections = get_pickle( PermanentConnections, [] ) check_permanent_connections = classmethod( check_permanent_connections ) #--------------------------------------------------------------------------- # Adds a permanent connection: #--------------------------------------------------------------------------- def add_permanent_connection ( cls, connection ): """ Adds a permanent connection. """ cls.check_permanent_connections() cls.permanent_connections.append( connection.clone() ) set_pickle( PermanentConnections, cls.permanent_connections ) add_permanent_connection = classmethod( add_permanent_connection ) #--------------------------------------------------------------------------- # Removes a permanent connection: #--------------------------------------------------------------------------- def remove_permanent_connection ( cls, connection ): """ Removes a permanent connection. """ cls.check_permanent_connections() for i, connection2 in enumerate( cls.permanent_connections ): if connection == connection2: del cls.permanent_connections[i] set_pickle( PermanentConnections, cls.permanent_connections ) break remove_permanent_connection = classmethod( remove_permanent_connection ) #------------------------------------------------------------------------------- # 'Connection' class: #------------------------------------------------------------------------------- class Connection ( HasPrivateTraits ): #--------------------------------------------------------------------------- # Trait definitions: #--------------------------------------------------------------------------- # The first object in the connection: object1 = Instance( HasTraits ) # The name of the trait connected on that object: name1 = Str # The user friendly name of the trait connected on that object: ui_name1 = Str # The ConnectFeature for that object: feature1 = Instance( ConnectFeature ) # Label of the object: label1 = Str # The second object in the connection: object2 = Instance( HasTraits ) # The name of the trait on that object: name2 = Str # The user friendly name of the trait connected on that object: ui_name2 = Str # The ConnectFeature for that object: feature2 = Instance( ConnectFeature ) # Label of the object: label2 = Str # The direction of the connection: connection = Enum( 'to', 'from', 'both' ) #--------------------------------------------------------------------------- # Connects the objects: #--------------------------------------------------------------------------- def connect ( self ): """ Connects the objects. """ connection = self.connection if connection in ( 'from', 'both' ): self.object1.on_trait_change( self.connect_from, self.name1 ) self.connect_from( getattr( self.object1, self.name1 ) ) if connection in ( 'to', 'both' ): self.object2.on_trait_change( self.connect_to, self.name2 ) if connection == 'to': self.connect_to( getattr( self.object2, self.name2 ) ) #--------------------------------------------------------------------------- # Disconnects the objects: #--------------------------------------------------------------------------- def disconnect ( self ): """ Disconnects the objects. """ connection = self.connection if connection in ( 'from', 'both' ): self.object1.on_trait_change( self.connect_from, self.name1, remove = True ) if connection in ( 'to', 'both' ): self.object2.on_trait_change( self.connect_to, self.name2, remove = True ) #--------------------------------------------------------------------------- # Copies a value from object1 to object2: #--------------------------------------------------------------------------- def connect_from ( self, value ): """ Copies a value from object1 to object2. """ if not self._frozen: self._frozen = True try: setattr( self.object2, self.name2, value ) except: pass self._frozen = False #--------------------------------------------------------------------------- # Copies a value from object2 to object1: #--------------------------------------------------------------------------- def connect_to ( self, value ): """ Copies a value from object1 to object2. """ if not self._frozen: self._frozen = True try: setattr( self.object1, self.name1, value ) except: pass self._frozen = False #--------------------------------------------------------------------------- # Returns a persistable clone of this connection: #--------------------------------------------------------------------------- def clone ( self ): """ Returns a persistable clone of this connection. """ return self.clone_traits( [ 'name1', 'label1', 'name2', 'label2', 'connection' ] ) #--------------------------------------------------------------------------- # Implements the equality comparison operators: #--------------------------------------------------------------------------- def __eq__ ( self, other ): return (isinstance( other, Connection ) and (self.name1 == other.name1) and (self.label1 == other.label1) and (self.name2 == other.name2) and (self.label2 == other.label2) and (self.connection == other.connection)) def __ne__ ( self, other ): return (not self.__eq__( other ))