Changeset 11443:ff959d88f2d9 in orange


Ignore:
Timestamp:
03/26/13 13:38:01 (13 months ago)
Author:
Ales Erjavec <ales.erjavec@…>
Branch:
default
Message:

Added docstring documentation for canvas interactions.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • Orange/OrangeCanvas/document/interactions.py

    r11401 r11443  
    11""" 
    2 User interaction handlers for CanvasScene. 
     2========================= 
     3User Interaction Handlers 
     4========================= 
     5 
     6User interaction handlers for a :class:`~.SchemeEditWidget`. 
     7 
     8User interactions encapsulate the logic of user interactions with the 
     9scheme document. 
     10 
     11All interactions are subclasses of :class:`UserInteraction`. 
     12 
    313 
    414""" 
     15 
    516import logging 
    617 
     
    2637 
    2738class UserInteraction(QObject): 
    28     # cancel reason flags 
    29     NoReason = 0  # No specified reason 
    30     UserCancelReason = 1  # User canceled the operation (e.g. pressing ESC) 
    31     InteractionOverrideReason = 3  # Another interaction was set 
    32     ErrorReason = 4  # An internal error occurred 
     39    """ 
     40    Base class for user interaction handlers. 
     41 
     42    Parameters 
     43    ---------- 
     44    document : :class:`~.SchemeEditWidget` 
     45        An scheme editor instance with which the user is interacting. 
     46    parent : :class:`QObject`, optional 
     47        A parent QObject 
     48    deleteOnEnd : bool, optional 
     49        Should the UserInteraction be deleted when it finishes (``True`` 
     50        by default). 
     51 
     52    """ 
     53    # Cancel reason flags 
     54 
     55    #: No specified reason 
     56    NoReason = 0 
     57    #: User canceled the operation (e.g. pressing ESC) 
     58    UserCancelReason = 1 
     59    #: Another interaction was set 
     60    InteractionOverrideReason = 3 
     61    #: An internal error occurred 
     62    ErrorReason = 4 
     63    #: Other (unspecified) reason 
    3364    OtherReason = 5 
    3465 
    35     # Emitted when the interaction is set on the scene. 
     66    #: Emitted when the interaction is set on the scene. 
    3667    started = Signal() 
    3768 
    38     # Emitted when the interaction finishes successfully. 
     69    #: Emitted when the interaction finishes successfully. 
    3970    finished = Signal() 
    4071 
    41     # Emitted when the interaction ends (canceled or finished) 
     72    #: Emitted when the interaction ends (canceled or finished) 
    4273    ended = Signal() 
    4374 
    44     # Emitted when the interaction is canceled. 
     75    #: Emitted when the interaction is canceled. 
    4576    canceled = Signal([], [int]) 
    4677 
     
    5990 
    6091    def start(self): 
    61         """Start the interaction. This is called by the scene when 
     92        """ 
     93        Start the interaction. This is called by the :class:`CanvasScene` when 
    6294        the interaction is installed. 
    6395 
    64         Must be called from subclass implementations. 
     96        .. note:: Must be called from subclass implementations. 
    6597 
    6698        """ 
     
    68100 
    69101    def end(self): 
    70         """Finish the interaction. Restore any leftover state in 
    71         this method. 
    72  
    73         .. note:: This gets called from the default `cancel` implementation. 
     102        """ 
     103        Finish the interaction. Restore any leftover state in this method. 
     104 
     105        .. note:: This gets called from the default :func:`cancel` 
     106                  implementation. 
    74107 
    75108        """ 
     
    91124 
    92125    def cancel(self, reason=OtherReason): 
    93         """Cancel the interaction for `reason`. 
     126        """ 
     127        Cancel the interaction with `reason`. 
    94128        """ 
    95129 
     
    100134 
    101135    def isFinished(self): 
    102         """Has the interaction finished. 
     136        """ 
     137        Is the interaction finished. 
    103138        """ 
    104139        return self.__finished 
    105140 
    106141    def isCanceled(self): 
    107         """Was the interaction canceled. 
     142        """ 
     143        Was the interaction canceled. 
    108144        """ 
    109145        return self.__canceled 
    110146 
    111147    def cancelReason(self): 
    112         """Return the reason the interaction was canceled. 
     148        """ 
     149        Return the reason the interaction was canceled. 
    113150        """ 
    114151        return self.__cancelReason 
    115152 
    116153    def mousePressEvent(self, event): 
     154        """ 
     155        Handle a `QGraphicsScene.mousePressEvent`. 
     156        """ 
    117157        return False 
    118158 
    119159    def mouseMoveEvent(self, event): 
     160        """ 
     161        Handle a `GraphicsScene.mouseMoveEvent`. 
     162        """ 
    120163        return False 
    121164 
    122165    def mouseReleaseEvent(self, event): 
     166        """ 
     167        Handle a `QGraphicsScene.mouseReleaseEvent`. 
     168        """ 
    123169        return False 
    124170 
    125171    def mouseDoubleClickEvent(self, event): 
     172        """ 
     173        Handle a `QGraphicsScene.mouseDoubleClickEvent`. 
     174        """ 
    126175        return False 
    127176 
    128177    def keyPressEvent(self, event): 
     178        """ 
     179        Handle a `QGraphicsScene.keyPressEvent` 
     180        """ 
    129181        if self.cancelOnEsc and event.key() == Qt.Key_Escape: 
    130182            self.cancel(self.UserCancelReason) 
     
    132184 
    133185    def keyReleaseEvent(self, event): 
     186        """ 
     187        Handle a `QGraphicsScene.keyPressEvent` 
     188        """ 
    134189        return False 
    135190 
     
    140195 
    141196def reversed_arguments(func): 
    142     """Return a function with reversed argument order. 
     197    """ 
     198    Return a function with reversed argument order. 
    143199    """ 
    144200    def wrapped(*args): 
     
    148204 
    149205class NewLinkAction(UserInteraction): 
    150     """User drags a new link from an existing node anchor item to create 
     206    """ 
     207    User drags a new link from an existing `NodeAnchorItem` to create 
    151208    a connection between two existing nodes or to a new node if the release 
    152209    is over an empty area, in which case a quick menu for new node selection 
     
    165222        self.direction = None 
    166223 
     224        # An `NodeItem` currently under the mouse as a possible 
     225        # link drop target. 
    167226        self.current_target_item = None 
     227        # A temporary `LinkItem` used while dragging. 
    168228        self.tmp_link_item = None 
     229        # An temporary `AnchorPoint` inserted into `current_target_item` 
    169230        self.tmp_anchor_point = None 
     231        # An `AnchorPoint` following the mouse cursor 
    170232        self.cursor_anchor_point = None 
    171233 
    172234    def remove_tmp_anchor(self): 
    173         """Remove a temp anchor point from the current target item. 
     235        """ 
     236        Remove a temporary anchor point from the current target item. 
    174237        """ 
    175238        if self.direction == self.FROM_SOURCE: 
     
    180243 
    181244    def create_tmp_anchor(self, item): 
    182         """Create a new tmp anchor at the item (`NodeItem`). 
     245        """ 
     246        Create a new tmp anchor at the `item` (:class:`NodeItem`). 
    183247        """ 
    184248        assert(self.tmp_anchor_point is None) 
     
    189253 
    190254    def can_connect(self, target_item): 
    191         """Is the connection between `self.from_item` (item where the drag 
    192         started) and `target_item`. 
     255        """ 
     256        Is the connection between `self.from_item` (item where the drag 
     257        started) and `target_item` possible. 
    193258 
    194259        """ 
     
    202267 
    203268    def set_link_target_anchor(self, anchor): 
    204         """Set the temp line target anchor 
     269        """ 
     270        Set the temp line target anchor. 
    205271        """ 
    206272        if self.direction == self.FROM_SOURCE: 
     
    210276 
    211277    def target_node_item_at(self, pos): 
    212         """Return a suitable NodeItem on which a link can be dropped. 
    213         """ 
    214         # Test for a suitable NodeAnchorItem or NodeItem at pos. 
     278        """ 
     279        Return a suitable :class:`NodeItem` at position `pos` on which 
     280        a link can be dropped. 
     281 
     282        """ 
     283        # Test for a suitable `NodeAnchorItem` or `NodeItem` at pos. 
    215284        if self.direction == self.FROM_SOURCE: 
    216285            anchor_type = items.SinkAnchorItem 
     
    347416 
    348417    def create_new(self, event): 
    349         """Create and return a new node with a QuickWidgetMenu. 
     418        """ 
     419        Create and return a new node with a `QuickMenu`. 
    350420        """ 
    351421        pos = event.screenPos() 
     
    391461 
    392462    def connect_existing(self, node): 
    393         """Connect anchor_item to `node`. 
     463        """ 
     464        Connect anchor_item to `node`. 
    394465        """ 
    395466        if self.direction == self.FROM_SOURCE: 
     
    495566    def end(self): 
    496567        self.cleanup() 
     568        # Remove the help tip set in mousePressEvent 
    497569        helpevent = QuickHelpTipEvent("", "") 
    498570        QCoreApplication.postEvent(self.document, helpevent) 
     
    504576 
    505577    def cleanup(self): 
    506         """Cleanup all temp items in the scene that are left. 
     578        """ 
     579        Cleanup all temporary items in the scene that are left. 
    507580        """ 
    508581        if self.tmp_link_item: 
     
    525598 
    526599class NewNodeAction(UserInteraction): 
    527     """Present the user with a quick menu for node selection and 
     600    """ 
     601    Present the user with a quick menu for node selection and 
    528602    create the selected node. 
    529603 
     
    536610 
    537611    def create_new(self, pos): 
    538         """Create a new widget with a QuickWidgetMenu at `pos` 
    539         (in screen coordinates). 
     612        """ 
     613        Create a new widget with a `QuickMenu` at `pos` (in screen 
     614        coordinates). 
    540615 
    541616        """ 
     
    558633 
    559634class RectangleSelectionAction(UserInteraction): 
    560     """Select items in the scene using a Rectangle selection 
     635    """ 
     636    Select items in the scene using a Rectangle selection 
    561637    """ 
    562638    def __init__(self, document, *args, **kwargs): 
    563639        UserInteraction.__init__(self, document, *args, **kwargs) 
     640        # The initial selection at drag start 
    564641        self.initial_selection = None 
     642        # Selection when last updated in a mouseMoveEvent 
    565643        self.last_selection = None 
     644        # A selection rect (`QRectF`) 
    566645        self.selection_rect = None 
     646        # Keyboard modifiers 
    567647        self.modifiers = 0 
    568648 
     
    603683    def mouseMoveEvent(self, event): 
    604684        if not self.rect_item.scene(): 
     685            # Add the rect item to the scene when the mouse moves. 
    605686            self.scene.addItem(self.rect_item) 
    606687        self.update_selection(event) 
     
    618699 
    619700    def update_selection(self, event): 
     701        """ 
     702        Update the selection rectangle from a QGraphicsSceneMouseEvent 
     703        `event` instance. 
     704 
     705        """ 
    620706        if self.initial_selection is None: 
    621707            self.initial_selection = set(self.scene.selectedItems()) 
     
    625711        self.selection_rect = QRectF(self.selection_rect.topLeft(), pos) 
    626712 
     713        # Make sure the rect_item does not cause the scene rect to grow. 
    627714        rect = self._bound_selection_rect(self.selection_rect.normalized()) 
    628715 
    629         # Need that constant otherwise the sceneRect will still grow 
     716        # Need that 0.5 constant otherwise the sceneRect will still 
     717        # grow (anti-aliasing correction by QGraphicsScene?) 
    630718        pw = self.rect_item.pen().width() + 0.5 
    631719 
     
    662750 
    663751    def viewport_rect(self): 
    664         """Return the bounding rect of the document's viewport on the 
    665         scene. 
    666  
     752        """ 
     753        Return the bounding rect of the document's viewport on the scene. 
    667754        """ 
    668755        view = self.document.view() 
     
    672759 
    673760    def _bound_selection_rect(self, rect): 
    674         """Bound the selection `rect` to a sensible size. 
     761        """ 
     762        Bound the selection `rect` to a sensible size. 
    675763        """ 
    676764        srect = self.scene.sceneRect() 
     
    681769 
    682770class EditNodeLinksAction(UserInteraction): 
     771    """ 
     772    Edit multiple links between two NodeItems using a :class:`EditLinksDialog` 
     773 
     774    Parameters 
     775    ---------- 
     776    document : :class:`SchemeEditWidget` 
     777        The editor widget. 
     778    source_node : :class:`SchemeNode` 
     779        The source (link start) node for the link editor. 
     780    sink_node : :class:`SchemeNode` 
     781        The sink (link end) node for the link editor. 
     782 
     783    """ 
    683784    def __init__(self, document, source_node, sink_node, *args, **kwargs): 
    684785        UserInteraction.__init__(self, document, *args, **kwargs) 
     
    689790        """ 
    690791        Show and execute the `EditLinksDialog`. 
    691         Optional `initial_links` list can provide the initial 
     792        Optional `initial_links` list can provide a list of initial 
    692793        `(source, sink)` channel tuples to show in the view, otherwise 
    693         the dialog is populated with existing links in the scheme 
    694         (pass an empty list to disable all initial links). 
     794        the dialog is populated with existing links in the scheme (passing 
     795        an empty list will disable all initial links). 
    695796 
    696797        """ 
     
    725826            stack.beginMacro("Edit Links") 
    726827 
    727             # First remove links into a single sink channel, 
     828            # First remove links into a 'Single' sink channel, 
    728829            # but only the ones that do not have self.source_node as 
    729830            # a source (they will be removed later from links_to_remove) 
     
    760861 
    761862def point_to_tuple(point): 
    762     return point.x(), point.y() 
     863    """ 
     864    Convert a QPointF into a (x, y) tuple. 
     865    """ 
     866    return (point.x(), point.y()) 
    763867 
    764868 
    765869class NewArrowAnnotation(UserInteraction): 
    766     """Create a new arrow annotation. 
     870    """ 
     871    Create a new arrow annotation handler. 
    767872    """ 
    768873    def __init__(self, document, *args, **kwargs): 
     
    789894 
    790895    def setColor(self, color): 
     896        """ 
     897        Set the color for the new arrow. 
     898        """ 
    791899        self.color = color 
    792900 
     
    852960 
    853961def rect_to_tuple(rect): 
     962    """ 
     963    Convert a QRectF into a (x, y, width, height) tuple. 
     964    """ 
    854965    return rect.x(), rect.y(), rect.width(), rect.height() 
    855966 
    856967 
    857968class NewTextAnnotation(UserInteraction): 
     969    """ 
     970    A New Text Annotation interaction handler 
     971    """ 
    858972    def __init__(self, document, *args, **kwargs): 
    859973        UserInteraction.__init__(self, document, *args, **kwargs) 
     
    884998 
    885999    def createNewAnnotation(self, rect): 
    886         """Create a new TextAnnotation at with `rect` as the geometry. 
     1000        """ 
     1001        Create a new TextAnnotation at with `rect` as the geometry. 
    8871002        """ 
    8881003        annot = scheme.SchemeTextAnnotation(rect_to_tuple(rect)) 
     
    9521067 
    9531068    def defaultTextGeometry(self, point): 
    954         """Return the default text geometry. Used in case the user 
    955         single clicked in the scene. 
     1069        """ 
     1070        Return the default text geometry. Used in case the user single 
     1071        clicked in the scene. 
    9561072 
    9571073        """ 
     
    9831099 
    9841100class ResizeTextAnnotation(UserInteraction): 
     1101    """ 
     1102    Resize a Text Annotation interaction handler. 
     1103    """ 
    9851104    def __init__(self, document, *args, **kwargs): 
    9861105        UserInteraction.__init__(self, document, *args, **kwargs) 
     
    10221141 
    10231142    def commit(self): 
    1024         """Commit the current item geometry state to the document. 
     1143        """ 
     1144        Commit the current item geometry state to the document. 
    10251145        """ 
    10261146        rect = self.item.geometry() 
     
    10681188 
    10691189class ResizeArrowAnnotation(UserInteraction): 
     1190    """ 
     1191    Resize an Arrow Annotation interaction handler. 
     1192    """ 
    10701193    def __init__(self, document, *args, **kwargs): 
    10711194        UserInteraction.__init__(self, document, *args, **kwargs) 
Note: See TracChangeset for help on using the changeset viewer.