qtcreator.qdoc

    combobox named \gui Thread in the debugger's status bar can be used to
    switch from one thread to another. The \gui Stack view adjusts itself
    accordingly.


    \section1 Viewing Modules and Source Files

    The \gui{Modules} view and \gui{Source Files} views display information
    that the debugger plugin has about modules and source files included in
    the project. The \gui{Modules} view lists the modules in the project and
    symbols within the modules. In addition, it indicates where the module
    was loaded.

    The \gui{Source Files} view lists all the source files included in the project.
    If you cannot step into an instruction, you can check whether the source file is
    actually part of the project, or whether it was compiled
    elsewhere. The view shows the path to each file in the file system.

    By default, the \gui{Modules} view and \gui{Source Files} view are hidden.


    \section1 Viewing Disassembled Code and Register State

    The \gui{Disassembler} view displays disassembled code for the current
    function. The \gui{Registers} view displays the current state of the CPU's
    registers.

    The \gui{Disassembler} view and the \gui{Registers} view are both useful
    for low-level commands for checking single instructions, such as \gui{Step Into}
    and \gui{Step Over}. By default, both \gui{Disassembler} and
    \gui{Registers} view are hidden.

    \section1 Locals and Watchers

    Whenever a program stops under the control of the debugger, it retrieves
    information about the topmost stack frame and displays it in the
    \gui{Locals and Watchers} view. The \gui{Locals and Watchers} view
    typically includes information about parameters of the function in that
    frame as well as the local variables.

    \image qtcreator-watcher.png "Locals and Watchers view"

    Compound variables of struct or class type are displayed as
    expandable in the view. Expand entries to show
    all members. Together with the display of value and type, you can
    examine and traverse the low-level layout of object data.


    \table
        \row
            \i  \bold{Note:}

        \row
            \i  Gdb, and therefore Qt Creator's debugger works for optimized
                builds on Linux and Mac OS X. Optimization can lead to
                re-ordering of instructions or removal of some local variables,
                causing the \gui{Locals and Watchers} view to show unexpected
                data.
        \row
            \i  The debug information provided by gcc does not include enough
                information about the time when a variable is initialized.
                Therefore, Qt Creator can not tell whether the contents of a
                local variable contains "real data", or "initial noise". If a
                QObject appears uninitialized, its value is reported as
                \gui {not in scope}. Not all uninitialized objects, however, can be
                recognized as such.
    \endtable


    The \gui{Locals and Watchers} view also provides access to the most
    powerful feature of the debugger: comprehensive display of data belonging
    to Qt's basic objects.

    To enable Qt's basic objects data display feature:
    \list
       \o  Select \gui Tools > \gui {Options...} > \gui Debugger >
           \gui{Debugging Helper} and check the \gui{Use Debugging Helper}
           checkbox.
       \o  The \gui{Locals and Watchers} view is reorganized to provide a
           high-level view of the objects.
    \endlist

    For example, in case of QObject, instead of displaying a pointer to some
    private data structure, you see a list of children, signals and slots.

    Similarly, instead of displaying many pointers and integers, Qt Creator's
    debugger displays the contents of a QHash or QMap in an orderly manner.
    Also, the debugger displays access data for QFileInfo and provides
    access to the "real" contents of QVariant.

    You can use the \gui{Locals and Watchers} view to change the contents of
    variables of simple data types, for example, \c int or \c float when the
    program is interrupted. To do so, click the \gui Value column, modify
    the value with the inplace editor, and press \key Enter (or \key Return).

    \note The set of watched items is saved in your session.

*/


