Merge pull request #166 from jchanvfx/custom_port_shapes

Custom port shapes

Author: jchanvfx

NodeGraphQt/base/node.py

@@ -529,6 +529,12 @@ def __init__(self):
         self._view.text_item.editingFinished.connect(self.set_name)
 
     def draw(self, force=True):
+        """
+        Redraws the node in the scene.
+
+        Args:
+            force (bool): force redraw if not visible.
+        """
         if force:
             if not self.model.visible:
                 self._has_draw = False
@@ -544,14 +550,16 @@ def hide(self):
         Hide node.
         """
         super(BaseNode, self).hide()
-        [pipe.hide() for port in self._inputs + self._outputs for pipe in port.view.connected_pipes]
+        [pipe.hide() for port in self._inputs + self._outputs
+         for pipe in port.view.connected_pipes]
 
     def show(self):
         """
         Show node.
         """
         super(BaseNode, self).show()
-        [pipe.show() for port in self._inputs + self._outputs for pipe in port.view.connected_pipes]
+        [pipe.show() for port in self._inputs + self._outputs
+         for pipe in port.view.connected_pipes]
         self.draw(False)
 
     def update_model(self):
@@ -755,7 +763,7 @@ def add_checkbox(self, name, label='', text='', state=False, tab=None):
         self.view.add_widget(widget)
 
     def add_input(self, name='input', multi_input=False, display_name=True,
-                  color=None, data_type='None'):
+                  color=None, data_type='None', painter_func=None):
         """
         Add input :class:`Port` to node.
 
