Commits

Aleš Erjavec  committed ccb4a5f

More fixes to Widgets Development documentation

  • Participants
  • Parent commits 17b1758

Comments (0)

Files changed (6)

File docs/extend-widgets/rst/api.rst

 
 Following is an example that defines two output channels::
 
-    self.outputs = [("Sampled Data", orange.ExampleTable), ("Learner", orange.Learner)]
+    self.outputs = [("Sampled Data", orange.ExampleTable),
+                    ("Learner", orange.Learner)]
 
 :obj:`self.outputs` should thus be a list of tuples, within
 each the first element is a name of the channel, and the second the
 defintion, hence :obj:`self` for the first attribute)::
 
     def receiveData(self, data):
-    # handle data in some way
+        # handle data in some way
+
 
 Any time our widget would receive a token, :obj:`receiveData`
 would be called. Notice there would be no way of knowing anything
 about deletion. Similar, when channels connecting two widgets are
 deleted, Orange Canvas would automatically send :obj:`None` to
 the receiving widget. Make sure your widget handles :obj:`None`
-tokens appropriately!`
+tokens appropriately!
 
 There are cases when widget would like to know about the origin of
 a token. Say, you would like to input several learners to the
 receiving function should include an extra argument for the ID, like::
 
    def learner(self, learnertoken, tokenid):
-   # handle learnertoken and tokeid in some way
+       # handle learnertoken and tokeid in some way
 
 Widgets such as :obj:`OWTestLearners` and alike use such
 schema.
 would declare input channels like::
 
     self.inputs = [("Data", orange.ExampleTable, self.maindata),
-               ("Additional Data", orange.ExampleTable, self.otherdata)]
+                   ("Additional Data", orange.ExampleTable, self.otherdata)]
 
 and we connect this widget in Orange Canvas to a sending widget
 that has a single orange.ExampleTable output channel, Canvas would
-bring up Set Channels dialog. There, a sending widget's channel could
+bring up *Set Channels* dialog. There, a sending widget's channel could
 be connected to both receiving channels. As we would often prefer to
 connect to a single (default) channel instead (still allowing user of
 Orange Canvas to set up a different schema manually), we set that channel
 definition list, like::
 
     self.inputs = [("Data", orange.ExampleTable, self.maindata, Default),
-               ("Additional Data", orange.ExampleTable, self.otherdata)]
+                   ("Additional Data", orange.ExampleTable, self.otherdata)]

File docs/extend-widgets/rst/basics.rst

 OrangeWidget directory; these subdirectories define widget
 categories. For instance, under windows and default settings, a
 directory that stores all the widgets displayed in the Evaluate pane is
-C:\Python23\Lib\site-packages\orange\OrangeWidgets\Evaluate. Figure
+*C:\\Python23\\Lib\\site-packages\\Orange\\OrangeWidgets\\Evaluate*. Figure
 above shows that at the time of writing of this text there were five
 widgets for evaluation of classifiers, and this is how my Evaluate
 directory looked like:
 tokens. Each widget would define its input and output channels in
 something like::
 
-    self.inputs = [("Test Data Set", ExampleTable, self.cdata), ("Learner", orange.Learner, self.learner, 0)]
+    self.inputs = [("Test Data Set", ExampleTable, self.cdata),
+                   ("Learner", orange.Learner, self.learner, 0)]
     self.outputs = [("Evaluation Results", orngTest.ExperimentResults)]
 
 Above two lines are for Test Learners widget, so hovering with your
 We will go over the syntax of channel definitions later, but for
 now the following is important:
 
-   -  Widgets are defined in a Python files.
-   - For Orange and Orange canvas to find them, they reside in subdirectories in OrangeWidgets directory of Orange installation. The name of the subdirectory matters, as this is the name of the widget category. Widgets in the same directory will be grouped in the same pane of widget toolbox in Orange Canvas.
-   - A file describing a widget starts with a header. This, given in sort of XMLish style, tells about the name, short description, location of an icon and priority of the widget.
-   - The sole role of priority is to specify the placement (order) of widgets in the Orange Canvas toolbox.
-   - Somewhere in the code (where we will learn later) there are two lines which tell which channels the widgets uses for communication. These, together with the header information, completely specify the widget as it is seen from the outside.
+   - Widgets are defined in a Python files.
+   - For Orange and Orange canvas to find them, they reside in subdirectories
+     in OrangeWidgets directory of Orange installation. The name of the
+     subdirectory matters, as this is the name of the widget category. Widgets
+     in the same directory will be grouped in the same pane of widget toolbox
+     in Orange Canvas.
+   - A file describing a widget starts with a header. This, given in sort of
+     XMLish style, tells about the name, short description, location of an
+     icon and priority of the widget.
+   - The sole role of priority is to specify the placement (order) of widgets
+     in the Orange Canvas toolbox.
+   - Somewhere in the code (where we will learn later) there are two lines
+     which tell which channels the widgets uses for communication. These,
+     together with the header information, completely specify the widget as it
+     is seen from the outside.
 
 Oh, by the way. Orange caches widget descriptions to achieve a faster
 startup, but this cache is automatically refreshed at startup if any change

File docs/extend-widgets/rst/channels.rst

 
 Say we want to build a widget that takes a data set and test
 various predictive modelling techniques on it. A widget has to have an
-input data channel, and this we know how to deal with from our :doc:`previous <settings>`
-lesson. But, somehow differently, we
+input data channel, and this we know how to deal with from our
+:doc:`previous <settings>` lesson. But, somehow differently, we
 want to connect any number of widgets which define learners to our
 testing widget. Just like in a schema below, where three different
 learners are used:

File docs/extend-widgets/rst/graphing.rst

     tab.layout().addWidget(self.graph)
     self.setGraphGrid()
 
-:obj:`OWGrap` is a convenience subclass of QwtPlot and is imported from OWGraph module. For the graph, we use :obj:`setAxisAutoScale` to
+:obj:`OWGrap` is a convenience subclass of QwtPlot and is imported from
+OWGraph module. For the graph, we use :obj:`setAxisAutoScale` to
 request that the axis are automatically set in regard to the data that
 is plotted in the graph. We plot the graph in using the following
 code::

File docs/extend-widgets/rst/owgui.rst

 
 `value` (required)
    String with the name of the master's attribute that synchronizes with the
-   state of the control (and vice-versa - when this attribute is changed, the control changes as well). This attribute should usually be also included the master's :obj:`settingsList`, so that it is automatically saved and retrieved.
+   state of the control (and vice-versa - when this attribute is changed, the
+   control changes as well). This attribute should usually be also included
+   the master's :obj:`settingsList`, so that it is automatically saved and
+   retrieved.
 
 `box` (default: None)
-   Indicates if there should be a box that is drawn around the control. If `box` is ``None``, no box is drawn; if it is a string, it is also used as box's name. If `box` is any other true value (such as ``True`` :), an unlabeled box is drawn.
+   Indicates if there should be a box that is drawn around the control.
+   If `box` is ``None``, no box is drawn; if it is a string, it is also used
+   as box's name. If `box` is any other true value (such as ``True`` :),
+   an unlabeled box is drawn.
 
 `callback` (default: None)
    A function to be called when the state of the control is changed. Can
       of :func:`listBox` function.
 
 `tooltip` (default: None)
-   A string that is displayed in a tooltip that appears when mouse is over the control.
+   A string that is displayed in a tooltip that appears when mouse is over the
+   control.
 
 `label` (default: None)
    A string that is displayed as control's label.
    Sets the label's width. This is useful for aligning the controls.
 
 `orientation` (default: "vertical")
-   When label is used, determines the relative placement of the label and the control. Label can be above the control, "vertical", or in the same line with control, "horizontal". Instead of "vertical" and "horizontal" you can also use ``True`` and ``False`` or 1 and 0, respectively. (Remember this as "vertical" being the usual order of controls in the widgets, so vertical is "true".)
+   When label is used, determines the relative placement of the label and the
+   control. Label can be above the control, "vertical", or in the same line
+   with control, "horizontal". Instead of "vertical" and "horizontal" you can
+   also use ``True`` and ``False`` or 1 and 0, respectively. (Remember this
+   as "vertical" being the usual order of controls in the widgets, so vertical
+   is "true".)
 
 `disabled` (default: False)
    Tells whether the control be disabled upon the initialization.
 
 `addSpace` (default: False)
-   If true, a space of 8 pixels is added after the widget by calling :func:`separator`. `addSpace` can also be an integer specifying the height of the added space.
+   If true, a space of 8 pixels is added after the widget by calling
+   :func:`separator`. `addSpace` can also be an integer specifying the height
+   of the added space.
 
 
 ********
 
 This section describes the OWGUI wrappers for controls like check boxes, buttons
 and similar. All the important Qt's controls can be constructed through this
-functions. You should always use them instead of calling Qt directly, not only
-because they are convenient, but also because they set up a lot of things that happen in behind.
+functions.
+
+..
+   You should always use them instead of calling Qt directly, not only
+   because they are convenient, but also because they set up a lot of things
+   that happen in behind.
 
 
 Check Box
 .. function:: checkBox(widget, master, value, label[, box, tooltip, callback, disabled, labelWidth, disables])
 
    `disables` (default: [])
-      If the check box needs to disable some other controls they can be given in list  `disables`, e.g. ``disables=[someOtherCheckBox, someLineEdit]``. If the other control should be disabled when the checkbox is checked, do it like this: ``disables=[someOtherCheckBox, (-1, someLineEdit)]`` - now `someOtherCheckBox` will be enabled when this check box is checked, while `someLineEdit` will be enabled when the check box is unchecked.
+      If the check box needs to disable some other controls they can be given
+      in list  `disables`, e.g. ``disables=[someOtherCheckBox, someLineEdit]``.
+      If the other control should be disabled when the checkbox is checked, do
+      it like this: ``disables=[someOtherCheckBox, (-1, someLineEdit)]`` - now
+      `someOtherCheckBox` will be enabled when this check box is checked,
+      while `someLineEdit` will be enabled when the check box is unchecked.
 
    `labelWidth` (default: None)
       `labelWidth` can be used to align this widget with others.
 .. function:: lineEdit(widget, master, value[, label, labelWidth, orientation, box, tooltip, callback, valueType, validator, controlWidth])
 
    `valueType` (default: str)
-      A type into which the value is cast.
+      A type into which the `value` is cast.
 
    `validator` (default: None)
       A standard Qt validator that can be associated with the control.
 .. function:: comboBox(widget, master, value[, box, label, labelWidth, orientation, items, tooltip, callback, sendSelectedValue, valueType, control2attributeDict, emptyString])
 
    `items` (default: [])
-      A list of combo box's items. Unlike most OWGUI, `items` have one Orange-specific quirk: its element can be either a string, in which case it is used as a label, or a tuple, where the first element is a label name and the last is the attribute type which is used to create an icon. Most attribute lists in Orange Widgets are constructed this way.
+      A list of combo box's items. Unlike most OWGUI, `items` have one
+      Orange-specific quirk: its element can be either a string, in which
+      case it is used as a label, or a tuple, where the first element is a
+      label name and the last is the attribute type which is used to create
+      an icon. Most attribute lists in Orange Widgets are constructed this way.
 
    `sendSelectedValue` (default: 0)
-      If false, attribute `value` will be assigned the index of the selected item. Otherwise, it is assigned the currently selected item's label.
+      If false, attribute `value` will be assigned the index of the selected
+      item. Otherwise, it is assigned the currently selected item's label.
 
    `control2attributeDict` (default: {})
-      A dictionary for translating the item's label into `value`. It is used only is `sendSelectedValue` is true, and even then a label is translated only if an item with such a key is found in the dictionary; otherwise, label is written to `value` as it is. 
+      A dictionary for translating the item's label into `value`. It is used
+      only is `sendSelectedValue` is true, and even then a label is translated
+      only if an item with such a key is found in the dictionary; otherwise,
+      label is written to `value` as it is.
 
    `emptyString` (default: "")
-      Tells which combo box's item corresponds to an empty `value`. This is typically used when combo box's labels are attribute names and an item "(none)", which allows user to select no attribute. If we give ``emptyString="(none)"``, `value` will be an empty string when the user selects "(none)". This is equivalent to specifying ``control2attributeDict={"(none)": ""}`` (and is actually implemented like that), but far more convenient.
+      Tells which combo box's item corresponds to an empty `value`. This is
+      typically used when combo box's labels are attribute names and an item
+      "(none)", which allows user to select no attribute. If we give
+      ``emptyString="(none)"``, `value` will be an empty string when the user
+      selects "(none)". This is equivalent to specifying
+      ``control2attributeDict={"(none)": ""}`` (and is actually implemented
+      like that), but far more convenient.
 
    `valueType` (default: str or unicode)
-      A function through which the currently selected item's label is converted prior to looking into `control2attributeDict`. Needed to convert Qt's QString.
+      A function through which the currently selected item's label is 
+      converted prior to looking into `control2attributeDict`. Needed to
+      convert Qt's QString.
 
 
 List Box
 ********
 
 This control, which might be the most complicated control in OWGUI, is a
-sophisticated wrapper around QListBox. It's complexity arises from synchronization.
+sophisticated wrapper around QListBox. It's complexity arises from
+synchronization.
 
 
 .. function:: listBox(widget, master, value, labels[, box, tooltip, callback, selectionMode])
       The name of master's attribute containing indices of all selected values.
 
    `labels` (required)
-      The name of master's attribute containing the list box's labels. Similar to `items` in combo box, list `labels` have one Orange-specific quirk: its element can be either a string, in which case it is used as a label, or a tuple, where the first element is a label name and the second can be either an icon on an integer, representing the attribute type which is used to create an icon. Most attribute lists in Orange Widgets are constructed this way.
+      The name of master's attribute containing the list box's labels. Similar
+      to `items` in combo box, list `labels` have one Orange-specific quirk:
+      its element can be either a string, in which case it is used as a label
+      or a tuple, where the first element is a label name and the second can
+      be either an icon on an integer, representing the attribute type which
+      is used to create an icon. Most attribute lists in Orange Widgets are
+      constructed this way.
 
    `selectionMode` (default: QListWidget.SingleSelection)
-      Tells whether the user can select a single item (:obj:`QListWidget.SingleSelection`), multiple items (:obj:`QListWidget.MultiSelection`, :obj:`QListWidget.ExtendedSelection`) or nothing (:obj:`QListWidget.NoSelection`).
+      Tells whether the user can select a single item
+      (:obj:`QListWidget.SingleSelection`), multiple items
+      (:obj:`QListWidget.MultiSelection`, :obj:`QListWidget.ExtendedSelection`)
+      or nothing (:obj:`QListWidget.NoSelection`).
 
-   `value` is automatically cast to :obj:`OWGUI.ControlledList` (this is needed because the list should report any changes to the control, the list box; :obj:`OWGUI.ControlledList` is like an ordinary Python :obj:`list` except that it triggers synchronization with the list box at every change).
+   `value` is automatically cast to :obj:`OWGUI.ControlledList` (this is
+   needed because the list should report any changes to the control, the list
+   box; :obj:`OWGUI.ControlledList` is like an ordinary Python :obj:`list`
+   except that it triggers synchronization with the list box at every change).
 
-   `labels` is only partially synchronized with the list box: if a new list is assigning to `labels` attribute, the list will change. If elements of the existing list are changed or added, the list box won't budge. You should never change the list, but always assign a new list (or reassign the same after it's changed). If the labels are stored in ``self.listLabels`` and you write ``self.listLabels[1]="a new label"``, the list box won't change. To trigger the synchronization, you should continue by ``self.listLabels = self.listLabels``. This may seem awkward, but by our experience a list of selected items is seldom changed changed "per-item", so we were too lazy to write the annoyingly complex backward callbacks.
-
+   `labels` is only partially synchronized with the list box: if a new list
+   is assigning to `labels` attribute, the list will change. If elements of
+   the existing list are changed or added, the list box won't budge. You
+   should never change the list, but always assign a new list (or reassign
+   the same after it's changed). If the labels are stored in
+   ``self.listLabels`` and you write ``self.listLabels[1]="a new label"``,
+   the list box won't change. To trigger the synchronization, you should
+   continue by ``self.listLabels = self.listLabels``. This may seem awkward,
+   but by our experience a list of selected items is seldom changed changed
+   "per-item", so we were too lazy to write the annoyingly complex backward
+   callbacks.
 
 
 Spin
 Slider
 ******
 
-A wrapper around QSlider that allows user setting a numerical value between the given bounds.
+A wrapper around QSlider that allows user setting a numerical value between
+the given bounds.
 
 .. function:: hSlider(widget, master, value[, box, minValue, maxValue, step, callback, labelFormat, ticks, divideFactor])
 
       Minimal and maximal value for the spin control, and its step.
 
    `ticks` (default: 0)
-      If non-zero, it gives the interval between two ticks. The ticks will appear below the groove.
+      If non-zero, it gives the interval between two ticks. The ticks will
+      appear below the groove.
 
    `labelFormat` (default: " %d")
-      Defines the look of the label on the righthand side of the slider. It has to contain one format character (like %d in the default), but can contain other text as well.
+      Defines the look of the label on the righthand side of the slider. It
+      has to contain one format character (like %d in the default), but can
+      contain other text as well.
 
    `divideFactor` (default: 1.0)
       The value printed in the label is divided by `divideFactor`.
 Check Box with Spin
 *******************
 
-Check box with spin, or, essentially, a wrapper around
-OWGUI.checkBox and OWGUI.spin.
+Check box with spin, or, essentially, a wrapper around OWGUI.checkBox and
+OWGUI.spin.
 
 .. function:: checkWithSpin(widget, master, label, min, max, checked, value[, posttext, step, tooltip, checkCallback, spinCallback, labelWidth])
 
 Labels
 ******
 
-There are two functions for constructing labels. The first is a simple wrapper around QLabel which differs only in allowing to specify a fixed width without needing an extra line. Note that unlike most other OWGUI widgets, this one does not have the argument `master`.
+There are two functions for constructing labels. The first is a simple wrapper
+around QLabel which differs only in allowing to specify a fixed width without
+needing an extra line. Note that unlike most other OWGUI widgets, this one
+does not have the argument `master`.
 
 .. function:: widgetLabel(widget, label[, labelWidth])
 
-   The second is a label which can synchronize with values of master widget's attributes.
+   The second is a label which can synchronize with values of master widget's
+   attributes.
 
 .. function:: label(widget, master, label[, labelWidth])
 
 Send automatically / Send
 *************************
 
-Many widgets have a "Send" button (perhaps named "Apply", "Commit"...) accompanied with a check box "Send automatically", having the same effect as if the user pressed the button after each change. A well behaved widget cares to:
+Many widgets have a "Send" button (perhaps named "Apply", "Commit"...)
+accompanied with a check box "Send automatically", having the same effect as
+if the user pressed the button after each change. A well behaved widget cares
+to:
 
 * disable the button, when the check box is checked;
-* when the user checks the check box, the data needs to be send (or the changes applied), but only if there is any pending change which has not been (manually) sent yet.
+* when the user checks the check box, the data needs to be send (or the
+  changes applied), but only if there is any pending change which has not been
+  (manually) sent yet.
 
-Programming this into every widget is annoying and error-prone; at the time when the function described here was written, not many widgets actually did this properly.
+Programming this into every widget is annoying and error-prone; at the time
+when the function described here was written, not many widgets actually did
+this properly.
 
 .. function:: setStopper(master, sendButton, stopCheckbox, changedFlag, callback)
 
       The button that will be disabled when the check box is checked.
 
    `stopCheckbox`
-      Check box that decides whether the changes are sent/commited/applied automatically.
+      Check box that decides whether the changes are sent/commited/applied
+      automatically.
 
    `changedFlag`
-      The name of the `master`'s attribute which tells whether there is a change which has not been sent/applied yet.
+      The name of the `master`'s attribute which tells whether there is a
+      change which has not been sent/applied yet.
 
    `callback`
-      The function that sends the data or applies the changes. This is typically the function which is also used as the `sendButton`'s callback.
+      The function that sends the data or applies the changes. This is
+      typically the function which is also used as the `sendButton`'s callback.
 
 
-:obj:`setStopper` is a trivial three lines long function which connects a few signals. Its true importance is in enforcing the correct procedure for implementing such button-check box combinations.
+:obj:`setStopper` is a trivial three lines long function which connects a few
+signals. Its true importance is in enforcing the correct procedure for
+implementing such button-check box combinations.
 
 ..
    Make sure to carefully observe and follow the example provided below.
 
    Missing, where did it go?
-

File docs/extend-widgets/rst/settings.rst

 
 In general, the function should go like this.
 
-* Do any clean-up you need, but without clearing any of the settings that need to be saved. Scatter plot needs none.
-* Call :obj:`self.closeContext`; this ensures that all the context dependent settings (e.g. attribute names from the list boxes) are remembered.
-* Get the data (or whatever you do) and set the controls to some defaults as if there were no context retrieving mechanism. Scatter plot does it by calling :obj:`initAttrValues()` which assigns the first two attributes to the x and y axis and the class attribute to the color. At this phase, you shouldn't call any functions that depend on the settings, such as drawing the graph.
-* Call :obj:`self.openContext` (more about the arguments later). This will search for a suitable context and assign the controls new values if one is found. If there is no saved context that can be used, a new context is created and filled with the default values that were assigned at the previous point.
-* Finally, adjust the widget according to the retrieved controls. Scatter plot now plots the graph by calling :obj:`updateGraph`.
+* Do any clean-up you need, but without clearing any of the settings that need
+  to be saved. Scatter plot needs none.
+* Call :obj:`self.closeContext()`; this ensures that all the context dependent
+  settings (e.g. attribute names from the list boxes) are remembered.
+* Get the data (or whatever you do) and set the controls to some defaults as
+  if there were no context retrieving mechanism. Scatter plot does it by
+  calling :obj:`initAttrValues()` which assigns the first two attributes to
+  the x and y axis and the class attribute to the color. At this phase, you
+  shouldn't call any functions that depend on the settings, such as drawing
+  the graph.
+* Call :obj:`self.openContext` (more about the arguments later). This will
+  search for a suitable context and assign the controls new values if one is
+  found. If there is no saved context that can be used, a new context is
+  created and filled with the default values that were assigned at the previous
+  point.
+* Finally, adjust the widget according to the retrieved controls. Scatter plot
+  now plots the graph by calling :obj:`updateGraph`.
 
 
-:obj:`closeContext` has an argument, the name of the context. If omitted (like above), the default name (:obj:`""`) is used. When opening the context, we give the name and some arguments on which the context depends. In case of :obj:`DomainContextHandler`, which scatter plot uses, we can give it a domain or any object that has a field :obj:`domain` containing a domain. Whether a saved context can be reused is judged upon the presence of attributes in the domain.
+:obj:`closeContext` has an argument, the name of the context. If omitted
+(like above), the default name (:obj:`""`) is used. When opening the context,
+we give the name and some arguments on which the context depends. In case of
+:obj:`DomainContextHandler`, which scatter plot uses, we can give it a domain
+or any object that has a field :obj:`domain` containing a domain. Whether a
+saved context can be reused is judged upon the presence of attributes in the
+domain.
 
-If the widget is constructed appropriately (that is, if it strictly uses OWGUI controls instead of the Qt's), no other administration is needed to switch the context.
+If the widget is constructed appropriately (that is, if it strictly uses OWGUI
+controls instead of the Qt's), no other administration is needed to switch the
+context.
 
-Except for declaring the context settings, that is. Scatter plot has this just below the :obj:`settingsList`::
+Except for declaring the context settings, that is. Scatter plot has this just
+below the :obj:`settingsList`::
 
     contextHandlers = {"": DomainContextHandler("",
       [("attrX", DomainContextHandler.Required),
        ("attrShape", DomainContextHandler.Optional),
        ("attrSize", DomainContextHandler.Optional)])}
 
-:obj:`contextHandlers` is a dictionary whose keys are contexts' names. Each widget can have multiple contexts; for an unrealistic example, consider a scatter plot which gets two data sets and uses one attribute from the first for the x axis, and an attribute from the other for y. Since we won't see this often, the default name for a context is an empty string.
+:obj:`contextHandlers` is a dictionary whose keys are contexts' names. Each
+widget can have multiple contexts; for an unrealistic example, consider a
+scatter plot which gets two data sets and uses one attribute from the first
+for the x axis, and an attribute from the other for y. Since we won't see this
+often, the default name for a context is an empty string.
 
-The values in the dictionary are context handlers. Scatter plot declares that it has a DomainContextHandler with name "" (sorry for the repetition) with attributes "attrX", "attrY", "attrLabel", "attrShape" and "attrSize". The first two are required, while the other three are optional.
+The values in the dictionary are context handlers. Scatter plot declares that
+it has a DomainContextHandler with name "" (sorry for the repetition) with
+attributes "attrX", "attrY", "attrLabel", "attrShape" and "attrSize". The
+first two are required, while the other three are optional.
 
 *********************************
 Using :obj:`DomainContextHandler`
 *********************************
 
-What we said above is not exactly
-true. :obj:`DomainContextHandler.Required` is the default flag,
-so :obj:`("attrX", DomainContextHandler.Required)` can be
-replaced by simply :obj:`"attrX"`. And the latter three have the
+What we said above is not exactly true. :obj:`DomainContextHandler.Required`
+is the default flag, so :obj:`("attrX", DomainContextHandler.Required)` can
+be replaced by simply :obj:`"attrX"`. And the latter three have the
 same flags, so they can be grouped into :obj:`(["attrLabel",
 "attrShape", "attrSize"], DomainContextHandler.Optional)`. So
 what scatter plot really says is ::
        "attrX", "attrY",
        (["attrLabel", "attrShape", "attrSize"], DomainContextHandler.Optional)])}
 
-What do "optional" and "required" mean? Say that you used the
+What do ``Optional`` and ``Required`` mean? Say that you used the
 scatter plot on the data with attributes A, B, C and D; A and B are
 used for the x and y axis and D defined the colors of examples. Now
 you load a new data with attributes A, B, E, and F. The same context
 upon its constructor, so the above applies only to the usual
 :obj:`DomainContextHandler`.
 
-DomainContextHandler's constructor has the following arguments
+:class:`DomainContextHandler`'s constructor has the following arguments
 
-contextName
-The name of the context; it should consist of letters and digits (it is used as a prt of a variable name). In case the widget has multiple contexts, they should have unique names. In most cases there will be only one context, so you can leave it empty.
+`contextName`
+   The name of the context; it should consist of letters and digits (it is
+   used as a part of a variable name). In case the widget has multiple
+   contexts, they should have unique names. In most cases there will be only
+   one context, so you can leave it empty.
 
-fields
-The names of the attributes to be saved and the corresponding flags. They are described in more details below.
+`fields`
+   The names of the attributes to be saved and the corresponding flags. They
+   are described in more details below.
 
-cloneIfImperfect
-states that when the context doesn't match perfectly, that is, unless the domain is exactly the same as the domain from which the context was originally created, :obj:`openContext` shouldn't reuse a context but create a copy of the best matching context instead. Default is :obj:`True`.
+`cloneIfImperfect`
+   States that when the context doesn't match perfectly, that is, unless the
+   domain is exactly the same as the domain from which the context was
+   originally created, :obj:`openContext` shouldn't reuse a context but create
+   a copy of the best matching context instead. Default is :obj:`True`.
 
-loadImperfect
-tells whether the contexts that do not match perfectly (see above) should be used or not. Default is :obj:`True`.
+`loadImperfect`
+   tells whether the contexts that do not match perfectly (see above) should
+   be used or not. Default is :obj:`True`.
 
-findImperfect
-tells whether imperfect contexts match at all or not (this flag is somewhat confused with :obj:`loadImperfect`, but it may come useful some day. Default is :obj:`True` again.
+`findImperfect`
+   Tells whether imperfect contexts match at all or not (this flag is
+   somewhat confused with :obj:`loadImperfect`, but it may come useful some
+   day). Default is :obj:`True` again.
 
-syncWithGlobal
-tells whether instances of this widget should have a shared list of contexts (default). The alternative is that each keeps its own list; each individual list is merged with the global when the widget is deleted from the canvas (or when the canvas is closed). This setting only applies to canvas, while in saved applications widgets always have separate settings lists.
+`syncWithGlobal`
+   Tells whether instances of this widget should have a shared list of
+   contexts (default). The alternative is that each keeps its own list;
+   each individual list is merged with the global when the widget is deleted
+   from the canvas (or when the canvas is closed). This setting only applies
+   to canvas, while in saved applications widgets always have separate settings
+   lists.
 
-maxAttributesToPickle
-To keep the size of the context file small, settings for domains exceeding a certain number of attributes are not pickled. Default is 100, but you can increase (or decrease this) if you need to.
+`maxAttributesToPickle`
+   To keep the size of the context file small, settings for domains exceeding
+   a certain number of attributes are not pickled. Default is 100, but you can
+   increase (or decrease this) if you need to.
 
 
 The truly interesting argument is :obj:`fields`. It roughly corresponds to the
 latter). When given as tuples, they should consist of two elements, the field
 name (just like in :obj:`settingsList`) and a flag. Here are the possible flags:
 
-* :obj:`DomainContextHandler.Optional`, :obj:`DomainContextHandler.SelectedRequired` and :obj:`DomainContextHandler.Required` state whether the attribute is optional or required, as explained above. Default is :obj:`Required`. :obj:`DomainContextHandler.SelectedRequired` is applicable only if the control is a list box, where it means that the attributes that are selected are required while the other attributes from the list are not.
-* :obj:`DomainContextHandler.NotAttribute` the setting is not an attribute name. You can essentially make a check box context dependent, but we very strongly dissuade from this since it can really confuse the user if some check boxes change with the data while most do not.
-* :obj:`DomainContextHandler.List` tells that the attribute corresponds to a list box.
+* :obj:`DomainContextHandler.Optional`,
+  :obj:`DomainContextHandler.SelectedRequired` and
+  :obj:`DomainContextHandler.Required` state whether the attribute is optional
+  or required, as explained above. Default is :obj:`Required`.
+  :obj:`DomainContextHandler.SelectedRequired` is applicable only if the
+  control is a list box, where it means that the attributes that are selected
+  are required while the other attributes from the list are not.
+
+* :obj:`DomainContextHandler.NotAttribute` the setting is not an attribute
+  name. You can essentially make a check box context dependent, but we very
+  strongly dissuade from this since it can really confuse the user if some
+  check boxes change with the data while most do not.
+
+* :obj:`DomainContextHandler.List` tells that the attribute corresponds to a
+  list box.
 
 
 Flags can be combined, so to specify a list in which all attributes
 
 But the tuples are actually a shortcut for instances of
 :obj:`ContextField`. When you say :obj:`"attrX"` this is actually
-:obj:`ContextField("attrX", DomainContextHandler.Required)` (you should
-appreciate the shortcurt, right?). But see this monster from widget "Select
-Attributes" (file OWDataDomain.py)::
+:obj:`ContextField("attrX", DomainContextHandler.Required)`
 
-    contextHandlers = {"": DomainContextHandler("",
-        [ContextField("chosenAttributes",
-                       DomainContextHandler.RequiredList,
-                       selected="selectedChosen", reservoir="inputAttributes"),
-         ContextField("classAttribute",
-                       DomainContextHandler.RequiredList,
-                       selected="selectedClass", reservoir="inputAttributes"),
-         ContextField("metaAttributes",
-                       DomainContextHandler.RequiredList,
-                       selected="selectedMeta", reservoir="inputAttributes")
-    ])}
+..
+   But see this monster from widget "Select Attributes" (file OWDataDomain.py)::
 
+       contextHandlers = {"": DomainContextHandler("",
+           [ContextField("chosenAttributes",
+                          DomainContextHandler.RequiredList,
+                          selected="selectedChosen", reservoir="inputAttributes"),
+            ContextField("classAttribute",
+                          DomainContextHandler.RequiredList,
+                          selected="selectedClass", reservoir="inputAttributes"),
+            ContextField("metaAttributes",
+                          DomainContextHandler.RequiredList,
+                          selected="selectedMeta", reservoir="inputAttributes")
+       ])}
 
-:obj:`ContextField`'s constructor gets the name and flags and a list of
-arguments that are written directly into the object instance. To follow the
-example, recall what Select Attributes looks like: it allows you to select a
-subset of attributes, the class attribute and the meta attributes that you
-want to use; the attributes in the corresponding three list boxes are stored
-in the widget's variables :obj:`chosenAttributes`, :obj:`classAttribute`
-and :obj:`metaAttributes` respectively. When the user selects some attributes
-in any of these boxes, the selection is stored in :obj:`selectedChosen`,
-:obj:`selectedClass` and :obj:`selectedMeta`. The remaining attributes
-- those that are not in any of these three list boxes - are in the leftover
-listbox on the left-hand side of the widget, and the content of the box is
-stored in the widget's variable :obj:`inputAttributes`.
 
-The above definition tells that the context needs to store the contents of
-the three list boxes by specifying the corresponding variables; the list of
-attributes is given as the name of the field and the list of selected
-attributes is in the optional named attribute :obj:`selected`. By
-:obj:`reservoir` we told the context handler that the attributes are taken
-from :obj:`inputAttributes`. So, when a context is retrieved, all the
-attributes that are not in any of the three list boxes are put into
-:obj:`inputAttributes`.
+   :obj:`ContextField`'s constructor gets the name and flags and a list of
+   arguments that are written directly into the object instance. To follow the
+   example, recall what Select Attributes looks like: it allows you to select a
+   subset of attributes, the class attribute and the meta attributes that you
+   want to use; the attributes in the corresponding three list boxes are stored
+   in the widget's variables :obj:`chosenAttributes`, :obj:`classAttribute`
+   and :obj:`metaAttributes` respectively. When the user selects some attributes
+   in any of these boxes, the selection is stored in :obj:`selectedChosen`,
+   :obj:`selectedClass` and :obj:`selectedMeta`. The remaining attributes
+   - those that are not in any of these three list boxes - are in the leftover
+   listbox on the left-hand side of the widget, and the content of the box is
+   stored in the widget's variable :obj:`inputAttributes`.
 
-Why the mess? Couldn't we just store :obj:`inputAttributes` as the fourth
-list box? Imagine that the user first loads the data with attributes A, B,
-C, D, E and F, puts A, B, C in chosen and D in class. E and F are left in
-:obj:`inputAttributes`. Now she loads another data which has attributes A,
-B, C, D, E, and G. The contexts should match (the new data has all the
-attributes we need), but :obj:`inputAttributes` should now contain E and
-G, not E and F, since F doesn't exist any more, while G needs to be made
-available.
+   The above definition tells that the context needs to store the contents of
+   the three list boxes by specifying the corresponding variables; the list of
+   attributes is given as the name of the field and the list of selected
+   attributes is in the optional named attribute :obj:`selected`. By
+   :obj:`reservoir` we told the context handler that the attributes are taken
+   from :obj:`inputAttributes`. So, when a context is retrieved, all the
+   attributes that are not in any of the three list boxes are put into
+   :obj:`inputAttributes`.
 
-You can use :obj:`ContextField` (instead of tuples and strings) for
-declaring any fields, but you will usually need them only for lists or,
-maybe, some complicated future controls.
+   Why the mess? Couldn't we just store :obj:`inputAttributes` as the fourth
+   list box? Imagine that the user first loads the data with attributes A, B,
+   C, D, E and F, puts A, B, C in chosen and D in class. E and F are left in
+   :obj:`inputAttributes`. Now she loads another data which has attributes A,
+   B, C, D, E, and G. The contexts should match (the new data has all the
+   attributes we need), but :obj:`inputAttributes` should now contain E and
+   G, not E and F, since F doesn't exist any more, while G needs to be made
+   available.
+
+   You can use :obj:`ContextField` (instead of tuples and strings) for
+   declaring any fields, but you will usually need them only for lists or,
+   maybe, some complicated future controls.
 
 
 *****************************
 Defining New Context Handlers
 *****************************
 
-Avoid it if you can. If you can't, here's the list of the methods you may need to implement. You may want to copy as much from the :obj:`DomainContextHandler` as you can.
+Avoid it if you can. If you can't, here's the list of the methods you may need
+to implement. You may want to copy as much from the :obj:`DomainContextHandler`
+as you can.
 
 
-__init__
-Has the same arguments as the :obj:`DomainContextHandler`'s, except for the :obj:`fields`.
+:obj:`__init__`
+   Has the same arguments as the :obj:`DomainContextHandler`'s, except for the
+   :obj:`fields`.
 
-newContext
-Creates and returns a new context. In :obj:`ContextHandler` is returns an instance of :obj:`Context`; you probably won't need to change this.
+:obj:`newContext()`
+   Creates and returns a new context. In :obj:`ContextHandler` it returns an
+   instance of :obj:`Context`; you probably won't need to change this.
 
-openContext
-The method is given a widget and some additional arguments based on which the contexts are compared. In case of :obj:`DomainContextHandler` this is a domain. There can be one or more such arguments. Note that the method :obj:`openContext` which we talked about above is a method of :obj:`OWBaseWidget`, while here we describe a method of context handlers. Actually, :obj:`OWBaseWidget(self, contextName, *args)` calls the context handler's, passing it's :obj:`self` and :obj:`*args`.
+:obj:`openContext(widget, *args)`
+   The method is given a widget and some additional arguments based on which
+   the contexts are compared. In case of :obj:`DomainContextHandler` this is
+   a domain. There can be one or more such arguments. Note that the method
+   :obj:`openContext` which we talked about above is a method of
+   :obj:`OWBaseWidget`, while here we describe a method of context handlers.
+   Actually, :obj:`OWBaseWidget.openContext(self,contextName, *args)` calls
+   the context handler's, passing it's :obj:`self` and :obj:`*args`.
 
-It needs to find a matching context and copy its settings to the widget or construct a new context and copy the settings from the widget. Also, when an old context is reused, it should be moved to the beginning of the list. :obj:`ContextHandler` already defines this method, which should usually suffice. :obj:`DomainContextHandler` adds very little to it.
+   It needs to find a matching context and copy its settings to the widget or
+   construct a new context and copy the settings from the widget. Also, when an
+   old context is reused, it should be moved to the beginning of the list.
+   :obj:`ContextHandler` already defines this method, which should usually
+   suffice. :obj:`DomainContextHandler` adds very little to it.
 
-closeContext
-Copies the settings from the widget by calling :obj:`settingsFromWidget`. You probably won't need to overwrite it.
+:obj:`closeContext`
+   Copies the settings from the widget by calling :obj:`settingsFromWidget`.
+   You probably won't need to overwrite it.
 
-match
-The method is called by :obj:`openContext` to find a matching context. Given an existing context and the arguments that were given to :obj:`openContext` (for instance, a domain), it should decide whether the context matches or not. If it returns 2, it is a perfect match (e.g. domains are the same). If it returns 0, the context is not applicable (e.g. some of the required attributes are missing). In case it returns a number between 0 and 1 (excluding 0), the higher the number the better the match. :obj:`openContext` will use the best matching context (or the perfect one, if found).
+:obj:`match`
+   The method is called by :obj:`openContext` to find a matching context.
+   Given an existing context and the arguments that were given to
+   :obj:`openContext` (for instance, a domain), it should decide whether the
+   context matches or not. If it returns 2, it is a perfect match (e.g.
+   domains are the same). If it returns 0, the context is not applicable
+   (e.g. some of the required attributes are missing). In case it returns a
+   number between 0 and 1 (excluding 0), the higher the number the better the
+   match. :obj:`openContext` will use the best matching context (or the
+   perfect one, if found).
 
-settingsToWidget/settingsFromWidget
-Copy the settings to and from the widget.
+:obj:`settingsToWidget` / :obj:`settingsFromWidget`
+   Copy the settings to and from the widget.
 
-fastSave
-This function is called by the widget's :obj:`__setattr__` each time any widget's variable is changed to immediately synchronize the context with the state of the widget. The method is really needed only when :obj:`syncWithGlobal` is set. When the context is closed, :obj:`closeContext` will save the settings anyway.
+:obj:`fastSave`
+   This function is called by the widget's :obj:`__setattr__` each time any
+   widget's variable is changed to immediately synchronize the context with
+   the state of the widget. The method is really needed only when
+   :obj:`syncWithGlobal` is set. When the context is closed,
+   :obj:`closeContext` will save the settings anyway.
 
-cloneContext
-Given an existing context, it prepares and returns a copy. The method is optional; :obj:`copy.deepcopy` can be used instead.
+:obj:`cloneContext`
+   Given an existing context, it prepares and returns a copy. The method is
+   optional; :obj:`copy.deepcopy` can be used instead.
 
 
 ***************************
 ***************************
 
 Settings can be saved in two different places. Orange Canvas save
-settings in .ini files in directory
-Orange/OrangeWidgets/widgetSettings. Each widget type has its separate
-file; for instance, the scatter plot's settings are saved in
+settings in .ini files in its application data directory. Each widget type has
+a separate file; for instance, the scatter plot's settings are saved in
 :obj:`ScatterPlot.ini`. Saved schemas and applications save
 settings in .sav files; the .sav file is placed in the same directory
 as the schema or application, has the same name (except for the
 
 Saving and loading is done automatically by canvas or the
 application. In a very rare case you need it to run these operations
-manually, the functions involved are :obj:`loadSettings(self, file =
-None)`, :obj:`saveSettings(self, file = None)`,
-:obj:`loadSettingsStr(self, str)`,
+manually, the functions involved are :obj:`loadSettings(self, file=None)`,
+:obj:`saveSettings(self, file=None)`, :obj:`loadSettingsStr(self, str)`,
 :obj:`saveSettingsStr(self)`. The first two load and save from
 the file; if not given, the default name (widget's name +
 :obj:`.ini`) is used. They are called by the canvas, never by a