source: orange/docs/extend-widgets/rst/owgui.rst @ 11408:c2d2400b6a90

Revision 11408:c2d2400b6a90, 15.8 KB checked in by Ales Erjavec <ales.erjavec@…>, 13 months ago (diff)

Fixes for Widgets Development documentation.

Line 
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),
13attaches a callback function to the control, make it disable or enable other
14controls...
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
25`widget` (required)
26   Widget on which control will be drawn - can be widget's :obj:`controlArea`
27   or another box.
28
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.
33
34`value` (required)
35   String with the name of the master's attribute that synchronizes with the
36   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.
37
38`box` (default: None)
39   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.
40
41`callback` (default: None)
42   A function to be called when the state of the control is changed. Can
43   include a single function, or a list of functions that will be called in
44   the order provided. If callback function changes the value of the controlled
45   attribute (the one given as the `value` argument described above) it may
46   trigger a cycle
47
48   ..
49      ; a simple trick to avoid this is shown in the description
50      of :func:`listBox` function.
51
52`tooltip` (default: None)
53   A string that is displayed in a tooltip that appears when mouse is over the control.
54
55`label` (default: None)
56   A string that is displayed as control's label.
57
58`labelWidth` (default: None)
59   Sets the label's width. This is useful for aligning the controls.
60
61`orientation` (default: "vertical")
62   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".)
63
64`disabled` (default: False)
65   Tells whether the control be disabled upon the initialization.
66
67`addSpace` (default: False)
68   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.
69
70
71********
72Controls
73********
74
75This section describes the OWGUI wrappers for controls like check boxes, buttons
76and similar. All the important Qt's controls can be constructed through this
77functions. You should always use them instead of calling Qt directly, not only
78because they are convenient, but also because they set up a lot of things that happen in behind.
79
80
81Check Box
82*********
83
84Check box, a wrapper around QCheckBox, adding a label, box, tooltip, callback
85and synchronization with the designated widget's attribute.
86
87.. function:: checkBox(widget, master, value, label[, box, tooltip, callback, disabled, labelWidth, disables])
88
89   `disables` (default: [])
90      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.
91
92   `labelWidth` (default: None)
93      `labelWidth` can be used to align this widget with others.
94
95
96Line Edit
97*********
98
99Edit box, a wrapper around QLineEdit.
100
101.. function:: lineEdit(widget, master, value[, label, labelWidth, orientation, box, tooltip, callback, valueType, validator, controlWidth])
102
103   `valueType` (default: str)
104      A type into which the value is cast.
105
106   `validator` (default: None)
107      A standard Qt validator that can be associated with the control.
108
109
110Button
111******
112
113A wrapper around QPushButton, just to be able to define a button
114and its callback in a single line.
115
116.. function:: button(widget, master, label[, callback, disabled, tooltip])
117
118
119Radio Buttons
120*************
121
122OWGUI can create an individual radio button or a box of radio buttons or an
123individual radio button.
124
125An individual radio button is created by :obj:`radioButton`.
126
127.. function:: radioButton(widget, master, value, label[, box, tooltip, callback, addSpace])
128
129   The function provides the usual capabilities of OWGUI controls. It is though
130   your responsibility to put it in something like a :obj:`QVButtonGroup`.
131
132A box of radio buttons is created by function :obj:`radioButtonsInBox`.
133
134.. function:: radioButtonsInBox(widget, master, value, btnLabels[, box, tooltips, callback)
135
136   `value` (required)
137      Synchronized with the index of the selected radio button.
138
139   `btnLabels` (required)
140      A list with labels for radio buttons. Labels can be strings or pixmaps.
141
142   `tooltips` (default: None)
143      A list of tooltips, one for each button.
144
145
146Combo Box
147*********
148
149A wrapper around QComboBox.
150
151.. function:: comboBox(widget, master, value[, box, label, labelWidth, orientation, items, tooltip, callback, sendSelectedValue, valueType, control2attributeDict, emptyString])
152
153   `items` (default: [])
154      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.
155
156   `sendSelectedValue` (default: 0)
157      If false, attribute `value` will be assigned the index of the selected item. Otherwise, it is assigned the currently selected item's label.
158
159   `control2attributeDict` (default: {})
160      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.
161
162   `emptyString` (default: "")
163      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.
164
165   `valueType` (default: str or unicode)
166      A function through which the currently selected item's label is converted prior to looking into `control2attributeDict`. Needed to convert Qt's QString.
167
168
169List Box
170********
171
172This control, which might be the most complicated control in OWGUI, is a
173sophisticated wrapper around QListBox. It's complexity arises from synchronization.
174
175
176.. function:: listBox(widget, master, value, labels[, box, tooltip, callback, selectionMode])
177
178   `value` (required)
179      The name of master's attribute containing indices of all selected values.
180
181   `labels` (required)
182      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.
183
184   `selectionMode` (default: QListWidget.SingleSelection)
185      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`).
186
187   `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).
188
189   `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.
190
191
192
193Spin
194****
195
196Spin control, a wrapper around QSpinBox.
197
198.. function:: spin(widget, master, value, min, max[, step, box, label, labelWidth, orientation, tooltip, callback, controlWidth])
199
200   `min`, `max`, `step=1`
201      Minimal and maximal value, and step.
202
203
204Slider
205******
206
207A wrapper around QSlider that allows user setting a numerical value between the given bounds.
208
209.. function:: hSlider(widget, master, value[, box, minValue, maxValue, step, callback, labelFormat, ticks, divideFactor])
210
211
212   `minValue` (default: 0), `maxValue` (default: 10), `step` (default: 1)
213      Minimal and maximal value for the spin control, and its step.
214
215   `ticks` (default: 0)
216      If non-zero, it gives the interval between two ticks. The ticks will appear below the groove.
217
218   `labelFormat` (default: " %d")
219      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.
220
221   `divideFactor` (default: 1.0)
222      The value printed in the label is divided by `divideFactor`.
223
224
225Check Box with Spin
226*******************
227
228Check box with spin, or, essentially, a wrapper around
229OWGUI.checkBox and OWGUI.spin.
230
231.. function:: checkWithSpin(widget, master, label, min, max, checked, value[, posttext, step, tooltip, checkCallback, spinCallback, labelWidth])
232
233   `min`, `max`, `step` (required)
234      Minimal and maximal value for the spin control, and its step.
235
236   `checked` (required)
237      Master's attribute that is synchronized with the state of the check box.
238
239   `value` (required)
240      The attribute that is synchronized with the spin.
241
242   `posttext` (default: None)
243      Text which appears on the right-hand side of the control.
244
245   `checkCallback` (default: None), `spinCallback` (default: None)
246      Function that are called when the state of the check box or spin changes.
247
248
249Labels
250******
251
252There 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`.
253
254.. function:: widgetLabel(widget, label[, labelWidth])
255
256   The second is a label which can synchronize with values of master widget's attributes.
257
258.. function:: label(widget, master, label[, labelWidth])
259
260   `label`
261      `label` is a format string following Python's syntax (see the
262      corresponding Python documentation): the label's content is rendered as
263      ``label % master.__dict__``.
264
265
266*********
267Utilities
268*********
269
270Widget box
271**********
272
273
274.. function:: widgetBox(widget, box=None, orientation='vertical', addSpace=False)
275
276   Creates a box in which other widgets can be put. If `box` is given
277   and not false, the box will be framed. If `box` is a string, it will
278   be used for the box name (don't capitalize each word; spaces in front or
279   after the string will be trimmed and replaced with a single space).
280   Argument `orientation` can be ``"vertical"`` or ``"horizontal"``
281   (or ``True`` and ``False``, or ``1`` and ``0``, respectively).
282
283
284Idented box
285***********
286
287
288.. function:: indentedBox(widget, sep=20)
289
290      Creates an indented box. Widgets which are subsequently put into
291      that box will be arranged vertically and aligned with an indentation
292      of `sep`.
293
294
295Inserting Space between Widgets
296*******************************
297
298Most widgets look better if we insert some vertical space between the controls
299or groups of controls. A few functions have an optional argument `addSpace`
300by which we can request such space to be added. For other occasions, we can use
301the following two functions.
302
303.. function:: separator(widget, width=0, height=8)
304
305   Function `separator` inserts a fixed amount of space into `widget`.
306   Although the caller can specify the amount, leaving the default will help the
307   widgets having uniform look.
308
309.. function:: rubber(widget[, orientation="vertical"])
310
311   Similar to separator, except that the size is (1, 1) and that it expands in the
312   specified direction if the widget is expanded. Most widgets should have rubber
313   somewhere in their :obj:`controlArea`.
314
315Attribute Icons
316***************
317
318.. function:: getAttributeIcons()
319
320   Returns a dictionary with attribute types (:obj:`orange.VarTypes.Discrete`,
321   :obj:`orange.VarTypes.Continuous`, :obj:`orange.VarTypes.String`, -1) as keys
322   and colored pixmaps as values. The dictionary can be used in list and combo
323   boxes showing attributes for easier distinguishing between attributes of different types.
324
325Send automatically / Send
326*************************
327
328Many 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:
329
330* disable the button, when the check box is checked;
331* 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.
332
333Programming 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.
334
335.. function:: setStopper(master, sendButton, stopCheckbox, changedFlag, callback)
336
337   `sendButton`
338      The button that will be disabled when the check box is checked.
339
340   `stopCheckbox`
341      Check box that decides whether the changes are sent/commited/applied automatically.
342
343   `changedFlag`
344      The name of the `master`'s attribute which tells whether there is a change which has not been sent/applied yet.
345
346   `callback`
347      The function that sends the data or applies the changes. This is typically the function which is also used as the `sendButton`'s callback.
348
349
350: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.
351
352..
353   Make sure to carefully observe and follow the example provided below.
354
355   Missing, where did it go?
356
Note: See TracBrowser for help on using the repository browser.