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