summaryrefslogtreecommitdiffstats
path: root/doc/kommander/widgets.docbook
blob: 45504ee418591866ead80f761eed1347a54faf5c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
<?xml version="1.0"  encoding="UTF-8" ?>

<sect1 id="widgets">
<sect1info>
<title>Widgets</title>
</sect1info>

<title>Widgets</title>

<para>
The building blocks of a &kommander; dialog are the widgets.  They are like any other widget in the &Qt; and &kde; libraries except they have some extra functionality that allows them to have a <quote>text association</quote>.  Text is associated with a state of the widget or its populate slot.  The number of states depends on the widget.  If a widget only has one state, that state is called default.
</para>

<note>
<para>The main dialog has two special states for &kommander; text.  They are Initialization and Destroy.  These are run when the dialog is initialized and when it is destroyed.  These protect against what is know as <quote>race</quote> problems on open and mean that you do not require any special procedures on close to manage housekeeping.</para>
<para>In case of using a MainWindow based application (created with &Qt; Designer), there are no Initialization and Destroy states, instead the <emphasis>initialize</emphasis> and <emphasis>destroy</emphasis> signals can be used to get information when is the application constructed or closed</para>
</note>

<para>
Below are the standard &kommander; widgets. Each of them has numerous functions, you can learn about them by looking at the widget functions in the <guilabel>Function Browser</guilabel>. Many of them have signals and slots as well, documentation about these methods can be found in the &Qt; and &kde; API documentation. Each &kommander; widget has a note about its base widget.
</para>

<variablelist>

