Commit a5661dda authored by Leena Miettinen's avatar Leena Miettinen

Doc: divide file into several files

Mostly, place one topic into one file.

Change-Id: I8fdf43f14179816c0a57883068acd15b13a3761a
Reviewed-by: default avatarKai Koehne <kai.koehne@nokia.com>
parent 0238f919
/****************************************************************************
**
** This file is part of Qt Creator
**
** Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies).
**
** Contact: Nokia Corporation (qt-info@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 qt-info@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 quick-components.html
\page quick-buttons.html
\nextpage quick-scalable-image.html
\title Creating Buttons
To create a button component:
\list 1
\o Select \gui {File > New File or Project > QML > QML File > Choose}
to create a QML file called Button.qml (for example).
\note Components are listed in the \gui Library pane only if the
filename begins with a capital letter.
\o Click \gui {Design} to edit the file in the visual editor.
\o In the \gui Navigator pane, click \gui Rectangle to set properties
for it.
\o In the \gui Properties pane, modify the appearance of the button.
\list a
\o In the \gui Size field, set the width (\gui W) and height
(\gui H) of the button.
\o In the \gui Color field, select the button color.
\o In the \gui Radius field, use the slider to set the radius of
the rectangle and produce rounded corners for the button.
\endlist
\o Drag and drop a \gui {Text} item on top of the \gui Rectangle. This
creates a nested element where \gui Rectangle is the parent element
of \gui Text. Elements are positioned relative to their parents.
\o In the \gui Properties pane, edit the properties of the \gui Text
item.
\list a
\o In the \gui Text field, type \bold Button.
You can select the text color, font, size, and style in the
\gui Font section.
\o In the \gui Alignment field, select the center buttons to align
the text to the center of the button.
\o Click \gui {Layout}, and then click the
\inlineimage qmldesigner-anchor-fill-screen.png
button to anchor the text to the whole button area.
\endlist
\o Press \key {Ctrl+S} to save the button.
\image qmldesigner-button.png "Button component"
\endlist
\note To view the button, you must add it to a Qt Quick Application or
Qt Quick UI project.
To create a graphical button that scales beautifully without using vector
graphics, use the \l{http://doc.qt.nokia.com/4.7/qml-borderimage.html}
{Border Image} element. For more information, see
\l{Creating Scalable Buttons and Borders}.
*/
/*!
\contentspage index.html
\previouspage quick-buttons.html
\page quick-scalable-image.html
\nextpage quick-screens.html
\title Creating Scalable Buttons and Borders
You can use the \l{http://doc.qt.nokia.com/4.7/qml-borderimage.html}
{Border Image} element to display an image, such as a PNG file, as a border
and a background.
Use two Border Image elements and suitable graphics to make it look like the
button is pushed down when it is clicked. One of the Border Image elements
is visible by default. You can specify that it is hidden and the other one
becomes visible when the mouse is clicked.
Add a MouseArea that covers the whole area and emits the clicked signal
(\c {parent.clicked()}) when it detects a mouse click.
You can add text to the button and set it up as a property. The text can
then be initialized from the outside, making the button a reusable UI
component. The font size is also available in case the default size is too
big. You can scale down the button text and use smooth text rendering for
some extra quality.
\image qmldesigner-borderimage.png "Graphical button"
To create a graphical button:
\list 1
\o Select \gui {File > New File or Project > QML > QML File > Choose}
to create a QML file called Button.qml (for example).
\o Double-click the file to open it in the code editor.
\o Replace the \gui Rectangle with an \gui Item, as illustrated by the
following code snippet:
\qml
Item {
}
\endqml
\o Specify properties and set expressions for the \gui Item, as
illustrated by the following code snippet:
\snippet snippets/qml/quick-scalable-image.qml properties and signal definitions
You will point to the properties and expression later.
\o Click \gui {Design} to edit the file in the visual editor.
\o Drag and drop two \gui BorderImage items from the \gui Library pane
to the scene.
\o Drag and drop a \gui Text item to the scene.
\o Drag and drop a \gui MouseArea to the screen.
\o In the \gui Navigator pane, select \gui border_image1 to specify
settings for it in the \gui Properties pane:
\list a
\o Select \gui {Set Expression} in the menu next to the
\gui Visibility check box.
\o Enter the following expression to specify that the image is
visible when the mouse is not pressed down:
\c {!mouse_area1.pressed}.
\o In the \gui Source field, select the image file for the button,
for example button_up.png.
\o Click \gui {Layout}, and then click the
\inlineimage qmldesigner-anchor-fill-screen.png
button to anchor the border image to the \gui Item.
\endlist
\o Select \gui border_image2 to specify similar settings for it:
\list a
\o Set the following epression for \gui Visibility, to specify that
the image is visible when the mouse is pressed down:
\c {mouse_area1.pressed}.
\o In the \gui Source field, select the image file for the button
when it is clicked, for example button_down.png.
\o Click \gui {Layout}, and then click the
\inlineimage qmldesigner-anchor-fill-screen.png
button to anchor the border image to the \gui Item.
\endlist
\o Select \gui text1 to specify font size and color, and text
scaling and rendering:
\list a
\o In the \gui Color field, use the color picker to select
the font color, or enter a value in the field.
\o In the \gui Text field, select \gui {Set Expression} and
enter a pointer to the \c {text} property that you specified
earlier: \c {parent.txt}.
\o Select the \gui Aliasing check box to enable smooth text
rendering.
\o In the \gui Size field, select \gui {Pixels} to specify the font
size in pixels. By default, the size is specified in points.
\o In the \gui Size field, select \gui {Set Expression} and enter a
pointer to the \c {fontSize} property that you specified
earlier.
\o Click \gui {Layout}, and then click the
\inlineimage qmldesigner-center-in.png "Anchor buttons"
buttons to inherit the vertical and horizontal centering from
the parent.
\o Click \gui Advanced to specify scaling for the text in the
\gui Scale field.
\o Select \gui {Set Expression} and enter the following expression:
\c {if (!mousearea1.pressed) { 1 } else { 0.95 }}.
\note You can enter long and complicated expressions also in the
code editor.
\endlist
\o In the code editor, add to the \c MouseArea item a pointer to the
\c clicked expression that you added earlier:
\c {onClicked: parent.clicked()}.
\endlist
\note To view the button, you must add it to a Qt Quick Application or Qt
Quick UI project.
*/
/****************************************************************************
**
** This file is part of Qt Creator
**
** Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies).
**
** Contact: Nokia Corporation (qt-info@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 qt-info@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-using-qt-quick-designer.html
\page quick-components.html
\nextpage quick-buttons.html
\title Creating Components
A \l{glossary-component}{component} provides a way of defining a new type
that you can re-use in other QML files. A component is like a black box; it
interacts with the outside world through properties, signals, and slots, and
is generally defined in its own QML file. You can import components to
screens and applications.
You can use the following QML elements to create components:
\list
\o \l{http://doc.qt.nokia.com/4.7/qml-borderimage.html}{Border Image}
uses an image as a border or background.
\o \l{http://doc.qt.nokia.com/4.7/qml-image.html}{Image}
adds a bitmap to the scene. You can stretch and tile images.
\o \l{http://doc.qt.nokia.com/4.7/qml-item.html}{Item}
is the most basic of all visual items in QML. Even though it has no
visual appearance, it defines all the properties that are common
across visual items, such as the x and y position, width and height,
anchoring, and key handling.
\o \l{http://doc.qt.nokia.com/4.7/qml-rectangle.html}{Rectangle}
adds a rectangle that is painted with a solid fill color and an
optional border. You can also use the radius property to create
rounded rectangles.
\o \l{http://doc.qt.nokia.com/4.7/qml-text.html}{Text}
adds formatted read-only text.
\o \l{http://doc.qt.nokia.com/4.7/qml-textedit.html}{Text Edit}
adds a single line of editable formatted text that can be validated.
\o \l{http://doc.qt.nokia.com/4.7/qml-textinput.html}{Text Input}
adds a single line of editable plain text that can be validated.
\o \l{http://doc.qt.nokia.com/4.7-snapshot/qml-webview.html}{Web View}
adds web content to a canvas.
\endlist
QML elements allow you to write cross-platform applications with custom look
and feel. You can also use ready-made Qt Quick Components that enable you to
create applications with a native look and feel for a particular target
platform. You can install the components as part of \QSDK.
When you use the \QC project wizard to create Qt Quick applications, you
can select which component set to use in your application.
Even if you use the Qt Quick Components, you can still write cross-platform
applications, by using different sets of QML files for each platform.
You can dowload a set of commonly used UI-components for generic use in
Qt Quick projects from \l{https://projects.forum.nokia.com/QMLTemplates}
{QML Templates}. You can open and edit the templates in \QD.
\section1 Creating Components in Qt Quick Designer
\list 1
\o Select \gui {File > New File or Project > Files and Classes > QML
> Choose} to create a new .qml file.
\note Components are listed in the \gui {QML Components} section of
the \gui Library pane only if the filename begins with a capital
letter.
\o Click \gui Design to open the .qml file in \QMLD.
\o Drag and drop an item from the \gui Library pane to the editor.
\o Edit item properties in the \gui Properties pane.
The available properties depend on the item.
\endlist
\if defined(qcmanual)
The following sections contain examples of how to create some common
components:
\list
\o \l{Creating Buttons}
\o \l{Creating Scalable Buttons and Borders}
\endlist
\section1 Moving Within Components
Components can consist of several other components. To view the component
hierarchy as a bread crumb path when you edit a component on the canvas,
select \gui {Go into Component} or press \key F2. Click the component
names in the path to navigate to them. You can easily navigate back to the
top level when you are done editing the component.
\image qmldesigner-breadcrumbs.png "Go into Component command"
\endif
*/
This diff is collapsed.
/****************************************************************************
**
** This file is part of Qt Creator
**
** Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies).
**
** Contact: Nokia Corporation (qt-info@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 qt-info@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 quick-user-interaction.html
\page quick-export-to-qml.html
\nextpage quick-application-logic.html
\title Exporting Designs from Graphics Software
You can export designs from graphics software, such as Adobe Photoshop and
GIMP, to QML files. Each scene is converted into a single QML file with an
Image or a Text element for each layer and saved on the development PC.
Top-level layer groups are converted into merged QML Image elements.
\note GIMP does not support grouping, and therefore, each layer is exported
as an item in GIMP.
You can open the QML file in \QC for editing. If you edit the file in Adobe
Photoshop and export it to the same directory again, any changes you made in
\QC are overwritten. However, you can re-export graphical assets without
recreating the QML code.
If you create vector graphics with other tools that have an Adobe Photoshop
export option, such as Adobe Illustrator, you can export them first to
Photoshop and then to QML.
\section1 Conversion Rules
The following rules apply to the conversions:
\list
\o Layer names are used as element names. Spaces and hash marks (#) are
replaced with underscore characters to create valid ids for the
elements.
\o Layer styles, such as drop shadows, are converted to images.
\o Offset, size, ordering and opacity are preserved.
\o Text layers are converted to Text elements, unless you specify that
they be converted to Image elements.
\o Hidden layers can be exported, and their visibility is set to
hidden.
\o PNG images are copied to the images subirectory.
\endlist
\section1 Preparing Files for Conversion
To create QML files that are easy to use, prepare the Adobe Photoshop or
GIMP designs for exporting, as follows:
\list
\o To minimize the number of elements, minimize the number of layers or
use top-level layer groups, because each layer or layer group is
exported as a Text or Image element.
\o To make sure that all related elements are exported to the same
element, use top-level layer groups.
\o To determine that some layers are not exported, hide them, and
deselect the \gui {Export hidden} check box during exporting.
\o To make it easier to find the layers and layer groups after
exporting them, use descriptive names for them.
\o To make sure that image dimensions are preserved during export,
create at least one fully filled layer (which can be hidden), such
as a background layer. If the export script does not find a fully
filled layer, it resizes all images to the size of the canvas.
\o To prevent errors during export, make sure that the layers are not
locked. Locked layers cannot be exported.
\o To avoid unexpected results, do not use Blending Mode effects. They
are not exported.
\endlist
\section1 Exporting from Adobe Photoshop to QML
\image qml-export-photoshop.png
The script has been tested to work on Adobe Photoshop CS 4 and 5, but it
might also work on other versions.
\list 1
\o Download the export script, \e{Export QML.jx}, from
\l{http://qt.gitorious.org/qt-labs/photoshop-qmlexporter/trees/master}
{Gitorious}.
\note Read the README.txt file in the repository for latest
information about the script.
\o Double-click the export script to add the export command to the
\gui Scripts menu. You can also copy the script file to the Adobe
Photoshop scripts directory (typically, \c{\Presets\Scripts} in the
Photoshop installation directory).
\o In Adobe Photoshop, choose \gui {File > Scripts > Export to QML} to
export the scene to a QML file.
\o In the \gui {Export Document to QML} dialog, enter a name and
location for the QML file.
\o Select the \gui {Rasterize text} check box to export text layers as
images, not as Text elements.
\o Select the \gui {Group layers} check box to export each top-level
group as a merged QML Image element.
\o Select the \gui {Export hidden} check box to export hidden layers
and to set their visibility property to hidden.
\o Deselect the \gui {Export QML} check box if you have modified the
QML document in \QC, but still want to re-export graphical assets.
\o Click \gui Export.
\endlist
The QML file is saved to the location that you specified. In \QC, choose
\gui {File > Open File or Project} to open the QML file.
\note Existing files are replaced without warning.
\section1 Exporting from GIMP to QML
\image qml-export-gimp.png
The script has been tested to work on GIMP 2. You can download GIMP 2 from
\l{http://www.gimp.org/downloads/}{GIMP Downloads}.
To use the export script on Microsoft Windows, you also need to install the
GIMP Python extension (Python, PyCairo, PyGobject, PyGTK). However, GIMP is
not officially supported on Windows, so we cannot guarantee that this will
work.
\list 1
\o On Microsoft Windows, you must first add Python support to your GIMP
installation, as instructed in
\l {http://www.gimpusers.com/tutorials/install-python-for-gimp-2-6-windows}
{Tutorial: Installing Python for GIMP 2.6 (Windows)}.
\o Download the export script, \e qmlexporter.py, from
\l{http://qt.gitorious.org/qt-labs/gimp-qmlexporter/trees/master}
{Gitorious}.
\note Read the INSTALL.txt in the repository for latest information
about the script.
\o Copy the export script to the plug-ins directory in the GIMP
installation directory.
\o Check the properties of the file to make sure that it is executable.
On Linux, run the following command: \c {chmod u+rx}
\o Restart GIMP to have the export command added to the \gui File menu.
\o Choose \gui {File > Export to QML} to export the design to a QML
file.
\o In the \gui {Export Layers to a QML Document} dialog, enter a name
and location for the QML file, and click \gui Export.
\endlist
The QML file is saved to the location that you specified. In \QC, choose
\gui {File > Open File or Project} to open the QML file.
\note Existing files are replaced without warning.
*/
/****************************************************************************
**
** This file is part of Qt Creator
**
** Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies).
**
** Contact: Nokia Corporation (qt-info@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 qt-info@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 quick-application-logic.html
\page creator-qml-modules-with-plugins.html
\nextpage creator-using-qt-designer.html
\title Using QML Modules with Plugins
QML modules may use plugins to expose components defined in C++ to QML
applications. \QC cannot load the plugins to determine the details of
the contained components, and therefore, the modules must provide extra type
information for code completion and the semantic checks to work correctly.
When you write a QML module or use QML from a C++ application you typically
register new types with
\l{http://doc.qt.nokia.com/4.8/qdeclarativeengine.html#qmlRegisterType}
{qmlRegisterType} or expose some class instances with
\l{http://doc.qt.nokia.com/4.8/qdeclarativecontext.html#setContextProperty}
{setContextProperty}. The \QC C++ code model now scans for these calls and
tells the QML code model about them. This means that properties are
displayed during code completion and the JavaScript code checker does not
complain about unknown types. However, this works only when the source code
is available, and therefore, you must explicitly generate type information
for QML modules with plugins before distributing them.
Ideally, QML modules have a \c{plugins.qmltypes} file in the same directory
as the \c qmldir file. The \c qmltypes file contains a description of the
components exported by the module's plugins and is loaded by \QC when the
module is imported.
For Qt 4.8 and later, one or more \c qmltypes files can be listed in the
\c qmldir file under the \c typeinfo header. These files will be read in
addition to \c{plugins.qmltypes}. For more information, see
\l{http://doc.qt.nokia.com/4.8/qdeclarativemodules.html#writing-a-qmldir-file}
{Writing a qmldir File}.
\section1 Generating qmltypes Files
You can create and edit \c qmltypes files manually, but you are recommended
to use the \c qmlplugindump tool shipped with Qt 4.8 and later to generate
them automatically. For earlier versions of Qt, you can compile a version
of the tool called \c qmldump from the sources in
\c{<QtCreator>/share/qtcreator/qml/qmldump} if the Qt version contains
private headers.
Once you have obtained qmlplugindump for the Qt version the QML module's
plugins were compiled with, run the following command to load My.Module
version 1.0 from \c{/import/path/my/module} including all its plugins and
output a description of the plugins' types to
\c{/import/path/my/module/plugins.qmltypes}:
\code
qmlplugindump My.Module 1.0 /import/path > /import/path/my/module/plugins.qmltypes
\endcode
You can safely ignore the debug output.
\section1 Dumping Plugins Automatically
If a module with plugins lacks the \c qmltypes file, \QC tries to generate
a temporary file itself by running the \c qmldump program in the background.
However, this automatic dumping is a fallback mechanism with many points of
failure and you cannot rely upon it.
*/
/****************************************************************************
**
** This file is part of Qt Creator
**
** Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies).
**
** Contact: Nokia Corporation (qt-info@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 qt-info@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 quick-scalable-image.html
\page quick-screens.html
\nextpage quick-animations.html
\title Creating Screens
You can use predefined QML elements and your own components to create
screens. Typically, the main qml file in a Qt Quick project specifies the
main window of an application.
\if defined(qcmanual)
The QML files in the project folder are displayed in \gui {QML Components}
in the \gui Library pane.
\endif
You can also use ready-made Qt Quick Components that allow you to create
screens with a native look and feel for a particular target platform. You
can install the components as