Ignore:
Timestamp:
02/22/13 16:00:22 (14 months ago)
Author:
Ales Erjavec <ales.erjavec@…>
Branch:
default
Message:

Added rst documentation for the canvas package.

Fixing docstrings in the process.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • Orange/OrangeCanvas/canvas/items/nodeitem.py

    r11343 r11369  
    99    QGraphicsItem, QGraphicsPathItem, QGraphicsObject, 
    1010    QGraphicsTextItem, QGraphicsDropShadowEffect, QGraphicsView, 
    11     QPen, QBrush, QColor, QPalette, QFont, QIcon, QStyle, 
    12     QPainter, QPainterPath, QPainterPathStroker, QApplication 
     11    QPen, QBrush, QColor, QPalette, QIcon, QStyle, QPainter, 
     12    QPainterPath, QPainterPathStroker, QApplication 
    1313) 
    1414 
     
    2626 
    2727def create_palette(light_color, color): 
    28     """Return a new `QPalette` from for the NodeShapeItem. 
    29  
     28    """ 
     29    Return a new :class:`QPalette` from for the :class:`NodeBodyItem`. 
    3030    """ 
    3131    palette = QPalette() 
     
    4949 
    5050def default_palette(): 
    51     """Create and return a default palette for a node. 
    52  
     51    """ 
     52    Create and return a default palette for a node. 
    5353    """ 
    5454    return create_palette(QColor(NAMED_COLORS["light-orange"]), 
     
    6161 
    6262class NodeBodyItem(QGraphicsPathItem): 
    63     """The central part (body) of the `NodeItem`. 
    64  
     63    """ 
     64    The central part (body) of the `NodeItem`. 
    6565    """ 
    6666    def __init__(self, parent=None): 
     
    9696    # paths (for instance rounded rect, ...) 
    9797    def setShapeRect(self, rect): 
    98         """Set the shape items `rect`. The item should be confined within 
     98        """ 
     99        Set the item's shape `rect`. The item should be confined within 
    99100        this rect. 
    100101 
     
    106107 
    107108    def setPalette(self, palette): 
    108         """Set the shape color palette. 
     109        """ 
     110        Set the body color palette (:class:`QPalette`). 
    109111        """ 
    110112        self.palette = palette 
     
    112114 
    113115    def setProcessingState(self, state): 
    114         """Set the processing state of the node. 
     116        """ 
     117        Set the processing state of the node. 
    115118        """ 
    116119        self.__processingState = state 
     
    118121 
    119122    def setProgress(self, progress): 
     123        """ 
     124        Set the progress indicator state of the node. `progress` should 
     125        be a number between 0 and 100. 
     126 
     127        """ 
    120128        self.__progress = progress 
    121129        self.update() 
     
    132140 
    133141    def paint(self, painter, option, widget): 
    134         """Paint the shape and a progress meter. 
     142        """ 
     143        Paint the shape and a progress meter. 
    135144        """ 
    136145        # Let the default implementation draw the shape 
     
    186195 
    187196    def setSelected(self, selected): 
    188         """Set the `selected` state. 
    189  
    190         .. note:: The item does not have QGraphicsItem.ItemIsSelectable flag. 
     197        """ 
     198        Set the `selected` state. 
     199 
     200        .. note:: The item does not have `QGraphicsItem.ItemIsSelectable` flag. 
    191201                  This property is instead controlled by the parent NodeItem. 
    192202 
     
    196206 
    197207    def setHasFocus(self, focus): 
    198         """Set the `has focus` state. 
    199  
    200         .. note:: The item does not have QGraphicsItem.ItemIsFocusable flag. 
     208        """ 
     209        Set the `has focus` state. 
     210 
     211        .. note:: The item does not have `QGraphicsItem.ItemIsFocusable` flag. 
    201212                  This property is instead controlled by the parent NodeItem. 
     213 
    202214        """ 
    203215        self.__hasFocus = focus 
     
    206218 
    207219class AnchorPoint(QGraphicsObject): 
    208     """A anchor indicator on the NodeAnchorItem 
    209     """ 
    210  
     220    """ 
     221    A anchor indicator on the :class:`NodeAnchorItem`. 
     222    """ 
     223 
     224    # Signal emitted when the item's scene position changes. 
    211225    scenePositionChanged = Signal(QPointF) 
     226 
    212227    anchorDirectionChanged = Signal(QPointF) 
    213228 
     
    220235 
    221236    def anchorScenePos(self): 
    222         """Return anchor position in scene coordinates. 
     237        """ 
     238        Return anchor position in scene coordinates. 
    223239        """ 
    224240        return self.mapToScene(QPointF(0, 0)) 
    225241 
    226242    def setAnchorDirection(self, direction): 
    227         """Set the preferred direction (QPointF) in item coordinates. 
     243        """ 
     244        Set the preferred direction (QPointF) in item coordinates. 
    228245        """ 
    229246        if self.__direction != direction: 
     
    232249 
    233250    def anchorDirection(self): 
    234         """Return the preferred anchor direction. 
     251        """ 
     252        Return the preferred anchor direction. 
    235253        """ 
    236254        return self.__direction 
     
    247265 
    248266class NodeAnchorItem(GraphicsPathObject): 
    249     """The left/right widget input/output anchors. 
     267    """ 
     268    The left/right widget input/output anchors. 
    250269    """ 
    251270 
     
    284303 
    285304    def parentNodeItem(self): 
    286         """Return a parent `NodeItem` or `None` if this anchor's 
    287         parent is not a `NodeItem` instance. 
     305        """ 
     306        Return a parent :class:`NodeItem` or ``None`` if this anchor's 
     307        parent is not a :class:`NodeItem` instance. 
    288308 
    289309        """ 
     
    291311 
    292312    def setAnchorPath(self, path): 
    293         """Set the anchor's curve path as a QPainterPath. 
     313        """ 
     314        Set the anchor's curve path as a :class:`QPainterPath`. 
    294315        """ 
    295316        self.__anchorPath = path 
     
    318339 
    319340    def anchorPath(self): 
    320         """Return the QPainterPath of the anchor path (a curve on 
    321         which the anchor points lie) 
     341        """ 
     342        Return the anchor path (:class:`QPainterPath`). This is a curve on 
     343        which the anchor points lie. 
    322344 
    323345        """ 
     
    325347 
    326348    def setAnchored(self, anchored): 
    327         """Set the items anchored state. When false the item draws it self 
     349        """ 
     350        Set the items anchored state. When ``False`` the item draws it self 
    328351        with a dotted stroke. 
    329352 
     
    338361 
    339362    def setConnectionHint(self, hint=None): 
    340         """Set the connection hint. This can be used to indicate if 
     363        """ 
     364        Set the connection hint. This can be used to indicate if 
    341365        a connection can be made or not. 
    342366 
     
    345369 
    346370    def count(self): 
    347         """Return the number of anchor points. 
     371        """ 
     372        Return the number of anchor points. 
    348373        """ 
    349374        return len(self.__points) 
    350375 
    351376    def addAnchor(self, anchor, position=0.5): 
    352         """Add a new AnchorPoint to this item and return it's index. 
     377        """ 
     378        Add a new :class:`AnchorPoint` to this item and return it's index. 
     379 
     380        The `position` specifies where along the `anchorPath` is the new 
     381        point inserted. 
     382 
    353383        """ 
    354384        return self.insertAnchor(self.count(), anchor, position) 
    355385 
    356386    def insertAnchor(self, index, anchor, position=0.5): 
    357         """Insert a new AnchorPoint at `index`. 
     387        """ 
     388        Insert a new :class:`AnchorPoint` at `index`. 
     389 
     390        See also 
     391        -------- 
     392        NodeAnchorItem.addAnchor 
     393 
    358394        """ 
    359395        if anchor in self.__points: 
     
    374410 
    375411    def removeAnchor(self, anchor): 
    376         """Remove and delete the anchor point. 
     412        """ 
     413        Remove and delete the anchor point. 
    377414        """ 
    378415        anchor = self.takeAnchor(anchor) 
     
    383420 
    384421    def takeAnchor(self, anchor): 
    385         """Remove the anchor but don't delete it. 
     422        """ 
     423        Remove the anchor but don't delete it. 
    386424        """ 
    387425        index = self.__points.index(anchor) 
     
    408446 
    409447    def anchorPoints(self): 
    410         """Return a list of anchor points. 
     448        """ 
     449        Return a list of anchor points. 
    411450        """ 
    412451        return list(self.__points) 
    413452 
    414453    def anchorPoint(self, index): 
    415         """Return the anchor point at `index`. 
     454        """ 
     455        Return the anchor point at `index`. 
    416456        """ 
    417457        return self.__points[index] 
    418458 
    419459    def setAnchorPositions(self, positions): 
    420         """Set the anchor positions in percentages (0..1) along 
    421         the path curve. 
    422  
     460        """ 
     461        Set the anchor positions in percentages (0..1) along the path curve. 
    423462        """ 
    424463        if self.__pointPositions != positions: 
     
    428467 
    429468    def anchorPositions(self): 
    430         """Return the positions of anchor points as a list of floats where 
     469        """ 
     470        Return the positions of anchor points as a list of floats where 
    431471        each float is between 0 and 1 and specifies where along the anchor 
    432472        path does the point lie (0 is at start 1 is at the end). 
     
    464504 
    465505class SourceAnchorItem(NodeAnchorItem): 
    466     """A source anchor item 
     506    """ 
     507    A source anchor item 
    467508    """ 
    468509    pass 
     
    470511 
    471512class SinkAnchorItem(NodeAnchorItem): 
    472     """A sink anchor item. 
     513    """ 
     514    A sink anchor item. 
    473515    """ 
    474516    pass 
     
    476518 
    477519def standard_icon(standard_pixmap): 
    478     """Return return the application style's standard icon for a 
     520    """ 
     521    Return return the application style's standard icon for a 
    479522    `QStyle.StandardPixmap`. 
    480523 
     
    485528 
    486529class GraphicsIconItem(QGraphicsItem): 
    487     """A graphics item displaying an `QIcon`. 
     530    """ 
     531    A graphics item displaying an :class:`QIcon`. 
    488532    """ 
    489533    def __init__(self, parent=None, icon=None, iconSize=None, **kwargs): 
     
    505549 
    506550    def setIcon(self, icon): 
    507         """Set the icon (:class:`QIcon`). 
     551        """ 
     552        Set the icon (:class:`QIcon`). 
    508553        """ 
    509554        if self.__icon != icon: 
     
    512557 
    513558    def icon(self): 
    514         """Return the icon (:class:`QIcon`). 
     559        """ 
     560        Return the icon (:class:`QIcon`). 
    515561        """ 
    516562        return QIcon(self.__icon) 
    517563 
    518564    def setIconSize(self, size): 
    519         """Set the icon (and this item's) size (:class:`QSize`). 
     565        """ 
     566        Set the icon (and this item's) size (:class:`QSize`). 
    520567        """ 
    521568        if self.__iconSize != size: 
     
    525572 
    526573    def iconSize(self): 
    527         """Return the icon size (:class:`QSize`). 
     574        """ 
     575        Return the icon size (:class:`QSize`). 
    528576        """ 
    529577        return QSize(self.__iconSize) 
    530578 
    531579    def setTransformationMode(self, mode): 
    532         """Set pixmap transformation mode. (`Qt.SmoothTransformation` or 
     580        """ 
     581        Set pixmap transformation mode. (`Qt.SmoothTransformation` or 
    533582        `Qt.FastTransformation`). 
    534583 
     
    539588 
    540589    def transformationMode(self): 
    541         """Return the pixmap transformation mode. 
     590        """ 
     591        Return the pixmap transformation mode. 
    542592        """ 
    543593        return self.__transformationMode 
     
    588638 
    589639class NodeItem(QGraphicsObject): 
    590     """An widget node item in the canvas. 
    591     """ 
    592  
     640    """ 
     641    An widget node item in the canvas. 
     642    """ 
     643 
     644    # Scene position of the node has changed. 
    593645    positionChanged = Signal() 
    594     """Position of the node on the canvas changed""" 
    595  
     646 
     647    # Geometry of the channel anchors changed 
    596648    anchorGeometryChanged = Signal() 
    597     """Geometry of the channel anchors changed""" 
    598  
     649 
     650    # The item has been activated (by a mouse double click or a keyboard). 
    599651    activated = Signal() 
    600     """The item has been activated (by a mouse double click or a keyboard)""" 
    601  
     652 
     653    # The item is under the mouse. 
    602654    hovered = Signal() 
    603     """The item is under the mouse.""" 
    604  
     655 
     656    #: Span of the anchor in degrees 
    605657    ANCHOR_SPAN_ANGLE = 90 
    606     """Span of the anchor in degrees""" 
    607  
     658 
     659    #: Z value of the item 
    608660    Z_VALUE = 100 
    609     """Z value of the item""" 
    610661 
    611662    def __init__(self, widget_description=None, parent=None, **kwargs): 
     
    649700    @classmethod 
    650701    def from_node(cls, node): 
    651         """Create an `NodeItem` instance and initialize it from an 
    652         `SchemeNode` instance. 
     702        """ 
     703        Create an :class:`NodeItem` instance and initialize it from a 
     704        :class:`SchemeNode` instance. 
    653705 
    654706        """ 
     
    660712    @classmethod 
    661713    def from_node_meta(cls, meta_description): 
    662         """Create an `NodeItem` instance from a node meta description. 
     714        """ 
     715        Create an `NodeItem` instance from a node meta description. 
    663716        """ 
    664717        self = cls() 
     
    667720 
    668721    def setupGraphics(self): 
    669         """Set up the graphics. 
     722        """ 
     723        Set up the graphics. 
    670724        """ 
    671725        shape_rect = QRectF(-24, -24, 48, 48) 
     
    708762        self.infoItem = iconItem(QStyle.SP_MessageBoxInformation) 
    709763 
     764    # TODO: Remove the set[Widget|Category]Description. The user should 
     765    # handle setting of icons, title, ... 
    710766    def setWidgetDescription(self, desc): 
    711         """Set widget description. 
     767        """ 
     768        Set widget description. 
    712769        """ 
    713770        self.widget_description = desc 
     
    731788 
    732789    def setWidgetCategory(self, desc): 
     790        """ 
     791        Set the widget category. 
     792        """ 
    733793        self.category_description = desc 
    734794        if desc and desc.background: 
     
    739799 
    740800    def setIcon(self, icon): 
    741         """Set the widget's icon 
     801        """ 
     802        Set the node item's icon. 
    742803        """ 
    743804        if isinstance(icon, QIcon): 
     
    749810 
    750811    def setColor(self, color, selectedColor=None): 
    751         """Set the widget color. 
     812        """ 
     813        Set the widget color. 
    752814        """ 
    753815        if selectedColor is None: 
     
    756818        self.shapeItem.setPalette(palette) 
    757819 
    758     def setPalette(self): 
    759         """ 
    760         """ 
    761         pass 
     820    def setPalette(self, palette): 
     821        # TODO: The palette should override the `setColor` 
     822        raise NotImplementedError 
    762823 
    763824    def setTitle(self, title): 
    764         """Set the widget title. 
     825        """ 
     826        Set the node title. The title text is displayed at the bottom of the 
     827        node. 
     828 
    765829        """ 
    766830        self.__title = title 
     
    768832 
    769833    def title(self): 
     834        """ 
     835        Return the node title. 
     836        """ 
    770837        return self.__title 
    771838 
    772     title_ = Property(unicode, fget=title, fset=setTitle) 
     839    title_ = Property(unicode, fget=title, fset=setTitle, 
     840                      doc="Node title text.") 
    773841 
    774842    def setFont(self, font): 
    775843        """ 
    776         Set the title text font. 
     844        Set the title text font (:class:`QFont`). 
    777845        """ 
    778846        if font != self.font(): 
     
    788856 
    789857    def setProcessingState(self, state): 
    790         """Set the node processing state i.e. the node is processing 
     858        """ 
     859        Set the node processing state i.e. the node is processing 
    791860        (is busy) or is idle. 
    792861 
     
    800869 
    801870    def processingState(self): 
     871        """ 
     872        The node processing state. 
     873        """ 
    802874        return self.__processingState 
    803875 
     
    806878 
    807879    def setProgress(self, progress): 
    808         """Set the node work progress indicator. 
     880        """ 
     881        Set the node work progress state (number between 0 and 100). 
    809882        """ 
    810883        if progress is None or progress < 0: 
     
    818891 
    819892    def progress(self): 
     893        """ 
     894        Return the node work progress state. 
     895        """ 
    820896        return self.__progress 
    821897 
    822     progress_ = Property(float, fget=progress, fset=setProgress) 
     898    progress_ = Property(float, fget=progress, fset=setProgress, 
     899                         doc="Node progress state.") 
    823900 
    824901    def setProgressMessage(self, message): 
    825         """Set the node work progress message. 
     902        """ 
     903        Set the node work progress message. 
     904 
     905        .. note:: Not yet implemented 
     906 
    826907        """ 
    827908        pass 
     
    843924 
    844925    def newInputAnchor(self): 
    845         """Create and return a new input anchor point. 
     926        """ 
     927        Create and return a new input anchor point. 
    846928        """ 
    847929        if not (self.widget_description and self.widget_description.inputs): 
     
    858940 
    859941    def removeInputAnchor(self, anchor): 
    860         """Remove input anchor. 
     942        """ 
     943        Remove input anchor. 
    861944        """ 
    862945        self.inputAnchorItem.removeAnchor(anchor) 
     
    867950 
    868951    def newOutputAnchor(self): 
    869         """Create a new output anchor indicator. 
     952        """ 
     953        Create a new output anchor indicator. 
    870954        """ 
    871955        if not (self.widget_description and self.widget_description.outputs): 
     
    882966 
    883967    def removeOutputAnchor(self, anchor): 
    884         """Remove output anchor. 
     968        """ 
     969        Remove output anchor. 
    885970        """ 
    886971        self.outputAnchorItem.removeAnchor(anchor) 
     
    891976 
    892977    def inputAnchors(self): 
    893         """Return a list of input anchor points. 
     978        """ 
     979        Return a list of input anchor points. 
    894980        """ 
    895981        return self.inputAnchorItem.anchorPoints() 
    896982 
    897983    def outputAnchors(self): 
    898         """Return a list of output anchor points. 
     984        """ 
     985        Return a list of output anchor points. 
    899986        """ 
    900987        return self.outputAnchorItem.anchorPoints() 
    901988 
    902989    def setAnchorRotation(self, angle): 
    903         """Set the anchor rotation. 
     990        """ 
     991        Set the anchor rotation. 
    904992        """ 
    905993        self.inputAnchorItem.setRotation(angle) 
     
    908996 
    909997    def anchorRotation(self): 
    910         """Return the anchor rotation. 
     998        """ 
     999        Return the anchor rotation. 
    9111000        """ 
    9121001        return self.inputAnchorItem.rotation() 
     
    9191008 
    9201009    def shape(self): 
    921         """Reimplemented: Return the shape of the 'shapeItem', This is used 
    922         for hit testing in QGraphicsScene. 
    923  
    924         """ 
    925         # Should this return the union of all child items? 
     1010        # Shape for mouse hit detection. 
     1011        # TODO: Should this return the union of all child items? 
    9261012        return self.shapeItem.shape() 
    9271013 
    9281014    def __updateTitleText(self): 
    929         """Update the title text item. 
     1015        """ 
     1016        Update the title text item. 
    9301017        """ 
    9311018        title_safe = escape(self.title()) 
     
    9451032 
    9461033    def __updateMessages(self): 
    947         """Update message items (position, visibility and tool tips). 
     1034        """ 
     1035        Update message items (position, visibility and tool tips). 
    9481036        """ 
    9491037        items = [self.errorItem, self.warningItem, self.infoItem] 
     
    10171105 
    10181106def NodeItem_toolTipHelper(node, links_in=[], links_out=[]): 
    1019     """A helper function for constructing a standard tooltop for the node 
     1107    """ 
     1108    A helper function for constructing a standard tooltop for the node 
    10201109    in on the canvas. 
    10211110 
Note: See TracChangeset for help on using the changeset viewer.