/*!
    \contentspage index.html
    \previouspage creator-debugging-cpp.html
    \page creator-debugging-example.html
    \nextpage creator-debug-mode.html

    \title Debugging the Example Application

    This section uses the \l{Creating a Qt C++ Application}{TextFinder} example to
    illustrate how to debug applications in the \gui Debug mode. TextFinder
    reads a text file into
    QString and then displays it with QTextEdit.
    To look at the example QString, \c{line}, and see the
    stored data, place a breakpoint and view the QString object
    data, as follows:

    \list 1
        \o Click in between the line number and the window border on the line
        where we invoke \l{http://doc.trolltech.com/qtextedit.html#plainText-prop}{setPlainText()}
        to set a breakpoint.

        \image qtcreator-setting-breakpoint1.png

        \o Select \gui{Debug > Start Debugging > Start Debugging} or press \key{F5}.


        \o To view the breakpoint, click the \gui{Breakpoints} tab.

        \image qtcreator-setting-breakpoint2.png

        \o To remove a breakpoint, right-click it and select \gui{Delete Breakpoint}.


        \o To view the contents of \c{line}, go to the \gui{Locals and
    Watchers} view.

        \image qtcreator-watcher.png

    \endlist

    Modify the \c{on_findButton_clicked()} function to move back to
    the start of the document and continue searching once the cursor hits the
    end of the document. Add the following code snippet:

    \code
    void TextFinder::on_findButton_clicked()
    {
        QString searchString = ui->lineEdit->text();

        QTextDocument *document = ui->textEdit->document();
        QTextCursor cursor = ui->textEdit->textCursor();
        cursor = document->find(searchString, cursor,
            QTextDocument::FindWholeWords);
        ui->textEdit->setTextCursor(cursor);

        bool found = cursor.isNull();

        if (!found && previouslyFound) {
            int ret = QMessageBox::question(this, tr("End of Document"),
            tr("I have reached the end of the document. Would you like "
            "me to start searching from the beginning of the document?"),
            QMessageBox::Yes | QMessageBox::No, QMessageBox::Yes);

            if (ret == QMessageBox::Yes) {
                cursor = document->find(searchString,
                    QTextDocument::FindWholeWords);
                ui->textEdit->setTextCursor(cursor);
            } else
                return;
        }
        previouslyFound = found;
    }
    \endcode

    If you compile and run the above code, however, the application does not
    work correctly due to a logic error. To locate this logic error, step
    through the code using the following buttons:

    \image qtcreator-debugging-buttons.png

 */