<varlistentry>
<term>
<inlinemediaobject><imageobject>
<imagedata fileref="label.png" format="PNG" />
</imageobject></inlinemediaobject>
Label
</term>
<listitem>
<para>
A simple widget that contains a piece of text.  This widget lets you set a pixmap too.
</para>
<para> 
See the QLabel documentation to learn more about text labels in &Qt;.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<inlinemediaobject><imageobject>
<imagedata fileref="pixlabel.png" format="PNG" />
</imageobject></inlinemediaobject>
PixmapLabel
</term>
<listitem>
<para>
A simple widget that contains an image or text label.  The pixmap to display is set in the pixmap property.  The text is set in the text property.  Only one of these properties can be set at the same time (I think, I can't get the editor to set both at the same time).  If scaledContents is set to true the image will be scaled to fit the size of the widget.  The format of the text can be set with the textFormat property.
</para>
<para>
See the QLabel documentation to learn more about text labels in &Qt;.
</para>
</listitem>
</varlistentry>


<varlistentry>
<term>
<inlinemediaobject><imageobject>
<imagedata fileref="lineedit.png" format="PNG" />
</imageobject></inlinemediaobject>
LineEdit
</term>
<listitem>
<para>
A LineEdit widget is a one line text editor.  It allows the user to enter and modify a single line of text.  Initial text for the editor can be set in the text property.  The widget can be set to read-only with the readOnly property.  There are 3 modes for the widget, Normal, NoEcho, and Password.  The mode is set with the echoMode property.
</para>
<para>
LineEdit has one state, default.
</para>
<para>
The widget text for LineEdit is the text contained in the editor.
</para>
<para>
See the KLineEdit documentation to learn more about text labels in &kde;.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<inlinemediaobject><imageobject>
<imagedata fileref="multilineedit.png" format="PNG" />
</imageobject></inlinemediaobject>
TextEdit
</term>
<listitem>
<para>
A simple multi-line text editor.
</para>
<para>
See the KTextEdit documentation to learn more about multiline text edit in &kde;.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<inlinemediaobject><imageobject>
<imagedata fileref="textbrowser.png" format="PNG" />
</imageobject></inlinemediaobject>
TextBrowser
</term>
<listitem>
<para>
A simple reach text browser with hyperlink navigation.
</para>
<para>
See the KTextBrowser documentation to learn more about it.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<inlinemediaobject><imageobject>
<imagedata fileref="listbox.png" format="PNG" />
</imageobject></inlinemediaobject>
ListBox
</term>
<listitem>
<para>
A ListBox widget provides a list of selectable items.  Normally one or no items are selected.  This behavior can be changed with the selectionMode property.  Items are added to the ListBox using the edit window.
</para>
<para>
A ListBox has only one state, default.
</para>
<para>
The widget text for a ListBox is the items contained in the ListBox.  @selectedWidgetText will return only the items that are currently selected.
</para>
<para>
See the TDEListBox documentation to learn more about it.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<inlinemediaobject><imageobject>
<imagedata fileref="combobox.png" format="PNG" />
</imageobject></inlinemediaobject>
ComboBox
</term>
<listitem>
<para>
ComboBox is a selection widget that combines a button and a pop-up menu.  It shows the user's current choice from a list of options in minimal space.  Items are added to the list using the edit window.  If the editable property is set to true the user can enter arbitrary strings.
</para>
<para>
ComboBox has one state, default.
</para>
<para>
The widget text for a ComboBox is the text of the selected item.
</para>
<para>
See the KComboBox documentation to learn more about it.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<inlinemediaobject><imageobject>
<imagedata fileref="listview.png" format="PNG" />
</imageobject></inlinemediaobject>
TreeWidget
</term>
<listitem>
<para>
A widget that provides a list in the form of a tree structure. You can add child items and multi-column data. The current limitation is that you cannot modify columns. To add a child node use <quote>/</quote> as a separator. To add column data use the escaped tab <quote>\t</quote> character between columns.
</para>
<para>
See the TDEListView documentation to learn more about it.
</para>

</listitem>
</varlistentry>

<varlistentry>
<term>
<inlinemediaobject><imageobject>
<imagedata fileref="table.png" format="PNG" />
</imageobject></inlinemediaobject>
Table
</term>
<listitem>
<para>
A table widget that support different widgets in its cells.
</para>
<para>
See the QTable documentation to learn more about it.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<inlinemediaobject><imageobject>
<imagedata fileref="pushbutton.png" format="PNG" />
</imageobject></inlinemediaobject>
ExecButton
</term>
<listitem>
<para>
A button that when clicked executes its text association.  The label on the button is set with the text property.  Output from the text association (how to say that) will be echoed to stdout if the writeStdout property is set to true.  The button can be the default action for the dialog if the default property is set to true.
</para>
<para>
ExecButton has one state, default.
</para>
<para>
There isn't widget text associated with ExecButton.
</para>
<para>
See the KPushButton documentation to learn more about it.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<inlinemediaobject><imageobject>
<imagedata fileref="closebutton.png" format="PNG" />
</imageobject></inlinemediaobject>
CloseButton
</term>
<listitem>
<para>
A button that when clicked, executes its text association and then closes the dialog.  The label on the button is set with the text property.  Output from the text association (how to say that) will be echoed to stdout if the writeStdout property is set to true.  The button can be the default action for the dialog if the default property is set to true.
</para>
<para>
CloseButton has one state, default.
</para>
<para>
There isn't any widget text associated with a CloseButton.
</para>
<para>
See the KPushButton documentation to learn more about it.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<inlinemediaobject><imageobject>
<imagedata fileref="konsole.png" format="PNG" />
</imageobject></inlinemediaobject>
Konsole
</term>
<listitem>
<para>
A widget that captures the output of scripts in a text browser. The default state is executed and the output of those commands (internal or external) are shown in the widget.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<inlinemediaobject><imageobject>
<imagedata fileref="lineedit.png" format="PNG" />
</imageobject></inlinemediaobject>
FileSelector
</term>
<listitem>
<para>
The FileSelector widget combines a LineEdit with a button when clicked will present the user with dialog for the selection of files/folders.  The file/folder selected is stored in the LineEdit.  The type of the FileSelector is set with the selectionType property.  Available types are Open, Save, and Directory.  Multiple files/folders can be selected if the selectionOpenMutliple property is set to true.  A caption for the FileChooser can be set with the selectionCaption property.  This is display as the window title of the dialog.  If a caption isn't specified, the type of selection will be display in the title.  The files displayed in the dialog can be limited using the selectionFilter property.
</para>
<para>
FileSelector has one state, default.
</para>
<para>
The widget text for a FileSelector is the text contained in the LineEdit (the file chosen by the user).
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<inlinemediaobject><imageobject>
<imagedata fileref="checkbox.png" format="PNG" />
</imageobject></inlinemediaobject>
CheckBox
</term>
<listitem>
<para>
A button that can be checked on and off.  It can also be semi-checked if the tristate property is set to true.  The label associated with the CheckBox is set in the text property.  Setting the checked property will have the CheckBox initially checked.
</para>
<para>
A CheckBox has 3 states, checked, semichecked, and unchecked.
</para>
<para>
The widget text for a CheckBox is the value from the text property.
</para>
<para>
See the KCheckBox documentation to learn more about it.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<inlinemediaobject><imageobject>
<imagedata fileref="radiobutton.png" format="PNG" />
</imageobject></inlinemediaobject>
RadioButton
</term>
<listitem>
<para>
A button that can be checked or unchecked, usually used in the ButtonGroup to make an exclusive choice.  A label associated with the button can be set in the text property.  A button can be initialized to checked by setting the checked property to true.  If all RadioButtons in a ButtonGroup have the checked property set to true, then the last button will be the one that is checked.
</para>
<para>
RadioButton has 2 states checked and unchecked.
</para>
<para>
There is no widget text associated with a RadioButton.
</para>
<para>
See the TDERadioButton documentation to learn more about it.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<inlinemediaobject><imageobject>
<imagedata fileref="buttongroup.png" format="PNG" />
</imageobject></inlinemediaobject>
ButtonGroup
</term>
<listitem>
<para>
A container to organize buttons into a group.  An optional title can be set using the title property.  The frame can be adjusted with the lineWidth property.  The button group can be set to exclusive by setting the exclusive property to true.  This means when one toggle button is clicked all other toggle buttons will be set to off with the exception of radio buttons that are always mutual exclusive even if the group is non-exclusive.  Radio buttons can be set to non-exclusive using the radioButtonExclusive property.  (I am not so sure that this property actually works.)
</para>
<para>ButtonGroup has one state, default.</para>
<para>
The widget text for a ButtonGroup is the text associations for each of the buttons in the order they appear in the ButtonGroup.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<inlinemediaobject><imageobject>
<imagedata fileref="groupbox.png" format="PNG" />
</imageobject></inlinemediaobject>
GroupBox
</term>
<listitem>
<para>
A container widget that holds other widgets.  The frame is adjusted with the lineWidth property.  A title can be added by setting the title property.
</para>
<para>
GroupBox has one state, default.
</para>
<para>
The widget text for GroupBox is the text associations of each of the widgets it contains combined.  They will be in the order they appear inside of the GroupBox.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<inlinemediaobject><imageobject>
<imagedata fileref="tabwidget.png" format="PNG" />
</imageobject></inlinemediaobject>
TabWidget
</term>
<listitem>
<para>
A widget that provides multiple tabs each may contain other widgets.
</para>
<para>
See the KTabWidget documentation to learn more about it.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<inlinemediaobject><imageobject>
<imagedata fileref="spinbox.png" format="PNG" />
</imageobject></inlinemediaobject>
SpinBoxInt
</term>
<listitem>
<para>
A widget that allows the user to change a integer value by either press up and down arrows or entering a value into the box.  Minimum and maximum values for the widget can be set with the minValue and maxValue properties.  The specialValueText property is used to set a text value that will be displayed instead of the minimum value.
</para>
<para>
This widget has only one state, default.
</para>
<para>
The widget text for a SpinBoxInt is the currently displayed integer.
</para>
<para>
See the QSpinBox documentation to learn more about it.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<inlinemediaobject><imageobject>
<imagedata fileref="slider.png" format="PNG" />
</imageobject></inlinemediaobject>
Slider
</term>
<listitem>
<para>
A widget that provides horizontal or vertical slider.
</para>
<para>
See the QSlider documentation to learn more about it.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<inlinemediaobject><imageobject>
<imagedata fileref="richtextedit.png" format="PNG" />
</imageobject></inlinemediaobject>
RichTextEditor
</term>
<listitem>
<para>
This widgets provides a text editor that allows for simple text formatting.
</para>
<para>
RichTextEditor has one state, default.
</para>
<para>
The widget text for RichTextEditor is the text contained in the editor in rich text format.  Selected text can be returned with @selectedWidgetText.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<inlinemediaobject><imageobject>
<imagedata fileref="statusbar.png" format="PNG" />
</imageobject></inlinemediaobject>
StatusBar
</term>
<listitem>
<para>
A widget to display status information, usually used at the bottom of the dialogs.
</para>
<para>
See the KStatusBar documentation to learn more about it.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<inlinemediaobject><imageobject>
<imagedata fileref="progress.png" format="PNG" />
</imageobject></inlinemediaobject>
ProgressBar
</term>
<listitem>
<para>
A widget to display progress information.
</para>
<para>
See the KProgress documentation to learn more about it.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<inlinemediaobject><imageobject>
<imagedata fileref="shellscript.png" format="PNG" />
</imageobject></inlinemediaobject>
ScriptObject
</term>
<listitem>
<para>
This is a pseudo-widget, it does not appear when the dialog is run. It can be though about as a function. A ScriptObject holds code that can be executed anytime from the dialog by calling its <emphasis>execute</emphasis> function. Arguments can be passed to the ScripObject with the above method and accessed inside the ScriptObject as <emphasis>@Self.item(0), @Self.item(1), etc.</emphasis> if using the old style parsing or <emphasis>Self.item(0, Self.item(1), etc.</emphasis> with the new parser.
</para>
<para>
Signals can be connected to the <emphasis>execute</emphasis> function as well, as it acts also as a slot.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<inlinemediaobject><imageobject>
<imagedata fileref="timer.png" format="PNG" />
</imageobject></inlinemediaobject>
Timer
</term>
<listitem>
<para>
This is a pseudo-widget, it does not appear when the dialog is run. It can be used to perform an action after a specified time once, or regularly. Set the timeout <guilabel>interval</guilabel> in milliseconds, choose if it should run once (<guilabel>singleShot</guilabel>) or not. Connect its <emphasis>timeout</emphasis> signal to a slot, which will be executed once the specified time passes.
</para>
<para>
The timer is not started by default, run the <emphasis>execute</emphasis> function to start it.
</para>
<para>
See the QTimer documentation to learn more.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<inlinemediaobject><imageobject>
<imagedata fileref="datepicker.png" format="PNG" />
</imageobject></inlinemediaobject>
DatePicker
</term>
<listitem>
<para>
A widget used to select a date. The default date can be set in the <guilabel>date</guilabel> property or with the <emphasis>setText</emphasis> function in ISO format: <emphasis>YYYY-MM-DD</emphasis>.
</para>
<para>
The widget text is the currently displayed date.
</para>
<para>
See the KDatePicker documentation to learn more.
</para>
<note><para>New in Kommander 1.3.</para></note>
</listitem>
</varlistentry>

<varlistentry>
<term>
<inlinemediaobject><imageobject>
<imagedata fileref="kommander.png" format="PNG" />
</imageobject></inlinemediaobject>
AboutDialog
</term>
<listitem>
<para>
This is a pseudo-widget, it does not appear when the dialog is run. It stores information about the application, the authors, the license. Shows the about dialog 
when the <emphasis>execute</emphasis> function is called.
<warning><para>The <emphasis>initialize</emphasis> function must be called before anything else, including the <emphasis>execute</emphasis> function.</para></warning>
</para>
<note><para>New in Kommander 1.3.</para></note>
</listitem>
</varlistentry>

<varlistentry>
<term>
<inlinemediaobject><imageobject>
<imagedata fileref="tdefontcombo.png" format="PNG" />
</imageobject></inlinemediaobject>
FontDialog
</term>
<listitem>
<para>
A pseudo-widget, that can be used to get a font selection dialog. The default font can be set with the <emphasis>setFont</emphasis> function, and the selected font's properties retrieved with the <emphasis>family, pointSize, bold, italic</emphasis> functions. The dialog is shown when the <emphasis>execute</emphasis> function is called.
</para>
<note><para>New in Kommander 1.3.</para></note>
</listitem>
</varlistentry>

<varlistentry>
<term>
<inlinemediaobject><imageobject>
<imagedata fileref="contents.png" format="PNG" />
</imageobject></inlinemediaobject>
PopupMenu
</term>
<listitem>
<para>
A pseudo-widget, that can be used to display a menu. Use the <emphasis>insert...</emphasis> functions to add menu entries. Whenever the user clicks on a menu entry, the specified <emphasis>executeWidget</emphasis>'s <emphasis>execute</emphasis> function will be run. It is possible to connect the menu entries to the popupmenu's own <emphasis>execute</emphasis> function, in which case the text assigned to the <emphasis>default</emphasis> state is run. When adding menu items you can assign an index to them and handle the all the items on a menu in the menu widget as the request passes this index back. To see how this works look at the current example <link linkend="example-key-value">keyvaluecombo.kmdr</link> included with this release. To find it look on the tools menu of the editor for the examples dialog.
</para>
<para>To show the menu, use <emphasis>popup</emphasis> slot. Usually this is connected to another widget's <emphasis>contextMenuRequested</emphasis> signal.</para>
<para>A menu can contain other PopupMenu submenus.</para>
<note><para>New in Kommander 1.3.</para></note>
</listitem>
</varlistentry>

<varlistentry>
<term>
<inlinemediaobject><imageobject>
<imagedata fileref="toolbox.png" format="PNG" />
</imageobject></inlinemediaobject>
ToolBox
</term>
<listitem>
<para>
A container widget, like TabWidget. It has several pages, each page can hold other widgets.
</para>
<warning><para>This widget has an editor bug that does not affect it's use in execution, but does affect it's use in the editor. If you try to add pages in the editor it will become unreadable. Don't do this. If you want to use the ToolBox please use fill the widget on the fly using the <command>addWidget</command> command. If there is time an example will be added to the 1.3 release, or check the web site.</para></warning>
<para>See the QToolBox documentation to learn more about it.</para>
<note><para>New in Kommander 1.3.</para></note>
</listitem>
</varlistentry>


</variablelist>
</sect1>