path: root/doc/src/tutorials/declarative.qdoc

/****************************************************************************
**
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
** Contact: Qt Software Information (qt-info@nokia.com)
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** No Commercial Usage
** This file contains pre-release code and may not be distributed.
** You may use this file in accordance with the terms and conditions
** contained in the either Technology Preview License Agreement or the
** Beta Release License Agreement.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 2.1 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU Lesser General Public License version 2.1 requirements
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
**
** In addition, as a special exception, Nokia gives you certain
** additional rights. These rights are described in the Nokia Qt LGPL
** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
** package.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 3.0 as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU General Public License version 3.0 requirements will be
** met: http://www.gnu.org/copyleft/gpl.html.
**
** If you are unsure which license is appropriate for your use, please
** contact the sales department at qt-sales@nokia.com.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \page tutorials-declarative-contacts.html
    \startpage {index.html}{Qt Reference Documentation}
    \nextpage {tutorials/declarative/contacts/part1}{Chapter 1}

    \title Declarative UI Tutorial
    \ingroup howto
    \ingroup tutorials
    \brief An introduction to using Qt Declarative UI to put together a
    simple animated application.

    \omit 
    At the time of writing the tutorial Declarative UI was still under
    development.  It is extremely likely that an update will be required
    prior to 4.6 release.
    \endomit

    This tutorial gives an introduction to using the Qt Declarative UI
    animation framework.

    In this process we will learn about some of the basics of using
    Declarative UI, such as

    \list
    \o Basic drawing
    \o States and Transitions
    \o Reuse of components
    \o Models and Views
    \endlist

    An existing knowledge of Qt is not required.

    The tutorial's source code is located in Qt's
    \c examples/declarative/tutorials/contacts directory.
    It is split up into a number of sub directories, and within each
    sub directory the files are numbered in an order of increasing features.

    The code in this example is not compiled, but interpreted at run time.
    This means you should use the duiviewer application provided with
    Qt to run the examples.

    \list
    \o \l{tutorials/declarative/contacts/part1}{Drawing and Animation}
    \o \l{tutorials/declarative/contacts/part2}{Reusing QML Components}
    \o \l{tutorials/declarative/contacts/part3}{Models, Views and Delegates}
    \o \l{tutorials/declarative/contacts/part4}{Other Tricks}
    \endlist
*/

