source: orange/docs/extend-widgets/rst/owgui.rst @ 11424:ccb4a5fac5e1

Revision 11424:ccb4a5fac5e1, 16.1 KB checked in by Ales Erjavec <ales.erjavec@…>, 13 months ago (diff)

More fixes to Widgets Development documentation

RevLine 
[11049]1#####################################
2OWGUI: Library of Common GUI Controls
3#####################################
4
5Orange Widgets wrap Orange's classes in an easy to use interactive graphical
6interface. As such, much of their code is about the interface, event control
7and maintaining the state of the GUI controls.
8
9In the spirit of constructive laziness, we wrote a library using which a single
10line of code can construct a check box, line edit or a combo, make it being
11synchronized with a Python object's attribute (which, by the way, gets
12automatically saved and retrieved when the widgets is closed and reopened),
[11408]13attaches a callback function to the control, make it disable or enable other
14controls...
[11049]15
16*****************
17Common Attributes
18*****************
19
20Many functions that construct controls share one or more common arguments,
21usually in the same order. These are described here. Descriptions of individual
22controls will only list their specific arguments, while the arguments which are
23presented here will only be described in cases where they have a different meaning.
24
[11408]25`widget` (required)
26   Widget on which control will be drawn - can be widget's :obj:`controlArea`
27   or another box.
[11049]28
[11408]29`master` (required)
30   Object which includes an attribute that are used to store control's
31   state, most often the object which called the function that
32   initialized the control.
[11049]33
[11408]34`value` (required)
35   String with the name of the master's attribute that synchronizes with the
[11424]36   state of the control (and vice-versa - when this attribute is changed, the
37   control changes as well). This attribute should usually be also included
38   the master's :obj:`settingsList`, so that it is automatically saved and
39   retrieved.
[11049]40
[11408]41`box` (default: None)
[11424]42   Indicates if there should be a box that is drawn around the control.
43   If `box` is ``None``, no box is drawn; if it is a string, it is also used
44   as box's name. If `box` is any other true value (such as ``True`` :),
45   an unlabeled box is drawn.
[11049]46
[11408]47`callback` (default: None)
48   A function to be called when the state of the control is changed. Can
49   include a single function, or a list of functions that will be called in
50   the order provided. If callback function changes the value of the controlled
51   attribute (the one given as the `value` argument described above) it may
52   trigger a cycle
[11049]53
[11408]54   ..
55      ; a simple trick to avoid this is shown in the description
56      of :func:`listBox` function.
[11049]57
[11408]58`tooltip` (default: None)
[11424]59   A string that is displayed in a tooltip that appears when mouse is over the
60   control.
[11049]61
[11408]62`label` (default: None)
63   A string that is displayed as control's label.
[11049]64
[11408]65`labelWidth` (default: None)
66   Sets the label's width. This is useful for aligning the controls.
[11049]67
[11408]68`orientation` (default: "vertical")
[11424]69   When label is used, determines the relative placement of the label and the
70   control. Label can be above the control, "vertical", or in the same line
71   with control, "horizontal". Instead of "vertical" and "horizontal" you can
72   also use ``True`` and ``False`` or 1 and 0, respectively. (Remember this
73   as "vertical" being the usual order of controls in the widgets, so vertical
74   is "true".)
[11049]75
[11408]76`disabled` (default: False)
77   Tells whether the control be disabled upon the initialization.
78
79`addSpace` (default: False)
[11424]80   If true, a space of 8 pixels is added after the widget by calling
81   :func:`separator`. `addSpace` can also be an integer specifying the height
82   of the added space.
[11049]83
84
85********
86Controls
87********
88
89This section describes the OWGUI wrappers for controls like check boxes, buttons
90and similar. All the important Qt's controls can be constructed through this
[11424]91functions.
92
93..
94   You should always use them instead of calling Qt directly, not only
95   because they are convenient, but also because they set up a lot of things
96   that happen in behind.
[11049]97
98
99Check Box
100*********
101
102Check box, a wrapper around QCheckBox, adding a label, box, tooltip, callback
103and synchronization with the designated widget's attribute.
104
[11408]105.. function:: checkBox(widget, master, value, label[, box, tooltip, callback, disabled, labelWidth, disables])
[11049]106
[11408]107   `disables` (default: [])
[11424]108      If the check box needs to disable some other controls they can be given
109      in list  `disables`, e.g. ``disables=[someOtherCheckBox, someLineEdit]``.
110      If the other control should be disabled when the checkbox is checked, do
111      it like this: ``disables=[someOtherCheckBox, (-1, someLineEdit)]`` - now
112      `someOtherCheckBox` will be enabled when this check box is checked,
113      while `someLineEdit` will be enabled when the check box is unchecked.
[11049]114
[11408]115   `labelWidth` (default: None)
116      `labelWidth` can be used to align this widget with others.
[11049]117
118
119Line Edit
120*********
121
122Edit box, a wrapper around QLineEdit.
123
[11408]124.. function:: lineEdit(widget, master, value[, label, labelWidth, orientation, box, tooltip, callback, valueType, validator, controlWidth])
[11049]125
[11408]126   `valueType` (default: str)
[11424]127      A type into which the `value` is cast.
[11049]128
[11408]129   `validator` (default: None)
130      A standard Qt validator that can be associated with the control.
[11049]131
132
133Button
134******
135
136A wrapper around QPushButton, just to be able to define a button
137and its callback in a single line.
138
[11408]139.. function:: button(widget, master, label[, callback, disabled, tooltip])
[11049]140
141
142Radio Buttons
143*************
144
[11408]145OWGUI can create an individual radio button or a box of radio buttons or an
146individual radio button.
[11049]147
148An individual radio button is created by :obj:`radioButton`.
149
[11408]150.. function:: radioButton(widget, master, value, label[, box, tooltip, callback, addSpace])
[11049]151
[11408]152   The function provides the usual capabilities of OWGUI controls. It is though
153   your responsibility to put it in something like a :obj:`QVButtonGroup`.
[11049]154
155A box of radio buttons is created by function :obj:`radioButtonsInBox`.
156
[11408]157.. function:: radioButtonsInBox(widget, master, value, btnLabels[, box, tooltips, callback)
[11049]158
[11408]159   `value` (required)
160      Synchronized with the index of the selected radio button.
[11049]161
[11408]162   `btnLabels` (required)
163      A list with labels for radio buttons. Labels can be strings or pixmaps.
[11049]164
[11408]165   `tooltips` (default: None)
166      A list of tooltips, one for each button.
[11049]167
168
169Combo Box
170*********
171
172A wrapper around QComboBox.
173
[11408]174.. function:: comboBox(widget, master, value[, box, label, labelWidth, orientation, items, tooltip, callback, sendSelectedValue, valueType, control2attributeDict, emptyString])
[11049]175
[11408]176   `items` (default: [])
[11424]177      A list of combo box's items. Unlike most OWGUI, `items` have one
178      Orange-specific quirk: its element can be either a string, in which
179      case it is used as a label, or a tuple, where the first element is a
180      label name and the last is the attribute type which is used to create
181      an icon. Most attribute lists in Orange Widgets are constructed this way.
[11049]182
[11408]183   `sendSelectedValue` (default: 0)
[11424]184      If false, attribute `value` will be assigned the index of the selected
185      item. Otherwise, it is assigned the currently selected item's label.
[11049]186
[11408]187   `control2attributeDict` (default: {})
[11424]188      A dictionary for translating the item's label into `value`. It is used
189      only is `sendSelectedValue` is true, and even then a label is translated
190      only if an item with such a key is found in the dictionary; otherwise,
191      label is written to `value` as it is.
[11049]192
[11408]193   `emptyString` (default: "")
[11424]194      Tells which combo box's item corresponds to an empty `value`. This is
195      typically used when combo box's labels are attribute names and an item
196      "(none)", which allows user to select no attribute. If we give
197      ``emptyString="(none)"``, `value` will be an empty string when the user
198      selects "(none)". This is equivalent to specifying
199      ``control2attributeDict={"(none)": ""}`` (and is actually implemented
200      like that), but far more convenient.
[11049]201
[11408]202   `valueType` (default: str or unicode)
[11424]203      A function through which the currently selected item's label is
204      converted prior to looking into `control2attributeDict`. Needed to
205      convert Qt's QString.
[11049]206
207
208List Box
209********
210
211This control, which might be the most complicated control in OWGUI, is a
[11424]212sophisticated wrapper around QListBox. It's complexity arises from
213synchronization.
[11049]214
215
[11408]216.. function:: listBox(widget, master, value, labels[, box, tooltip, callback, selectionMode])
[11049]217
[11408]218   `value` (required)
219      The name of master's attribute containing indices of all selected values.
[11049]220
[11408]221   `labels` (required)
[11424]222      The name of master's attribute containing the list box's labels. Similar
223      to `items` in combo box, list `labels` have one Orange-specific quirk:
224      its element can be either a string, in which case it is used as a label
225      or a tuple, where the first element is a label name and the second can
226      be either an icon on an integer, representing the attribute type which
227      is used to create an icon. Most attribute lists in Orange Widgets are
228      constructed this way.
[11049]229
[11408]230   `selectionMode` (default: QListWidget.SingleSelection)
[11424]231      Tells whether the user can select a single item
232      (:obj:`QListWidget.SingleSelection`), multiple items
233      (:obj:`QListWidget.MultiSelection`, :obj:`QListWidget.ExtendedSelection`)
234      or nothing (:obj:`QListWidget.NoSelection`).
[11049]235
[11424]236   `value` is automatically cast to :obj:`OWGUI.ControlledList` (this is
237   needed because the list should report any changes to the control, the list
238   box; :obj:`OWGUI.ControlledList` is like an ordinary Python :obj:`list`
239   except that it triggers synchronization with the list box at every change).
[11049]240
[11424]241   `labels` is only partially synchronized with the list box: if a new list
242   is assigning to `labels` attribute, the list will change. If elements of
243   the existing list are changed or added, the list box won't budge. You
244   should never change the list, but always assign a new list (or reassign
245   the same after it's changed). If the labels are stored in
246   ``self.listLabels`` and you write ``self.listLabels[1]="a new label"``,
247   the list box won't change. To trigger the synchronization, you should
248   continue by ``self.listLabels = self.listLabels``. This may seem awkward,
249   but by our experience a list of selected items is seldom changed changed
250   "per-item", so we were too lazy to write the annoyingly complex backward
251   callbacks.
[11049]252
253
254Spin
255****
256
257Spin control, a wrapper around QSpinBox.
258
[11408]259.. function:: spin(widget, master, value, min, max[, step, box, label, labelWidth, orientation, tooltip, callback, controlWidth])
[11049]260
[11408]261   `min`, `max`, `step=1`
262      Minimal and maximal value, and step.
[11049]263
264
265Slider
266******
267
[11424]268A wrapper around QSlider that allows user setting a numerical value between
269the given bounds.
[11049]270
[11408]271.. function:: hSlider(widget, master, value[, box, minValue, maxValue, step, callback, labelFormat, ticks, divideFactor])
[11049]272
273
[11408]274   `minValue` (default: 0), `maxValue` (default: 10), `step` (default: 1)
275      Minimal and maximal value for the spin control, and its step.
[11049]276
[11408]277   `ticks` (default: 0)
[11424]278      If non-zero, it gives the interval between two ticks. The ticks will
279      appear below the groove.
[11049]280
[11408]281   `labelFormat` (default: " %d")
[11424]282      Defines the look of the label on the righthand side of the slider. It
283      has to contain one format character (like %d in the default), but can
284      contain other text as well.
[11049]285
[11408]286   `divideFactor` (default: 1.0)
287      The value printed in the label is divided by `divideFactor`.
[11049]288
289
290Check Box with Spin
291*******************
292
[11424]293Check box with spin, or, essentially, a wrapper around OWGUI.checkBox and
294OWGUI.spin.
[11049]295
[11408]296.. function:: checkWithSpin(widget, master, label, min, max, checked, value[, posttext, step, tooltip, checkCallback, spinCallback, labelWidth])
[11049]297
[11408]298   `min`, `max`, `step` (required)
299      Minimal and maximal value for the spin control, and its step.
[11049]300
[11408]301   `checked` (required)
302      Master's attribute that is synchronized with the state of the check box.
[11049]303
[11408]304   `value` (required)
305      The attribute that is synchronized with the spin.
[11049]306
[11408]307   `posttext` (default: None)
308      Text which appears on the right-hand side of the control.
[11049]309
[11408]310   `checkCallback` (default: None), `spinCallback` (default: None)
311      Function that are called when the state of the check box or spin changes.
[11049]312
313
314Labels
315******
316
[11424]317There are two functions for constructing labels. The first is a simple wrapper
318around QLabel which differs only in allowing to specify a fixed width without
319needing an extra line. Note that unlike most other OWGUI widgets, this one
320does not have the argument `master`.
[11049]321
[11408]322.. function:: widgetLabel(widget, label[, labelWidth])
[11049]323
[11424]324   The second is a label which can synchronize with values of master widget's
325   attributes.
[11049]326
[11408]327.. function:: label(widget, master, label[, labelWidth])
[11049]328
[11408]329   `label`
330      `label` is a format string following Python's syntax (see the
331      corresponding Python documentation): the label's content is rendered as
332      ``label % master.__dict__``.
[11049]333
334
335*********
336Utilities
337*********
338
339Widget box
340**********
341
342
[11408]343.. function:: widgetBox(widget, box=None, orientation='vertical', addSpace=False)
344
345   Creates a box in which other widgets can be put. If `box` is given
346   and not false, the box will be framed. If `box` is a string, it will
347   be used for the box name (don't capitalize each word; spaces in front or
348   after the string will be trimmed and replaced with a single space).
349   Argument `orientation` can be ``"vertical"`` or ``"horizontal"``
350   (or ``True`` and ``False``, or ``1`` and ``0``, respectively).
[11049]351
352
353Idented box
354***********
355
356
[11408]357.. function:: indentedBox(widget, sep=20)
358
359      Creates an indented box. Widgets which are subsequently put into
360      that box will be arranged vertically and aligned with an indentation
361      of `sep`.
[11049]362
363
364Inserting Space between Widgets
365*******************************
366
367Most widgets look better if we insert some vertical space between the controls
[11408]368or groups of controls. A few functions have an optional argument `addSpace`
[11049]369by which we can request such space to be added. For other occasions, we can use
370the following two functions.
371
[11408]372.. function:: separator(widget, width=0, height=8)
[11049]373
[11408]374   Function `separator` inserts a fixed amount of space into `widget`.
375   Although the caller can specify the amount, leaving the default will help the
376   widgets having uniform look.
[11049]377
[11408]378.. function:: rubber(widget[, orientation="vertical"])
[11049]379
[11408]380   Similar to separator, except that the size is (1, 1) and that it expands in the
381   specified direction if the widget is expanded. Most widgets should have rubber
382   somewhere in their :obj:`controlArea`.
[11049]383
384Attribute Icons
385***************
386
[11408]387.. function:: getAttributeIcons()
[11049]388
[11408]389   Returns a dictionary with attribute types (:obj:`orange.VarTypes.Discrete`,
390   :obj:`orange.VarTypes.Continuous`, :obj:`orange.VarTypes.String`, -1) as keys
391   and colored pixmaps as values. The dictionary can be used in list and combo
392   boxes showing attributes for easier distinguishing between attributes of different types.
[11049]393
394Send automatically / Send
395*************************
396
[11424]397Many widgets have a "Send" button (perhaps named "Apply", "Commit"...)
398accompanied with a check box "Send automatically", having the same effect as
399if the user pressed the button after each change. A well behaved widget cares
400to:
[11049]401
402* disable the button, when the check box is checked;
[11424]403* when the user checks the check box, the data needs to be send (or the
404  changes applied), but only if there is any pending change which has not been
405  (manually) sent yet.
[11049]406
[11424]407Programming this into every widget is annoying and error-prone; at the time
408when the function described here was written, not many widgets actually did
409this properly.
[11049]410
[11408]411.. function:: setStopper(master, sendButton, stopCheckbox, changedFlag, callback)
[11049]412
[11408]413   `sendButton`
414      The button that will be disabled when the check box is checked.
[11049]415
[11408]416   `stopCheckbox`
[11424]417      Check box that decides whether the changes are sent/commited/applied
418      automatically.
[11049]419
[11408]420   `changedFlag`
[11424]421      The name of the `master`'s attribute which tells whether there is a
422      change which has not been sent/applied yet.
[11049]423
[11408]424   `callback`
[11424]425      The function that sends the data or applies the changes. This is
426      typically the function which is also used as the `sendButton`'s callback.
[11049]427
428
[11424]429:obj:`setStopper` is a trivial three lines long function which connects a few
430signals. Its true importance is in enforcing the correct procedure for
431implementing such button-check box combinations.
[11049]432
[11408]433..
434   Make sure to carefully observe and follow the example provided below.
435
436   Missing, where did it go?
Note: See TracBrowser for help on using the repository browser.