Changeset 8658:f37fd03c4099 in orange


Ignore:
Timestamp:
08/11/11 09:33:26 (3 years ago)
Author:
Noughmad <Noughmad@…>
Branch:
default
Convert:
040a0e736fa40d8ef2b91398b2fa14c4f65bbd70
Message:

Add documentation for OWPlot and OWLegend.

Files:
2 added
4 edited

Legend:

Unmodified
Added
Removed
  • orange/OrangeWidgets/plot/owlegend.py

    r8655 r8658  
    1  
     1""" 
     2########################## 
     3Plot legend (``owlegend``) 
     4########################## 
     5 
     6.. autoclass:: OWLegendItem 
     7 
     8.. autoclass:: OWLegendTitle 
     9 
     10.. autoclass:: OWLegend 
     11    :members: 
     12 
     13""" 
    214 
    315from PyQt4.QtGui import QGraphicsTextItem, QGraphicsRectItem, QGraphicsObject, QColor, QPen 
     
    1325 
    1426class OWLegendItem(QGraphicsObject): 
     27    """ 
     28        Represents a legend item with a title and a point symbol. 
     29         
     30        :param name: The text to display 
     31        :type name: str 
     32         
     33        :param point: The point symbol 
     34        :type point: :obj:`.OWPoint` 
     35         
     36        :param parent: The parent item, passed to QGraphicsItem 
     37        :type parent: :obj:`QGraphicsItem` 
     38         
     39        .. seealso:: :meth:`.OWLegend.add_item`, :meth:`.OWLegend.add_curve`.  
     40    """ 
    1541    def __init__(self, name, point, parent): 
    1642        QGraphicsObject.__init__(self, parent) 
     
    4268     
    4369class OWLegendTitle(QGraphicsObject): 
     70    """ 
     71        A legend item that shows ``text`` with a bold font and no symbol.  
     72    """ 
    4473    def __init__(self, text, parent): 
    4574        QGraphicsObject.__init__(self, parent) 
     
    5685         
    5786class OWLegend(QGraphicsObject): 
     87    """ 
     88        A legend for :obj:`.OWPlot`.  
     89         
     90        Its items are arranged into a hierarchy by `category`. This is useful when points differ in more than one attribute.  
     91        In such a case, there can be one category for point color and one for point shape. Usually the category name 
     92        will be the name of the attribute, while the item's title will be the value.  
     93         
     94        Arbitrary categories can be created, for an example see :meth:`.OWPlot.update_axes`, which creates a special category 
     95        for unused axes.  
     96         
     97        .. image:: files/legend-categories.png 
     98         
     99        In the image above, `type` and `milk` are categories with 7 and 2 possible values, respectively.  
     100         
     101    """ 
    58102    def __init__(self, graph, scene): 
    59103        QGraphicsObject.__init__(self) 
     
    81125 
    82126    def clear(self): 
     127        """ 
     128            Removes all items from the legend 
     129        """ 
    83130        for lst in self.items.itervalues(): 
    84131            for i in lst: 
     
    89136         
    90137 
    91     def add_curve(self, curve, attributes = []): 
     138    def add_curve(self, curve): 
     139        """ 
     140            Adds a legend item with the same point symbol and name as ``curve``. 
     141             
     142            If the curve's name contains the equal sign (=), it is split at that sign. The first part of the curve 
     143            is a used as the category, and the second part as the value.  
     144        """ 
    92145        i = curve.name.find('=') 
    93146        if i == -1: 
     
    100153         
    101154    def add_item(self, category, value, point): 
     155        """ 
     156            Adds an item with title ``value`` and point symbol ``point`` to the specified ``category``.  
     157        """ 
    102158        if category not in self.items: 
    103159            self.items[category] = [OWLegendTitle(category, self)] 
     
    106162         
    107163    def remove_category(self, category): 
     164        """ 
     165            Removes ``category`` and all items that belong to it.  
     166        """ 
    108167        if category not in self.items: 
    109168            return 
     
    113172         
    114173    def update(self): 
     174        """ 
     175            Updates the legend, repositioning the items according to the legend's orientation.  
     176        """ 
    115177        self.box_rect = QRectF() 
    116178        x, y = 0, 0 
     
    127189        elif self._orientation == Qt.Horizontal: 
    128190            for lst in self.items.itervalues(): 
     191                max_h = max(item.boundingRect().height() for item in lst) 
     192                if lst: 
     193                    x = 0 
     194                    y = y + max_h 
    129195                for item in lst: 
    130196                    if self.max_size.width() and x and x + item.boundingRect().width() > self.max_size.width(): 
    131197                        x = 0 
    132                         y = y + item.boundingRect().height() 
     198                        y = y + max_h 
    133199                    self.box_rect = self.box_rect | item.boundingRect().translated(x, y) 
    134200                    move_item_xy(item, x, y, self.graph.use_animations) 
    135                     x = x + item.boundingRect().width() 
     201                    x = x + item.boundingRect().width()                 
    136202        else: 
    137203            qDebug('A bad orientation of the legend') 
     
    166232     
    167233    def set_orientation(self, orientation): 
     234        """ 
     235            Sets the legend's orientation to ``orientation``.  
     236        """ 
    168237        if self._orientation != orientation: 
    169238            self._orientation = orientation 
     
    185254         
    186255    def set_floating(self, floating, pos=None): 
     256        """ 
     257            If floating is ``True``, the legend can be dragged with the mouse.  
     258            Otherwise, it's fixed in its position.  
     259             
     260            If ``pos`` is specified, the legend is moved there.  
     261        """ 
    187262        if floating == self._floating: 
    188263            return 
  • orange/OrangeWidgets/plot/owplot.py

    r8656 r8658  
    9292         
    9393        .. automethod:: set_show_main_title 
     94         
     95        .. attribute:: axis_margin 
     96             
     97            How much space (in pixels) should be left on each side for the axis, its label and its title. 
     98         
     99        .. attribute:: title_margin 
     100         
     101            How much space (in pixels) should be left at the top of the plot for the title, if the title is shown.  
     102             
     103            .. seealso:: attribute :attr:`show_main_title` 
     104             
     105        .. attribute:: plot_margin 
     106         
     107            How much space (in pixels) should be left at each side of the plot as whitespace.  
     108             
    94109     
    95110    **Coordinate transformation** 
    96111     
     112        There are several coordinate systems used by OWPlot: 
     113         
     114        * `widget` coordinates.  
     115           
     116          This is the coordinate system of the position returned by :meth:`.QEvent.pos()`.  
     117          No calculations or positions is done with this coordinates, they must first be converted  
     118          to scene coordinates with :meth:`mapToScene`.  
     119           
     120        * `data` coordinates.  
     121         
     122          The value used internally in Orange to specify the values of attributes.  
     123          For example, this can be age in years, the number of legs, or any other numeric value.  
     124           
     125        * `plot` coordinates.  
     126         
     127          These coordinates specify where the plot items are placed on the graph, but doesn't account for zoom.  
     128          They can be retrieved for a particular plot item with :meth:`.PlotItem.pos()`.  
     129           
     130        * `scene` or `zoom` coordinates.  
     131         
     132          Like plot coordinates, except that they take the :attr:`zoom_transform` into account. They represent the 
     133          actual position of an item on the scene.  
     134           
     135          These are the coordinates returned by :meth:`.PlotItem.scenePos()` and :meth:`mapToScene`.  
     136           
     137          For example, they can be used to determine what is under the cursor.  
     138           
     139        In most cases, you will use data coordinates for interacting with the actual data, and scene coordinates for 
     140        interacting with the plot items. The other two sets are mostly used for converting.  
    97141         
    98142        .. automethod:: map_to_graph 
     
    125169         
    126170    **Data curves** 
    127          
     171        The preferred method for showing a series of data points is :meth:`set_main_curve_data`.  
     172        It allows you to specify point positions, colors, labels, sizes and shapes.  
     173         
     174        .. automethod:: set_main_curve_data 
    128175         
    129176        .. automethod:: add_curve 
     
    243290        self._legend_moved = False 
    244291        self.axes = dict() 
     292 
    245293        self.axis_margin = 50 
    246294        self.title_margin = 40 
    247295        self.graph_margin = 20 
     296         
    248297        self.mainTitle = None 
    249298        self.showMainTitle = False 
     
    356405        ''' 
    357406            Maps ``point``, which can be ether a tuple of (x,y), a QPoint or a QPointF, from data coordinates 
    358             to scene coordinates.  
     407            to plot coordinates.  
    359408             
    360409            :param point: The point in data coordinates 
     
    365414            :type axes: tuple of float float 
    366415             
    367             :param zoom: if ``True``, the current :attr:`zoom_transform` will be considered in the transformation. 
     416            :param zoom: if ``True``, the current :attr:`zoom_transform` will be considered in the transformation, and the result will be in scene coordinates instead.  
    368417            :type zoom: int 
    369418             
     
    385434    def map_from_graph(self, point, axes = None, zoom = False): 
    386435        ''' 
    387             Maps ``point``, which can be ether a tuple of (x,y), a QPoint or a QPointF, from data coordinates 
    388             to scene coordinates.  
     436            Maps ``point``, which can be ether a tuple of (x,y), a QPoint or a QPointF, from plot coordinates 
     437            to data coordinates.  
    389438             
    390439            :param point: The point in data coordinates 
     
    394443            :type axes: tuple of float float 
    395444             
    396             :param zoom: if ``True``, the current :attr:`zoom_transform` will be considered in the transformation. 
     445            :param zoom: if ``True``, the current :attr:`zoom_transform` will be considered in the transformation, and the ``point`` should be in scene coordinates instead.  
    397446            :type zoom: int 
    398447             
     
    618667        """ 
    619668            Creates a single curve that can have points of different colors, shapes and sizes.  
     669            This is the preferred method for visualization that show a series of different points.  
     670             
     671            :param x_data: The list of X coordinates of the points  
     672            :type x_data: list of float 
     673             
     674            :param y_data: The list of Y coordinates of the points  
     675            :type y_data: list of float 
     676             
     677            :param color_data: The list of point colors 
     678            :type color_data: list of QColor 
     679             
     680            :param label_data: The list of point labels 
     681            :type label_data: list of str 
     682             
     683            :param size_data: The list of point sizes 
     684            :type size_data: list of int 
     685             
     686            :param shape_data: The list of point symbols 
     687            :type shape_data: list of int 
     688             
     689            The number of points in the curve will be equal to min(len(x_data), len(y_data)).  
     690            The other four list can be empty, in which case a default value will be used.  
     691            If they contain only one element, its value will be used for all points.  
     692             
     693            .. note:: This function does not add items to the legend automatically.  
     694                      You will have to add them yourself with :meth:`.OWLegend.add_item`.  
    620695        """ 
    621696        if not self.main_curve: 
     
    11631238    def transform(self, axis_id, value): 
    11641239        """ 
    1165             Transforms the ``value`` from data to scene coordinates along the axis ``axis_id``.  
     1240            Transforms the ``value`` from data to plot coordinates along the axis ``axis_id``.  
    11661241             
    11671242            This function always ignores zoom. If you need to account for zooming, use :meth:`map_to_graph`.  
     
    11811256    def inv_transform(self, axis_id, value): 
    11821257        """ 
    1183             Transforms the ``value`` from scene to data coordinates along the axis ``axis_id``.  
     1258            Transforms the ``value`` from plot to data coordinates along the axis ``axis_id``.  
    11841259             
    11851260            This function always ignores zoom. If you need to account for zooming, use :meth:`map_from_graph`.  
  • orange/OrangeWidgets/plot/owpoint.py

    r8423 r8658  
    33from PyQt4.QtCore import Qt, QPointF 
    44 
    5 from orangeplot import Point 
     5import orangeplot 
    66 
    7 class OWPoint(Point): 
    8     pass 
     7OWPoint = orangeplot.Point 
  • source/orangeplot/plot.sip

    r8651 r8658  
    7676    Point* point_at(const DataPoint& pos); 
    7777     
     78    void add_point(Point* point, PlotItem* parent); 
     79    void add_points(const QList<Point*>& items, PlotItem* parent); 
     80    void remove_point(Point* point, PlotItem* parent); 
     81    void remove_all_points(PlotItem* parent); 
     82 
    7883Q_SIGNALS: 
    7984    void selection_changed(); 
Note: See TracChangeset for help on using the changeset viewer.