doc/src/qtquick1/basicelements.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: http://www.qt-project.org/
   6 **
   7 ** This file is part of the documentation of the Qt Toolkit.
   8 **
   9 ** $QT_BEGIN_LICENSE:FDL$
  10 ** GNU Free Documentation License
  11 ** Alternatively, this file may be used under the terms of the GNU Free
  12 ** Documentation License version 1.3 as published by the Free Software
  13 ** Foundation and appearing in the file included in the packaging of
  14 ** this file.
  15 **
  16 ** Other Usage
  17 ** Alternatively, this file may be used in accordance with the terms
  18 ** and conditions contained in a signed written agreement between you
  19 ** and Nokia.
  20 **
  21 **
  22 **
  23 **
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29 \page qmlbasicelements.html
  30 \inqmlmodule QtQuick 1
  31 \ingroup qml-features
  32 \contentspage QML Features
  33 \previouspage QML Features
  34 \nextpage {QML Basic Types}{Data Types}
  35
  36 \title QML Basic Elements
  37
  38 QML's basic elements allow the easy inclusion of objects into the
  39 scene.
  40
  41 \section1 Basic Elements
  42 This is a list of some of the elements readily available for users.
  43 \list
  44 \o \l {Item}
  45 \o \l {Rectangle}
  46 \o \l {Image}
  47 \o \l {Text}
  48 \o \l {TextInput}
  49 \o \l {TextEdit}
  50 \o \l {FocusScope}
  51 \o \l {Component}
  52 \o \l {MouseArea}
  53 \endlist
  54
  55 For a complete list of QML elements, please visit the \l {QML Elements} page.
  56
  57 \section1 Properties and Qt Declarative Module
  58
  59 When using QML elements, keep in mind that elements may possess properties that
  60 other elements also possess. This is because QML and its underlying engine is
  61 implemented in C++ using Qt. More importantly, the chain of property inheritance
  62 is directly due to QML's use of the \l {Qt Declarative Module} and Qt's
  63 \l {Meta-Object System}{meta-object} and \l {The Property System}{property} systems. For example, visual elements that have C++ implementation are sublcasses of
  64 \l {QDeclarativeItem}. As a result, elements such as \l {Rectangle} and
  65 \l {Text} elements inherit properties such as \c clip and \c smooth.
  66
  67 \section1 Item Element
  68
  69 Many QML elements inherit \l Item properties. \c Item possesses important properties
  70 such as \c focus, \c children, and dimension properties such as \c width and
  71 \c height. Although \c Item has physical properties, it is not a visual element.
  72 Using \c Item as the top-level QML element (as the screen) will not produce a
  73 visual result, use the \l {Rectangle} element instead. Use the \c Item to create
  74 opacity effects, such as when creating an invisible container to hold other
  75 components.
  76
  77 \section1 Rectangle Element
  78
  79 The \l Rectangle element is the basic visual element, for displaying different
  80 types of items onto the screen. The \c Rectangle is customizable and utilizes
  81 other elements such as \l Gradient and \l BorderImage for displaying advanced
  82 customized graphics.
  83
  84 \section1 Image Element
  85
  86 To insert an image into a QML scene, merely declare an \l Image element. The
  87 \c Image element can load images in formats supported by Qt.
  88
  89 \section1 Text Elements
  90
  91 The \l Text and \l TextEdit elements display formatted text onto the screen.
  92 \c TextEdit features multi-line editing while the \l TextInput element is for
  93 single line text input.
  94
  95 \keyword qml-top-level-component
  96 \section1 Using Elements as the Top-Level Component
  97
  98 For creating components (or displaying a simple scene), there are different
  99 elements that could be used as the top-level component. To display a simple scene,
 100 a \l Rectangle as the top-level component may suffice. \l Rectangle,
 101 \l FocusScope, \l Component, \l {QML:QtObject} {QtObject}, \l Item, are some of
 102 the commonly used elements as the top-level component.
 103
 104 When importing components, the top-level component is important because the
 105 top-level component's properties are the only properties exposed to the parent.
 106
 107 For example, a \c Button component may be implemented using different elements as
 108 its top-level component. When this component is loaded into another QML scene,
 109 the component will retain the top-level component's properties. If a non-visual
 110 component is the top-level component, the visual properties should be aliased to
 111 the top-level to display the component properly.
 112
 113 For more information on how to build upon QML elements, see the
 114 \l{Importing Reusable Components} document.
 115 */