@@ -764,19 +772,26 @@ def add_input(self, name='input', multi_input=False, display_name=True,
             multi_input (bool): allow port to have more than one connection.
             display_name (bool): display the port name on the node.
             color (tuple): initial port color (r, g, b) ``0-255``.
-            data_type(str): port data type name.
+            data_type (str): port data type name.
+            painter_func (function): custom function to override the drawing
+                of the port shape see example: :ref:`Creating Custom Shapes`
 
         Returns:
             NodeGraphQt.Port: the created port object.
         """
         if name in self.inputs().keys():
             raise PortRegistrationError(
                 'port name "{}" already registered.'.format(name))
-        view = self.view.add_input(name, multi_input, display_name)
+
+        port_args = [name, multi_input, display_name]
+        if painter_func and callable(painter_func):
+            port_args.append(painter_func)
+        view = self.view.add_input(*port_args)
 
         if color:
             view.color = color
             view.border_color = [min([255, max([0, i + 80])]) for i in color]
+
         port = Port(self, view)
         port.model.type_ = IN_PORT
         port.model.name = name
@@ -788,7 +803,7 @@ def add_input(self, name='input', multi_input=False, display_name=True,
         return port
 
     def add_output(self, name='output', multi_output=True, display_name=True,
-                   color=None, data_type='None'):
+                   color=None, data_type='None', painter_func=None):
         """
         Add output :class:`Port` to node.
 
@@ -798,14 +813,21 @@ def add_output(self, name='output', multi_output=True, display_name=True,
             display_name (bool): display the port name on the node.
             color (tuple): initial port color (r, g, b) ``0-255``.
             data_type(str): port data type name.
+            painter_func (function): custom function to override the drawing
+                of the port shape see example: :ref:`Creating Custom Shapes`
 
         Returns:
             NodeGraphQt.Port: the created port object.
         """
         if name in self.outputs().keys():
             raise PortRegistrationError(
                 'port name "{}" already registered.'.format(name))
-        view = self.view.add_output(name, multi_output, display_name)
+
+        port_args = [name, multi_output, display_name]
+        if painter_func and callable(painter_func):
+            port_args.append(painter_func)
+        view = self.view.add_output(*port_args)
+
         if color:
             view.color = color
             view.border_color = [min([255, max([0, i + 80])]) for i in color]
@@ -914,9 +936,25 @@ def set_ports(self, port_data):
         Set node input and output ports.
 
         Args:
-            port_data(dict): {'input_ports':[{'name':...,'multi_connection':...,'display_name':...,'data_type':...}, ...],
-            "                 'output_ports':[{'name':...,'multi_connection':...,'display_name':...,'data_type':...}, ...]}
-        """
+            port_data(dict): port data.
+        """
+
+        # port data eg.
+        # {
+        #     'input_ports':
+        #         [{'name': ...,
+        #           'multi_connection': ...,
+        #           'display_name': ...,
+        #           'data_type': ...
+        #           }, ...],
+        #     'output_ports':
+        #         [{'name': ...,
+        #           'multi_connection': ...,
+        #           'display_name': ...,
+        #           'data_type': ...
+        #           }, ...]
+        # }
+
         for port in self._inputs:
             self._view.delete_input(port.view)
             port.model.node = None
@@ -927,11 +965,15 @@ def set_ports(self, port_data):
         self._outputs = []
         self._model.outputs = {}
         self._model.inputs = {}
-        [self.add_input(name=port['name'], multi_input=port['multi_connection'],
-                        display_name=port['display_name'], data_type=port['data_type'])
+        [self.add_input(name=port['name'],
+                        multi_input=port['multi_connection'],
+                        display_name=port['display_name'],
+                        data_type=port['data_type'])
          for port in port_data['input_ports']]
-        [self.add_output(name=port['name'], multi_output=port['multi_connection'],
-                         display_name=port['display_name'], data_type=port['data_type'])
+        [self.add_output(name=port['name'],
+                         multi_output=port['multi_connection'],
+                         display_name=port['display_name'],
+                         data_type=port['data_type'])
          for port in port_data['output_ports']]
         self.draw()
 
@@ -1196,6 +1238,12 @@ class SubGraph(object):
     """
     The ``NodeGraphQt.SubGraph`` class is the base class that all
     Sub Graph Node inherit from.
+
+    *Implemented on NodeGraphQt: * ``v0.1.0``
+
+    .. image:: _images/example_subgraph.gif
+        :width: 80%
+
     """
 
     def __init__(self):
@@ -1210,8 +1258,9 @@ def children(self):
     def create_from_nodes(self, nodes):
         """
         Create sub graph from the nodes.
+
         Args:
-            nodes(list): nodes to create the sub graph.
+            nodes (list[NodeGraphQt.NodeObject]): nodes to create the sub graph.
         """
         if self in nodes:
             nodes.remove(self)
@@ -1220,16 +1269,18 @@ def create_from_nodes(self, nodes):
     def add_child(self, node):
         """
         Add a node to the sub graph.
+
         Args:
-            node(NodeGraphQt.BaseNode).
+            node (NodeGraphQt.BaseNode): node object.
         """
         self._children.add(node)
 
     def remove_child(self, node):
         """
         Remove a node from the sub graph.
+
         Args:
-            node(NodeGraphQt.BaseNode).
+            node (NodeGraphQt.BaseNode): node object.
         """
         if node in self._children:
             self._children.remove(node)

NodeGraphQt/base/port.py

@@ -1,9 +1,9 @@
 #!/usr/bin/python
 from .commands import (PortConnectedCmd,
-                             PortDisconnectedCmd,
-                             PortVisibleCmd,
-                             NodeInputConnectedCmd,
-                             NodeInputDisconnectedCmd)
+                       PortDisconnectedCmd,
+                       PortVisibleCmd,
+                       NodeInputConnectedCmd,
+                       NodeInputDisconnectedCmd)
 from .model import PortModel
 from ..constants import IN_PORT, OUT_PORT
 

NodeGraphQt/base/utils.py

@@ -503,8 +503,12 @@ def topological_sort_by_down(start_nodes=None, all_nodes=None):
     'start_nodes' and 'all_nodes' only one needs to be given.
 
     Args:
-        start_nodes (list[NodeGraphQt.BaseNode])(Optional): the start update nodes of the graph.
-        all_nodes (list[NodeGraphQt.BaseNode])(Optional): if 'start_nodes' is None the function can calculate start nodes from 'all_nodes'.
+        start_nodes (list[NodeGraphQt.BaseNode]):
+            (Optional) the start update nodes of the graph.
+        all_nodes (list[NodeGraphQt.BaseNode]):
+            (Optional) if 'start_nodes' is None the function can calculate
+            start nodes from 'all_nodes'.
+
     Returns:
         list[NodeGraphQt.BaseNode]: sorted nodes.
     """
@@ -533,8 +537,11 @@ def topological_sort_by_up(start_nodes=None, all_nodes=None):
     'start_nodes' and 'all_nodes' only one needs to be given.
 
     Args:
-        start_nodes (list[NodeGraphQt.BaseNode])(Optional): the end update nodes of the graph.
-        all_nodes (list[NodeGraphQt.BaseNode])(Optional): if 'start_nodes' is None the function can calculate start nodes from 'all_nodes'.
+        start_nodes (list[NodeGraphQt.BaseNode]):
+            (Optional) the end update nodes of the graph.
+        all_nodes (list[NodeGraphQt.BaseNode]):
+            (Optional) if 'start_nodes' is None the function can calculate
+            start nodes from 'all_nodes'.
     Returns:
         list[NodeGraphQt.BaseNode]: sorted nodes.
     """
@@ -636,11 +643,12 @@ def _compute_rank_down(start_nodes):
     Compute the rank of the down stream nodes.
 
     Args:
-        start_nodes (list[NodeGraphQt.BaseNode])(Optional): the start nodes of the graph.
+        start_nodes (list[NodeGraphQt.BaseNode]):
+            (Optional) the start nodes of the graph.
+
     Returns:
         dict{NodeGraphQt.BaseNode: node_rank, ...}
     """
-
     nodes_rank = {}
     for node in start_nodes:
         nodes_rank[node] = 0
@@ -663,7 +671,9 @@ def _compute_rank_up(start_nodes):
     Compute the rank of the up stream nodes.
 
     Args:
-        start_nodes (list[NodeGraphQt.BaseNode])(Optional): the end nodes of the graph.
+        start_nodes (list[NodeGraphQt.BaseNode]):
+            (Optional) the end nodes of the graph.
+
     Returns:
         dict{NodeGraphQt.BaseNode: node_rank, ...}
     """
@@ -680,8 +690,11 @@ def auto_layout_up(start_nodes=None, all_nodes=None):
     Auto layout the nodes by up stream direction.
 
     Args:
-        start_nodes (list[NodeGraphQt.BaseNode])(Optional): the end nodes of the graph.
-        all_nodes (list[NodeGraphQt.BaseNode])(Optional): if 'start_nodes' is None the function can calculate start nodes from 'all_nodes'.
+        start_nodes (list[NodeGraphQt.BaseNode]):
+            (Optional) the end nodes of the graph.
+        all_nodes (list[NodeGraphQt.BaseNode]):
+            (Optional) if 'start_nodes' is None the function can calculate
+            start nodes from 'all_nodes'.
     """
     if not start_nodes and not all_nodes:
         return
@@ -741,8 +754,11 @@ def auto_layout_down(start_nodes=None, all_nodes=None):
     Auto layout the nodes by down stream direction.
 
     Args:
-        start_nodes (list[NodeGraphQt.BaseNode])(Optional): the start update nodes of the graph.
-        all_nodes (list[NodeGraphQt.BaseNode])(Optional): if 'start_nodes' is None the function can calculate start nodes from 'all_nodes'.
+        start_nodes (list[NodeGraphQt.BaseNode]):
+            (Optional) the start update nodes of the graph.
+        all_nodes (list[NodeGraphQt.BaseNode]):
+            (Optional) if 'start_nodes' is None the function can calculate
+            start nodes from 'all_nodes'.
     """
     if not start_nodes and not all_nodes:
         return