/*!
    \page tutorials-declarative-contacts-part1.html
    \contentspage {Declarative UI Tutorial}{Contents}
    \nextpage {tutorials/declarative/contacts/part2}{Chapter 2}
    \example tutorials/declarative/contacts/part1
    \title Drawing and Animation
    \tableofcontents

    The first part of this tutorial covers basic drawing of elements on the
    screen and causing them to animate.  The file 1_Drawing_and_Animation.qml
    loads and displays each of the five stages of this tutorial in a single
    window.  For now you don't need to worry about the contents of
    1_Drawing_and_Animation.qml.

    \section1 Drawing

    In this first chapter we will build a button that indicates something
    can be removed and asks for confirmation.  When clicked it will expand
    from a small button with a trash can icon, to a wide button with a
    confirm icon on the left, the text "Remove" in the middle, and a
    cancel icon on the right.

    \image declarative-removebutton.png

    Because Declarative UI is declarative, you don't pass instructions on
    what to paint in a sequential manner as you may be used to.  Instead
    elements and how they appear on the screen are declared in much the
    same was as elements on a web page are declared.

    We will start by drawing a simple red rectangle with rounded corners.

    \image declarative-roundrect.png

    \code
    <Rect id="removeButton"
        width="30" height="30"
        color="red"
        radius="5"/>
    \endcode

    This is the simplest of QML components.  It describes a rectangle with
    some simple properties.  In QML all components start with a capital
    letter, and their properties with lower case letters.  Properties
    can either be declared as XML attributes or as children of the 
    component element.  The above rectangle could equally be written
    
    \code
    <Rect id="removeButton" color="red">
        <width>30</width>
        <height>30</height>
        <radius>5</radius>
    </Rect>
    \endcode

    The rectangle component is one of the more simple QML components.  Apart
    from the properties all QML components share, it has the properties

    \list
    \o color - The background color of the rectangle
    \o tintColor - The overlay color of the rectangle
    \o gradientColor - The color at the base of the rectangle to blend upwards
    \o pen - The description of how to draw the border of the rectangle
    \o radius - The corner radius used to draw rounded rectangles.
    \endlist

    \omit
    For more information on the Rect element, see: TODO
    \endomit

    There are also a number of properties all QML components share.  To see
    a full description of the base QML item, see {QFxItem}.  The rectangle
    drawn in the above code uses the properties;

    \list
    \o id - An identifier of the component
    \o width - the width of the component when drawn
    \o height - the height of the component when drawn
    \endlist

    All items have properties to handle their position on the screen, size,
    clipping, rotation, scale and layout in regards to other elements.  In
    the current example width and height refer to how large to draw the
    rectangle.  The identifier allows other components to refer to the
    identified component.

    Another important property of a component is its children.  All components
    have a list of children.  When drawing, first any components earlier
    siblings are drawn, then the component, then any of the components children.

    \section1 Layout

    The next step of the tutorial adds an image over the rectangle.

    \image declarative-removebutton-close.png

    \code
    <Rect id="removeButton"
        width="30" height="30"
            color="red"
        radius="5">
        <Image id="trashIcon"
            width="22" height="22"
            anchors.right="{parent.right}" anchors.rightMargin="4"
            anchors.verticalCenter="{parent.verticalCenter}"
            src="../shared/pics/trash.png"/>
    </Rect>
    \endcode

    The trashIcon image is added as a child of the Rectangle.  In this case
    the <children> tag isn't used because the default property of the
    Rect component is its children.  Some elements don't often have children
    and use some other default component, when this is the case its possible
    to explicitly list the sub component as a child as follows:

    \code
    <Rect id="removeButton"
        width="30" height="30"
            color="red"
        radius="5">
        <children>
            <Image id="trashIcon"
                width="22" height="22"
                anchors.right="{parent.right}" anchors.rightMargin="4"
                anchors.verticalCenter="{parent.verticalCenter}"
                src="../shared/pics/trash.png"/>
        </children>
    </Rect>
    \endcode

    The Image element allows loading an image file for display.  The source
    specified is a URL, and in this case refers to a portable network graphics
    file in a relative directory to where the QML file was loaded from.

    Also new in this code is the use of anchors.  In QML components can either
    have their position and size specified explicitly using x, y, width
    and height, or they can instead specify the size and position in relation
    to elements either parent or sibling elements.  The Image component uses
    a combination of both styles.  It has a fixed size, but specifies its
    position to align to the right of its parent and for its vertical center
    to align with the vertical center of its parent.  The braces "{}" are
    used to indicate that the value is not a static value, but instead a
    binding to an expression.  In this case it binds to the parent
    element, which is a special identifier that always refers to the
    parent component of a component.  The removeButton identifier can
    be used interchangeably with parent in this case, however it must
    always be a parent or sibling.  Because of this its most common to
    use the parent identifier as it makes later refactoring of code easier.

    Anchors are most useful when the size of items might change based on
    the component state or contents.

    \omit
    See TODO for full list of anchor properties.
    \endomit

    At this point the initial state of the RemoveButton is complete.  A small
    rounded rectangle with a trash icon.  The component also needs a
    description of its open state:

    \image declarative-removebutton-open.png

    This is a wider rectangle with two images and some text.  The code to
    draw this state of the button could be written as follows:

    \code
    <Rect id="removeButton"
        width="230" height="30"
        color="red"
        radius="5">
        <Image id="cancelIcon"
            width="22" height="22"
            anchors.right="{parent.right}" anchors.rightMargin="4"
            anchors.verticalCenter="{parent.verticalCenter}"
            src="../shared/pics/cancel.png"/>
        <Image id="confirmIcon"
            width="22" height="22"
            anchors.left="{parent.left}" anchors.leftMargin="4"
            anchors.verticalCenter="{parent.verticalCenter}"
            src="../shared/pics/ok.png"/>
        <Text id="text"
            anchors.verticalCenter="{parent.verticalCenter}"
            anchors.left="{confirmIcon.right}" anchors.leftMargin="4"
            anchors.right="{cancelIcon.left}" anchors.rightMargin="4"
            font.bold="true"
            color="white"
            hAlign="AlignHCenter"
            text="Remove"/>
    </Rect>
    \endcode

    The rectangle with is now wider by 200 pixels.  Also the trashIcon has
    been replaced with the confirm state children.  Normally we wouldn't
    remove the trashIcon when developing an alternate state of the RemoveButton,
    however since this is a tutorial its been done so that its easier to
    understand the alternate state we are aiming for and how it relates to
    transitioning between states.

    We also introduce the Text element, which is used to display read only
    text.  \omit see {Text} for more information on the text element \endomit
    Because we want text to fill the space between the icons, rather than
    a fixed with the left and right anchors are specified instead.  This
    means as the parent removeButton gets wider, so will the text component.
    It also means that if we animate a width change on the removeButton,
    any bindings, that is the values specified by a braced expression such as
    "{parent.left}" will be evaluated and animated as well.

    \section1 Defining States

    When designing a component with multiple states, it should be developed
    with the initial state and the changes that would be made specified
    as an additional state.  Its not possible to add new children to an
    element when changing state, only changing the properties of existing
    children.  This means that all possible child components should be included
    in the initial state, and those that should not be visible in the initial
    state should have their opacity set to zero.  Thus
    for the RemoveButton we specify the starting size of the removeButton
    and hide any items that should not initially be visible.

    The code snippet below shows what the start of the duel state specification
    might look like.

    \code
    <Rect id="removeButton"
        width="30" height="30"
            color="red"
        radius="5">
        <Image id="trashIcon"
            width="22" height="22"
            anchors.right="{parent.right}" anchors.rightMargin="4"
            anchors.verticalCenter="{parent.verticalCenter}"
            src="../shared/pics/trash.png"/>
        <Image id="cancelIcon"
            width="22" height="22"
            anchors.right="{parent.right}" anchors.rightMargin="4"
            anchors.verticalCenter="{parent.verticalCenter}"
            src="../shared/pics/cancel.png"
            opacity="0"/>
    \endcode

    The code above includes components from both states of the RemoveButton,
    but by setting opacity="0" for the cancelIcon it means that the
    components of the second state won't be drawn yet.
    The base state of a component always has an empty name, however new
    states can be added that describe how a component and its children
    should be changed.  For the RemoveButton there is only one non-base state
    required.  In this tutorial we will name it the 'opened' state.

    \code
    <states>
        <State name="opened">
            <SetProperty target="{removeButton}" property="width" value="230"/>
            <SetProperty target="{text}" property="opacity" value="1"/>
            <SetProperty target="{confirmIcon}" property="opacity" value="1"/>
            <SetProperty target="{cancelIcon}" property="opacity" value="1"/>
            <SetProperty target="{trashIcon}" property="opacity" value="0"/>
        </State>
    </states>
    \endcode

    In the opened state the width of the button itself changes from the base
    width of 30 to the new width of 230.  Also the opacity of the children
    are changed so that the trash icon is now hidden and the other elements
    are now visible.

    \section1 Changing States

    To trigger the change we will react to the 'clicked' signal of a
    MouseRegion component.

    \code
    <Image id="trashIcon"
        width="22" height="22"
        anchors.right="{parent.right}" anchors.rightMargin="4"
        anchors.verticalCenter="{parent.verticalCenter}"
        src="../shared/pics/trash.png"
        opacity="1">
        <MouseRegion
            anchors.fill="{parent}"
            onClicked="toggle()"/>
    </Image>
    \endcode

    MouseRegion components handle mouse actions within their geometry.  This
    geometry behaves the same way as painted components, such that children
    cover their parents and later siblings will cover earlier siblings and
    all the children of the earlier sibling, should they overlap.

    When a component has a signal, such as clicked, the action for the signal
    can be specified using on<SignalName>, as is done above.  In this
    case when the clicked signal is emitted by the MouseRegion component,
    a function called toggle() is called.  It might also have been written

    \code
    onClicked="removeButton.state='opened'"
    \endcode

    However in this case we are using a function because it allows multiple
    mouse regions to use the same functionality, and also makes it
    easier to specify complex behavior in response to a signal.

    The toggle() function is a new function specified as part of the remove
    button element.

    \code
    <resources>
        <Script>
            function toggle() {
                print('removeButton.toggle()');
                if (removeButton.state == 'opened') {
                    removeButton.state = '';
                } else {
                    removeButton.state = 'opened';
                }
            }
        </Script>
    </resources>
    \endcode

    Any QML component can have a set of resources specified.  One of those
    resources is any Script that might be needed.   See the
    {QtScript Module}{QtScript Module} for more information on how to write
    script code in Qt.  There are only a couple of additional items to
    note when using Script with QML components.  The first is that it
    is an xml file, that means either CDATA or other forms of escaping
    should be used if special characters are needed.  For example, 
    the expression;

    \code
    if (a && b) {}
    \endcode

    Should either be escaped as:

    \code
    if (a &amp;&amp; b) {}
    \endcode

    or enclosed in a CDATA section as

    \code
    <![CDATA[if (a && b) {}]]>
    \endcode

    The other item to note is that you can refer to identified QML components
    within the script.  Hence the function for our RemoveButton will check
    if the state is already open to determine what the new state should be.

    We also have added a print function.  This isn't required for the button
    to function, but is useful for tracking down possible bugs when
    working with QML.

    See the file RemoveButton4.qml for the full multi-state specification.

    \section1 Animation

    Currently the RemoveButton is function, but snaps between our two states.
    Fortunately making the transition between states smooth is very simple.
    We only need one more bit of code at the end of our removeButton component.

    \code
    <transitions>
        <Transition fromState="*" toState="opened" reversible="true">
            <NumericAnimation properties="opacity,x,width" duration="200"/>
        </Transition>
    </transitions>
    \endcode

    All QML components have a transitions property.  This describes how
    properties of items within the component should change.  In this case
    we specify that if the x, width or opacity of the removeButton or its
    children change due to a change in state, that they should take 200ms
    to complete their transition.

    \omit
        TODO More on types of animation, e.g. ColorAnimation, Behaviors.
    \endomit

    In the next chapter we will show how we can use the remove button in
    other QML components.
*/

