source: orange/orange/doc/extend-widgets/owguiex.htm @ 9398:a6b3d9c13ee0

Revision 9398:a6b3d9c13ee0, 11.3 KB checked in by mitar, 2 years ago (diff)

Renaming documentation for widgets developers.

Line 
1<html>
2<head>
3<title>Orange Widgets: OWGUIEx</title>
4<link rel=stylesheet HREF="../style.css" type="text/css">
5<link rel=stylesheet href="style-print.css" type="text/css" media=print>
6
7
8<script type="text/javascript">
9function toggleVisibility(obj)
10{
11   var exampleStyle = obj.parentNode.getElementsByTagName('div')[0].style;
12   var buttonText = obj.firstChild;
13
14   if ((exampleStyle.visibility == "hidden") || (exampleStyle.visibility=="")) {
15     exampleStyle.visibility = "visible";
16     exampleStyle.height = "auto";
17     buttonText.data = "Hide Example";
18     if (navigator.appName == "Microsoft Internet Explorer")
19       exampleStyle.position = "fixed";
20   }
21   else {
22     exampleStyle.visibility = "hidden";
23     exampleStyle.height = "1%";
24     buttonText.data = "Show Example";
25     if (navigator.appName == "Microsoft Internet Explorer")
26       exampleStyle.position = "absolute";
27   }
28}
29
30function onLoad()
31{
32   if (navigator.appName == "Microsoft Internet Explorer") {
33       try {
34            for(var x = 0, ss = document.styleSheets; ss[x]; x++) {
35                for (var y=0, rr = ss[x].rules; rr[y]; y++) {
36                    if (rr[y].selectorText == ".example") {
37                        rr[y].style.position = "absolute";
38                        rr[y].style.marginTop = "0px";
39                    }
40                    if (rr[y].selectorText == ".hideShow")
41                        rr[y].style.marginBottom = "0px";
42                }
43            }
44       }
45       catch (e) {}
46   }
47}
48
49</script>
50
51<style>
52P.function { font-family: monospace; font-weight: bold; font-size: 8pt; margin-top: 1em }
53
54xmp.code { font-size: 8pt; background-color: white; }
55
56.example { visibility: hidden; height: 1%; border: 1px solid #000000; padding-left: 6px; margin-top: -7px; padding-top: 0px; background-color: #f8f8f8; }
57
58.hideshow { border: 1px dotted #000000; padding: 2px; margin-bottom: -7px; background-color: #eeeeee; margin-right: 6px; }
59
60/*.example { visibility: hidden; height: 1%; border: 1px solid #000000; padding-left: 6px; margin-top: -5px; padding-top: 0px; background-color: #f8f8f8; z-index: -1;}
61
62.hideshow { border: 1px dotted #000000; padding: 2px; margin-bottom: -5px; background-color: #eeeeee; margin-right: 6px; z-index: 1;}
63*/
64
65.header {margin: 0px; padding: 0px;  }
66
67.function { background-color: #eeeeee; padding: 2px; }
68
69H1 { margin-top: 48px; font-size: 12pt; background-color: white; color: black; }
70H2 { margin-top: 36px; font-size: 10pt; background-color: white; font-weight: bold; color: blue; }
71
72</style>
73
74</head>
75<body onLoad="onLoad();">
76
77
78<h1>OWGUIEx: Library of Advanced GUI Controls</h1>
79
80<p>OWGUIEx library contains a set of more advanced GUI components. We didn't simply put them in the OWGUI module since these components typically take tens or hundreds of lines of code and are less frequently used in widgets.</p>
81
82<hr>
83
84<h1>Common Attributes</h1>
85
86<P>Since this file is basically an extension of the OWGUI library, many of the attributes that can be specified when constructing a control are described in the "Common attributes" section in the documentation on <a href="owgui.htm">OWGUI</a>. It is highly recomended that you are familiar with those attributes.</P>
87
88
89<h1>Controls</h1>
90
91<P>This section describes the OWGUI wrappers for controls that are defined in OWGUIEx.</P>
92
93<h2>Line Edit with Filter</h2>
94
95<P>A modification of the <a href="owgui.htm#lineedit">OWGUI.lineEdit</a> control. It can be used to filter content of a list box based on the text in this control. </P>
96
97<p class="function">
98lineEditFilter(widget, master, value [, label, labelWidth, orientation, box, tooltip, valueType, validator, controlWidth, caseSensitive, useRE, matchAnywhere, callback, emptyText])
99</p>
100
101The meaning of attributes <code>label</code>, <code>labelWidth</code>, <code>orientation</code>, <code>box</code>, <code>tooltip</code>, <code>valueType</code>, <code>validator</code> and <code>controlWidth</code> are described in the <a href="owgui.htm#lineedit">OWGUI.lineEdit</a> documentation.
102
103
104<dl class="attributes">
105
106<DT>caseSensitive (default: 1)</DT>
107<DD>Determines whether the filtering of items in the list box will be case sensitive or not.</DD>
108
109<DT>useRE (default: 0)</DT>
110<DD>Determines whether use of regular expressions is allowed or not. If regular expressions are allowed then certain characters have different meaning, e.g. typing ".a" in the line edit will keep all those list box items that have letter a as the second character (no matter what the first character is).</DD>
111
112<DT>matchAnywhere (default: 0)</DT>
113<DD>Do we want to match only those list box items that start with the text in the line edit control or can the text appear anywhere in the item's text. <code>matchAnywhere</code> attribute is relevant only when we don't use regular expressions (<code>useRe = 0</code>).</DD>
114
115<dt>callback (default: None)</dt>
116<dd>The specified callback function will be called each time the line edit control is changed (edited).</dd>
117
118<dt>emptyText (default: "")</dt>
119<dd>When the text in the control will be empty and the control will be out of focus, the specified <code>emptyText</code> will be displayed in gray color. This attribute can be used to make it easier for the user to know what is the function of the control. For example, by setting <code>emptyText="Filter attributes..."</code> we can let user know that he can use the control to filter out the attributes.</dd>
120</dl>
121
122Along with the described attributes there are also some important methods that can/have to be used:
123
124<dl class="attributes">
125
126<DT>setListBox(listbox)</DT>
127<DD>Using this method we can specify which list box instance we would like to control using the line edit.</DD>
128
129<DT>setAllListItems(items)</DT>
130<DD>Using this method we tell the line edit control what is the complete (unfiltered) content of the list box. The list of items can be a list of strings or <code>QListWidgetItem</code> instances.</DD>
131
132<DT>updateListBoxItems(callCallback=1)</DT>
133<DD>We can call this function if we want manually to cause the update of the associated list box based on the content of the line edit. The value of <code>callCallback</code> argument determines whether we would like to call the callback function after this update or not.</DD>
134</dl>
135
136<span>
137<span onclick="toggleVisibility(this);" class="hideshow">Show Example</span>
138<span class="hideshow"><a href="gui_lineeditFilter.py">Download example (gui_lineeditFilter.py)</a></span>
139<div class="example">
140
141<p>In the following code we create a lineEditFilter and a list box component. We add to the list box 10.000 randomly generated strings of length 10 and also tell the line edit control that these are all of the items. By typing in the line edit we can then keep only those list box items that match the text.</p>
142
143<table><tr>
144<td width="600px">
145<xmp class=code>self.filter = ""
146self.listboxValue = ""
147lineEdit = OWGUIEx.lineEditFilter(self.controlArea, self, "filter", "Filter:", useRE = 1, emptyText = "filter...")
148
149listbox = OWGUI.listBox(self.controlArea, self, "listboxValue")
150lineEdit.setListBox(listbox)
151
152names = []
153for i in range(10000):
154  names.append("".join([string.ascii_lowercase[random.randint(0, len(string.ascii_lowercase)-1)] for c in range(10)]))
155lineEdit.listbox.addItems(names)
156lineEdit.setAllListItems(names)
157</xmp>
158</td>
159<td valign="top"><img src="gui_lineeditFilter.png"></td>
160</tr></table>
161</div></span>
162
163<h2>Line Edit with Hint</h2>
164
165<P>A modification of the <a href="owgui.htm#lineedit">OWGUI.lineEdit</a> control. It helps the user to enter the text by showing a drop-down list of items that match the current text.</P>
166
167<p class="function">
168lineEditHint(widget, master, value [, label, labelWidth, orientation, box, tooltip, valueType, validator, controlWidth, caseSensitive, useRE, matchAnywhere, callback, listUpdateCallback, nrOfSuggestions, autoSizeListWidget, delimiters])
169</p>
170
171The meaning of attributes <code>label</code>, <code>labelWidth</code>, <code>orientation</code>, <code>box</code>, <code>tooltip</code>, <code>valueType</code>, <code>validator</code> and <code>controlWidth</code> are described in the <a href="owgui.htm#lineedit">OWGUI.lineEdit</a> documentation.
172
173<dl class="attributes">
174
175<DT>caseSensitive (default: 1)</DT>
176<DD>Determines whether the filtering of items in the list box will be case sensitive or not.</DD>
177
178<DT>useRE (default: 0)</DT>
179<DD>Determines whether use of regular expressions is allowed or not. If regular expressions are allowed then certain characters have different meaning, e.g. typing ".a" in the line edit will show in the suggestion-list all those items that have letter a as the second character (no matter what the first character is).</DD>
180
181<DT>matchAnywhere (default: 0)</DT>
182<DD>Do we want to match only those items that start with the text in the line edit control or can the text appear anywhere in the item's text. <code>matchAnywhere</code> attribute is relevant only when we don't use regular expressions (<code>useRe = 0</code>).</DD>
183
184<dt>callback (default: None)</dt>
185<dd>The specified callback function will be called each time some suggested item is selected.</dd>
186
187<dt>listUpdateCallback (default: None)</dt>
188<dd>The specified function will be called each time the list of suggested items is updated.</dd>
189
190<dt>nrOfSuggestions (default: 10)</dt>
191<dd>This attribute determines the height of the list of suggested items. By default, the height is determined so that the list will show maximum 10 items. If more items match the criteria, a vertical scrollbar will be shown.</dd>
192
193<dt>autoSizeListWidget (default: 0)</dt>
194<dd>If <code>autoSizeListWidget</code> is 1 then the width of the suggestions list will be adjusted automatically based on the width of the items in the list. The width of the list will be at least as wide as the line edit control.
195</dd>
196
197<dt>delimiters (default: None)</dt>
198<dd>Sometimes we would like to have more than one item in the line edit. To be able to show the suggestions when entering the second, third, ... item, we have to specify which characters are delimiters that separate items. For example, let's assume we would like to use the line edit to specify a list of our favourite colors, which are red, blue and yellow. If we'd like to get a list of suggestions when we start typing the second color name (blue) we have to set <code>delimiters=', '</code> (notice that the string also contains SPACE besides the comma).
199</dd>
200</dl>
201
202Along with the described attributes there is also an important methods that has to be used:
203
204<dl class="attributes">
205
206<DT>setItems(items)</DT>
207<DD>Using this method we tell the line edit control what are the possible items that can be suggested when user is entering text. The list of items can be a list of strings or <code>QListWidgetItem</code> instances.</DD>
208</dl>
209
210<span>
211<span onclick="toggleVisibility(this);" class="hideshow">Show Example</span>
212<span class="hideshow"><a href="gui_lineeditHint.py">Download example (gui_lineeditHint.py)</a></span>
213<div class="example">
214
215<p>In the following example we create a lineEditHint and set a short list of items. By typing in the line edit we can then keep only those list box items that match the text.</p>
216
217<table><tr>
218<td width="600px">
219<xmp class=code>s = OWGUIEx.lineEditHint(self.controlArea, self, "text", useRE = 0, caseSensitive = 0, matchAnywhere = 0, delimiters = "., ")
220s.listWidget.setSpacing(2)
221items = ["janez", "joza", "danica", "jani", "jok", "jure"]
222s.setItems(items)
223</xmp>
224</td>
225<td valign="top"><img src="gui_lineeditHint.png"></td>
226</tr></table>
227</div></span>
228
229</body>
230</html>
231
Note: See TracBrowser for help on using the repository browser.