/*!
    \contentspage index.html
    \previouspage creator-debugger-engines.html
    \page creator-debugging-helpers.html
    \nextpage creator-debugging-qml.html

    \title Using Debugging Helpers

    \section1 Debugging Helper Library with C++

    While debugging, Qt Creator dynamically loads a helper library into your
    program. This helper library enables Qt Creator to pretty print Qt and STL
    types. The Qt SDK package already contains a prebuilt debugging helper
    library. To create your own debugging helper library, select \gui{Tools} >
    \gui{Options...} > \gui{Qt4} > \gui{Qt Versions}. As the internal data
    structures of Qt can change between versions, the debugging helper
    library is built for each Qt version.


    \section1 Debugging Helper Library with Python

    With the gdb Python version, you can
    use debugging helpers also for user defined types. To do so,
    define one Python function per user defined type in \c{.gdbinit}.

    The function name has to be qdump__NS__Foo, where NS::Foo is the class
    or class template to be examined. Nested namespaces are possible.

    The debugger plugin calls this function whenever you want to
    display an object of this type. The function is passed the following
    parameters:
    \list
       \o  \c d of type \c Dumper
       \o  \c item of type \c Item
    \endlist

    The function has to feed the Dumper object with certain information
    which is used to build up the object and its children's display in the
    \gui{Locals and Watchers} view.


    Example:

    \code
    def qdump__QVector(d, item):
        d_ptr = item.value["d"]
        p_ptr = item.value["p"]
        alloc = d_ptr["alloc"]
        size = d_ptr["size"]

        check(0 <= size and size <= alloc and alloc <= 1000 * 1000 * 1000)
        check(d_ptr["ref"]["_q_value"] > 0)

        innerType = item.value.type.template_argument(0)
        d.putItemCount(size)
        d.putNumChild(size)
        if d.isExpanded(item):
            p = gdb.Value(p_ptr["array"]).cast(innerType.pointer())
            d.beginChildren([size, 2000], innerType)
            for i in d.childRange():
                d.safePutItem(Item(p.dereference(), item.iname, i))
                p += 1
            d.endChildren()
    \endcode

    \section2 Item Python Class

    The Item Python class is a thin wrapper around values corresponding to one
    line in the \gui{Locals and Watchers} view. The Item members are as follows :

    \list

    \o \gui{__init__(self, value, parentiname, iname, name = None)} - A
       constructor. The object's internal name is created by concatenating
       \c parentiname and \c iname. If \c None is passed as \c name, a
       serial number is used.

    \o \gui{value} - An object of type gdb.Value representing the value to
        be displayed.

    \o \gui{iname} - The internal name of the object, constituting a dot-separated
    list of identifiers, corresponding to the position of the object's
    representation in the view.

    \o \gui{name} - An optional name. If given, is used in the
    \gui{name} column of the view. If not, a simple number in brackets
    is used instead.

    \endlist


    \section2 Dumper Python Class

    For each line in the \gui{Locals and Watchers} view, a string like the
    following needs to be created and channeled to the debugger plugin.
    \code
    "{iname='some internal name',
      addr='object address in memory',
      name='contents of the name column',
      value='contents of the value column',
      type='contents of the type column',
      numchild='number of children',        // zero/nonzero is sufficient
      childtype='default type of children', // optional
      childnumchild='default number of grandchildren', // optional
      children=[              // only needed if item is expanded in view
         {iname='internal name of first child',
          ... },
         {iname='internal name of second child',
          ... },
         ...
      ]}"
    \endcode

    While in theory, you can build up the entire string above manually, it is
    easier to employ the Dumper Python class for that purpose. The Dumper
    Python class contains a complete framework to take care of the \c iname and
    \c addr fields, to handle children of simple types, references, pointers,
    enums, known and unknown structs as well as some convenience methods to
    handle common situations.

    The Dumper members are the following:

    \list

    \o \gui{__init__(self)} - Initializes the output to an empty string and
        empties the child stack.

    \o \gui{put(self, value)} - Low level method to directly append to the
        output string.

    \o \gui{putCommaIfNeeded(self)} - Appends a comma if the current output
        ends in '}', '"' or ']' .

    \o \gui{putField(self, name, value)} - Appends a comma if needed, and a
         name='value' field.

    \o \gui{beginHash(self)} - Appends a comma if needed and a '{', marking
        the begin of a set of fields.

    \o \gui{endHash(self)} - Appends a '}', marking the end of a set of
        fields.

    \o \gui{beginItem(self, name)} - Starts writing a field by writing \c {name='}.

    \o \gui{endItem(self)} - Ends writing a field by writing \c {'}.

    \o \gui{beginChildren(self, numChild_ = 1, childType_ = None, childNumChild_ = None)}
        - Starts writing a list of \c numChild children, with type
        \c childType_ and \c childNumChild_ grandchildren each. If \c numChild_
        is a list of two integers, the first one specifies the actual number
        of children and the second the maximum number of children to print.

    \o \gui{endChildren(self)} - Ends writing a list of children.

    \o \gui{childRange(self)} - Return the range of children specified in
        \c beginChildren.

    \o \gui{putItemCount(self, count)} - Appends a field  \c {value='<%d items'}
        to the output.

    \o \gui{putEllipsis(self)} - Appends fields
        \c {'{name="<incomplete>",value="",type="",numchild="0"}'}. This is
        automatically done by \c endChildren if the number of children to
        print is smaller than the number of actual children.

    \o \gui{putName(self, name)} - Appends a \c {name='...'} field.

    \o \gui{putType(self, type)} - Appends a field \c {type='...'} unless the
        \a type coincides with the parent's default child type.

    \o \gui{putNumChild(self, numchild)} - Appends a field \c {numchild='...'}
        unless the \c numchild coincides with the parent's default child numchild
        value.

    \o \gui{putValue(self, value, encoding = None)} - Append a file \c {value='...'},
        optionally followed by a field \c {valueencoding='...'}. The \c value
        needs to be convertible to a string entirely consisting of
        alphanumerical values. The \c encoding parameter can be used to
        specify the encoding in case the real value had to be encoded in some
        way to meet the alphanumerical-only requirement.
        Currently the following encodings are supported:

        \list
            \o 0: unencoded 8 bit data, interpreted as Latin1.

            \o 1: base64 encoded 8 bit data, used for QByteArray,
                double quotes are added.

            \o 2: base64 encoded 16 bit data, used for QString,
                double quotes are added.

            \o 3: base64 encoded 32 bit data,
                double quotes are added.

            \o 4: base64 encoded 16 bit data, without quotes (see 2)

            \o 5: base64 encoded 8 bit data, without quotes (see 1)

            \o 6: %02x encoded 8 bit data (as with \c QByteArray::toHex),
                double quotes are added.

            \o 7: %04x encoded 16 bit data (as with \c QByteArray::toHex),
                double quotes are added.
        \endlist

    \o \gui{putStringValue(self, value)} - Encodes a QString and calls
        \c putValue with the correct \c encoding setting.

    \o \gui{putByteArrayValue(self, value)} - Encodes a QByteArray and calls
        \c putValue with the correct \c encoding setting.

    \o \gui{isExpanded(self, item)} - Checks whether the item with the
        internal name \c item.iname is expanded in the view.

    \o \gui{isExpandedIName(self, iname)} - Checks whether the item with the
        internal name \c iname is expanded in the view.

        \o \gui{putIntItem(self, name, value)} - Equivalent to:
        \code
        self.beginHash()
        self.putName(name)
        self.putValue(value)
        self.putType("int")
        self.putNumChild(0)
        self.endHash()
        \endcode

        \o \gui{putBoolItem(self, name, value)} - Equivalent to:
        \code
        self.beginHash()
        self.putName(name)
        self.putValue(value)
        self.putType("bool")
        self.putNumChild(0)
        self.endHash()
        \endcode

    \o \gui{pushOutput(self)} - Moves the output string to a safe location
        from with it is sent to the debugger plugin even if further operations
        raise an exception.

    \o \gui{putCallItem(self, name, item, func)} -
        Uses gdb to call the function \c func on the value specified by
        \a {item.value} and output the resulting item. This function is
        not available when debugging core dumps and it is not available
        on the Symbian platform due to restrictions imposed by AppTRK.

    \o \gui{putItemHelper(self, item)} - The "master function", handling
        basic types, references, pointers and enums directly, iterates
        over base classes and class members of compound types and calls
        \c qdump__* functions whenever appropriate.

        \o \gui{putItem(self, item)} - Equivalent to:
        \code
        self.beginHash()
        self.putItemHelper(item)
        self.endHash()
        \endcode

    \o \gui{safePutItemHelper(self, item)} - Calls \c putItemHelper(self, item).
        If an exception is raised, catches it, and replaces all output produced by
        \c putItemHelper with the output of:
        \code
        self.putName(item.name)
        self.putValue("<invalid>")
        self.putType(str(item.value.type))
        self.putNumChild(0)
        self.beginChildren()
        self.endChildren()
        \endcode


    \o \gui{safePutItem(self, item)} - Equivalent to:
        \code
        self.beginHash()
        self.safePutItemHelper(item)
        self.endHash()
        \endcode

    \endlist

*/


