Qt
Internal/Contributor docs for the Qt SDK. Note: These are NOT official API docs; those are found at https://doc.qt.io/
Loading...
Searching...
No Matches
designer-manual.qdoc
Go to the documentation of this file.
1
// Copyright (C) 2016 The Qt Company Ltd.
2
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
3
4
/*!
5
\page qtdesigner-manual.html
6
7
\title Qt Widgets Designer Manual
8
\ingroup qttools
9
\keyword Qt Widgets Designer
10
11
\QD is the Qt tool for designing and building graphical user
12
interfaces (GUIs) with \l {Qt Widgets}. For user interface design with
13
\l {Qt Quick}, see \l {Qt Design Studio Manual} {Qt Design Studio}.
14
15
You can compose and customize your windows or dialogs in a
16
what-you-see-is-what-you-get (WYSIWYG) manner, and test them using different
17
styles and resolutions. Widgets and forms created with \QD integrate
18
seamlessly with programmed code, using Qt's signals and slots mechanism, so
19
that you can easily assign behavior to graphical elements. All properties
20
set in \QD can be changed dynamically within the code. Furthermore, features
21
like widget promotion and custom plugins allow you to use your own
22
components with \QD.
23
24
\note You have the option of using \l {Qt Quick} and
25
\l {Qt Design Studio Manual}{Qt Design Studio} for user interface
26
design rather than widgets. It is a much easier way to write many kinds of
27
applications. It enables a completely customizable appearance,
28
touch-reactive elements, and smooth animated transitions, taking advantage
29
of hardware acceleration.
30
31
If you are new to \QD, you can take a look at the
32
\l{Getting To Know Qt Widgets Designer} document. For a quick tutorial on how to
33
use \QD, refer to \l{A Quick Start to Qt Widgets Designer}.
34
35
\image designer-multiple-screenshot.png
36
37
\section1 Table of Contents
38
39
\list
40
\li \l{A Quick Start to Qt Widgets Designer}
41
\li \l{Qt Widgets Designer's Editing Modes}
42
\list
43
\li \l{Qt Widgets Designer's Widget Editing Mode}{Widget Editing Mode}
44
\li \l{Qt Widgets Designer's Signals and Slots Editing Mode}
45
{Signals and Slots Editing Mode}
46
\li \l{Qt Widgets Designer's Buddy Editing Mode}
47
{Buddy Editing Mode}
48
\li \l{Qt Widgets Designer's Tab Order Editing Mode}
49
{Tab Order Editing Mode}
50
\endlist
51
\li \l{Using Layouts in Qt Widgets Designer}
52
\li \l{Saving, Previewing and Printing Forms in Qt Widgets Designer}
53
\li \l{Using Containers in Qt Widgets Designer}
54
\li \l{Creating Main Windows in Qt Widgets Designer}
55
\li \l{Editing Resources with Qt Widgets Designer}
56
\li \l{Using Stylesheets with Qt Widgets Designer}
57
\li \l{Using a Designer UI File in Your C++ Application}
58
\li \l{Using a Designer UI File in Your Qt for Python Application}
59
\li Advanced Use
60
\list
61
\li \l{Customizing Qt Widgets Designer Forms}
62
\li \l{Using Custom Widgets with Qt Widgets Designer}
63
\li \l{Creating Custom Widgets for Qt Widgets Designer}
64
\li \l{Creating Custom Widget Extensions}
65
\li \l{Qt Widgets Designer's UI File Format}
66
\endlist
67
\endlist
68
*/
69
70
71
/*!
72
\page designer-to-know.html
73
74
75
\title Getting to Know Qt Widgets Designer
76
77
\image designer-screenshot.png
78
79
\section1 Launching Designer
80
81
Once you have installed Qt, you can start \QD in the same way as any other
82
application on the development host. You can also launch \QD directly from
83
Qt Creator. Qt Creator automatically opens all .ui files in the integrated
84
\QD, in \gui Design mode.
85
86
Generally, the integrated \QD contains the same functions as the standalone
87
\QD. For more information about the differences, see the
88
\l{http://doc.qt.io/qtcreator/index.html}{Qt Creator Manual}.
89
90
If you have large forms that do not fit in the Qt Creator \gui Design mode,
91
you can open them in the stand-alone \QD.
92
93
\section1 The User Interface
94
95
When used as a standalone application, \QD's user interface can be
96
configured to provide either a multi-window user interface (the default
97
mode), or it can be used in docked window mode. When used from within an
98
integrated development environment (IDE) only the multi-window user
99
interface is available. You can switch modes in the \gui Preferences dialog
100
from the \gui Edit menu.
101
102
In multi-window mode, you can arrange each of the tool windows to suit your
103
working style. The main window consists of a menu bar, a tool bar, and a
104
widget box that contains the widgets you can use to create your user
105
interface.
106
107
\target MainWindow
108
\table
109
\row
110
\li \inlineimage designer-main-window.png
111
\li \b{Qt Widgets Designer's Main Window}
112
113
The menu bar provides all the standard actions for managing forms,
114
using the clipboard, and accessing application-specific help.
115
The current editing mode, the tool windows, and the forms in use can
116
also be accessed via the menu bar.
117
118
The tool bar displays common actions that are used when editing a form.
119
These are also available via the main menu.
120
121
The widget box provides common widgets and layouts that are used to
122
design components. These are grouped into categories that reflect their
123
uses or features.
124
\endtable
125
126
Most features of \QD are accessible via the menu bar, the tool bar, or the
127
widget box. Some features are also available through context menus that can
128
be opened over the form windows. On most platforms, the right mouse is used
129
to open context menus.
130
131
\target WidgetBox
132
\table
133
\row
134
\li \inlineimage designer-widget-box.png
135
\li \b{Qt Widgets Designer's Widget Box}
136
137
The widget box provides a selection of standard Qt widgets, layouts,
138
and other objects that can be used to create user interfaces on forms.
139
Each of the categories in the widget box contain widgets with similar
140
uses or related features.
141
142
You can display all of the available objects in a category by clicking
143
on the handle next to the category label. When in
144
\l{Qt Widgets Designer's Widget Editing Mode}{Widget Editing
145
Mode}, you can add objects to a form by dragging the appropriate items
146
from the widget box onto the form, and dropping them in the required
147
locations.
148
149
\QD provides a scratch pad feature that allows you to collect
150
frequently used objects in a separate category. The scratch pad
151
category can be filled with any widget currently displayed in a form
152
by dragging them from the form and dropping them onto the widget box.
153
These widgets can be used in the same way as any other widgets, but
154
they can also contain child widgets. Open a context menu over a widget
155
to change its name or remove it from the scratch pad.
156
\endtable
157
158
159
\section1 The Concept of Layouts in Qt
160
161
A layout is used to arrange and manage the elements that make up a user
162
interface. Qt provides a number of classes to automatically handle layouts
163
-- QHBoxLayout, QVBoxLayout, QGridLayout, and QFormLayout. These classes
164
solve the challenge of laying out widgets automatically, providing a user
165
interface that behaves predictably. Fortunately knowledge of the layout
166
classes is not required to arrange widgets with \QD. Instead, select one of
167
the \gui{Lay Out Horizontally}, \gui{Lay Out in a Grid}, etc., options from
168
the context menu.
169
170
Each Qt widget has a recommended size, known as \l{QWidget::}{sizeHint()}.
171
The layout manager will attempt to resize a widget to meet its size hint.
172
In some cases, there is no need to have a different size. For example, the
173
height of a QLineEdit is always a fixed value, depending on font size and
174
style. In other cases, you may require the size to change, e.g., the width
175
of a QLineEdit or the width and height of item view widgets. This is where
176
the widget size constraints -- \l{QWidget::minimumSize()}{minimumSize} and
177
\l{QWidget::maximumSize()}{maximumSize} constraints come into play. These
178
are properties you can set in the property editor. For example, to override
179
the default \l{QWidget::}{sizeHint()}, simply set
180
\l{QWidget::minimumSize()}{minimumSize} and \l{QWidget::maximumSize()}
181
{maximumSize} to the same value. Alternatively, to use the current size as
182
a size constraint value, choose one of the \gui{Size Constraint} options
183
from the widget's context menu. The layout will then ensure that those
184
constraints are met. To control the size of your widgets via code, you can
185
reimplement \l{QWidget::}{sizeHint()} in your code.
186
187
The screenshot below shows the breakdown of a basic user interface designed
188
using a grid. The coordinates on the screenshot show the position of each
189
widget within the grid.
190
191
\image addressbook-tutorial-part3-labeled-layout.png
192
193
\note Inside the grid, the QPushButton objects are actually nested. The
194
buttons on the right are first placed in a QVBoxLayout; the buttons at the
195
bottom are first placed in a QHBoxLayout. Finally, they are put into
196
coordinates (1,2) and (2,1) of the QGridLayout.
197
198
To visualize, imagine the layout as a box that shrinks as much as possible,
199
attempting to \e squeeze your widgets in a neat arrangement, and, at the
200
same time, maximize the use of available space.
201
202
Qt's layouts help when you:
203
204
\list 1
205
\li Resize the user face to fit different window sizes.
206
\li Resize elements within the user interface to suit different
207
localizations.
208
\li Arrange elements to adhere to layout guidelines for different
209
platforms.
210
\endlist
211
212
So, you no longer have to worry about rearranging widgets for different
213
platforms, settings, and languages.
214
215
The example below shows how different localizations can affect the user
216
interface. When a localization requires more space for longer text strings
217
the Qt layout automatically scales to accommodate this, while ensuring that
218
the user interface looks presentable and still matches the platform
219
guidelines.
220
221
\table
222
\header
223
\li A Dialog in English
224
\li A Dialog in French
225
\row
226
\li \image designer-english-dialog.png
227
\li \image designer-french-dialog.png
228
\endtable
229
230
The process of laying out widgets consists of creating the layout hierarchy
231
while setting as few widget size constraints as possible.
232
233
For a more technical perspective on Qt's layout classes, refer to the
234
\l{Layout Management} documentation.
235
*/
236
237
238
/*!
239
\page designer-quick-start.html
240
241
242
\title A Quick Start to Qt Widgets Designer
243
244
Using \QD involves \b four basic steps:
245
246
\list 1
247
\li Choose your form and objects
248
\li Lay the objects out on the form
249
\li Connect the signals to the slots
250
\li Preview the form
251
\endlist
252
253
\image rgbController-screenshot.png
254
255
Suppose you would like to design a small widget (see screenshot above) that
256
contains the controls needed to manipulate Red, Green and Blue (RGB) values
257
-- a type of widget that can be seen everywhere in image manipulation
258
programs.
259
260
\table
261
\row
262
\li \inlineimage designer-choosing-form.png
263
\li \b{Choosing a Form}
264
265
You start by choosing \gui Widget from the \gui{New Form} dialog.
266
\endtable
267
268
269
\table
270
\row
271
\li \inlineimage rgbController-arrangement.png
272
\li \b{Placing Widgets on a Form}
273
274
Drag three labels, three spin boxes and three vertical sliders on to your
275
form. To change the label's default text, simply double-click on it. You
276
can arrange them according to how you would like them to be laid out.
277
\endtable
278
279
To ensure that they are laid out exactly like this in your program, you
280
need to place these widgets into a layout. We will do this in groups of
281
three. Select the "RED" label. Then, hold down \key Ctrl while you select
282
its corresponding spin box and slider. In the \gui{Form} menu, select
283
\gui{Lay Out in a Grid}.
284
285
\table
286
\row
287
\li \inlineimage rgbController-form-gridLayout.png
288
\li \inlineimage rgbController-selectForLayout.png
289
\endtable
290
291
292
Repeat the step for the other two labels along with their corresponding
293
spin boxes and sliders as well.
294
295
The next step is to combine all three layouts into one \b{main layout}.
296
The main layout is the top level widget's (in this case, the QWidget)
297
layout. It is important that your top level widget has a layout; otherwise,
298
the widgets on your window will not resize when your window is resized. To
299
set the layout, \gui{Right click} anywhere on your form, outside of the
300
three separate layouts, and select \gui{Lay Out Horizontally}.
301
Alternatively, you could also select \gui{Lay Out in a Grid} -- you will
302
still see the same arrangement (shown below).
303
304
\image rgbController-final-layout.png
305
306
\note Main layouts cannot be seen on the form. To check if you have a main
307
layout installed, try resizing your form; your widgets should resize
308
accordingly. Alternatively, you can take a look at \QD's
309
\gui{Object Inspector}. If your top level widget does not have a layout,
310
you will see the broken layout icon next to it,
311
\inlineimage rgbController-no-toplevel-layout.png
312
.
313
314
When you click on the slider and drag it to a certain value, you want the
315
spin box to display the slider's position. To accomplish this behavior, you
316
need to connect the slider's \l{QAbstractSlider::}{valueChanged()} signal
317
to the spin box's \l{QSpinBox::}{setValue()} slot. You also need to make
318
the reverse connections, e.g., connect the spin box's \l{QSpinBox::}
319
{valueChanged()} signal to the slider's \l{QAbstractSlider::value()}
320
{setValue()} slot.
321
322
To do this, you have to switch to \gui{Edit Signals/Slots} mode, either by
323
pressing \key{F4} or selecting \gui{Edit Signals/Slots} from the \gui{Edit}
324
menu.
325
326
\table
327
\row
328
\li \inlineimage rgbController-signalsAndSlots.png
329
\li \b{Connecting Signals to Slots}
330
331
Click on the slider and drag the cursor towards the spin box. The
332
\gui{Configure Connection} dialog, shown below, will pop up. Select the
333
correct signal and slot and click \gui OK.
334
\endtable
335
336
\image rgbController-configure-connection1.png
337
338
Repeat the step (in reverse order), clicking on the spin box and dragging
339
the cursor towards the slider, to connect the spin box's
340
\l{QSpinBox::}{valueChanged()} signal to the slider's
341
\l{QAbstractSlider::value()}{setValue()} slot.
342
343
You can use the screenshot below as a guide to selecting the correct signal
344
and slot.
345
346
\image rgbController-configure-connection2.png
347
348
Now that you have successfully connected the objects for the "RED"
349
component of the RGB Controller, do the same for the "GREEN" and "BLUE"
350
components as well.
351
352
Since RGB values range between 0 and 255, we need to limit the spin box
353
and slider to that particular range.
354
355
\table
356
\row
357
\li \inlineimage rgbController-property-editing.png
358
\li \b{Setting Widget Properties}
359
360
Click on the first spin box. Within the \gui{Property Editor}, you will
361
see \l{QSpinBox}'s properties. Enter "255" for the
362
\l{QSpinBox::}{maximum} property. Then, click on the first vertical
363
slider, you will see \l{QAbstractSlider}'s properties. Enter "255" for
364
the \l{QAbstractSlider::}{maximum} property as well. Repeat this
365
process for the remaining spin boxes and sliders.
366
\endtable
367
368
Now, we preview your form to see how it would look in your application -
369
press \key{Ctrl + R} or select \gui Preview from the \gui Form menu. Try
370
dragging the slider - the spin box will mirror its value too (and vice
371
versa). Also, you can resize it to see how the layouts that are used to
372
manage the child widgets, respond to different window sizes.
373
*/
374
375
376
/*!
377
\page designer-editing-mode.html
378
\previouspage Getting to Know Qt Widgets Designer
379
\nextpage Using Layouts in Qt Widgets Designer
380
381
\title Qt Widgets Designer's Editing Modes
382
383
\QD provides four editing modes: \l{Qt Widgets Designer's Widget Editing Mode}
384
{Widget Editing Mode}, \l{Qt Widgets Designer's Signals and Slots Editing Mode}
385
{Signals and Slots Editing Mode}, \l{Qt Widgets Designer's Buddy Editing Mode}
386
{Buddy Editing Mode} and \l{Qt Widgets Designer's Tab Order Editing Mode}
387
{Tab Order Editing Mode}. When working with \QD, you will always be in one
388
of these four modes. To switch between modes, simply select it from the
389
\gui{Edit} menu or the toolbar. The table below describes these modes in
390
further detail.
391
392
\table
393
\header \li \li \b{Editing Modes}
394
\row
395
\li \inlineimage designer-widget-tool.png
396
\li In \l{Qt Widgets Designer's Widget Editing Mode}{Edit} mode, we can
397
change the appearance of the form, add layouts, and edit the
398
properties of each widget. To switch to this mode, press
399
\key{F3}. This is \QD's default mode.
400
401
\row
402
\li \inlineimage designer-connection-tool.png
403
\li In \l{Qt Widgets Designer's Signals and Slots Editing Mode}
404
{Signals and Slots} mode, we can connect widgets together using
405
Qt's signals and slots mechanism. To switch to this mode, press
406
\key{F4}.
407
408
\row
409
\li \inlineimage designer-buddy-tool.png
410
\li In \l{Qt Widgets Designer's Buddy Editing Mode}{Buddy Editing Mode},
411
buddy widgets can be assigned to label widgets to help them
412
handle keyboard focus correctly.
413
414
\row
415
\li \inlineimage designer-tab-order-tool.png
416
\li In \l{Qt Widgets Designer's Tab Order Editing Mode}
417
{Tab Order Editing Mode}, we can set the order in which widgets
418
receive the keyboard focus.
419
\endtable
420
421
*/
422
423
424
/*!
425
\page designer-widget-mode.html
426
\previouspage Qt Widgets Designer's Editing Modes
427
\nextpage Qt Widgets Designer's Signals and Slots Editing Mode
428
429
\title Qt Widgets Designer's Widget Editing Mode
430
431
\image designer-editing-mode.png
432
433
In the Widget Editing Mode, objects can be dragged from the main window's
434
widget box to a form, edited, resized, dragged around on the form, and even
435
dragged between forms. Object properties can be modified interactively, so
436
that changes can be seen immediately. The editing interface is intuitive
437
for simple operations, yet it still supports Qt's powerful layout
438
facilities.
439
440
441
To create and edit new forms, open the \gui File menu and select
442
\gui{New Form...} or press \key{Ctrl+N}. Existing forms can also be edited
443
by selecting \gui{Open Form...} from the \gui File menu or pressing
444
\key{Ctrl+O}.
445
446
At any point, you can save your form by selecting the \gui{Save From As...}
447
option from the \gui File menu. The UI files saved by \QD contain
448
information about the objects used, and any details of signal and slot
449
connections between them.
450
451
452
\section1 Editing A Form
453
454
By default, new forms are opened in widget editing mode. To switch to Edit
455
mode from another mode, select \gui{Edit Widgets} from the \gui Edit menu
456
or press the \key F3 key.
457
458
Objects are added to the form by dragging them from the main widget box
459
and dropping them in the desired location on the form. Once there, they
460
can be moved around simply by dragging them, or using the cursor keys.
461
Pressing the \key Ctrl key at the same time moves the selected widget
462
pixel by pixel, while using the cursor keys alone make the selected widget
463
snap to the grid when it is moved. Objects can be selected by clicking on
464
them with the left mouse button. You can also use the \key Tab key to
465
change the selection.
466
467
The widget box contains objects in a number of different categories, all of
468
which can be placed on the form as required. The only objects that require
469
a little more preparation are the \gui Container widgets. These are
470
described in further detail in the \l{Using Containers in Qt Widgets Designer}
471
chapter.
472
473
474
\target SelectingObjects
475
\table
476
\row
477
\li \inlineimage designer-selecting-widget.png
478
\li \b{Selecting Objects}
479
480
Objects on the form are selected by clicking on them with the left
481
mouse button. When an object is selected, resize handles are shown at
482
each corner and the midpoint of each side, indicating that it can be
483
resized.
484
485
To select additional objects, hold down the \key Control key and click on
486
them. If more than one object is selected, the current object will be
487
displayed with resize handles of a different color.
488
489
To move a widget within a layout, hold down \key Shift and \key Control
490
while dragging the widget. This extends the selection to the widget's
491
parent layout.
492
493
Alternatively, objects can be selected in the
494
\l{The Object Inspector}{Object Inspector}.
495
\endtable
496
497
When a widget is selected, normal clipboard operations such as cut, copy,
498
and paste can be performed on it. All of these operations can be done and
499
undone, as necessary.
500
501
The following shortcuts can be used:
502
503
\target ShortcutsForEditing
504
\table
505
\header \li Action \li Shortcut \li Description
506
\row
507
\li Cut
508
\li \key{Ctrl+X}
509
\li Cuts the selected objects to the clipboard.
510
\row
511
\li Copy
512
\li \key{Ctrl+C}
513
\li Copies the selected objects to the clipboard.
514
\row
515
\li Paste
516
\li \key{Ctrl+V}
517
\li Pastes the objects in the clipboard onto the form.
518
\row
519
\li Delete
520
\li \key Delete
521
\li Deletes the selected objects.
522
\row
523
\li Clone object
524
\li \key{Ctrl+drag} (leftmouse button)
525
\li Makes a copy of the selected object or group of objects.
526
\row
527
\li Preview
528
\li \key{Ctrl+R}
529
\li Shows a preview of the form.
530
\endtable
531
532
All of the above actions (apart from cloning) can be accessed via both the
533
\gui Edit menu and the form's context menu. These menus also provide
534
funcitons for laying out objects as well as a \gui{Select All} function to
535
select all the objects on the form.
536
537
Widgets are not unique objects; you can make as many copies of them as you
538
need. To quickly duplicate a widget, you can clone it by holding down the
539
\key Ctrl key and dragging it. This allows widgets to be copied and placed
540
on the form more quickly than with clipboard operations.
541
542
543
\target DragAndDrop
544
\table
545
\row
546
\li \inlineimage designer-dragging-onto-form.png
547
\li \b{Drag and Drop}
548
549
\QD makes extensive use of the drag and drop facilities provided by Qt.
550
Widgets can be dragged from the widget box and dropped onto the form.
551
552
Widgets can also be "cloned" on the form: Holding down \key Ctrl and
553
dragging the widget creates a copy of the widget that can be dragged to
554
a new position.
555
556
It is also possible to drop Widgets onto the \l {The Object Inspector}
557
{Object Inspector} to handle nested layouts easily.
558
\endtable
559
560
\QD allows selections of objects to be copied, pasted, and dragged between
561
forms. You can use this feature to create more than one copy of the same
562
form, and experiment with different layouts in each of them.
563
564
565
\section2 The Property Editor
566
567
The Property Editor always displays properties of the currently selected
568
object on the form. The available properties depend on the object being
569
edited, but all of the widgets provided have common properties such as
570
\l{QObject::}{objectName}, the object's internal name, and
571
\l{QWidget::}{enabled}, the property that determines whether an
572
object can be interacted with or not.
573
574
575
\target EditingProperties
576
\table
577
\row
578
\li \inlineimage designer-property-editor.png
579
\li \b{Editing Properties}
580
581
The property editor uses standard Qt input widgets to manage the
582
properties of objects on the form. Textual properties are shown in line
583
edits, integer properties are displayed in spinboxes, boolean
584
properties are displayed in check boxes, and compound properties such
585
as colors and sizes are presented in drop-down lists of input widgets.
586
587
Modified properties are indicated with bold labels. To reset them, click
588
the arrow button on the right.
589
590
Changes in properties are applied to all selected objects that have the
591
same property.
592
\endtable
593
594
Certain properties are treated specially by the property editor:
595
596
\list
597
\li Compound properties -- properties that are made up of more than one
598
value -- are represented as nodes that can be expanded, allowing
599
their values to be edited.
600
\li Properties that contain a choice or selection of flags are edited
601
via combo boxes with checkable items.
602
\li Properties that allow access to rich data types, such as QPalette,
603
are modified using dialogs that open when the properties are edited.
604
QLabel and the widgets in the \gui Buttons section of the widget box
605
have a \c text property that can also be edited by double-clicking
606
on the widget or by pressing \gui F2. \QD interprets the backslash
607
(\\) character specially, enabling newline (\\n) characters to be
608
inserted into the text; the \\\\ character sequence is used to
609
insert a single backslash into the text. A context menu can also be
610
opened while editing, providing another way to insert special
611
characters and newlines into the text.
612
\endlist
613
614
615
\section2 Dynamic Properties
616
617
The property editor can also be used to add new
618
\l{QObject#Dynamic Properties}{dynamic properties} to both standard Qt
619
widgets and to forms themselves. Since Qt 4.4, dynamic properties are added
620
and removed via the property editor's toolbar, shown below.
621
622
\image designer-property-editor-toolbar.png
623
624
To add a dynamic property, click on the \gui Add button
625
\inlineimage designer-property-editor-add-dynamic.png
626
. To remove it, click on the \gui Remove button
627
\inlineimage designer-property-editor-remove-dynamic.png
628
instead. You can also sort the properties alphabetically and change the
629
color groups by clickinig on the \gui Configure button
630
\inlineimage designer-property-editor-configure.png
631
.
632
633
\section2 The Object Inspector
634
\table
635
\row
636
\li \inlineimage designer-object-inspector.png
637
\li \b{The Object Inspector}
638
639
The \gui{Object Inspector} displays a hierarchical list of all the
640
objects on the form that is currently being edited. To show the child
641
objects of a container widget or a layout, click the handle next to the
642
object label.
643
644
Each object on a form can be selected by clicking on the corresponding
645
item in the \gui{Object Inspector}. Right-clicking opens the form's
646
context menu. These features can be useful if you have many overlapping
647
objects. To locate an object in the \gui{Object Inspector}, use
648
\key{Ctrl+F}.
649
650
Since Qt 4.4, double-clicking on the object's name allows you to change
651
the object's name with the in-place editor.
652
653
Since Qt 4.5, the \gui{Object Inspector} displays the layout state of
654
the containers. The broken layout icon ###ICON is displayed if there is
655
something wrong with the layouts.
656
657
\endtable
658
*/
659
660
661
/*!
662
\page designer-layouts.html
663
\previouspage Qt Widgets Designer's Widget Editing Mode
664
\nextpage Qt Widgets Designer's Signals and Slots Editing Mode
665
666
\title Using Layouts in Qt Widgets Designer
667
668
Before a form can be used, the objects on the form need to be placed into
669
layouts. This ensures that the objects will be displayed properly when the
670
form is previewed or used in an application. Placing objects in a layout
671
also ensures that they will be resized correctly when the form is resized.
672
673
Once widgets have been inserted into a layout, it is not possible to move
674
and resize them individually because the layout itself controls the
675
geometry of each widget within it, taking account of the hints provided by
676
spacers. Spacers can be added to the layout to influence the geometries of
677
the widgets.
678
679
Layouts can be nested to form a hierarchy. For example, to achieve a
680
typical dialog layout with a horizontal row of buttons, the dialog
681
elements can be laid out using a vertical box layout with a horizontal
682
box layout containing the buttons at the bottom. For an introduction to
683
the Qt layout system, refer to \l{Layout Management}.
684
685
To break a layout, press \key{Ctrl+0} or choose \gui{Break Layout} from
686
the form's context menu, the \gui Form menu or the main toolbar.
687
688
\section1 Setting A Top Level Layout
689
690
The form's top level layout can be set by clearing the selection (click the
691
left mouse button on the form itself) and applying a layout. A top level
692
layout is necessary to ensure that your widgets will resize correctly when
693
its window is resized. To check if you have set a top level layout, preview
694
your widget and attempt to resize the window by dragging the size grip.
695
696
\table
697
\row
698
\li \inlineimage designer-set-layout.png
699
\li \b{Applying a Layout}
700
701
To apply a layout, you can select your choice of layout from the
702
toolbar shown on the left, or from the context menu shown below.
703
\endtable
704
705
Similary, top level layouts are set on container widgets (QGroupBox)
706
or on pages of page-based container widgets (QTabWidget, QToolBox
707
and QStackedWidget), respectively. The container widget needs to be
708
selected for this to succeed.
709
710
Top level layouts are not visible as separate objects in the Object
711
Inspector. Their properties appear below the widget properties of the
712
main form, container widget, or page of a container widget in the
713
Property Editor.
714
715
\image designer-set-layout2.png
716
717
718
\section1 Layout Objects
719
720
Layout objects are created by applying a layout to a group of
721
existing objects. This is achieved by selecting the objects that you need
722
to manage and applying one of the standard layouts using the main toolbar,
723
the \gui Form menu, or the form's context menu.
724
725
The layout object is indicated by a red frame on the form and appears as
726
an object in the Object Inspector. Its properties (margins and constraints)
727
are shown in the Property Editor.
728
729
The layout object can be selected and placed within another layout along
730
with other widgets and layout objects to build a layout hierarchy.
731
732
When a child layout object is selected, its parent layout object can be
733
selected by pressing down the \key Shift key while clicking on it. This
734
makes it possible to select a specific layout in a hierarchy, which is
735
otherwise difficult due to the small frame.
736
737
738
\section1 Inserting Objects Into a Layout
739
\target InsertingObjectsIntoALayout
740
741
Objects can be inserted into an existing layout by dragging them from
742
their current positions and dropping them at the required location. A
743
blue cursor is displayed in the layout as an object is dragged over
744
it to indicate where the object will be added.
745
746
\image designer-layout-inserting.png
747
\caption Inserting Objects into a Layout
748
749
\section1 Layout Types
750
\section2 Horizontal and Vertical (Box) Layouts
751
752
The simplest way to arrange objects on a form is to place them in a
753
horizontal or vertical layout. Horizontal layouts ensure that the widgets
754
within are aligned horizontally; vertical layouts ensure that they are
755
aligned vertically.
756
757
Horizontal and vertical layouts can be combined and nested to any depth.
758
However, if you need more control over the placement of objects, consider
759
using the grid layout.
760
761
762
\section2 The Grid Layout
763
764
Complex form layouts can be created by placing objects in a grid layout.
765
This kind of layout gives the form designer much more freedom to arrange
766
widgets on the form, but can result in a much less flexible layout.
767
However, for some kinds of form layout, a grid arrangement is much more
768
suitable than a nested arrangement of horizontal and vertical layouts.
769
770
771
\section2 The Form Layout
772
773
The QFormLayout
774
class manages widgets in a two-column form; the left column holds labels
775
and the right column holds field widgets such as line edits, spin boxes,
776
etc. The QFormLayout class adheres to various platform look and feel
777
guidelines and supports wrapping for long rows.
778
779
\image designer-form-layout.png
780
781
The UI file above results in the previews shown below.
782
783
\table
784
\header
785
\li Windows XP
786
\li \macos
787
\li Cleanlooks
788
\row
789
\li \inlineimage designer-form-layout-windowsXP.png
790
\li \inlineimage designer-form-layout-macintosh.png
791
\li \inlineimage designer-form-layout-cleanlooks.png
792
\endtable
793
794
795
\section2 Splitter Layouts
796
797
Another common way to manage the layout of objects on a form is to place
798
them in a splitter. These splitters arrange the objects horizontally or
799
vertically in the same way as normal layouts, but also allow the user to
800
adjust the amount of space allocated to each object.
801
802
\image designer-splitter-layout.png
803
804
Although QSplitter is a container widget, \QD treats splitter objects as
805
layouts that are applied to existing widgets. To place a group of widgets
806
into a splitter, select them
807
\l{Qt Widgets Designer's Widget Editing Mode#SelectingObjects}{as described here}
808
then apply the splitter layout by using the appropriate toolbar button,
809
keyboard shortcut, or \gui{Lay out} context menu entry.
810
811
812
\section1 Shortcut Keys
813
814
In addition to the standard toolbar and context menu entries, there is also
815
a set of keyboard shortcuts to apply layouts on widgets.
816
817
\target LayoutShortcuts
818
\table
819
\header
820
\li Layout
821
\li Shortcut
822
\li Description
823
\row
824
\li Horizontal
825
\li \key{Ctrl+1}
826
\li Places the selected objects in a horizontal layout.
827
\row
828
\li Vertical
829
\li \key{Ctrl+2}
830
\li Places the selected objects in a vertical layout.
831
\row
832
\li Grid
833
\li \key{Ctrl+5}
834
\li Places the selected objects in a grid layout.
835
\row
836
\li Form
837
\li \key{Ctrl+6}
838
\li Places the selected objects in a form layout.
839
\row
840
\li Horizontal splitter
841
\li \key{Ctrl+3}
842
\li Creates a horizontal splitter and places the selected objects
843
inside it.
844
\row
845
\li Vertical splitter
846
\li \key{Ctrl+4}
847
\li Creates a vertical splitter and places the selected objects
848
inside it.
849
\row
850
\li Adjust size
851
\li \key{Ctrl+J}
852
\li Adjusts the size of the layout to ensure that each child object
853
has sufficient space to display its contents. See
854
QWidget::adjustSize() for more information.
855
\endtable
856
857
\note \key{Ctrl+0} is used to break a layout.
858
859
*/
860
861
862
/*!
863
\page designer-preview.html
864
\previouspage Using Layouts in Qt Widgets Designer
865
\nextpage Qt Widgets Designer's Buddy Editing Mode
866
\title Saving, Previewing and Printing Forms in Qt Widgets Designer
867
868
Although \QD's forms are accurate representations of the components being
869
edited, it is useful to preview the final appearance while editing. This
870
feature can be activated by opening the \gui Form menu and selecting
871
\gui Preview, or by pressing \key{Ctrl+R} when in the form.
872
873
\image designer-dialog-preview.png
874
875
The preview shows exactly what the final component will look like when used
876
in an application.
877
878
Since Qt 4.4, it is possible to preview forms with various skins - default
879
skins, skins created with Qt Style Sheets or device skins. This feature
880
simulates the effect of calling \c{QApplication::setStyleSheet()} in the
881
application.
882
883
To preview your form with skins, open the \gui Edit menu and select
884
\gui{Preferences...}
885
886
You will see the dialog shown below:
887
888
\image designer-preview-style.png
889
890
The \gui{Print/Preview Configuration} checkbox must be checked to activate
891
previews of skins. You can select the styles provided from the \gui{Style}
892
drop-down box.
893
894
\image designer-preview-style-selection.png
895
896
Alternatively, you can preview custom style sheet created with Qt Style
897
Sheets. The figure below shows an example of Qt Style Sheet syntax and the
898
corresponding output.
899
900
\image designer-preview-stylesheet.png
901
902
Another option would be to preview your form with device skins. A list of
903
generic device skins are available in \QD, however, you may also use
904
other QVFB skins with the \gui{Browse...} option.
905
906
\image designer-preview-deviceskin-selection.png
907
908
909
\section1 Viewing the Form's Code
910
911
Since Qt 4.4, it is possible to view code generated by the User Interface
912
Compiler (uic) for the \QD form.
913
914
\image designer-form-viewcode.png
915
916
Select \gui{View Code...} from the \gui{Form} menu and a dialog with the
917
generated code will be displayed. The screenshot below is an example of
918
code generated by the \c{uic}.
919
920
\image designer-code-viewer.png
921
922
\section1 Saving and Printing the Form
923
924
Forms created in \QD can be saved to an image or printed.
925
926
\table
927
\row
928
\li \inlineimage designer-file-menu.png
929
\li \b{Saving Forms}
930
931
To save a form as an image, choose the \gui{Save Image...} option. The file
932
will be saved in \c{.png} format.
933
934
\b{Printing Forms}
935
936
To print a form, select the \gui{Print...} option.
937
938
\endtable
939
*/
940
941
942
/*!
943
\page designer-connection-mode.html
944
\previouspage Using Layouts in Qt Widgets Designer
945
\nextpage Qt Widgets Designer's Buddy Editing Mode
946
947
948
\title Qt Widgets Designer's Signals and Slots Editing Mode
949
950
\image designer-connection-mode.png
951
952
In \QD's signals and slots editing mode, you can connect objects in a form
953
together using Qt's signals and slots mechanism. Both widgets and layouts
954
can be connected via an intuitive connection interface, using the menu of
955
compatible signals and slots provided by \QD. When a form is saved, all
956
connections are preserved so that they will be ready for use when your
957
project is built.
958
959
960
For more information on Qt's signals and sltos mechanism, refer to the
961
\l{Signals and Slots} document.
962
963
964
\section1 Connecting Objects
965
966
To begin connecting objects, enter the signals and slots editing mode by
967
opening the \gui Edit menu and selecting \gui{Edit Signals/Slots}, or by
968
pressing the \key F4 key.
969
970
All widgets and layouts on the form can be connected together. However,
971
spacers just provide spacing hints to layouts, so they cannot be connected
972
to other objects.
973
974
975
\target HighlightedObjects
976
\table
977
\row
978
\li \inlineimage designer-connection-highlight.png
979
\li \b{Highlighted Objects}
980
981
When the cursor is over an object that can be used in a connection, the
982
object will be highlighted.
983
\endtable
984
985
To make a connectionn, press the left mouse button and drag the cursor
986
towards the object you want to connect it to. As you do this, a line will
987
extend from the source object to the cursor. If the cursor is over another
988
object on the form, the line will end with an arrow head that points to the
989
destination object. This indicates that a connection will be made between
990
the two objects when you release the mouse button.
991
992
You can abandon the connection at any point while you are dragging the
993
connection path by pressing \key{Esc}.
994
995
\target MakingAConnection
996
\table
997
\row
998
\li \inlineimage designer-connection-making.png
999
\li \b{Making a Connection}
1000
1001
The connection path will change its shape as the cursor moves around
1002
the form. As it passes over objects, they are highlighted, indicating
1003
that they can be used in a signal and slot connection. Release the
1004
mouse button to make the connection.
1005
\endtable
1006
1007
The \gui{Configure Connection} dialog (below) is displayed, showing signals
1008
from the source object and slots from the destination object that you can
1009
use.
1010
1011
\image designer-connection-dialog.png
1012
1013
To complete the connection, select a signal from the source object and a
1014
slot from the destination object, then click \key OK. Click \key Cancel if
1015
you wish to abandon the connection.
1016
1017
\note If the \gui{Show all signals and slots} checkbox is selected, all
1018
available signals from the source object will be shown. Otherwise, the
1019
signals and slots inherited from QWidget will be hidden.
1020
1021
You can make as many connections as you like between objects on the form;
1022
it is possible to connect signals from objects to slots in the form itself.
1023
As a result, the signal and slot connections in many dialogs can be
1024
completely configured from within \QD.
1025
1026
\target ConnectingToTheForm
1027
\table
1028
\row
1029
\li \inlineimage designer-connection-to-form.png
1030
\li \b{Connecting to a Form}
1031
1032
To connect an object to the form itself, simply position the cursor
1033
over the form and release the mouse button. The end point of the
1034
connection changes to the electrical "ground" symbol.
1035
\endtable
1036
1037
1038
\section1 Editing and Deleting Connections
1039
1040
By default, connection paths are created with two labels that show the
1041
signal and slot involved in the connection. These labels are usually
1042
oriented along the line of the connection. You can move them around inside
1043
their host widgets by dragging the red square at each end of the connection
1044
path.
1045
1046
\target ConnectionEditor
1047
\table
1048
\row
1049
\li \inlineimage designer-connection-editor.png
1050
\li \b{The Signal/Slot Editor}
1051
1052
The signal and slot used in a connection can be changed after it has
1053
been set up. When a connection is configured, it becomes visible in
1054
\QD's signal and slot editor where it can be further edited. You can
1055
also edit signal/slot connections by double-clicking on the connection
1056
path or one of its labels to display the Connection Dialog.
1057
\endtable
1058
1059
\target DeletingConnections
1060
\table
1061
\row
1062
\li \inlineimage designer-connection-editing.png
1063
\li \b{Deleting Connections}
1064
1065
The whole connection can be selected by clicking on any of its path
1066
segments. Once selected, a connection can be deleted with the
1067
\key Delete key, ensuring that it will not be set up in the UI
1068
file.
1069
\endtable
1070
*/
1071
1072
1073
/*!
1074
\page designer-buddy-mode.html
1075
\previouspage Qt Widgets Designer's Signals and Slots Editing Mode
1076
\nextpage Qt Widgets Designer's Tab Order Editing Mode
1077
1078
\title Qt Widgets Designer's Buddy Editing Mode
1079
1080
\image designer-buddy-mode.png
1081
1082
One of the most useful basic features of Qt is the support for buddy
1083
widgets. A buddy widget accepts the input focus on behalf of a QLabel when
1084
the user types the label's shortcut key combination. The buddy concept is
1085
also used in Qt's \l{Model/View Programming}{model/view} framework.
1086
1087
1088
\section1 Linking Labels to Buddy Widgets
1089
1090
To enter buddy editing mode, open the \gui Edit menu and select
1091
\gui{Edit Buddies}. This mode presents the widgets on the form in a similar
1092
way to \l{Qt Widgets Designer's Signals and Slots Editing Mode}{signals and slots
1093
editing mode} but in this mode, connections must start at label widgets.
1094
Ideally, you should connect each label widget that provides a shortcut with
1095
a suitable input widget, such as a QLineEdit.
1096
1097
1098
\target MakingBuddies
1099
\table
1100
\row
1101
\li \inlineimage designer-buddy-making.png
1102
\li \b{Making Buddies}
1103
1104
To define a buddy widget for a label, click on the label, drag the
1105
connection to another widget on the form, and release the mouse button.
1106
The connection shown indicates how input focus is passed to the buddy
1107
widget. You can use the form preview to test the connections between
1108
each label and its buddy.
1109
\endtable
1110
1111
1112
\section1 Removing Buddy Connections
1113
1114
Only one buddy widget can be defined for each label. To change the buddy
1115
used, it is necessary to delete any existing buddy connection before you
1116
create a new one.
1117
1118
Connections between labels and their buddy widgets can be deleted in the
1119
same way as signal-slot connections in signals and slots editing mode:
1120
Select the buddy connection by clicking on it and press the \key Delete
1121
key. This operation does not modify either the label or its buddy in any
1122
way.
1123
*/
1124
1125
1126
/*!
1127
\page designer-tab-order.html
1128
\previouspage Qt Widgets Designer's Buddy Editing Mode
1129
\nextpage Using Containers in Qt Widgets Designer
1130
1131
\title Qt Widgets Designer's Tab Order Editing Mode
1132
1133
\image designer-tab-order-mode.png
1134
1135
Many users expect to be able to navigate between widgets and controls
1136
using only the keyboard. Qt lets the user navigate between input widgets
1137
with the \key Tab and \key{Shift+Tab} keyboard shortcuts. The default
1138
\e{tab order} is based on the order in which widgets are constructed.
1139
Although this order may be sufficient for many users, it is often better
1140
to explicitly specify the tab order to make your application easier to
1141
use.
1142
1143
1144
\section1 Setting the Tab Order
1145
1146
To enter tab order editing mode, open the \gui Edit menu and select
1147
\gui{Edit Tab Order}. In this mode, each input widget in the form is shown
1148
with a number indicating its position in the tab order. So, if the user
1149
gives the first input widget the input focus and then presses the tab key,
1150
the focus will move to the second input widget, and so on.
1151
1152
The tab order is defined by clicking on each of the numbers in the correct
1153
order. The first number you click will change to red, indicating the
1154
currently edited position in the tab order chain. The widget associated
1155
with the number will become the first one in the tab order chain. Clicking
1156
on another widget will make it the second in the tab order, and so on.
1157
1158
Repeat this process until you are satisfied with the tab order in the form
1159
-- you do not need to click every input widget if you see that the
1160
remaining widgets are already in the correct order. Numbers, for which you
1161
already set the order, change to green, while those which are not clicked
1162
yet, remain blue.
1163
1164
If you make a mistake, simply double click outside of any number or choose
1165
\gui{Restart} from the form's context menu to start again. If you have many
1166
widgets on your form and would like to change the tab order in the middle or
1167
at the end of the tab order chain, you can edit it at any position. Press
1168
\key{Ctrl} and click the number from which you want to start.
1169
Alternatively, choose \gui{Start from Here} in the context menu.
1170
1171
*/
1172
1173
1174
/*!
1175
\page designer-using-containers.html
1176
\previouspage Qt Widgets Designer's Tab Order Editing Mode
1177
\nextpage Creating Main Windows in Qt Widgets Designer
1178
1179
1180
\title Using Containers in Qt Widgets Designer
1181
1182
Container widgets provide high level control over groups of objects on a
1183
form. They can be used to perform a variety of functions, such as managing
1184
input widgets, providing paged and tabbed layouts, or just acting as
1185
decorative containers for other objects.
1186
1187
\image designer-widget-morph.png
1188
1189
\QD provides visual feedback to help you place objects inside your
1190
containers. When you drag an object from the widget box (or elsewhere) on
1191
the form, each container will be highlighted when the cursor is positioned
1192
over it. This indicates that you can drop the object inside, making it a
1193
child object of the container. This feedback is important because it is
1194
easy to place objects close to containers without actually placing them
1195
inside. Both widgets and spacers can be used inside containers.
1196
1197
Stacked widgets, tab widgets, and toolboxes are handled specially in \QD.
1198
Normally, when adding pages (tabs, pages, compartments) to these containers
1199
in your own code, you need to supply existing widgets, either as
1200
placeholders or containing child widgets. In \QD, these are automatically
1201
created for you, so you can add child objects to each page straight away.
1202
1203
Each container typically allows its child objects to be arranged in one or
1204
more layouts. The type of layout management provided depends on each
1205
container, although setting the layout is usually just a matter of
1206
selecting the container by clicking it, and applying a layout. The table
1207
below shows a list of available containers.
1208
1209
\table
1210
\row
1211
\li \inlineimage designer-containers-frame.png
1212
\li \b Frames
1213
1214
Frames are used to enclose and group widgets, as well as to provide
1215
decoration. They are used as the foundation for more complex
1216
containers, but they can also be used as placeholders in forms.
1217
1218
The most important properties of frames are \c frameShape,
1219
\c frameShadow, \c lineWidth, and \c midLineWidth. These are described
1220
in more detail in the QFrame class description.
1221
1222
\row
1223
\li \inlineimage designer-containers-groupbox.png
1224
\li \b{Group Boxes}
1225
1226
Group boxes are usually used to group together collections of
1227
checkboxes and radio buttons with similar purposes.
1228
1229
Among the significant properties of group boxes are \c title, \c flat,
1230
\c checkable, and \c checked, as described in the \l QGroupBox
1231
class documentation. Each group box can contain its own layout, and
1232
this is necessary if it contains other widgets. To add a layout to the
1233
group box, click inside it and apply the layout as usual.
1234
1235
\row
1236
\li \inlineimage designer-containers-stackedwidget.png
1237
\li \b{Stacked Widgets}
1238
1239
Stacked widgets are collections of widgets in which only the topmost
1240
layer is visible. Control over the visible layer is usually managed by
1241
another widget, such as combobox, using signals and slots.
1242
1243
\QD shows arrows in the top-right corner of the stack to allow you to
1244
see all the widgets in the stack when designing it. These arrows do not
1245
appear in the preview or in the final component. To navigate between
1246
pages in the stack, select the stacked widget and use the
1247
\gui{Next Page} and \gui{Previous Page} entries from the context menu.
1248
The \gui{Insert Page} and \gui{Delete Page} context menu options allow
1249
you to add and remove pages.
1250
1251
\row
1252
\li \inlineimage designer-containers-tabwidget.png
1253
\li \b{Tab Widgets}
1254
1255
Tab widgets allow the developer to split up the contents of a widget
1256
into different labelled sections, only one of which is displayed at any
1257
given time. By default, the tab widget contains two tabs, and these can
1258
be deleted or renamed as required. You can also add additional tabs.
1259
1260
To delete a tab:
1261
\list
1262
\li Click on its label to make it the current tab.
1263
\li Select the tab widget and open its context menu.
1264
\li Select \gui{Delete Page}.
1265
\endlist
1266
1267
To add a new tab:
1268
\list
1269
\li Select the tab widget and open its context menu.
1270
\li Select \gui{Insert Page}.
1271
\li You can add a page before or after the \e current page. \QD
1272
will create a new widget for that particular tab and insert it
1273
into the tab widget.
1274
\li You can set the title of the current tab by changing the
1275
\c currentTabText property in the \gui{Property Editor}.
1276
\endlist
1277
1278
\row
1279
\li \inlineimage designer-containers-toolbox.png
1280
\li \b{ToolBox Widgets}
1281
1282
Toolbox widgets provide a series of pages or compartments in a toolbox.
1283
They are handled in a way similar to stacked widgets.
1284
1285
To rename a page in a toolbox, make the toolbox your current pange and
1286
change its \c currentItemText property from the \gui{Property Editor}.
1287
1288
To add a new page, select \gui{Insert Page} from the toolbox widget's
1289
context menu. You can add the page before or after the current page.
1290
1291
To delete a page, select \gui{Delete Page} from the toolbox widget's
1292
context menu.
1293
1294
\row
1295
\li \inlineimage designer-containers-dockwidget.png
1296
\li \b{Dock Widgets}
1297
1298
Dock widgets are floating panels, often containing input widgets and
1299
more complex controls, that are either attached to the edges of the
1300
main window in "dock areas", or floated as independent tool windows.
1301
1302
Although dock widgets can be added to any type of form, they are
1303
typically used with forms created from the
1304
\l{Creating Main Windows in Qt Widgets Designer}{main window template}.
1305
1306
\endtable
1307
*/
1308
1309
1310
/*!
1311
\page designer-creating-mainwindows.html
1312
\previouspage Using Containers in Qt Widgets Designer
1313
\nextpage Editing Resources with Qt Widgets Designer
1314
1315
\title Creating Main Windows in Qt Widgets Designer
1316
1317
\QD can be used to create user interfaces for different purposes, and
1318
it provides different kinds of form templates for each user interface. The
1319
main window template is used to create application windows with menu bars,
1320
toolbars, and dock widgets.
1321
1322
\omit
1323
\image designer-mainwindow-example.png
1324
\endomit
1325
1326
Create a new main window by opening the \gui File menu and selecting the
1327
\gui{New Form...} option, or by pressing \key{Ctrl+N}. Then, select the
1328
\gui{Main Window} template. This template provides a main application
1329
window containing a menu bar and a toolbar by default -- these can be
1330
removed if they are not required.
1331
1332
If you remove the menu bar, a new one can be created by selecting the
1333
\gui{Create Menu Bar} option from the context menu, obtained by
1334
right-clicking within the main window form.
1335
1336
An application can have only \b one menu bar, but \b several
1337
toolbars.
1338
1339
1340
\section1 Menus
1341
1342
Menus are added to the menu bar by modifying the \gui{Type Here}
1343
placeholders. One of these is always present for editing purposes, and
1344
will not be displayed in the preview or in the finished window.
1345
1346
Once created, the properties of a menu can be accessed using the
1347
\l{Qt Widgets Designer's Widget Editing Mode#The Property Editor}{Property Editor},
1348
and each menu can be accessed for this purpose via the
1349
\l{Qt Widgets Designer's Widget Editing Mode#The Object Inspector}{The Object Inspector}.
1350
1351
Existing menus can be removed by opening a context menu over the label in
1352
the menu bar, and selecting \gui{Remove Menu 'menu_name'}.
1353
1354
1355
\target CreatingAMenu
1356
\div {class="float-left"}
1357
\inlineimage designer-creating-menu1.png
1358
\inlineimage designer-creating-menu2.png
1359
\br
1360
\inlineimage designer-creating-menu3.png
1361
\inlineimage designer-creating-menu4.png
1362
\enddiv
1363
1364
\section2 Creating a Menu
1365
1366
Double-click the placeholder item to begin editing. The menu text,
1367
displayed using a line edit, can be modified.
1368
1369
Insert the required text for the new menu. Inserting an
1370
ampersand character (&) causes the letter following it to be
1371
used as a mnemonic for the menu.
1372
1373
Press \key Return or \key Enter to accept the new text, or press
1374
\key Escape to reject it. You can undo the editing operation later if
1375
required.
1376
1377
\div {class="clear-both"}
1378
\enddiv
1379
1380
Menus can also be rearranged in the menu bar simply by dragging and
1381
dropping them in the preferred location. A vertical red line indicates the
1382
position where the menu will be inserted.
1383
1384
Menus can contain any number of entries and separators, and can be nested
1385
to the required depth. Adding new entries to menus can be achieved by
1386
navigating the menu structure in the usual way.
1387
1388
\target CreatingAMenuEntry
1389
\div {class="float-right"}
1390
\inlineimage designer-creating-menu-entry1.png
1391
\inlineimage designer-creating-menu-entry2.png
1392
\br
1393
\inlineimage designer-creating-menu-entry3.png
1394
\inlineimage designer-creating-menu-entry4.png
1395
\enddiv
1396
1397
\section2 Creating a Menu Entry
1398
1399
Double-click the \gui{Type Here} placeholder to begin editing, or
1400
double-click \gui{Add Separator} to insert a new separator line after
1401
the last entry in the menu.
1402
1403
The menu entry's text is displayed using a line edit, and can be
1404
modified.
1405
1406
Insert the required text for the new entry, optionally using
1407
the ampersand character (&) to mark the letter to use as a
1408
mnemonic for the entry.
1409
1410
Press \key Return or \key Enter to accept the new text, or press
1411
\key Escape to reject it. The action created for this menu entry will
1412
be accessible via the \l{#TheActionEditor}{Action Editor}, and any
1413
associated keyboard shortcut can be set there.
1414
1415
\div {class="clear-both"}
1416
\enddiv
1417
1418
Just like with menus, entries can be moved around simply by dragging and
1419
dropping them in the preferred location. When an entry is dragged over a
1420
closed menu, the menu will open to allow it to be inserted there. Since
1421
menu entries are based on actions, they can also be dropped onto toolbars,
1422
where they will be displayed as toolbar buttons.
1423
1424
\section1 Toolbars
1425
1426
\div {class="float-left"}
1427
\inlineimage designer-creating-toolbar.png
1428
\enddiv
1429
1430
\section2 Creating and Removing a Toolbar
1431
1432
Toolbars are added to a main window in a similar way to the menu bar:
1433
Select the \gui{Add Tool Bar} option from the form's context menu.
1434
Alternatively, if there is an existing toolbar in the main window, you can
1435
click the arrow on its right end to create a new toolbar.
1436
1437
Toolbars are removed from the form via an entry in the toolbar's context
1438
menu.
1439
1440
\div {class="clear-both"}
1441
\enddiv
1442
1443
\section2 Adding and Removing Toolbar Buttons
1444
1445
Toolbar buttons are created as actions in the
1446
\l{#TheActionEditor}{Action Editor} and dragged onto the toolbar.
1447
Since actions can be represented by menu entries and toolbar buttons,
1448
they can be moved between menus and toolbars.
1449
1450
\div {class="float-right"}
1451
\inlineimage designer-adding-toolbar-action.png
1452
\inlineimage designer-removing-toolbar-action.png
1453
\enddiv
1454
1455
To share an action between a menu and a toolbar, drag its icon from the
1456
action editor to the toolbar rather than from the menu where its entry is
1457
located. See \l{#Adding an Action}{Adding an Action} for more information
1458
about this process.
1459
1460
Toolbar buttons are removed via the toolbar's context menu.
1461
1462
\div {class="clear-both"}
1463
\enddiv
1464
1465
\section1 Actions
1466
1467
With the menu bar and the toolbars in place, it's time to populate them
1468
with actions. New actions for both menus and toolbars are created in the
1469
action editor window, simplifying the creation and management of actions.
1470
1471
\target TheActionEditor
1472
\div {class="float-left"}
1473
\inlineimage designer-action-editor.png
1474
\enddiv
1475
1476
\section2 The Action Editor
1477
1478
Enable the action editor by opening the \gui Tools menu, and switching
1479
on the \gui{Action Editor} option.
1480
1481
The action editor allows you to create \gui New actions and \gui Delete
1482
actions. It also provides a search function, \gui Filter, using the
1483
action's text.
1484
1485
\QD's action editor can be viewed in the classic \gui{Icon View} and
1486
\gui{Detailed View}. The screenshot below shows the action editor in
1487
\gui{Detailed View}. You can also copy and paste actions between menus,
1488
toolbars and forms.
1489
1490
\div {class="clear-both"}
1491
\enddiv
1492
1493
\section2 Creating an Action
1494
1495
To create an action, use the action editor's \gui New button, which will
1496
then pop up an input dialog. Provide the new action with a \gui Text --
1497
this is the text that will appear in a menu entry and as the action's
1498
tooltip. The text is also automatically added to an "action" prefix,
1499
creating the action's \gui{Object Name}.
1500
1501
In addition, the dialog provides the option of selecting an \gui Icon for
1502
the action, as well as removing the current icon.
1503
1504
Once the action is created, it can be used wherever actions are applicable.
1505
1506
\div {class="clear-left"}
1507
\enddiv
1508
1509
\target AddingAnAction
1510
\div {class="float-right"}
1511
\inlineimage designer-adding-menu-action.png
1512
\inlineimage designer-adding-toolbar-action.png
1513
\enddiv
1514
1515
\section2 Adding an Action
1516
1517
To add an action to a menu or a toolbar, simply press the left mouse
1518
button over the action in the action editor, and drag it to the
1519
preferred location.
1520
1521
\QD provides highlighted guide lines that tell you where the action
1522
will be added. Release the mouse button to add the action when you have
1523
found the right spot.
1524
1525
\div {class="clear-right"}
1526
\enddiv
1527
1528
\section1 Dock Widgets
1529
1530
Dock widgets are \l{Using Containers in Qt Widgets Designer}{container widgets}
1531
as well. They can be added to a form by dropping them onto the desired
1532
dock area.
1533
1534
\target AddingADockWidget
1535
1536
\div {class="float-left"}
1537
\inlineimage designer-adding-dockwidget.png
1538
\enddiv
1539
1540
\section2 Adding a Dock Widget
1541
1542
To add a dock widget to a form, drag one from the \gui Containers section
1543
of the widget box, and drop it onto the main form area. Do not add the
1544
dock widget to an existing layout. Instead, open the \gui{Property Editor}
1545
and enable the \gui{docked} property to place it in a dock area.
1546
1547
Note that it is sometimes easier to configure a dock widget if it is added
1548
to a form before a layout is applied to the central widget. For example,
1549
it is possible to undock it and resize it, making it more convenient to
1550
add child widgets.
1551
1552
Dock widgets can be optionally floated as independent tool windows.
1553
Hence, it is useful to give them window titles by setting their
1554
\l{QDockWidget::}{windowTitle} property. This also helps to identify them on the
1555
form.
1556
1557
\div {class="clear-both"}
1558
\enddiv
1559
*/
1560
1561
1562
/*!
1563
\page designer-resources.html
1564
\previouspage Creating Main Windows in Qt Widgets Designer
1565
\nextpage Using Stylesheets with Qt Widgets Designer
1566
1567
\title Editing Resources with Qt Widgets Designer
1568
1569
\image designer-resources-editing.png
1570
1571
\QD fully supports the \l{The Qt Resource System}{Qt Resource System},
1572
enabling resources to be specified together with forms as they are
1573
designed. To aid designers and developers manage resources for their
1574
applications, \QD's resource editor allows resources to be defined on a
1575
per-form basis. In other words, each form can have a separate resource
1576
file.
1577
1578
\section1 Defining a Resource File
1579
1580
To specify a resource file you must enable the resource editor by opening
1581
the \gui Tools menu, and switching on the \gui{Resource Browser} option.
1582
1583
\target ResourceFiles
1584
\table
1585
\row
1586
\li \inlineimage designer-resource-browser.png
1587
\li \b{Resource Files}
1588
1589
Within the resource browser, you can open existing resource files or
1590
create new ones. Click the \gui{Edit Resources} button
1591
\inlineimage designer-edit-resources-button.png
1592
to edit your resources. To reload resources, click on the \gui Reload
1593
button
1594
\inlineimage designer-reload-resources-button.png
1595
.
1596
\endtable
1597
1598
1599
Once a resource file is loaded, you can create or remove entries in it
1600
using the given \gui{Add Files}
1601
\inlineimage designer-add-resource-entry-button.png
1602
and \gui{Remove Files}
1603
\inlineimage designer-remove-resource-entry-button.png
1604
buttons, and specify resources (e.g., images) using the \gui{Add Files}
1605
button
1606
\inlineimage designer-add-files-button.png
1607
. Note that these resources must reside within the current resource file's
1608
directory or one of its subdirectories.
1609
1610
1611
\target EditResource
1612
\table
1613
\row
1614
\li \inlineimage designer-edit-resource.png
1615
\li \b{Editing Resource Files}
1616
1617
Press the
1618
\inlineimage designer-add-resource-entry-button.png
1619
button to add a new resource entry to the file. Then use the
1620
\gui{Add Files} button
1621
\inlineimage designer-add-files-button.png
1622
to specify the resource.
1623
1624
You can remove resources by selecting the corresponding entry in the
1625
resource editor, and pressing the
1626
\inlineimage designer-remove-resource-entry-button.png
1627
button.
1628
\endtable
1629
1630
1631
\section1 Using the Resources
1632
1633
Once the resources are defined you can use them actively when composing
1634
your form. For example, you might want to create a tool button using an
1635
icon specified in the resource file.
1636
1637
\target UsingResources
1638
\table
1639
\row
1640
\li \inlineimage designer-resources-using.png
1641
\li \b{Using Resources}
1642
1643
When changing properties with values that may be defined within a
1644
resource file, \QD's property editor allows you to specify a resource
1645
in addition to the option of selecting a source file in the ordinary
1646
way.
1647
1648
\row
1649
\li \inlineimage designer-resource-selector.png
1650
\li \b{Selecting a Resource}
1651
1652
You can open the resource selector by clicking \gui{Choose Resource...}
1653
to add resources any time during the design process.
1654
1655
\omit
1656
... check with Friedemann
1657
To quickly assign icon pixmaps to actions or pixmap properties, you may
1658
drag the pixmap from the resource editor to the action editor, or to the
1659
pixmap property in the property editor.
1660
\endomit
1661
1662
\endtable
1663
*/
1664
1665
1666
/*!
1667
\page designer-stylesheet.html
1668
\previouspage Editing Resources with Qt Widgets Designer
1669
\nextpage Using a Designer UI File in Your C++ Application
1670
1671
\title Using Stylesheets with Qt Widgets Designer
1672
1673
Since Qt 4.2, it is possible to edit stylesheets in \QD with the stylesheet
1674
editor.
1675
1676
\target UsingStylesheets
1677
\table
1678
\row
1679
\li \inlineimage designer-stylesheet-options.png
1680
\b{Setting a Stylesheet}
1681
1682
The stylesheet editor can be accessed by right-clicking a widget
1683
and selecting \gui{Change styleSheet...}
1684
1685
\row
1686
\li \inlineimage designer-stylesheet-usage.png
1687
\endtable
1688
1689
*/
1690
1691
1692
/*!
1693
\page designer-using-a-ui-file.html
1694
\previouspage Using Stylesheets with Qt Widgets Designer
1695
\nextpage Using a Designer UI File in Your Qt for Python Application
1696
1697
\keyword Using a Designer UI File in Your Application
1698
\title Using a Designer UI File in Your C++ Application
1699
1700
Qt Widgets Designer UI files represent the widget tree of the form in XML format. The
1701
forms can be processed:
1702
1703
\list
1704
\li \l{Compile Time Form Processing}{At compile time}, which means that forms
1705
are converted to C++ code that can be compiled.
1706
\li \l{Run Time Form Processing}{At runtime}, which means that forms are processed
1707
by the QUiLoader class that dynamically constructs the widget tree while
1708
parsing the XML file.
1709
\endlist
1710
1711
\tableofcontents
1712
\section1 Compile Time Form Processing
1713
1714
You create user interface components with \QD and use Qt's integrated build tools,
1715
\l{qmake Manual}{qmake} and \l{User Interface Compiler (uic)}{uic}, to generate code
1716
for them when the application is built. The generated code contains the form's user
1717
interface object. It is a C++ struct that contains:
1718
1719
\list
1720
\li Pointers to the form's widgets, layouts, layout items,
1721
button groups, and actions.
1722
\li A member function called \c setupUi() to build the widget tree
1723
on the parent widget.
1724
\li A member function called \c retranslateUi() that handles the
1725
translation of the string properties of the form. For more information,
1726
see \l{Reacting to Language Changes}.
1727
\endlist
1728
1729
The generated code can be included in your application and used directly from
1730
it. Alternatively, you can use it to extend subclasses of standard widgets.
1731
1732
A compile time processed form can be used in your application with one of
1733
the following approaches:
1734
1735
\list
1736
\li \l{The Direct Approach}: you construct a widget to use as a placeholder
1737
for the component, and set up the user interface inside it.
1738
\li \l{The Single Inheritance Approach}: you subclass the form's base class
1739
(QWidget or QDialog, for example), and include a private instance
1740
of the form's user interface object.
1741
\li \l{The Multiple Inheritance Approach}: you subclass both the form's base
1742
class and the form's user interface object. This allows the widgets
1743
defined in the form to be used directly from within the scope of
1744
the subclass.
1745
\endlist
1746
1747
To demonstrate, we create a simple Calculator Form application. It is based on the
1748
original \l{Calculator Form} example.
1749
1750
The application consists of one source file, \c main.cpp and a UI
1751
file.
1752
1753
The \c{calculatorform.ui} file designed with \QD is shown below:
1754
1755
\image directapproach-calculatorform.png
1756
1757
When using \c CMake to build the executable, a \c{CMakeLists.txt}
1758
file is required:
1759
1760
\snippet uitools/calculatorform/CMakeLists.txt 0
1761
1762
The form is listed among the C++ source files in \c qt_add_executable().
1763
The option \c CMAKE_AUTOUIC tells \c CMake to run the \c uic tool
1764
to create a \c ui_calculatorform.h file that can be used
1765
by the source files.
1766
1767
When using \c qmake to build the executable, a \c{.pro} file is required:
1768
1769
\snippet uitools/calculatorform/calculatorform.pro 0
1770
1771
The special feature of this file is the \c FORMS declaration that tells
1772
\c qmake which files to process with \c uic. In this case, the
1773
\c calculatorform.ui file is used to create a \c ui_calculatorform.h file
1774
that can be used by any file listed in the \c SOURCES declaration.
1775
1776
\note You can use Qt Creator to create the Calculator Form project. It
1777
automatically generates the main.cpp, UI, and a project file for the
1778
desired build tool, which you can modify.
1779
1780
\section2 The Direct Approach
1781
1782
To use the direct approach, we include the \c ui_calculatorform.h file
1783
directly in \c main.cpp:
1784
1785
\snippet uitools/calculatorform/main.cpp 0
1786
1787
The \c main function creates the calculator widget by constructing a
1788
standard QWidget that we use to host the user interface described by the
1789
\c calculatorform.ui file.
1790
1791
\snippet uitools/calculatorform/main.cpp 1
1792
1793
In this case, the \c{Ui::CalculatorForm} is an interface description object
1794
from the \c ui_calculatorform.h file that sets up all the dialog's widgets
1795
and the connections between its signals and slots.
1796
1797
The direct approach provides a quick and easy way to use simple, self-contained
1798
components in your applications. However, componens created with \QD often
1799
require close integration with the rest of the application code. For
1800
instance, the \c CalculatorForm code provided above will compile and run,
1801
but the QSpinBox objects will not interact with the QLabel as we need a
1802
custom slot to carry out the add operation and display the result in the
1803
QLabel. To achieve this, we need to use the single inheritance approach.
1804
1805
\section2 The Single Inheritance Approach
1806
1807
To use the single inheritance approach, we subclass a standard Qt widget and
1808
include a private instance of the form's user interface object. This can take
1809
the form of:
1810
1811
\list
1812
\li A member variable
1813
\li A pointer member variable
1814
\endlist
1815
1816
\section3 Using a Member Variable
1817
1818
In this approach, we subclass a Qt widget and set up the user interface
1819
from within the constructor. Components used in this way expose the widgets
1820
and layouts used in the form to the Qt widget subclass, and provide a
1821
standard system for making signal and slot connections between the user
1822
interface and other objects in your application.
1823
The generated \c{Ui::CalculatorForm} structure is a member of the class.
1824
1825
This approach is used in the \l{Calculator Form} example.
1826
1827
To ensure that we can use the user interface, we need to include the header
1828
file that \c uic generates before referring to \c{Ui::CalculatorForm}:
1829
1830
\snippet calculatorform/calculatorform.h 0
1831
1832
The project file must be updated to include \c{calculatorform.h}.
1833
For \c CMake:
1834
1835
\snippet calculatorform/CMakeLists.txt 1
1836
1837
In specific cases, such as the example below where the include directive
1838
uses a relative path, \l{qt6_add_ui}{qt_add_ui} can be used to generate the
1839
\c{ui_calculatorform.h} file instead of relying on
1840
\l{CMake AUTOUIC Documentation}{AUTOUIC}.
1841
1842
\l{When to prefer qt_add_ui over AUTOUIC}
1843
1844
\code
1845
#include "src/files/ui_calculatorform.h"
1846
\endcode
1847
1848
\code
1849
qt_add_ui(calculatorform SOURCES calculatorform.ui
1850
INCLUDE_PREFIX src/files)
1851
\endcode
1852
1853
For \c qmake:
1854
1855
\snippet calculatorform/calculatorform.pro 0
1856
1857
The subclass is defined in the following way:
1858
1859
\snippet calculatorform/calculatorform.h 1
1860
1861
The important feature of the class is the private \c ui object which
1862
provides the code for setting up and managing the user interface.
1863
1864
The constructor for the subclass constructs and configures all the widgets
1865
and layouts for the dialog just by calling the \c ui object's \c setupUi()
1866
function. Once this has been done, it is possible to modify the user
1867
interface as needed.
1868
1869
\snippet calculatorform/calculatorform.cpp 0
1870
1871
We can connect signals and slots in user interface widgets in the usual
1872
way by adding the on_<object name> - prefix. For more information,
1873
see \l{widgets-and-dialogs-with-auto-connect}.
1874
1875
The advantages of this approach are its simple use of inheritance to
1876
provide a QWidget-based interface, and its encapsulation of the user
1877
interface widget variables within the \c ui data member. We can use this
1878
method to define a number of user interfaces within the same widget, each
1879
of which is contained within its own namespace, and overlay (or compose)
1880
them. This approach can be used to create individual tabs from existing
1881
forms, for example.
1882
1883
\section3 Using a Pointer Member Variable
1884
1885
Alternatively, the \c{Ui::CalculatorForm} structure can be made a pointer
1886
member of the class. The header then looks as follows:
1887
1888
\code
1889
1890
namespace Ui {
1891
class CalculatorForm;
1892
}
1893
1894
class CalculatorForm : public QWidget
1895
...
1896
virtual ~CalculatorForm();
1897
...
1898
private:
1899
Ui::CalculatorForm *ui;
1900
...
1901
1902
\endcode
1903
1904
The corresponding source file looks as follows:
1905
1906
\code
1907
#include "ui_calculatorform.h"
1908
1909
CalculatorForm::CalculatorForm(QWidget *parent) :
1910
QWidget(parent), ui(new Ui::CalculatorForm)
1911
{
1912
ui->setupUi(this);
1913
}
1914
1915
CalculatorForm::~CalculatorForm()
1916
{
1917
delete ui;
1918
}
1919
\endcode
1920
1921
The advantage of this approach is that the user interface object can be
1922
forward-declared, which means that we do not have to include the generated
1923
\c ui_calculatorform.h file in the header. The form can then be changed without
1924
recompiling the dependent source files. This is particularly important if the
1925
class is subject to binary compatibility restrictions.
1926
1927
We generally recommend this approach for libraries and large applications.
1928
For more information, see \l{Creating Shared Libraries}.
1929
1930
\section2 The Multiple Inheritance Approach
1931
1932
Forms created with \QD can be subclassed together with a standard
1933
QWidget-based class. This approach makes all the user interface components
1934
defined in the form directly accessible within the scope of the subclass,
1935
and enables signal and slot connections to be made in the usual way with
1936
the \l{QObject::connect()}{connect()} function.
1937
1938
We need to include the header file that \c uic generates from the
1939
\c calculatorform.ui file, as follows:
1940
1941
\snippet ../designer/calculatorform_mi/calculatorform.h 0
1942
1943
The class is defined in a similar way to the one used in the
1944
\l{The Single Inheritance Approach}{single inheritance approach}, except that
1945
this time we inherit from \e{both} QWidget and \c{Ui::CalculatorForm},
1946
as follows:
1947
1948
\snippet ../designer/calculatorform_mi/calculatorform.h 1
1949
1950
We inherit \c{Ui::CalculatorForm} privately to ensure that the user
1951
interface objects are private in our subclass. We can also inherit it with
1952
the \c public or \c protected keywords in the same way that we could have
1953
made \c ui public or protected in the previous case.
1954
1955
The constructor for the subclass performs many of the same tasks as the
1956
constructor used in the \l{The Single Inheritance Approach}
1957
{single inheritance} example:
1958
1959
\snippet ../designer/calculatorform_mi/calculatorform.cpp 0
1960
1961
In this case, the widgets used in the user interface can be accessed in the
1962
same say as a widget created in code by hand. We no longer require the
1963
\c{ui} prefix to access them.
1964
1965
\section2 Reacting to Language Changes
1966
1967
Qt notifies applications if the user interface language changes by sending an
1968
event of the type QEvent::LanguageChange. To call the member function
1969
\c retranslateUi() of the user interface object, we reimplement
1970
\c QWidget::changeEvent() in the form class, as follows:
1971
1972
\code
1973
void CalculatorForm::changeEvent(QEvent *e)
1974
{
1975
QWidget::changeEvent(e);
1976
switch (e->type()) {
1977
case QEvent::LanguageChange:
1978
ui->retranslateUi(this);
1979
break;
1980
default:
1981
break;
1982
}
1983
}
1984
\endcode
1985
1986
\section1 Run Time Form Processing
1987
1988
Alternatively, forms can be processed at run time, producing dynamically-
1989
generated user interfaces. This can be done using the QtUiTools module
1990
that provides the QUiLoader class to handle forms created with \QD.
1991
1992
1993
\section2 The UiTools Approach
1994
1995
A resource file containing a UI file is required to process forms at
1996
run time. Also, the application needs to be configured to use the QtUiTools
1997
module. This is done by including the following declarations in a \c CMake
1998
project file, ensuring that the application is compiled and linked
1999
appropriately.
2000
2001
\snippet ../uitools/textfinder/CMakeLists.txt 0
2002
\snippet ../uitools/textfinder/CMakeLists.txt 1
2003
2004
For \c qmake:
2005
2006
\snippet manual/doc_src_designer-manual.pro 0
2007
2008
The QUiLoader class provides a form loader object to construct the user
2009
interface. This user interface can be retrieved from any QIODevice, e.g.,
2010
a QFile object, to obtain a form stored in a project's resource file. The
2011
QUiLoader::load() function constructs the form widget using the user
2012
interface description contained in the file.
2013
2014
The QtUiTools module classes can be included using the following directive:
2015
2016
\snippet manual/doc_src_designer-manual.cpp 1
2017
2018
The QUiLoader::load() function is invoked as shown in this code from the
2019
\l{Text Finder} example:
2020
2021
\snippet ../uitools/textfinder/textfinder.cpp 4
2022
2023
In a class that uses QtUiTools to build its user interface at run time, we
2024
can locate objects in the form using QObject::findChild(). For example, in the
2025
following code, we locate some components based on their object names and
2026
widget types:
2027
2028
\snippet ../uitools/textfinder/textfinder.cpp 1
2029
2030
Processing forms at run-time gives the developer the freedom to change a
2031
program's user interface, just by changing the UI file. This is useful
2032
when customizing programs to suit various user needs, such as extra large
2033
icons or a different colour scheme for accessibility support.
2034
2035
2036
\section1 Automatic Connections
2037
2038
The signals and slots connections defined for compile time or run time
2039
forms can either be set up manually or automatically, using QMetaObject's
2040
ability to make connections between signals and suitably-named slots.
2041
2042
Generally, in a QDialog, if we want to process the information entered by
2043
the user before accepting it, we need to connect the clicked() signal from
2044
the \gui OK button to a custom slot in our dialog. We will first show an
2045
example of the dialog in which the slot is connected by hand then compare
2046
it with a dialog that uses automatic connection.
2047
2048
2049
\section2 A Dialog Without Auto-Connect
2050
2051
We define the dialog in the same way as before, but now include a slot in
2052
addition to the constructor:
2053
2054
\snippet noautoconnection/imagedialog.h 0
2055
2056
The \c checkValues() slot will be used to validate the values provided by
2057
the user.
2058
2059
In the dialog's constructor we set up the widgets as before, and connect
2060
the \gui Cancel button's \l{QPushButton::clicked()}{clicked()} signal to
2061
the dialog's reject() slot. We also disable the
2062
\l{QPushButton::autoDefault}{autoDefault} property in both buttons to
2063
ensure that the dialog does not interfere with the way that the line edit
2064
handles return key events:
2065
2066
\snippet noautoconnection/imagedialog.cpp 0
2067
\dots
2068
\snippet noautoconnection/imagedialog.cpp 1
2069
2070
We connect the \gui OK button's \l{QPushButton::clicked()}{clicked()}
2071
signal to the dialog's checkValues() slot which we implement as follows:
2072
2073
\snippet noautoconnection/imagedialog.cpp 2
2074
2075
This custom slot does the minimum necessary to ensure that the data
2076
entered by the user is valid - it only accepts the input if a name was
2077
given for the image.
2078
2079
\section2 Widgets and Dialogs with Auto-Connect
2080
2081
Although it is easy to implement a custom slot in the dialog and connect
2082
it in the constructor, we could instead use QMetaObject's auto-connection
2083
facilities to connect the \gui OK button's clicked() signal to a slot in
2084
our subclass. \c{uic} automatically generates code in the dialog's
2085
\c setupUi() function to do this, so we only need to declare and
2086
implement a slot with a name that follows a standard convention:
2087
2088
\snippet manual/doc_src_designer-manual.cpp 2
2089
2090
\note When renaming widgets in the form, the slot names need to be
2091
adapted accordingly, which can become a maintenance problem.
2092
For this reason, we recommend against using this in new code.
2093
2094
Using this convention, we can define and implement a slot that responds to
2095
mouse clicks on the \gui OK button:
2096
2097
\snippet autoconnection/imagedialog.h 0
2098
2099
Another example of automatic signal and slot connection would be the
2100
\l{Text Finder} with its \c{on_findButton_clicked()}
2101
slot.
2102
2103
We use QMetaObject's system to enable signal and slot connections:
2104
2105
\snippet ../uitools/textfinder/textfinder.cpp 2
2106
2107
This enables us to implement the slot, as shown below:
2108
2109
\snippet ../uitools/textfinder/textfinder.cpp 6
2110
\dots
2111
\snippet ../uitools/textfinder/textfinder.cpp 8
2112
2113
Automatic connection of signals and slots provides both a standard naming
2114
convention and an explicit interface for widget designers to work to. By
2115
providing source code that implements a given interface, user interface
2116
designers can check that their designs actually work without having to
2117
write code themselves.
2118
*/
2119
2120
/*!
2121
\page designer-using-a-ui-file-python.html
2122
\previouspage Using a Designer UI File in Your C++ Application
2123
\nextpage Using Custom Widgets with Qt Widgets Designer
2124
2125
\title Using a Designer UI File in Your Qt for Python Application
2126
2127
\section1 Converting the Form to Python Code
2128
2129
To demonstrate, we use the Qt Widgets animation easing example.
2130
2131
The application consists of one source file, \c easing.py, a UI
2132
file \c form.ui, a resource file \c easing.qrc and the project
2133
file, \c{easing.pyproject} file in the YAML format:
2134
2135
\code
2136
{
2137
"files": ["easing.qrc", "ui_form.py", "easing.py", "easing_rc.py",
2138
"form.ui"]
2139
}
2140
\endcode
2141
2142
The UI file is converted to Python code building the form using the
2143
\l{User Interface Compiler (uic)}:
2144
2145
\code
2146
uic -g python form.ui > ui_form.py
2147
\endcode
2148
2149
Since the top level widget is named \c Form, this results in a Python
2150
class named \c Ui_Form being generated. It provides a function
2151
\c setupUi(), taking the widget as parameter, which is called to
2152
create the UI elements:
2153
2154
\code
2155
from ui_form import Ui_Form
2156
...
2157
class Window(QtWidgets.QWidget):
2158
def __init__(self, parent=None):
2159
super(Window, self).__init__(parent)
2160
2161
self.m_ui = Ui_Form()
2162
self.m_ui.setupUi(self)
2163
\endcode
2164
2165
Later on, the widgets can be accessed via the \c Ui_Form class:
2166
2167
\code
2168
self.m_ui.graphicsView.setScene(self.m_scene)
2169
\endcode
2170
2171
Besides \c setupUi(), \c Ui_Form provides another method
2172
\c retranslateUi(), which can be called in reaction to
2173
a QEvent of type QEvent.LanguageChange, which indicates
2174
a change in the application language.
2175
2176
\section2 The UiTools Approach
2177
2178
The QUiLoader class provides a form loader object to construct the user
2179
interface at runtime. This user interface can be retrieved from any
2180
QIODevice, e.g., a QFile object. The QUiLoader::load() function
2181
constructs the form widget using the user interface description
2182
contained in the file.
2183
2184
It is demonstrated by the uiloader example:
2185
2186
\code
2187
from PySide2.QtUiTools import QUiLoader
2188
2189
if __name__ == '__main__':
2190
# Some code to obtain the form file name, ui_file_name
2191
app = QApplication(sys.argv)
2192
ui_file = QFile(ui_file_name)
2193
if not ui_file.open(QIODevice.ReadOnly):
2194
print("Cannot open {}: {}".format(ui_file_name, ui_file.errorString()))
2195
sys.exit(-1)
2196
loader = QUiLoader()
2197
widget = loader.load(ui_file, None)
2198
ui_file.close()
2199
if not widget:
2200
print(loader.errorString())
2201
sys.exit(-1)
2202
widget.show()
2203
sys.exit(app.exec_())
2204
\endcode
2205
2206
\section1 Resource imports
2207
2208
\section2 Single directory usage
2209
2210
When using icons from \l{The Qt Resource System}{resource files}, say
2211
\c resources.qrc, \c uic will generate an import of the form:
2212
2213
\code
2214
import resources_rc
2215
\endcode
2216
2217
This assumes that a file \c resources_rc.py generated by calling the
2218
\l {Resource Compiler (rcc)} tool (passing the \c {-g python}
2219
command line option) exists in the same directory as the form source.
2220
2221
\c uic has a command line option \c --rc-prefix causing the \c rc indicator
2222
to be prepended:
2223
2224
\code
2225
import rc_resources
2226
\endcode
2227
2228
The command line option \c --from-imports causes the imports to be generated
2229
relative to '.':
2230
2231
\code
2232
from . import resources_rc
2233
\endcode
2234
2235
\section2 Directory trees
2236
2237
Some projects have more complicated directory trees, for example:
2238
2239
\badcode
2240
project
2241
resources (resources.qrc)
2242
ui (.ui files)
2243
\endcode
2244
2245
The resource file is then not in the same directory as the form source
2246
and the \c .ui files typically have relative paths to the resource files:
2247
2248
\badcode
2249
<include location="../resources/resources.qrc"/>
2250
\endcode
2251
2252
In this case, the command line option \c --absolute-imports can be used
2253
to generate an absolute import in Python, resulting in:
2254
2255
\code
2256
import resources.resources_rc
2257
\endcode
2258
2259
based on the assumption that \c .. is the root directory of the project
2260
contained in the Python import path list.
2261
2262
For more deeply nested trees, it is possible to use the
2263
command line option \c {--python-paths <path list>} to pass a Python
2264
import path list. \c uic will then try to determine the project root
2265
by matching the form file path against the path components.
2266
2267
If \c {--python-paths} is not given, the environment variable
2268
\c PYTHONPATH is by default checked.
2269
*/
2270
2271
/*!
2272
\page designer-customizing-forms.html
2273
\previouspage Using a Designer UI File in Your Qt for Python Application
2274
\nextpage Using Custom Widgets with Qt Widgets Designer
2275
2276
\title Customizing Qt Widgets Designer Forms
2277
2278
\image designer-form-settings.png
2279
2280
When saving a form in \QD, it is stored as a UI file. Several form
2281
settings, for example the grid settings or the margin and spacing for the
2282
default layout, are stored along with the form's components. These settings
2283
are used when the \l uic generates the form's C++ code. For more
2284
information on how to use forms in your application, see the
2285
\l{Using a Designer UI File in Your C++ Application} section.
2286
2287
2288
\section1 Modifying the Form Settings
2289
2290
To modify the form settings, open the \gui Form menu and select \gui{Form
2291
Settings...}
2292
2293
In the forms settings dialog you can specify the \gui Author of the form.
2294
2295
You can also alter the margin and spacing properties for the form's default
2296
layout (\gui {Layout Default}). These default layout properties will be
2297
replaced by the corresponding \gui {Layout Function}, if the function is
2298
specified, when \c uic generates code for the form. The form settings
2299
dialog lets you specify functions for both the margin and the spacing.
2300
2301
\target LayoutFunction
2302
\table
2303
\row
2304
\li \inlineimage designer-form-layoutfunction.png
2305
\li \b{Layout Function}
2306
2307
The default layout properties will be replaced by the corresponding
2308
\gui{Layout Function}, when \c uic generates code for the form. This is
2309
useful when different environments requires different layouts for the same
2310
form.
2311
2312
To specify layout functions for the form's margin and spacing, check the
2313
\gui{Layout Function} group box to enable the line edits.
2314
\endtable
2315
2316
You can also specify the form's \gui{Include Hints}; i.e., provide a list
2317
of the header files which will then be included in the form window's
2318
associated UI file. Header files may be local, i.e., relative to the
2319
project's directory, \c "mywidget.h", or global, i.e. part of Qt or the
2320
compilers standard libraries: \c <QtWidgets/QWidget>.
2321
2322
Finally, you can specify the function used to load pixmaps into the form
2323
window (the \gui {Pixmap Function}).
2324
*/
2325
2326
2327
/*!
2328
\page designer-using-custom-widgets.html
2329
\previouspage Customizing Qt Widgets Designer Forms
2330
\nextpage Creating Custom Widgets for Qt Widgets Designer
2331
2332
\title Using Custom Widgets with Qt Widgets Designer
2333
2334
\QD can display custom widgets through its extensible plugin mechanism,
2335
allowing the range of designable widgets to be extended by the user and
2336
third parties. Alternatively, it is possible
2337
to use existing widgets as placeholders for widget classes that provide
2338
similar APIs.
2339
2340
2341
\section1 Handling Custom Widgets
2342
2343
Although \QD supports all of the standard Qt widgets, some specialized
2344
widgets may not be available as standard for a number of reasons:
2345
2346
\list
2347
\li Custom widgets may not be available at the time the user interface
2348
is being designed.
2349
\li Custom widgets may be platform-specific, and designers may be
2350
developing the user interface on a different platform to end users.
2351
\li The source code for a custom widget is not available, or the user
2352
interface designers are unable to use the widget for non-technical
2353
reasons.
2354
\endlist
2355
2356
In the above situations, it is still possible to design forms with the aim
2357
of using custom widgets in the application. To achieve this, we can use
2358
the widget promotion feature of \QD.
2359
2360
In all other cases, where the source code to the custom widgets is
2361
available, we can adapt the custom widget for use with \QD.
2362
2363
2364
\section2 Promoting Widgets
2365
2366
\image designer-promoting-widgets.png
2367
2368
If some forms must be designed, but certain custom widgets are unavailble
2369
to the designer, we can substitute similar widgets to represent the missing
2370
widgets. For example, we might represent instances of a custom push button
2371
class, \c MyPushButton, with instances of QPushButton and promote these to
2372
\c MyPushButton so that \l{uic.html}{uic} generates suitable code for this
2373
missing class.
2374
2375
When choosing a widget to use as a placeholder, it is useful to compare the
2376
API of the missing widget with those of standard Qt widgets. For
2377
specialized widgets that subclass standard classes, the obvious choice of
2378
placeholder is the base class of the custom widget; for example, QSlider
2379
might be used for specialized QSlider subclasses.
2380
2381
For specialized widgets that do not share a common API with standard Qt
2382
widgets, it is worth considering adapting a custom widget for use in \QD.
2383
If this is not possible then QWidget is the obvious choice for a
2384
placeholder widget since it is the lowest common denominator for all
2385
widgets.
2386
2387
To add a placeholder, select an object of a suitable base class and choose
2388
\gui{Promote to ...} from the form's context menu. After entering the class
2389
name and header file in the lower part of the dialog, choose \gui{Add}. The
2390
placeholder class will now appear along with the base class in the upper
2391
list. Click the \gui{Promote} button to accept this choice.
2392
2393
Now, when the form's context menu is opened over objects of the base class,
2394
the placeholder class will appear in the \gui{Promote to} submenu, allowing
2395
for convenient promotion of objects to that class.
2396
2397
A promoted widget can be reverted to its base class by choosing
2398
\gui{Demote to} from the form's context menu.
2399
2400
2401
\section2 User Defined Custom Widgets
2402
2403
Custom widgets can be adapted for use with \QD, giving designers the
2404
opportunity to configure the user interface using the actual widgets that
2405
will be used in an application rather than placeholder widgets. The process
2406
of creating a custom widget plugin is described in the
2407
\l{Creating Custom Widgets for Qt Widgets Designer} chapter of this manual.
2408
2409
To use a plugin created in this way, it is necessary to ensure that the
2410
plugin is located on a path that \QD searches for plugins. Generally,
2411
plugins stored in \c{$QTDIR/plugins/designer} will be loaded when \QD
2412
starts. Further information on building and installing plugins can be found
2413
\l{Creating Custom Widgets for Qt Widgets Designer#BuildingandInstallingthePlugin}
2414
{here}. You can also refer to the \l{How to Create Qt Plugins}
2415
{Plugins HOWTO} document for information about creating plugins.
2416
*/
2417
2418
2419
/*!
2420
\page designer-creating-custom-widgets.html
2421
\previouspage Using Custom Widgets with Qt Widgets Designer
2422
\nextpage Creating Custom Widget Extensions
2423
2424
\title Creating Custom Widgets for Qt Widgets Designer
2425
2426
\QD's plugin-based architecture allows user-defined and third party custom
2427
widgets to be edited just like you do with standard Qt widgets. All of the
2428
custom widget's features are made available to \QD, including widget
2429
properties, signals, and slots. Since \QD uses real widgets during the form
2430
design process, custom widgets will appear the same as they do when
2431
previewed.
2432
2433
The \l QtDesigner module provides you with the ability to create custom
2434
widgets in \QD.
2435
2436
2437
\section1 Getting Started
2438
2439
To integrate a custom widget with \QD, you require a suitable description
2440
for the widget and an appropriate project file.
2441
2442
2443
\section2 Providing an Interface Description
2444
2445
To inform \QD about the type of widget you want to provide, create a
2446
subclass of QDesignerCustomWidgetInterface that describes the various
2447
properties your widget exposes. Most of these are supplied by functions
2448
that are pure virtual in the base class, because only the author of the
2449
plugin can provide this information.
2450
2451
\table
2452
\header
2453
\li Function
2454
\li Description of the return value
2455
\row
2456
\li \c name()
2457
\li The name of the class that provides the widget.
2458
\row
2459
\li \c group()
2460
\li The group in \QD's widget box that the widget belongs to.
2461
\row
2462
\li \c toolTip()
2463
\li A short description to help users identify the widget in \QD.
2464
\row
2465
\li \c whatsThis()
2466
\li A longer description of the widget for users of \QD.
2467
\row
2468
\li \c includeFile()
2469
\li The header file that must be included in applications that use
2470
this widget. This information is stored in UI files and will
2471
be used by \c uic to create a suitable \c{#includes} statement
2472
in the code it generates for the form containing the custom
2473
widget.
2474
\row
2475
\li \c icon()
2476
\li An icon that can be used to represent the widget in \QD's
2477
widget box.
2478
\row
2479
\li \c isContainer()
2480
\li True if the widget will be used to hold child widgets;
2481
false otherwise.
2482
\row
2483
\li \c createWidget()
2484
\li A QWidget pointer to an instance of the custom widget,
2485
constructed with the parent supplied.
2486
\note createWidget() is a factory function responsible for
2487
creating the widget only. The custom widget's properties will
2488
not be available until load() returns.
2489
\row
2490
\li \c domXml()
2491
\li A description of the widget's properties, such as its object
2492
name, size hint, and other standard QWidget properties.
2493
\row
2494
\li \c codeTemplate()
2495
\li This function is reserved for future use by \QD.
2496
\endtable
2497
2498
Two other virtual functions can also be reimplemented:
2499
2500
\table
2501
\row
2502
\li \c initialize()
2503
\li Sets up extensions and other features for custom widgets. Custom
2504
container extensions (see QDesignerContainerExtension) and task
2505
menu extensions (see QDesignerTaskMenuExtension) should be set
2506
up in this function.
2507
\row
2508
\li \c isInitialized()
2509
\li Returns true if the widget has been initialized; returns false
2510
otherwise. Reimplementations usually check whether the
2511
\c initialize() function has been called and return the result
2512
of this test.
2513
\endtable
2514
2515
2516
\section2 Notes on the \c{domXml()} Function
2517
2518
The \c{domXml()} function returns a UI file snippet that is used by
2519
\QD's widget factory to create a custom widget and its applicable
2520
properties.
2521
2522
Since Qt 4.4, \QD's widget box allows for a complete UI file to
2523
describe \b one custom widget. The UI file can be loaded using the
2524
\c{<ui>} tag. Specifying the <ui> tag allows for adding the <customwidget>
2525
element that contains additional information for custom widgets. The
2526
\c{<widget>} tag is sufficient if no additional information is required
2527
2528
If the custom widget does not provide a reasonable size hint, it is
2529
necessary to specify a default geometry in the string returned by the
2530
\c domXml() function in your subclass. For example, the
2531
\c AnalogClockPlugin provided by the \l{customwidgetplugin}
2532
{Custom Widget Plugin} example, defines a default widgetgeometry in the
2533
following way:
2534
2535
\dots
2536
\snippet customwidgetplugin/customwidgetplugin.cpp 11
2537
\dots
2538
2539
An additional feature of the \c domXml() function is that, if it returns
2540
an empty string, the widget will not be installed in \QD's widget box.
2541
However, it can still be used by other widgets in the form. This feature
2542
is used to hide widgets that should not be explicitly created by the user,
2543
but are required by other widgets.
2544
2545
A complete custom widget specification looks like:
2546
2547
\code
2548
<ui language="c++"> displayname="MyWidget">
2549
<widget class="widgets::MyWidget" name="mywidget"/>
2550
<customwidgets>
2551
<customwidget>
2552
<class>widgets::MyWidget</class>
2553
<addpagemethod>addPage</addpagemethod>
2554
<propertyspecifications>
2555
<stringpropertyspecification name="fileName" notr="true" type="singleline"/>
2556
<stringpropertyspecification name="text" type="richtext"/>
2557
<tooltip name="text">Explanatory text to be shown in Property Editor</tooltip>
2558
</propertyspecifications>
2559
</customwidget>
2560
</customwidgets>
2561
</ui>
2562
\endcode
2563
2564
Attributes of the \c{<ui>} tag:
2565
\table
2566
\header
2567
\li Attribute
2568
\li Presence
2569
\li Values
2570
\li Comment
2571
\row
2572
\li \c{language}
2573
\li optional
2574
\li "c++", "jambi"
2575
\li This attribute specifies the language the custom widget is intended for.
2576
It is mainly there to prevent C++-plugins from appearing in Qt Jambi.
2577
\row
2578
\li \c{displayname}
2579
\li optional
2580
\li Class name
2581
\li The value of the attribute appears in the Widget box and can be used to
2582
strip away namespaces.
2583
\endtable
2584
2585
The \c{<addpagemethod>} tag tells \QD and \l uic which method should be used to
2586
add pages to a container widget. This applies to container widgets that require
2587
calling a particular method to add a child rather than adding the child by passing
2588
the parent. In particular, this is relevant for containers that are not a
2589
a subclass of the containers provided in \QD, but are based on the notion
2590
of \e{Current Page}. In addition, you need to provide a container extension
2591
for them.
2592
2593
The \c{<propertyspecifications>} element can contain a list of property meta information.
2594
2595
The tag \c{<tooltip>} may be used to specify a tool tip to be shown in Property Editor
2596
when hovering over the property. The property name is given in the attribute \c name and
2597
the element text is the tooltip. This functionality was added in Qt 5.6.
2598
2599
For properties of type string, the \c{<stringpropertyspecification>} tag can be used.
2600
This tag has the following attributes:
2601
2602
\table
2603
\header
2604
\li Attribute
2605
\li Presence
2606
\li Values
2607
\li Comment
2608
\row
2609
\li \c{name}
2610
\li required
2611
\li Name of the property
2612
\row
2613
\li \c{type}
2614
\li required
2615
\li See below table
2616
\li The value of the attribute determines how the property editor will handle them.
2617
\row
2618
\li \c{notr}
2619
\li optional
2620
\li "true", "false"
2621
\li If the attribute is "true", the value is not meant to be translated.
2622
\endtable
2623
2624
Values of the \c{type} attribute of the string property:
2625
2626
\table
2627
\header
2628
\li Value
2629
\li Type
2630
\row
2631
\li \c{"richtext"}
2632
\li Rich text.
2633
\row
2634
\li \c{"multiline"}
2635
\li Multi-line plain text.
2636
\row
2637
\li \c{"singleline"}
2638
\li Single-line plain text.
2639
\row
2640
\li \c{"stylesheet"}
2641
\li A CSS-style sheet.
2642
\row
2643
\li \c{"objectname"}
2644
\li An object name (restricted set of valid characters).
2645
\row
2646
\li \c{"url"}
2647
\li URL, file name.
2648
\endtable
2649
2650
\section1 Plugin Requirements
2651
2652
In order for plugins to work correctly on all platforms, you need to ensure
2653
that they export the symbols needed by \QD.
2654
2655
First of all, the plugin class must be exported in order for the plugin to
2656
be loaded by \QD. Use the Q_PLUGIN_METADATA() macro to do this. Also, the
2657
QDESIGNER_WIDGET_EXPORT macro must be used to define each custom widget class
2658
within a plugin, that \QD will instantiate.
2659
2660
2661
\section1 Creating Well Behaved Widgets
2662
2663
Some custom widgets have special user interface features that may make them
2664
behave differently to many of the standard widgets found in \QD.
2665
Specifically, if a custom widget grabs the keyboard as a result of a call
2666
to QWidget::grabKeyboard(), the operation of \QD will be affected.
2667
2668
To give custom widgets special behavior in \QD, provide an implementation
2669
of the initialize() function to configure the widget construction process
2670
for \QD specific behavior. This function will be called for the first time
2671
before any calls to createWidget() and could perhaps set an internal flag
2672
that can be tested later when \QD calls the plugin's createWidget()
2673
function.
2674
2675
2676
\target BuildingandInstallingthePlugin
2677
\section1 Building and Installing the Plugin
2678
2679
\section2 A Simple Plugin
2680
2681
The \l{Custom Widget Plugin} demonstrates a simple \QD plugin.
2682
2683
The project file for a plugin must specify the headers and sources for
2684
both the custom widget and the plugin interface. Typically, this file only
2685
has to specify that the plugin's project will be built as a library, but
2686
with specific plugin support for \QD. For \c CMake, this is done with
2687
the following declarations:
2688
2689
\snippet customwidgetplugin/CMakeLists.txt 0
2690
\snippet customwidgetplugin/CMakeLists.txt 1
2691
\snippet customwidgetplugin/CMakeLists.txt 2
2692
2693
The link libraries list specifies \c Qt::UiPlugin. This indicates that
2694
the plugin uses the abstract interfaces QDesignerCustomWidgetInterface
2695
and QDesignerCustomWidgetCollectionInterface only and has no linkage
2696
to the \QD libraries. When accessing other interfaces of \QD that have
2697
linkage, \c Designer should be used instead; this ensures that the plugin
2698
dynamically links to the \QD libraries and has a run-time dependency on
2699
them.
2700
2701
It is also necessary to ensure that the plugin is installed together with
2702
other \QD widget plugins:
2703
2704
\snippet customwidgetplugin/CMakeLists.txt 3
2705
\snippet customwidgetplugin/CMakeLists.txt 4
2706
2707
For \c qmake:
2708
2709
\snippet customwidgetplugin/customwidgetplugin.pro 0
2710
\snippet customwidgetplugin/customwidgetplugin.pro 2
2711
2712
The \c QT variable contains the keyword \c uiplugin, which is
2713
the equivalent of the \c Qt::UiPlugin library.
2714
2715
It is also necessary to ensure that the plugin is installed together with
2716
other \QD widget plugins:
2717
2718
\snippet manual/doc_src_designer-manual.pro 4
2719
2720
The \c $[QT_INSTALL_PLUGINS] variable is a placeholder to the location of
2721
the installed Qt plugins. You can configure \QD to look for plugins in
2722
other locations by setting the \c QT_PLUGIN_PATH environment variable
2723
before running the application.
2724
2725
\note \QD will look for a \c designer subdirectory in each path supplied.
2726
2727
See QCoreApplication::libraryPaths() for more information about customizing
2728
paths for libraries and plugins with Qt applications.
2729
2730
If plugins are built in a mode that is incompatible with \QD, they will
2731
not be loaded and installed. For more information about plugins, see the
2732
\l{plugins-howto.html}{Plugins HOWTO} document.
2733
2734
\section2 Splitting up the Plugin
2735
2736
The simple approach explained above introduces a problem particularly
2737
when using the other interfaces of \QD that have linkage:
2738
The application using the custom widget will then depend on
2739
\QD headers and libraries. In a real world scenario, this is not desired.
2740
2741
The following sections describe how to resolve this.
2742
2743
\section3 Linking the Widget into the Application
2744
2745
When using \c qmake, the source and header file of the custom widget
2746
can be shared between the application and \QD by creating a \c{.pri}
2747
file for inclusion:
2748
2749
\code
2750
INCLUDEPATH += $$PWD
2751
HEADERS += $$PWD/analogclock.h
2752
SOURCES += $$PWD/analogclock.cpp
2753
\endcode
2754
2755
This file would then be included by the \c{.pro} file of the plugin and
2756
the application:
2757
2758
\code
2759
include(customwidget.pri)
2760
\endcode
2761
2762
When using \c CMake, the source files of the widget can similarly be
2763
added to the application project.
2764
2765
\section3 Sharing the Widget Using a Library
2766
2767
Another approach is to put the widget into a library that is linked to
2768
the \QD plugin as well as to the application. It is recommended to
2769
use static libraries to avoid problems locating the library at run-time.
2770
2771
For shared libraries, see \l{sharedlibrary.html}{Creating Shared Libraries}.
2772
2773
\section3 Using the Plugin with QUiLoader
2774
2775
The preferred way of adding custom widgets to QUiLoader is to subclass it
2776
reimplementing QUiLoader::createWidget().
2777
2778
However, it is also possible to use \QD custom widget plugins
2779
(see QUiLoader::pluginPaths() and related functions). To avoid having
2780
to deploy the \QD libraries onto the target device, those plugins should
2781
have no linkage to the \QD libraries (\c {QT = uiplugin}, see
2782
\l{Creating Custom Widgets for Qt Widgets Designer#BuildingandInstallingthePlugin}).
2783
2784
\section1 Related Examples
2785
2786
For more information on using custom widgets in \QD, refer to the
2787
\l{customwidgetplugin}{Custom Widget Plugin} and
2788
\l{taskmenuextension}{Task Menu Extension} examples for more
2789
information about using custom widgets in \QD. Also, you can use the
2790
QDesignerCustomWidgetCollectionInterface class to combine several custom
2791
widgets into a single library.
2792
*/
2793
2794
2795
/*!
2796
\page designer-creating-custom-widgets-extensions.html
2797
\previouspage Creating Custom Widgets for Qt Widgets Designer
2798
\nextpage Qt Widgets Designer's UI File Format
2799
2800
\title Creating Custom Widget Extensions
2801
2802
Once you have a custom widget plugin for \QD, you can provide it with the
2803
expected behavior and functionality within \QD's workspace, using custom
2804
widget extensions.
2805
2806
2807
\section1 Extension Types
2808
2809
There are several available types of extensions in \QD. You can use all of
2810
these extensions in the same pattern, only replacing the respective
2811
extension base class.
2812
2813
QDesignerContainerExtension is necessary when implementing a custom
2814
multi-page container.
2815
2816
\table
2817
\row
2818
\li \inlineimage designer-manual-taskmenuextension.png
2819
\li \b{QDesignerTaskMenuExtension}
2820
2821
QDesignerTaskMenuExtension is useful for custom widgets. It provides an
2822
extension that allows you to add custom menu entries to \QD's task
2823
menu.
2824
2825
The \l{taskmenuextension}{Task Menu Extension} example
2826
illustrates how to use this class.
2827
2828
\row
2829
\li \inlineimage designer-manual-containerextension.png
2830
\li \b{QDesignerContainerExtension}
2831
2832
QDesignerContainerExtension is necessary when implementing a custom
2833
multi-page container. It provides an extension that allows you to add
2834
and delete pages for a multi-page container plugin in \QD.
2835
2836
The \l{containerextension}{Container Extension} example
2837
further explains how to use this class.
2838
2839
\note It is not possible to add custom per-page properties for some
2840
widgets (e.g., QTabWidget) due to the way they are implemented.
2841
\endtable
2842
2843
\table
2844
\row
2845
\li \inlineimage designer-manual-membersheetextension.png
2846
\li \b{QDesignerMemberSheetExtension}
2847
2848
The QDesignerMemberSheetExtension class allows you to manipulate a
2849
widget's member functions displayed when connecting signals and slots.
2850
2851
\row
2852
\li \inlineimage designer-manual-propertysheetextension.png
2853
\li \b{QDesignerPropertySheetExtension,
2854
QDesignerDynamicPropertySheetExtension}
2855
2856
These extension classes allow you to control how a widget's properties
2857
are displayed in \QD's property editor.
2858
\endtable
2859
2860
\omit
2861
\row
2862
\li
2863
\li \b {QDesignerScriptExtension}
2864
2865
The QDesignerScriptExtension class allows you to define script
2866
snippets that are executed when a form is loaded. The extension
2867
is primarily intended to be used to set up the internal states
2868
of custom widgets.
2869
\endtable
2870
\endomit
2871
2872
2873
\QD uses the QDesignerPropertySheetExtension and the
2874
QDesignerMemberSheetExtension classes to feed its property and signal and
2875
slot editors. Whenever a widget is selected in its workspace, \QD will
2876
query for the widget's property sheet extension; likewise, whenever a
2877
connection between two widgets is requested, \QD will query for the
2878
widgets' member sheet extensions.
2879
2880
\warning All widgets have default property and member sheets. If you
2881
implement custom property sheet or member sheet extensions, your custom
2882
extensions will override the default sheets.
2883
2884
2885
\section1 Creating an Extension
2886
2887
To create an extension you must inherit both QObject and the appropriate
2888
base class, and reimplement its functions. Since we are implementing an
2889
interface, we must ensure that it is made known to the meta object system
2890
using the Q_INTERFACES() macro in the extension class's definition. For
2891
example:
2892
2893
\snippet manual/doc_src_designer-manual.cpp 7
2894
2895
This enables \QD to use the qobject_cast() function to query for supported
2896
interfaces using a QObject pointer only.
2897
2898
2899
\section1 Exposing an Extension to Qt Widgets Designer
2900
2901
In \QD the extensions are not created until they are required. For this
2902
reason, when implementing extensions, you must subclass QExtensionFactory
2903
to create a class that is able to make instances of your extensions. Also,
2904
you must register your factory with \QD's extension manager; the extension
2905
manager handles the construction of extensions.
2906
2907
When an extension is requested, \QD's extension manager will run through
2908
its registered factories calling QExtensionFactory::createExtension() for
2909
each of them until it finds one that is able to create the requested
2910
extension for the selected widget. This factory will then make an instance
2911
of the extension.
2912
2913
\image qtdesignerextensions.png
2914
2915
2916
\section2 Creating an Extension Factory
2917
2918
The QExtensionFactory class provides a standard extension factory, but it
2919
can also be used as an interface for custom extension factories.
2920
2921
The purpose is to reimplement the QExtensionFactory::createExtension()
2922
function, making it able to create your extension, such as a
2923
\l{containerextension}{MultiPageWidget} container extension.
2924
2925
You can either create a new QExtensionFactory and reimplement the
2926
QExtensionFactory::createExtension() function:
2927
2928
\snippet manual/doc_src_designer-manual.cpp 8
2929
2930
or you can use an existing factory, expanding the
2931
QExtensionFactory::createExtension() function to enable the factory to
2932
create your custom extension as well:
2933
2934
\snippet manual/doc_src_designer-manual.cpp 9
2935
2936
2937
\section2 Accessing Qt Widgets Designer's Extension Manager
2938
2939
When implementing a custom widget plugin, you must subclass the
2940
QDesignerCustomWidgetInterface to expose your plugin to \QD. This is
2941
covered in more detail in the
2942
\l{Creating Custom Widgets for Qt Widgets Designer} section. The registration of
2943
an extension factory is typically made in the
2944
QDesignerCustomWidgetInterface::initialize() function:
2945
2946
\snippet manual/doc_src_designer-manual.cpp 10
2947
2948
The \c formEditor parameter in the
2949
QDesignerCustomWidgetInterface::initialize() function is a pointer to \QD's
2950
current QDesignerFormEditorInterface object. You must use the
2951
QDesignerFormEditorInterface::extensionManager() function to retrieve an
2952
interface to \QD's extension manager. Then you use the
2953
QExtensionManager::registerExtensions() function to register your custom
2954
extension factory.
2955
2956
2957
\section1 Related Examples
2958
2959
For more information on creating custom widget extensions in \QD, refer to
2960
the \l{taskmenuextension}{Task Menu Extension} and
2961
\l{containerextension}{Container Extension} examples.
2962
*/
2963
2964
2965
/*!
2966
\page designer-ui-file-format.html
2967
\previouspage Creating Custom Widget Extensions
2968
2969
\title Qt Widgets Designer's UI File Format
2970
2971
The \c UI file format used by \QD is described by the
2972
\l{http://www.w3.org/XML/Schema}{XML schema} presented below,
2973
which we include for your convenience. Be aware that the format
2974
may change in future Qt releases.
2975
2976
\quotefile ../../../../data/ui4.xsd
2977
*/
qttools
src
designer
src
designer
doc
src
designer-manual.qdoc
Generated on Sat Sep 21 2024 01:06:10 for Qt by
1.12.0