diff options
Diffstat (limited to 'doc/src/declarative/tutorial2.qdoc')
| -rw-r--r-- | doc/src/declarative/tutorial2.qdoc | 135 |
1 files changed, 37 insertions, 98 deletions
diff --git a/doc/src/declarative/tutorial2.qdoc b/doc/src/declarative/tutorial2.qdoc index c97fddf..a3154de 100644 --- a/doc/src/declarative/tutorial2.qdoc +++ b/doc/src/declarative/tutorial2.qdoc @@ -1,130 +1,69 @@ /*! \page tutorial2.html \target tutorial2 -\title Tutorial 2 - Some colors +\title Tutorial 2 - QML Component This chapter adds a color picker to change the color of the text. \image declarative-tutorial2.png -Our color picker is made of many cells with different colors. To avoid writing the same code many times, we first create a new \c Cell component with a color property (see \l components). +Our color picker is made of six cells with different colors. +To avoid writing the same code multiple times, we first create a new \c Cell component. +A component provides a way of defining a new type that we can re-use in other QML files. +A QML component is like a black-box and interacts with the outside world through properties, signals and slots and is generally +defined in its own QML file (for more details, see \l components). Here is the QML code for \c Cell.qml: -\code -Item { - property var color - - id: CellContainer - width: 40 - height: 25 - - Rectangle { - anchors.fill: parent - color: CellContainer.color - } - MouseRegion { - anchors.fill: parent - onClicked: { HelloText.color = CellContainer.color } - } -} -\endcode - -Then, we use our \c Cell component to create the color picker in the QML code for the application: - -\code -Rectangle { - id: Page - width: 480 - height: 200 - color: "LightGrey" - Text { - id: HelloText - text: "Hello world!" - font.pointSize: 24 - font.bold: true - y: 30 - anchors.horizontalCenter: Page.horizontalCenter - } - Grid { - id: ColorPicker - x: 0 - anchors.bottom: Page.bottom - width: 120; height: 50 - rows: 2; columns: 3 - Cell { color: "#ff0000" } - Cell { color: "#00ff00" } - Cell { color: "#0000ff" } - Cell { color: "#ffff00" } - Cell { color: "#00ffff" } - Cell { color: "#ff00ff" } - } -} -\endcode +\snippet examples/declarative/tutorials/helloworld/Cell.qml 0 \section1 Walkthrough \section2 The Cell Component -\code -Item { - id: CellContainer - width: 40 - height: 25 -} -\endcode +\snippet examples/declarative/tutorials/helloworld/Cell.qml 1 -The root element of our component is an \c Item. It is the most basic element in QML and is often used as a container for other elements. +The root element of our component is an \l Item with the \c id \e container. +An \l Item is the most basic visual element in QML and is often used as a container for other elements. -\code -property var color -\endcode +\snippet examples/declarative/tutorials/helloworld/Cell.qml 4 -We declare a \c color property. This property is accessible from \e outside our component, this allows us to instantiate the cells with different colors. +We declare a \c color property. This property is accessible from \e outside our component, this allows us +to instantiate the cells with different colors. +This property is just an alias to an existing property - the color of the rectangle that compose the cell (see \l{Properties}). -\code -Rectangle { - anchors.fill: parent - color: CellContainer.color -} -\endcode +\snippet examples/declarative/tutorials/helloworld/Cell.qml 5 -Our cell component is basically a colored rectangle. +We want our component to also have a signal that we call \e clicked with a \e color parameter. +We will use this signal to change the color of the text in the main QML file later. -The \c anchors.fill property is a convenient way to set the size of an element. In this case the \c Rectangle will have the same size as its parent. +\snippet examples/declarative/tutorials/helloworld/Cell.qml 2 -We bind the \c color property of this \c Rectangle to the color property of our component. +Our cell component is basically a colored rectangle with the \c id \e rectangle. -\code -MouseRegion { - anchors.fill: parent - onClicked: { HelloText.color = CellContainer.color } -} -\endcode +The \c anchors.fill property is a convenient way to set the size of an element. +In this case the rectangle will have the same size as its parent (see \l{anchor-layout}{Anchor-based Layout}). -In order to change the color of the text when clicking on a cell, we create a \c MouseRegion element with the same size as its parent. +\snippet examples/declarative/tutorials/helloworld/Cell.qml 3 -The \c onClicked property sets the \c color property of the element named \e HelloText to our cell color. +In order to change the color of the text when clicking on a cell, we create a \l MouseRegion element with +the same size as its parent. + +A \l MouseRegion defines a signal called \e clicked. +When this signal is triggered we want to emit our own \e clicked signal with the color as parameter. \section2 The main QML file -\code -Grid { - id: ColorPicker - x: 0 - anchors.bottom: Page.bottom - width: 120; height: 50 - rows: 2; columns: 3 - Cell { color: "#ff0000" } - Cell { color: "#00ff00" } - Cell { color: "#0000ff" } - Cell { color: "#ffff00" } - Cell { color: "#00ffff" } - Cell { color: "#ff00ff" } -} -\endcode - -In the main QML file, the only thing we have to do is to create a color picker by putting 6 cells with different colors in a grid. +In our main QML file, we use our \c Cell component to create the color picker: + +\snippet examples/declarative/tutorials/helloworld/tutorial2.qml 0 + +We create the color picker by putting 6 cells with different colors in a grid. + +\snippet examples/declarative/tutorials/helloworld/tutorial2.qml 1 + +When the \e clicked signal of our cell is triggered, we want to set the color of the text to the color passed as a parameter. +We can react to any signal of our component through a property of the name \e 'onSignalName' (see \l{Signal Handlers}). [Previous: \l tutorial1] [Next: \l tutorial3] |