/*!
    \contentspage index.html
    \previouspage creator-project-qmake.html
    \page creator-project-cmake.html
    \nextpage creator-project-generic.html

    \title Setting Up a CMake Project

    CMake is an alternative to qmake for automating the generation of makefiles.
    It controls the software compilation process by using simple configuration
    files, called CMakeLists.txt files. CMake generates native makefiles and
    workspaces that you can use in the compiler environment of your choice.

    Since Qt Creator 1.1, CMake configuration files are supported.
    Qt Creator 1.3 supports the Microsoft Toolchain if the CMake version
    is at least 2.8.

    \section1 Setting the Path for CMake

    You can set the path for the \c CMake executable in \gui{Tools} >
    \gui{Options...} > \gui{CMake} > \gui{CMake}.

    \image qtcreator-cmakeexecutable.png

    \note Before you open a \c CMake project it is necessary to modify the
    \c{PATH} environment variable to include the bin folders of \c mingw and
    Qt Creator in the SDK.

    For instance, if you have the Qt Creator SDK installed in your C drive,
    use the following command to set the environment variables in
    the command line prompt:
    \code
    set PATH=C:\qtsdk\mingw\bin;C:\qtsdk\qt\bin;
    \endcode
    Then start Qt Creator by typing:
    \code
    C:\qtsdk\bin\qtcreator.exe
    \endcode

    \section1 Opening CMake Projects

    To open a \c CMake project:
    \list 1
        \o  Select \gui{File} > \gui{Open File or Project...}.
        \o  Select the \c{CMakeLists.txt} file from your \c CMake project.
    \endlist

    A wizard guides you through the rest of the process.

    \note If the \c CMake project does not have an in-place build, Qt Creator
    lets you specify the directory in which the project is built
   (\l{glossary-shadow-build}{shadow build}).

    \image qtcreator-cmake-import-wizard1.png

    The screenshot below shows how you can specify command line arguments to
    \c CMake for your project.

    \image qtcreator-cmake-import-wizard2.png

    Normally, there is no need to pass any command line arguments for projects
    that are already built, as \c CMake caches that information.


    \section1 Building CMake Projects

    Qt Creator builds \c CMake projects by running \c make, \c mingw32-make, or
    \c nmake depending on your platform. The build errors and warnings are
    parsed and displayed in the \gui{Build Issues} output pane.

    By default, Qt Creator builds the \bold{all} target. You can specify which
    targets to build in \gui{Project} mode, under \gui{Build Settings}.

    \image qtcreator-cmake-build-settings.png

    Qt Creator supports multiple build configurations. The build
    directory can also be modified after the initial import.

    \section1 Running CMake Projects
    Qt Creator automatically adds \gui{Run Configurations} for all targets
    specified in the \c CMake project file.

    Known issues for the current version can be found
    \l{Known Issues of version 1.3.84}{here}.


    \section1 Adding External Libraries to a CMake Project

    Through external libraries Qt Creator can support code completion and
    syntax highlighting as if they were part of the current project or the Qt
    library.

    Qt Creator detects the external libraries using the \c FIND_PACKAGE()
    macro. Some libraries come with the CMake installation. You can find those
    in the \bold{Modules} directory of your CMake installation.

    \note If you provide your own libraries, you also need to provide your own
    \c FindFoo.cmake file. For more information, see
    \l{http://vtk.org/Wiki/CMake_FAQ#Writing_FindXXX.cmake_files}{CMake FAQ}.

    Syntax completion and highlighting work once your project successfully
    builds and links against the external library.
*/


