From 910eb9b47fd6297da58643ef4361177fe284d252 Mon Sep 17 00:00:00 2001 From: Leena Miettinen Date: Tue, 27 Sep 2011 11:59:26 +0200 Subject: [PATCH] Doc: move info about Qt Designer and Qt widgets to a separate folder Change-Id: I92efa66d0dc1f8ed35e16f7f8b5293806355a400 Reviewed-on: http://codereview.qt-project.org/5614 Reviewed-by: Qt Sanity Bot Reviewed-by: Eike Ziller Reviewed-by: Casper van Donderen --- doc/src/widgets/creator-faq-qtdesigner.qdocinc | 10 + doc/src/widgets/qtdesigner-app-tutorial.qdoc | 320 +++++++++++++++++++++ .../widgets/qtdesigner-mobile-app-tutorial.qdoc | 291 +++++++++++++++++++ doc/src/widgets/qtdesigner-overview.qdoc | 132 +++++++++ doc/src/widgets/qtdesigner-plugins.qdoc | 149 ++++++++++ 5 files changed, 902 insertions(+) create mode 100644 doc/src/widgets/creator-faq-qtdesigner.qdocinc create mode 100644 doc/src/widgets/qtdesigner-app-tutorial.qdoc create mode 100644 doc/src/widgets/qtdesigner-mobile-app-tutorial.qdoc create mode 100644 doc/src/widgets/qtdesigner-overview.qdoc create mode 100644 doc/src/widgets/qtdesigner-plugins.qdoc diff --git a/doc/src/widgets/creator-faq-qtdesigner.qdocinc b/doc/src/widgets/creator-faq-qtdesigner.qdocinc new file mode 100644 index 0000000000..a3b9ad5df6 --- /dev/null +++ b/doc/src/widgets/creator-faq-qtdesigner.qdocinc @@ -0,0 +1,10 @@ + \section1 Qt Designer Integration Questions + + \bold {Why are custom widgets not loaded in Design mode even though it + works in standalone Qt Designer?} + + Qt Designer fetches plugins from standard locations and loads the plugins + that match its build key. The locations are different for standalone and + integrated Qt Designer. + + For more information, see \l{Adding Qt Designer Plugins}. diff --git a/doc/src/widgets/qtdesigner-app-tutorial.qdoc b/doc/src/widgets/qtdesigner-app-tutorial.qdoc new file mode 100644 index 0000000000..5a1ed0c9e1 --- /dev/null +++ b/doc/src/widgets/qtdesigner-app-tutorial.qdoc @@ -0,0 +1,320 @@ +/**************************************************************************** +** +** This file is part of Qt Creator +** +** Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies). +** +** Contact: Nokia Corporation (info@qt.nokia.com) +** +** +** GNU Free Documentation License +** +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at info@qt.nokia.com. +** +****************************************************************************/ + +// ********************************************************************** +// NOTE: the sections are not ordered by their logical order to avoid +// reshuffling the file each time the index order changes (i.e., often). +// Run the fixnavi.pl script to adjust the links to the index order. +// ********************************************************************** + +/*! + \contentspage index.html + \previouspage creator-qml-components-example.html + \page creator-writing-program.html + \nextpage creator-mobile-example.html + + \title Creating a Qt Widget Based Application + + This tutorial describes how to use \QC to create a small Qt application, + Text Finder. It is a simplified version of the QtUiTools + \l{http://doc.qt.nokia.com/4.7/uitools-textfinder.html}{Text Finder} + example. The application user interface is constructed from Qt widgets by + using \QD. The application logic is written in C++ by using the code editor. + + \image qtcreator-textfinder-screenshot.png + + \section1 Creating the Text Finder Project + + \note Create the project with two instances of \QC open and the \gui{Help} + mode active in one of them so that you can follow these instructions while + you work. + + \list 1 + + \o Select \gui{File > New File or Project > Qt Widget Project > Qt Gui + Application > Choose}. + + \image qtcreator-new-qt-gui-application.png "New File or Project dialog" + + The \gui{Introduction and Project Location} dialog opens. + + \image qtcreator-intro-and-location-qt-gui.png "Introduction and Project Location dialog" + + \o In the \gui{Name} field, type \bold {TextFinder}. + + \o In the \gui {Create in} field, enter the path for the project files. + For example, \c {C:\Qt\examples}, and then click \gui{Next}. + + The \gui {Target Setup} dialog opens. + + \image qtcreator-new-project-qt-versions-qt-gui.png "Target Setup dialog" + + \o Select the Qt versions to use as build targets for your project, + and click \gui{Next}. + + \note If you have only one Qt version installed, this dialog is + skipped. + + The \gui{Class Information} dialog opens. + + \image qtcreator-class-info-qt-gui.png "Class Information dialog" + + \o In the \gui{Class name} field, type \bold {TextFinder} as the class + name. + + \o In the \gui{Base class} list, select \bold {QWidget} as the base + class type. + + \note The \gui{Header file}, \gui{Source file} and \gui{Form file} + fields are automatically updated to match the name of the class. + + \o Click \gui{Next}. + + The \gui{Project Management} dialog opens. + + \image qtcreator-new-project-summary-qt-gui.png "Project Management dialog" + + \o Review the project settings, and click \gui{Finish} to create the + project. + + \endlist + + The TextFinder project now contains the following files: + + \list + + \o textfinder.h + \o textfinder.cpp + \o main.cpp + \o textfinder.ui + \o textfinder.pro + + \endlist + + \image qtcreator-textfinder-contents.png "TextFinder project contents" + + The .h and .cpp files come with the necessary boiler plate code. + The .pro file is complete. + + \section1 Filling in the Missing Pieces + + Begin by designing the user interface and then move on to filling + in the missing code. Finally, add the find functionality. + + \section2 Designing the User Interface + + \image qtcreator-textfinder-ui.png "Text Finder UI" + + \list 1 + + \o In the \gui{Editor} mode, double-click the textfinder.ui file in the + \gui{Projects} view to launch the integrated \QD. + + \o Drag and drop the following widgets to the form: + + \list + + \o \gui{Label} (QLabel) + \o \gui{Line Edit} (QLineEdit) + \o \gui{Push Button} (QPushButton) + + \endlist + + \image qtcreator-textfinder-ui-widgets.png "Adding widgets to Text Finder UI" + + \note To easily locate the widgets, use the search box at the top of the + \gui Sidebar. For example, to find the \gui Label widget, start typing + the word \bold label. + + \image qtcreator-texfinder-filter.png "Filter field" + + \o Double-click the \gui{Label} widget and enter the text + \bold{Keyword}. + + \o Double-click the \gui{Push Button} widget and enter the text + \bold{Find}. + + \o In the \gui Properties pane, change the \gui objectName to + \bold findButton. + + \image qtcreator-textfinder-objectname.png "Changing object names" + + \o Press \key {Ctrl+A} to select the widgets and click + \gui{Lay out Horizontally} (or press \gui{Ctrl+H}) to apply a + horizontal layout (QHBoxLayout). + + \image qtcreator-texfinder-ui-horizontal-layout.png "Applying horizontal layout" + + \o Drag and drop a \gui{Text Edit} widget (QTextEdit) to the form. + + \o Select the screen area and click \gui{Lay out Vertically} (or press + \gui{Ctrl+L}) to apply a vertical layout (QVBoxLayout). + + \image qtcreator-textfinder-ui.png "Text Finder UI" + + Applying the horizontal and vertical layouts ensures that the + application UI scales to different screen sizes. + + \o To call a find function when users press the \gui Find button, you + use the Qt signals and slots mechanism. A signal is emitted when a + particular event occurs and a slot is a function that is called in + response to a particular signal. Qt widgets have predefined signals + and slots that you can use directly from \QD. To add a slot for the + find function: + + \list + + \o Right-click the \gui Find button to open a context-menu. + + \o Select \gui {Go to Slot > clicked()}, and then select + \gui OK. + + A private slot, \c{on_findButton_clicked()}, is added to the + header file, textfinder.h and a private function, + \c{TextFinder::on_findButton_clicked()}, is added to the + source file, textfinder.cpp. + + \endlist + + \o Press \gui{Ctrl+S} to save your changes. + + \endlist + + For more information about designing forms with \QD, see the + \l{http://doc.qt.nokia.com/4.7/designer-manual.html}{Qt Designer Manual}. + + \section2 Completing the Header File + + The textfinder.h file already has the necessary #includes, a constructor, + a destructor, and the \c{Ui} object. You need to add a private function, + \c{loadTextFile()}, to read and display the contents of the input text file + in the QTextEdit. + + \list 1 + + \o In the \gui{Projects} pane in the \gui {Edit view}, double-click the + \c{textfinder.h} file to open it for editing. + + \o Add a private function to the \c{private} section, after the + \c{Ui::TextFinder} pointer, as illustrated by the following code + snippet: + + \snippet examples/textfinder/textfinder.h 0 + + \endlist + + \section2 Completing the Source File + + Now that the header file is complete, move on to the source file, + textfinder.cpp. + + \list 1 + + \o In the \gui{Projects} pane in the \gui Edit view, double-click the + textfinder.cpp file to open it for editing. + + \o Add code to load a text file using QFile, read it with QTextStream, + and then display it on \c{textEdit} with + \l{http://doc.qt.nokia.com/4.7/qtextedit.html#plainText-prop} + {setPlainText()}. + This is illustrated by the following code snippet: + + \snippet examples/textfinder/textfinder.cpp 0 + + \o To use QFile and QTextStream, add the following #includes to + textfinder.cpp: + + \snippet examples/textfinder/textfinder.cpp 1 + + \o For the \c{on_findButton_clicked()} slot, add code to extract the + search string and use the + \l{http://doc.qt.nokia.com/4.7/qtextedit.html#find}{find()} function + to look for the search string within the text file. This is + illustrated by the following code snippet: + + \snippet examples/textfinder/textfinder.cpp 2 + + \o Once both of these functions are complete, add a line to call + \c{loadTextFile()} in the constructor, as illustrated by the + following code snippet: + + \snippet examples/textfinder/textfinder.cpp 3 + + \endlist + + The \c{on_findButton_clicked()} slot is called automatically in + the uic generated ui_textfinder.h file by this line of code: + + \code + QMetaObject::connectSlotsByName(TextFinder); + \endcode + + \section2 Creating a Resource File + + You need a resource file (.qrc) within which you embed the input + text file. The input file can be any .txt file with a paragraph of text. + Create a text file called input.txt and store it in the textfinder + folder. + + To add a resource file: + + \list 1 + + \o Select \gui{File > New File or Project > Qt > Qt Resource File > + Choose}. + + \image qtcreator-add-resource-wizard.png "New File or Project dialog" + + The \gui {Choose the Location} dialog opens. + + \image qtcreator-add-resource-wizard2.png "Choose the Location dialog" + + \o In the \gui{Name} field, enter \bold{textfinder}. + + \o In the \gui{Path} field, enter \c{C:\Qt\examples\TextFinder}, + and click \gui{Next}. + + The \gui{Project Management} dialog opens. + + \image qtcreator-add-resource-wizard3.png "Project Management dialog" + + + \o In the \gui{Add to project} field, select \bold{TextFinder.pro} + and click \gui{Finish} to open the file in the code editor. + + \o Select \gui{Add > Add Prefix}. + + \o In the \gui{Prefix} field, replace the default prefix with a slash + (/). + + \o Select \gui{Add > Add Files}, to locate and add input.txt. + + \image qtcreator-add-resource.png "Editing resource files" + + \endlist + + \section1 Compiling and Running Your Program + + Now that you have all the necessary files, click the + \inlineimage qtcreator-run.png + button to compile and run your program. + +*/ diff --git a/doc/src/widgets/qtdesigner-mobile-app-tutorial.qdoc b/doc/src/widgets/qtdesigner-mobile-app-tutorial.qdoc new file mode 100644 index 0000000000..8e87b6c2e2 --- /dev/null +++ b/doc/src/widgets/qtdesigner-mobile-app-tutorial.qdoc @@ -0,0 +1,291 @@ +/**************************************************************************** +** +** This file is part of Qt Creator +** +** Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies). +** +** Contact: Nokia Corporation (info@qt.nokia.com) +** +** +** GNU Free Documentation License +** +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at info@qt.nokia.com. +** +****************************************************************************/ + +// ********************************************************************** +// NOTE: the sections are not ordered by their logical order to avoid +// reshuffling the file each time the index order changes (i.e., often). +// Run the fixnavi.pl script to adjust the links to the index order. +// ********************************************************************** + +/*! + \contentspage index.html + \previouspage creator-writing-program.html + \page creator-mobile-example.html + \nextpage creator-project-managing.html + + \title Creating a Qt Widget Based Mobile Application + + \note To complete this tutorial, you must install \QSDK. + The installation program installs and configures the necessary tool chains + for mobile application development. + + This tutorial describes how to use \QC to create a small Qt + application, Battery Indicator, that uses the System Information + Mobility API to fetch battery information from the device. + + The user interface for the application is designed using Qt widgets. This + enforces a platform look and feel for Symbian devices and Maemo 5 devices. + However, to achieve a platform look and feel for MeeGo Harmattan devices, + \l{Creating Qt Quick Applications}{create a Qt Quick Application} and use + the Qt Quick components for MeeGo. + + \image qtcreator-batteryindicator-screenshot.png + + \section1 Creating the Battery Indicator Project + + \note Create the project with the \gui{Help} mode active so that you can + follow these instructions while you work. + + \list 1 + + \o Select \gui{File > New File or Project > Qt Widget Project > Mobile + Qt Application > Choose}. + + \image qtcreator-new-mobile-project.png "New File or Project dialog" + + The \gui{Introduction and Project Location} dialog opens. + + \image qtcreator-mobile-intro-and-location.png "Introduction and Project Location dialog" + + \o In the \gui{Name} field, type \bold {BatteryIndicator}. + + \o In the \gui {Create in} field, enter the path for the project files. + For example, \c {C:\Qt\examples}, and then click \gui{Next}. + + The \gui{Target Setup} dialog opens. + + \image qtcreator-mobile-project-qt-versions.png "Target Setup dialog" + + \o Select \gui {Symbian Device}, \gui {Maemo5}, \gui Harmattan, and + \gui {Qt Simulator} targets, and click \gui{Next}. + + \note Targets are listed if you installed the appropriate + development environment, for example, as part of the \QSDK. You can + add targets later in the \gui Projects mode. + + The \gui {Mobile Options} dialog opens. + + \image qtcreator-mobile-project-app-options.png "Mobile Options dialog" + + \o In the \gui {Orientation behavior} field, determine how the + application behaves when the orientation of the device display + rotates between portrait and landscape, and then click \gui{Next}. + + \note This dialog opens only if you select \gui Maemo5 or + \gui {Symbian Device} target in the \gui {Target Setup} dialog. On + Harmattan, the Qt Quick Components for MeeGo provide native-looking + rotation. + + The \gui {Symbian Specific} dialog opens. + + \image qtcreator-mobile-project-symbian-options.png "Symbian Specific dialog" + + \note \QC contains a default program icon and generates an + \l{Application UID}, for testing the application on a device. You + only need to change the icon and UID if you deliver the application + for public use. + + \o Click \gui Next. + + The \gui {Maemo Specific} dialog opens. + + \image qtcreator-mobile-project-maemo-options.png "Maemo Specific dialog" + + \o In the \gui {Application icon} field, select the application + icon to use on Maemo 5 or Harmattan targets, or click \gui Next to + use the default icon. + + The \gui{Project Management} dialog opens. + + \image qtcreator-mobile-project-summary.png "Project Management dialog" + + \o Review the project settings, and click \gui{Finish} to create the + project. + + \endlist + + The BatteryIndicator project now contains the following files: + + \list + + \o BatteryIndicator.pro + \o main.cpp + \o BatteryIndicator.svg + \o BatteryIndicator.png + \o BatteryIndicator.desktop + \o deployment.pri + \o mainwindow.cpp + \o mainwindow.ui + \o mainwindow.h + \o templates for Debian deployment files + + \endlist + + \image qtcreator-mobile-project-contents.png "Project contents" + + The files come with the necessary boiler plate code that you must + modify, as described in the following sections. + + \section1 Declaring the Qt Mobility API + + To use the Qt Mobility APIs or develop applications for Symbian + devices, you must modify the .pro file to declare the Qt Mobility APIs + that you use. + + This example uses the System Info API, so you must declare it, as + illustrated by the following code snippet: + + \code + + CONFIG += mobility + MOBILITY = systeminfo + + \endcode + + Each Mobility API has its corresponding value that you have to add + as a value of MOBILITY to use the API. For a list of the APIs and the + corresponding values that you can assign to MOBILITY, see the + \l {http://doc.qt.nokia.com/qtmobility/quickstart.html}{Quickstart Example}. + + \section1 Designing the User Interface + + \list 1 + + \o In the \gui{Editor} mode, double-click the mainwindow.ui + file in the \gui{Projects} view to launch the integrated \QD. + + \o Drag and drop a \gui{Progress Bar} + (\l{http://doc.qt.nokia.com/4.7/qprogressbar.html}{QProgressBar}) + widget to the form. + + \image qtcreator-mobile-project-widgets.png "Adding widgets to the UI" + + \o In the \gui Properties pane, change the \gui objectName to + \bold batteryLevelBar. + + \o Right-click the \gui MainWindow object and select + \gui {Lay Out > Lay Out Horizontally} to ensure that the battery + indicator widget size is adjusted correctly on Maemo devices. + + \endlist + + \section1 Completing the Header File + + The mainwindow.h file contains some of the necessary #includes, a + constructor, a destructor, and the \c{Ui} object. You must include + the System Info header file, add a shortcut to the mobility name + space, and add a private function to update the battery level value in + the indicator when the battery power level changes. + + \list 1 + + \o In the \gui{Projects} view, double-click the \c{mainwindow.h} file + to open it for editing. + + \o Include the System Device Info header file, as illustrated by the + following code snippet: + + \snippet examples/batteryindicator/mainwindow.h 1 + + \o Add a shortcut to the mobility name space, as illustrated by the + following code snippet: + + \snippet examples/batteryindicator/mainwindow.h 2 + + \o Declare a private function in the \c{private} section, after the + \c{Ui::MainWindow} function, as illustrated by the following code + snippet: + + \snippet examples/batteryindicator/mainwindow.h 3 + + \endlist + + \section1 Completing the Source File + + Now that the header file is complete, move on to the source file, + mainwindow.cpp. + + \list 1 + + \o In the \gui{Projects} view, double-click the mainwindow.cpp file + to open it for editing. + + \o Create a QSystemDeviceInfo object and set its value. Then connect + the signal that indicates that battery level changed to the + \c setValue slot of the progress bar. This is illustrated by the + following code snippet: + + \snippet examples/batteryindicator/mainwindow.cpp 1 + + \o Use the constructor to set initial values and make sure that the + created object is in a defined state, as illustrated by the + following code snippet: + + \snippet examples/batteryindicator/mainwindow.cpp 2 + + \endlist + + \section1 Compiling and Running Your Program + + Now that you have all the necessary code, select \gui {Qt Simulator} + as the target and click the + \inlineimage qtcreator-run.png + button to build your program and run it in the Qt Simulator. + + In Qt Simulator, run the runOutOfBattery.qs example script + to see the value change in the Battery Indicator application. + Select \gui {Scripting > examples > runOutOfBattery.qs > Run}. + + \image qtcreator-mobile-simulated.png "Mobile example in Qt Simulator" + + \section1 Testing on a Symbian Device + + You also need to test the application on real devices. Before you can + start testing on Symbian devices, you must connect them to the development + PC by using a USB cable and install an on-device debugging agent on them. + + \list 1 + + \o Install the necessary software on the device. For more information, + see \l{Connecting Symbian Devices}. + + \o Start the CODA debugging agent on the device. + + \o Click the \gui {Target Selector} and select \gui {Symbian Device}. + + \o Click \gui Run to build the application for the Symbian device. + + \endlist + + \section1 Testing on the Maemo or MeeGo Harmattan Emulator + + The Maemo 5 (Fremantle) and MeeGo Harmattan emulator are installed as part + of the \QSDK. After they are installed, you can start them from \QC. + + The Maemo emulator emulates the Nokia N900 device environment. You can test + applications in conditions practically identical to running the application + on a Nokia N900 device with the software update release 1.3 (V20.2010.36-2). + + The MeeGo Harmattan emulator emulates the Nokia N9 device environment. + + For more information, see \l{Using Maemo or MeeGo Harmattan Emulator}. + +*/ diff --git a/doc/src/widgets/qtdesigner-overview.qdoc b/doc/src/widgets/qtdesigner-overview.qdoc new file mode 100644 index 0000000000..b124469402 --- /dev/null +++ b/doc/src/widgets/qtdesigner-overview.qdoc @@ -0,0 +1,132 @@ +/**************************************************************************** +** +** This file is part of Qt Creator +** +** Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies). +** +** Contact: Nokia Corporation (info@qt.nokia.com) +** +** +** GNU Free Documentation License +** +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at info@qt.nokia.com. +** +****************************************************************************/ + +// ********************************************************************** +// NOTE: the sections are not ordered by their logical order to avoid +// reshuffling the file each time the index order changes (i.e., often). +// Run the fixnavi.pl script to adjust the links to the index order. +// ********************************************************************** + +/*! + \contentspage index.html + \previouspage creator-qml-modules-with-plugins.html + \page creator-using-qt-designer.html + \nextpage creator-usability.html + + \title Developing Widget Based Applications + + Widgets and forms created with \QD are integrated seamlessly with programmed + code by using the Qt signals and slots mechanism that allows you to easily + assign behavior to graphical elements. All properties set in \QD can be + changed dynamically within the code. Furthermore, features such as widget + promotion and custom plugins allow you to use your own widgets with \QD. For + more information, see \l{Adding Qt Designer Plugins}. + + \QC automatically opens all .ui files in the integrated \QD, in \gui Design + mode. + + \image qtcreator-formedit.png + + For more information about \QD, see the + \l{http://doc.qt.nokia.com/4.7/designer-manual.html}{Qt Designer Manual}. + + Generally, the integrated \QD contains the same functions as the standalone + \QD. The following sections describe the differences. + + \section1 Code Editor Integration + + To switch between forms (\gui Design mode) and code (\gui Edit mode), + press \key Shift+F4. + + You can use \QC to create stub implementations of slot functions. In the + \gui Design mode, right-click a widget to open a context menu, and then + select \gui {Go to Slot}. Select a signal in the list to go to an existing + slot function or to create a new slot function. + + \section1 Managing Image Resources + + In standalone \QD, image resources are created using the built-in + \gui {Resource Editor}. In \QC, .ui files are usually part of a project, + which may contain several resource files (.qrc). They are created and + maintained by using the \QC Resource Editor. The \QD \gui {Resource Editor} + is de-activated and the image resources are displayed in the \QD + \gui {Resource Browser}. + + \section1 Specifying Settings for Qt Designer + + To change the layout of \QD user interface elements: + + \list 1 + + \o Select \gui Tools > \gui{Form Editor} > \gui Views > \gui Locked. + + When this option is not checked, you can change the layout. + + \o Click the header of an element and drag the element to a new + position. + + \endlist + + To specify settings for \QD: + + \list + + \o Select \gui Tools > \gui Options > \gui Designer. + + \o Specify settins for generating classes and code in \gui {Class + Generation}. + + \o Specify embedded device profiles, that determine style, font, and + screen resolution, for example, in \gui{Embedded Design}. + + \o Specify settings for the grid and previewing forms in \gui Forms. + + \o Specify an additional folder for saving templates in \gui{Template + Paths}. + + \endlist + + To preview the settings, select \gui Tools > \gui{Form Editor} > + \gui Preview, or press \key Alt+Shift+R. + + \section1 Previewing Forms Using Device Skins + + A \e {device skin} is a set of configuration files that describe a mobile + device. It includes a border image that surrounds the form and depicts a + mobile device with its buttons. + + To preview your form using device skins: + + \list 1 + + \o Select \gui Tools > \gui Options > \gui Designer. + + \o Select the \gui{Print/Preview Configuration} check box. + + \o In the \gui {Device skin} field, select a device skin. + + \o When the form is open in \gui Design mode, press \key Alt+Shift+R. + + \o To end the preview, right-click the skin and select \gui Close in + the context menu. + + \endlist +*/ diff --git a/doc/src/widgets/qtdesigner-plugins.qdoc b/doc/src/widgets/qtdesigner-plugins.qdoc new file mode 100644 index 0000000000..88de2c94b8 --- /dev/null +++ b/doc/src/widgets/qtdesigner-plugins.qdoc @@ -0,0 +1,149 @@ +/**************************************************************************** +** +** This file is part of Qt Creator +** +** Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies). +** +** Contact: Nokia Corporation (info@qt.nokia.com) +** +** +** GNU Free Documentation License +** +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at info@qt.nokia.com. +** +****************************************************************************/ + +// ********************************************************************** +// NOTE: the sections are not ordered by their logical order to avoid +// reshuffling the file each time the index order changes (i.e., often). +// Run the fixnavi.pl script to adjust the links to the index order. +// ********************************************************************** + +/*! + \contentspage index.html + \previouspage creator-version-control.html + \page adding-plugins.html + \nextpage creator-editor-external.html + + \title Adding Qt Designer Plugins + + You can use Qt APIs to create plugins that extend Qt applications. + This allows you to add your own widgets to \QD. + The most flexible way to include a plugin with an application is to compile + it into a dynamic library that is shipped separately, and detected and + loaded at runtime. + + The applications can detect plugins that are stored in the standard plugin + subdirectories. For more information on how to create and locate plugins + and to change the default plugin path, see \l{How to Create Qt Plugins}. + + For more information about how to create plugins for \QD, see + \l{http://doc.qt.nokia.com/4.7/designer-using-custom-widgets.html} + {Creating and Using Components for Qt Designer}. + + \section1 Locating Qt Designer Plugins + + \QD fetches plugins from the standard locations and loads the plugins + that match its build key. \QD is delivered both as a standalone application + and as part of the SDK, where it is integrated into \QC. The correct folder + to place the plugins depends on which one you use. + + The integrated \QD fetches plugins from the \c {%SDK%\bin\designer} folder + on Windows and Linux. For information about how to configure plugins on + Mac OS, see \l{Configuring Qt Designer Plugins on Mac OS}. + + To check which plugins + were loaded successfully and which failed, choose \gui{Tools > Form Editor > + About Qt Designer Plugins}. + + The standalone \QD is part of the Qt library used for building projects, + located under \c {%SDK%\qt}. Therefore, it fetches plugins from the + following folder: \c {%SDK%\qt\plugins\designer}. To check which plugins + were loaded successfully and which failed, choose \gui{Help > + About Plugins}. + + \section2 Configuring Qt Designer Plugins on Mac OS + + On the Mac, a GUI application must be built and run from a bundle. A bundle + is a directory structure that appears as a single entity when viewed in the + Finder. A bundle for an application typcially contains the executable and + all the resources it needs. + + \QC uses its own set of Qt Libraries located in the bundle, and therefore, + you need to configure the \QD plugins that you want to use with \QC. + Fore more information about how to deploy applications on Mac OS, see + \l{http://doc.qt.nokia.com/4.7/deployment-mac.html} + {Deploying an Application on Mac OS X}. + + The following example illustrates how to configure version 5.2.1 of the + \l{http://qwt.sourceforge.net/}{Qwt - Qt Widgets for Technical Applications} + library for use with \QC: + + \list 1 + + \o To check the paths used in the Qwt library, enter the following + \c otool command: + + \snippet examples/doc_src_plugins.qdoc 0 + + The output for Qwt 5.2.1 indicates that the plugin uses Qt core + libraries (QtDesigner, QtScript, QtXml, QtGui and QtCore) and + libqwt.5.dylib: + + \snippet examples/doc_src_plugins.qdoc 1 + + + \o You must copy the \QD plugin and the Qwt library files to the + following locations: + + \list + + \o \c {libqwt_designer_plugin.dylib} to + \c {QtCreator.app/Contents/MacOS/designer} + + \o \c {libqwt.*.dylib} to \c {QtCreator.app/Contents/Frameworks} + + \endlist + + Enter the following commands: + + \snippet examples/doc_src_plugins.qdoc 4 + + \o Enter the following \c otool command to check the libraries that are + used by the Qwt library: + + \snippet examples/doc_src_plugins.qdoc 2 + + The command returns the following output: + + \snippet examples/doc_src_plugins.qdoc 3 + + \o Enter the following \c install_name_tool command to fix the + references of the libraries: + + \snippet examples/doc_src_plugins.qdoc 5 + + \endlist + + \section1 Matching Build Keys + + The \QC that is included in pre-built SDK packages on Windows is built with + the Microsoft Visual Studio compiler, whereas the version of Qt shipped for + building applications is configured and built to use the MinGW/g++ compiler. + Plugins built by using this version of Qt cannot be loaded by \QC because + the build-keys do not match. The plugins can only be used in the standalone + version of \QD. Choose \gui{Help > About \QC} to check the Qt version \QC + was built with. + + To use \QD plugins that were built for the shipped Qt version, make sure + that \QC is built with the same compiler by either recompiling \QC using + MinGW or recompiling Qt with Microsoft Visual Studio, depending on which + configuration you want to use for your applications. + +*/ -- 2.11.0