/*!
    \page tutorials-declarative-contacts-part2.html
    \contentspage {Declarative UI Tutorial}{Contents}
    \previouspage {tutorials/declarative/contacts/part1}{Chapter 1}
    \nextpage {tutorials/declarative/contacts/part3}{Chapter 3}
    \example tutorials/declarative/contacts/part2
    \title Reusing QML Components
    \tableofcontents

    The second part of this tutorial covers how to reuse QML components and
    have them interact with each other.  The RemoveButton developed in the 
    previous chapter is intended to be part of a more complex control for
    editing a field of our contact.  This ContactField in turn is intended
    to be used in a contact editing control.

    \section1 Loading QML Components

    Reusing the RemoveButton itself is very simple.  When parsing a QML file
    if a Component is refered to that isn't already in the system, Qt
    will try to load it from a file of the same name with the ".qml" extension.

    \code
    <Item id="contactField"
        clip="true"
        width="230"
        height="30">
        <RemoveButton id="removeButton"
            anchors.right="{parent.right}"
            anchors.top="{parent.top}" anchors.bottom="{parent.bottom}"/>
    \endcode

    The above QML code will attempt to load the RemoveButton component from
    a file called "RemoveButton.qml".  All the properties of the button are
    accessible and can be overridden from defaults.  The loaded component
    can also refer to elements further up in the tree, so that code within
    RemoveButton.qml could refer to the contactField component.  However only
    properties of the top level element in RemoveButton.qml are visible to
    the contact field.  In order to allow contact field to modify how wide
    the remove button will be when opened we need to add a property to the
    remove button.

    \section1 Properties and Signals

    \code
    <Rect id="removeButton"
        width="30" height="30"
        color="red"
        radius="5">
        <properties>
            <Property name="expandedWidth" value="230"/>
        </properties>
        <signals>
            <Signal name="confirmed"/>
        </signals>
    \endcode

    \omit
    Need reference for more information on declaring properties and signals.
    \endomit

    These properties and signals are accessed from the contact field the same
    way standard system components are accessed.

    \code
    <Item id="contactField"
        clip="true"
        width="230"
        height="30">
        <RemoveButton id="removeButton"
            anchors.right="{parent.right}"
            anchors.top="{parent.top}" anchors.bottom="{parent.bottom}"
            expandedWidth="{contactField.width}"
            onConfirmed="print('Clear field text'); fieldText.text=''"/>
    \endcode

    Now when the remove button is expanded, it will expand to the width of the
    contact field.  Also when the user confirms the remove action, the
    text section of the contact field will be cleared.  When creating a
    component that does have children out of its own
    bounds its important to consider whether the item should be clipped,
    which is done above with \c{clip="true"}.

    \section1 States

    Its also possible to access the state of included components.  The FieldText
    component we will use in this tutorial is also been written specifically
    for our contacts application, as was the RemoveButton component.  In
    this case we want it to expand when editing.  One way to do this would
    be to anchor the field text component to the center of its parent and
    then let its own width change push the remove button away, however that
    would make it difficult to have the remove button also push the field
    text to the left when the remove button expands.

    So instead we will anchor the right edge of the field text to 
    the left edge of the remove button and use a state change in the
    contact field itself to move the remove button and the field icon out of
    view.

    \code
    <Item id="contactField"
        clip="true"
        width="230"
        height="30">
        <properties>
            <Property name="label" value="Name"/>
            <Property name="icon" value="../shared/pics/phone.png"/>
            <Property name="value"/>
        </properties>
        <RemoveButton id="removeButton"
            anchors.right="{parent.right}"
            anchors.top="{parent.top}" anchors.bottom="{parent.bottom}"
            expandedWidth="{contactField.width}"
            onConfirmed="print('Clear field text'); fieldText.text=''"/>
        <FieldText id="fieldText"
            width="{contactField.width-70}"
            anchors.right="{removeButton.left}" anchors.rightMargin="5"
            anchors.verticalCenter="{parent.verticalCenter}"
            label="{contactField.label}"
            text="{contactField.value}"/>
        <Image
            anchors.right="{fieldText.left}" anchors.rightMargin="5"
            anchors.verticalCenter="{parent.verticalCenter}"
            src="{contactField.icon}"/>
        <states>
            <State name="editingText" when="{fieldText.state == 'editing'}">
                <SetProperty target="{removeButton.anchors}" property="rightMargin" value="-35"/>
                <SetProperty target="{fieldText}" property="width" value="{contactField.width}"/>
            </State>
        </states>
        <transitions>
            <Transition fromState='' toState="*" reversible="true">
                <NumericAnimation properties="width,rightMargin" duration="200"/>
            </Transition>
        </transitions>
    </Item> 
    \endcode

    Apart from accessing the fieldText.state, the above code also uses the when
    attribute of its own editingText state.  This is an alternative to using
    a signal to change state.  When the value of the expression for the 
    when attribute changes, Qt will detect if the contactField needs to enter
    that state.  In the FieldText element a similar approach is used to fade
    out the label of the FieldText when the user enters some text of their own.

    \code
    <Text id="textLabel"
        x="5" width="{parent.width-10}"
        anchors.verticalCenter="{parent.verticalCenter}"
        hAlign="AlignHCenter"
        color="#505050"
        font.italic="true"
        text="{fieldText.label}"
        opacity="{textEdit.text == '' ? 1 : 0}">
        <opacity>
            <Behaviour>
                <NumericAnimation property="opacity" duration="250"/>
            </Behaviour>
        </opacity>
    </Text>
   \endcode

    fieldText is the enclosing component and textEdit is a TextEdit element
    provided by Qt.  In the QML code above, the opacity of the textLabel is
    only 1 if there is text for the textEdit is empty.  This is a form of
    short cut to using states for an element, useful if only one property
    is changing as it is for the textLabel.  To animate a property change is
    similar to animating a state change.  Using the Behavior element we can
    specify how the property changes if it does change state, allowing for
    a smooth transition.

    The fieldText element also handles changes to the text using the
    onValueChanged attribute when specifying properties.

    \code
    <Rect id="fieldText"
        height="30"
        radius="5"
        color="white">
        <properties>
            <Property
                name="text"
                value=""
                onValueChanged="reset()"/>
    \endcode

    Because the user needs to be able to edit text in the text edit, it
    shouldn't be simply bound to the text property of the FieldText component.
    However if a component using the FieldText component sets the text
    property of the FieldText component it should in turn set the text
    of the text edit.

    \section1 Key and Mouse Focus

    Unlike in Qt setting focus to true on a component does not always mean
    that the component has focus.  This is due to the declarative nature
    of QML, and can be affected by multiple components both indicating
    focus to be true.  At the time of writing this tutorial both key and mouse
    focus handling are still being improved.  Hence we will only lightly cover
    the topic.

    Normally in QML this is handled by FocusRealm components.  A focus realm
    is a sort of cut off point for determining focus.  If a FocusRealm does
    not have focus then any children of it won't be able to get focus even
    if they do set focus to true.  If your component has multiple child
    components that could gain focus ensure that they are guarded by FocusRealm
    component, and add code to handle which focus realms have focus
    at that level.  The alternative and approach done at this stage in
    the tutorial is to only have one component set focus to true at a time.

    Currently if multiple contact fields were put into our contact editor,
    any of the FieldText components could be clicked and opened, and
    any of the RemoveButton components could be clicked and opened, all
    at the same time.  We would like this behavior to be some what modal
    instead, encouraging the user to either accept or cancel the current
    action before moving onto a new action.

    In the tutorial we do this with a property of our top level component
    to handle whether we are in this state or not.

    \code
    <Item id="contactDetails"
        width="230"
        height="{layout.height}">
        <properties>
            <Property name="mouseGrabbed" value="false"/>
        </properties>
    \endcode

    And in the code where we want to check or avoid allowing mouse interaction.

    \code
    <Script>
        function toggle() {
            print('removeButton.toggle()');
            if (removeButton.state == 'opened') {
                removeButton.state = '';
                contactDetails.mouseGrabbed=false;
            } else {
                if (!contactDetails.mouseGrabbed) {
                    removeButton.state = 'opened';
                    contactDetails.mouseGrabbed=true;
                }
            }
        }
    </Script>
    \endcode

    Handling Key and Mouse focus in QML is quite likely to change before
    the Qt 4.6 release.
*/

