Ignore:
File:
1 edited

Legend:

Unmodified
Added
Removed
  • docs/extend-widgets/rst/owgui.rst

    r11408 r11424  
    3434`value` (required) 
    3535   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. 
     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. 
    3740 
    3841`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. 
     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. 
    4046 
    4147`callback` (default: None) 
     
    5157 
    5258`tooltip` (default: None) 
    53    A string that is displayed in a tooltip that appears when mouse is over the control. 
     59   A string that is displayed in a tooltip that appears when mouse is over the 
     60   control. 
    5461 
    5562`label` (default: None) 
     
    6067 
    6168`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".) 
     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".) 
    6375 
    6476`disabled` (default: False) 
     
    6678 
    6779`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. 
     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. 
    6983 
    7084 
     
    7589This section describes the OWGUI wrappers for controls like check boxes, buttons 
    7690and similar. All the important Qt's controls can be constructed through this 
    77 functions. You should always use them instead of calling Qt directly, not only 
    78 because they are convenient, but also because they set up a lot of things that happen in behind. 
     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. 
    7997 
    8098 
     
    88106 
    89107   `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. 
     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. 
    91114 
    92115   `labelWidth` (default: None) 
     
    102125 
    103126   `valueType` (default: str) 
    104       A type into which the value is cast. 
     127      A type into which the `value` is cast. 
    105128 
    106129   `validator` (default: None) 
     
    152175 
    153176   `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. 
     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. 
    155182 
    156183   `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. 
     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. 
    158186 
    159187   `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.  
     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. 
    161192 
    162193   `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. 
     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. 
    164201 
    165202   `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. 
     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. 
    167206 
    168207 
     
    171210 
    172211This control, which might be the most complicated control in OWGUI, is a 
    173 sophisticated wrapper around QListBox. It's complexity arises from synchronization. 
     212sophisticated wrapper around QListBox. It's complexity arises from 
     213synchronization. 
    174214 
    175215 
     
    180220 
    181221   `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. 
     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. 
    183229 
    184230   `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  
     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`). 
     235 
     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). 
     240 
     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. 
    191252 
    192253 
     
    205266****** 
    206267 
    207 A wrapper around QSlider that allows user setting a numerical value between the given bounds. 
     268A wrapper around QSlider that allows user setting a numerical value between 
     269the given bounds. 
    208270 
    209271.. function:: hSlider(widget, master, value[, box, minValue, maxValue, step, callback, labelFormat, ticks, divideFactor]) 
     
    214276 
    215277   `ticks` (default: 0) 
    216       If non-zero, it gives the interval between two ticks. The ticks will appear below the groove. 
     278      If non-zero, it gives the interval between two ticks. The ticks will 
     279      appear below the groove. 
    217280 
    218281   `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. 
     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. 
    220285 
    221286   `divideFactor` (default: 1.0) 
     
    226291******************* 
    227292 
    228 Check box with spin, or, essentially, a wrapper around 
    229 OWGUI.checkBox and OWGUI.spin. 
     293Check box with spin, or, essentially, a wrapper around OWGUI.checkBox and 
     294OWGUI.spin. 
    230295 
    231296.. function:: checkWithSpin(widget, master, label, min, max, checked, value[, posttext, step, tooltip, checkCallback, spinCallback, labelWidth]) 
     
    250315****** 
    251316 
    252 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`. 
     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`. 
    253321 
    254322.. function:: widgetLabel(widget, label[, labelWidth]) 
    255323 
    256    The second is a label which can synchronize with values of master widget's attributes. 
     324   The second is a label which can synchronize with values of master widget's 
     325   attributes. 
    257326 
    258327.. function:: label(widget, master, label[, labelWidth]) 
     
    326395************************* 
    327396 
    328 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: 
     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: 
    329401 
    330402* 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  
    333 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. 
     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. 
     406 
     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. 
    334410 
    335411.. function:: setStopper(master, sendButton, stopCheckbox, changedFlag, callback) 
     
    339415 
    340416   `stopCheckbox` 
    341       Check box that decides whether the changes are sent/commited/applied automatically. 
     417      Check box that decides whether the changes are sent/commited/applied 
     418      automatically. 
    342419 
    343420   `changedFlag` 
    344       The name of the `master`'s attribute which tells whether there is a change which has not been sent/applied yet. 
     421      The name of the `master`'s attribute which tells whether there is a 
     422      change which has not been sent/applied yet. 
    345423 
    346424   `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. 
     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. 
     427 
     428 
     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. 
    351432 
    352433.. 
     
    354435 
    355436   Missing, where did it go? 
    356  
Note: See TracChangeset for help on using the changeset viewer.