/*!
    \contentspage index.html
    \previouspage creator-project-cmake.html
    \page creator-project-generic.html
    \nextpage creator-developing-maemo.html

    \title Setting Up a Generic Project

    Qt Creator supports generic projects, so you can import existing projects
    that do not use qmake or CMake and Qt Creator ignores your build system.

    Generic project support allows you to use Qt Creator as a code editor. You
    can change the way your project is built by modifying the \c make command
    in the \gui{Projects} mode under \gui{Build Settings}.

    When you import a project, Qt Creator creates the following files that
    allow you to specify which files belong to your project and which include
    directories or defines you want to pass to your compile:
    \tt{.files}, \tt{.includes}, and \tt{.config}.


    \section1 Importing a Generic Project

    To import an existing generic project:
    \list 1
        \o Select \gui File > \gui{New File or Project...} >
           \gui{Other Project} > \gui{Import Existing Project}.
        \o In \gui{Import Existing Project}, enter the project name
           and select the location of the project file you want to import.

           Qt Creator automatically generates the following files in the
           project directory:
           \list
               \o \l{Specifying Files}{.files}
               \o \l{Specifying Include Paths}{.includes}
               \o \l{Specifying Defines}{.config}
               \o .creator
           \endlist
    \endlist

    When the project is successfully imported, Qt Creator creates the project
    tree in the sidebar.

    After importing a generic project into Qt Creator, open it by selecting the
    \tt{.creator} file.


    \section1 Working with Generic Project Files

    For a generic project, you have to manually specify which files belong to
    your project and which include directories or defines you want to pass to
    your compiler.


    \section1 Specifying Files

    The list of files for a generic project is specified in the \tt{.files}
    file. When you first create a generic project, Qt Creator adds any
    files it recognizes to your project.

    To add or remove files, edit the \tt{.files} file in Qt Creator.
    Qt Creator recreates your project tree when you save the \tt{.files} file.
    Alternatively, you can add and remove files using the context menu in the
    project tree.

    If you frequently need to update the \tt{.files} file, you can do so
    efficiently by using a script that updates the file for you. If the file
    is modified externally, you have to restart Qt Creator for the changes to
    take effect.

    To update the \tt{.files} on the \gui git repository use the following
    script:
    \code
    git ls-files *.cpp *.h > MyProject.files
    \endcode

    \section1 Specifying Include Paths

    The include paths are specified in the \tt{.includes} file, one include
    path per line. The paths can be either absolute or relative to the
    \tt{.includes} file.

    \section1 Specifying Defines

    The defines are specified in the \tt{.config} file. The \tt{.config} file is
    a regular C++ file, prepended to all your source files when they are parsed.
    Only use the \tt{.config} file to add lines as in the example below:

    \code
    #define NAME value
    \endcode


    \section1 Creating a Run Configuration

    Qt Creator cannot automatically determine which executable to run.

    In the \gui{Projects} mode under \gui{Run Settings}, define the executable
    file to run:
    \list 1
        \o Click \gui Add and select \gui{Custom Executable}.
        \o Define the configuration name, the location of the executable, any
           additional arguments and the working directory.
    \endlist

*/