/*!
    \page tutorials-declarative-contacts-part3.html
    \contentspage {Declarative UI Tutorial}{Contents}
    \previouspage {tutorials/declarative/contacts/part2}{Chapter 2}
    \nextpage {tutorials/declarative/contacts/part4}{Chapter 4}
    \example tutorials/declarative/contacts/part3
    \title Models, Views and Delegates
    \tableofcontents

    In the previous chapters we designed a component to display and
    edit a contact.  The next step is to display a list of those contacts
    and allow the user to expand individual contacts for editing.

    As the previous elements will not be changed in this section, they have
    been moved to a lib directory for this tutorial and the relevant
    name space path has been used.

    \section1 Simple List View

    Displaying lists requires three components.  A model that holds the
    data displayed, a delegate to indicate how elements are drawn and
    a view to arrange the elements.

    For the purposes of this tutorial we will be using an SQL query as our
    data model.  This can be declared in the resources section of
    the parent item.

    \code
    <SqlConnection id="contactDatabase"
        name="qmlConnection"
        driver="QSQLITE" databaseName="../../shared/contacts.sqlite"/>
    <SqlQuery id="contactList"
        connection="{contactDatabase}">
        <query>SELECT recid, label, email, phone FROM contacts ORDER BY label, recid</query>
    </SqlQuery>
    \endcode

    The SqlConnection component describes how to connect to the database in
    much the same ways as the QSqlDatabase::addDatabase() function is used.
    In this case an SQLite database is used as it can be connected to as a
    file, reducing complexity in setting up a database server or credentials.

    The SqlQuery component allows various forms of queries to be described.
    When the query is a select statement, the component also acts as a model
    allowing it to provide data to a ListView component.  The query above
    retrieves the fields recid, label, email and phone from a contacts table,
    and orders the results by the label of the contact first, and then by 
    the recid for any contacts with equivalent labels.

    To display the data retrieved from the table, a delegate is needed.  This
    is also declared in the resources section of the parent item.

    \code
    <Component id="contactDelegate">
        <Text
            x="45" y="12"
            width="{contactListView.width-45}"
            height="30"
            color="black"
            font.bold="true"
            text="{model.label}"/>
    </Component>
    \endcode
*/