source: trunk/doc/src/development/designer-manual.qdoc@ 1147

Last change on this file since 1147 was 846, checked in by Dmitry A. Kuminov, 14 years ago

trunk: Merged in qt 4.7.2 sources from branches/vendor/nokia/qt.

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