/*!

    \contentspage index.html
    \previouspage creator-build-dependencies.html
    \page creator-visual-editor.html
    \nextpage creator-usability.html

    \title Developing Qt Quick Applications

    You can either create Qt Quick projects from scratch or import them to
    Qt Creator. For example, you can import and run the
    \l {http://qt.nokia.com/doc/4.7-snapshot/qdeclarativeexamples.html} {QML examples and demos}
    to learn how to use various aspects of QML.

    You can use the code editor (\gui Edit mode) or the visual editor
    (\gui Design mode) to develop Qt Quick applications.

    \note The \QMLD visual editor is provided as an experimental plugin that you must
    enable to be able to edit QML files in the \gui Design mode. Enabling the
    visual editor can negatively affect the overall stability of Qt Creator.

    To enable or disable the \QMLD visual editor, select
    \gui {Help > About Plugins... > Qt Quick > QmlDesigner}. You must restart Qt Creator
    to enable or disable the visual editor.

    \section1 Creating Qt Quick Projects

    Select \gui {File > New File or Project > Qt Quick Project > Qt QML Application}.

    \QMLD creates the following files:

    \list

    \o .qmlproject project file defines that all QML, JavaScript, and image
    files in the project folder belong to the project. Therefore, you do not
    need to individually list all the files in the project.

    \o .qml file defines an element, such as a component, screen, or the whole
    application UI.

    \endlist

    The \c import statement in the beginning of the .qml file specifies the
    \l {http://qt.nokia.com/doc/4.7-snapshot/qdeclarativemodules.html} {Qt modules}
    to import to \QMLD. Each Qt module contains a set of default elements.
    Specify a version to get the features you want.

    To use JavaScript and image files in the application, copy them to the
    project folder.

    To import a QML project to Qt Creator, select
    \gui {File > New File or Project > Qt Quick Project > Import Existing Qt QML Directory}.

    \section1 Designing Application UI

    One .qml file can define a component, screen, or the whole application.

    \section2 Creating Components

    A QML 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 \gui Library items to create components. Drag and drop
    the following QML elements to the editor and modify their properties in the \gui Properties pane:

    \list

        \o \l{http://qt.nokia.com/doc/4.7-snapshot/qml-borderimage.html}{Border Image}
        uses an image as a border or background.
        \o \l{http://qt.nokia.com/doc/4.7-snapshot/qml-image.html}{Image}
        adds a bitmap to the scene. You can stretch and tile images.
        \o \l{http://qt.nokia.com/doc/4.7-snapshot/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://qt.nokia.com/doc/4.7-snapshot/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://qt.nokia.com/doc/4.7-snapshot/qml-text.html}{Text}
        adds formatted read-only text.
        \o \l{http://qt.nokia.com/doc/4.7-snapshot/qml-textedit.html}{Text Edit}
        adds a single line of editable formatted text that can be validated.
        \o \l{http://qt.nokia.com/doc/4.7-snapshot/qml-textinput.html}{Text Input}
        adds a single line of editable plain text that can be validated.

    \endlist

    You can use QML to add properties for a component in the code editor.

    The following sections describe some use cases for the QML elements.

    \section3 Creating Buttons

    To create a button component:

    \list 1

        \o Select \gui {File > New File or Project > Qt > Qt QML File} 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 Double-click the file to open it in the code editor.

        \o Click \gui {Design} to edit the file in the visual editor.

        \o Drag and drop a \gui Rectangle from the \gui Library pane to the scene.

        \o In the \gui Properties pane, modify the appearance of the button.

        \list a

        \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 button to align the text to the
        center of the button.

        \o Click \gui {Geometry}, and then click the
        \inlineimage qmldesigner-anchor-fill-screen.png
        button to anchor the text to the whole button area.

        \endlist

        \o Click \gui Edit to edit the \c width and \c height properties of the button
        to fit the button size.

        \o Press \key {Ctrl+S} to save the button.

        \image qmldesigner-button.png "Button component"

        \o Click the \gui Run button to view the button in the QML viewer.

    \endlist

    To create a graphical button that scales beautifully without using vector graphics,
    use the \l{http://qt.nokia.com/doc/4.7-snapshot/qml-borderimage.html}{Border Image}
    element.

    \section3 Creating Scalable Buttons and Borders

    You can use the \l{http://qt.nokia.com/doc/4.7-snapshot/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 > Qt > Qt QML File} 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:

        \code

        Item {

        }

        \endcode

        \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 Click \gui Edit to specify properties for the \gui Item, as
        illustrated by the following code snippet:

        \code

        property string text: ""
        property int fontSize: 44

        signal clicked

        \endcode

        \o In the \gui Navigator view, select \gui borderimage1 to specify
        settings for it in the \gui Properties pane:

        \list a

            \o In the \gui Source field, select the image file for the
            button, for example button_up.png.

            \o In the \gui Left, \gui Right, \gui Top, and \gui Bottom fields,
            enter 32 to set the margins for the image.

            \o Click \gui {Geometry}, and then click the
            \inlineimage qmldesigner-anchor-fill-screen.png
            button to anchor the border image to the \gui Item.

            \o Click \gui Advanced, and 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 {!mousearea1.pressed}.

        \endlist

        \o Select \gui borderimage2 to specify similar settings for it:

        \list a

            \o In the \gui Source field, select the image file for the
            button when it is clicked, for example button_down.png.

            \o In the \gui Left, \gui Right, \gui Top, and \gui Bottom fields,
            enter 32 to set the margins for the image.

            \o Click \gui {Geometry}, and then click the
            \inlineimage qmldesigner-anchor-fill-screen.png
            button to anchor the border image to the \gui Item.

            \o Click \gui Advanced, and set the following epression for
            \gui Visibility, to specify that the the image is visible
            when the mouse is pressed down: \c {mousearea1.pressed}.

        \endlist


        \o Select \gui Text 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 In the \gui Size field, select \gui {Pixel} 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 Select the \gui Smooth check box to enable smooth text
            rendering.

            \o Click \gui {Geometry}, 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()}.

        \o Click the \gui Run button to view the button in the QML viewer.

        \endlist

    \section2 Creating Screens

    You can use the \gui Library items and your own components to create screens.

    You can create the following types of views to organize items provided by
    \l{http://qt.nokia.com/doc/4.7-snapshot/qdeclarativemodels.html}{data models}:

    \list

        \o \l{http://qt.nokia.com/doc/4.7-snapshot/qml-gridview.html}{Grid View}