doc/src/declarative/basicelements.qdoc

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