Skip to content

2.01

Jump to bottom
Kimmo edited this page Apr 29, 2018 · 11 revisions

Rectangle, Image, BorderImage, Text (P0 | 0,5h)

Explanation of the contents of a topic page @ Week 1 Topic 1

Back to Week 2

Objective: Basic QML items

Beginner

  • What is an item?
  • What is the difference between a visual and non-visual QML object?
  • What is an object tree?

Intermediate

  • What is a root item?
  • What is a parent item?
  • What is a visual parent?
  • Can parent items and visual parents be different?
  • What are the basic properties of an item?
  • How do you create an ellipse using a Rectangle?
  • What is an item geometry (x, y, width, height)?

Comment: dimensions are width and height. I'd ask (this may be my question): What is an item geometry (x, y, width, height)

  • What is z?
  • What is implicit width for an image?
  • What is implicit height for an image?
  • When to use BorderImage?

Expert

  • How do you use a BorderImage to decorate a window?

Omitted

Course material content

Items and their properties (this includes visual and non-visual item, item dimensions, parenthood)

http://doc.qt.io/qt-5/qml-qtquick-item.html#details
http://doc.qt.io/qt-5/qtquick-visualcanvas-visualparent.html
http://doc.qt.io/archives/qt-4.8/qmlbasicelements.html
https://github.com/TestMyQt/material-outline/wiki/1.04

QML types are structures in the markup language, and they represent visual and non-visual parts.
Non-visual QML types include functionality, such as states, transitions, models, paths, gradients and timers. The Item type is the base type for all visual types in Qt Quick. It is itself, however, not a visual item.

Comment: The last sentence above is obsolete, as we will continue the explanation.

Using Item as the top-level QML object (as the root item of the window) will not produce a visual result. If you wish your top-level QML object to produce a visual result, use the Rectangle object instead. Use the Item to create opacity effects, such as when creating an invisible container to hold other components.

Comment: Do not use the word "element" any more. The right word is type or object, depending on the context.

All visual items in Qt Quick inherit from Item. Although an Item object has no visual appearance, it defines all the attributes that are common across visual items, such as x and y position, width and height, anchoring and key handling support. It supports layering and is usually used to group visual types.

The Item type can be useful for grouping several items under a single root visual item. For example:

E: [I want this code redone/made better and visualised at some point]

Item {
    id: root
    Image {
        id: imageOne
        source: "tile.png"
    }

    Image {
        id: imageTwo
        x: 80
        width: 100
        height: 100
        source: "tile.png"
    }

    Image {
        id: imageThree
        x: 190
        width: 100
        height: 100
        fillMode: Image.Tile
        source: "tile.png"
    }
}

Comment: Try to avoid magic numbers. It's ok here, but in general try to bind x, y, width, height to the parent or another item

Please note that we are only using magic numbers in the examples to get you started. In general, you should try to bind x, y, width and height to the parent, or another item.

E: I'm having some issues with semantics regarding with what I should be calling things (items, objects, types), that needs to be looked at at some point

Comment: Type - Rectangle, object - Rectangle [ ], item - any visual object. Quite often item is used to refer tyoes as well, which may be confusing.

As you can see from the example, QML objects are described by properties. The properties are simple name-value definitions (width, height etc.) and they are separated by semicolons or line breaks. Properties are used for customizing appearance and changing behaviour.
The id property is a special property used to identify QML objects. It is used to create relationships between objects. The id property of an object allows other objects refer to it in regard to:

  • Relative realignment and positioning
  • To use its properties
  • To change its properties (e.g. for animation)
  • For re-use of common types (e.g. gradients, images).

For example:

Item { 
    width: 300; height: 115 
    
    Text { 
        id: title 
        x: 50; y: 25 
        text: "Qt Quick" 
        font { family: "Helvetica"; pointSize: parent.width * 0.1 } 
      } 

    Rectangle { 
        x: title.x; y: title.y + title.height - height; height: 5 
        width: title.width 
        color: "green" 
    } 
}

The concept of QObject inheritance was discussed during the previous course week. This week we will be taking a look at visual parents and children, and it is important to understand how the concept differs from QObject inheritance. An item's visual parent may not necessarily be the same as its object parent.
The concept of the visual parent in Qt Quick is separate from, but related to, the concept of the object parent within the QObject parent hierarchy.

All QML objects have an object parent, which is determined by the object hierarchy in which the object is declared. When working with the QtQuick module, the Item type is the base type for all visual items provided by this module, and it provides the concept of an additional visual parent, as defined by an item's parent property. Every item has a visual parent; if an item's parent property value is null, the item will not be rendered in the scene.

Any object assigned to an item's data property becomes a child of the item within its QObject hierarchy, for memory management purposes. Additionally, if an object added to the data property is of the Item type, it is also assigned to the Item::children property and becomes a child of the item within the visual scene hierarchy. (Most Qt Quick hierarchy crawling algorithms, especially the rendering algorithms, only consider the visual parent hierarchy.)

For convenience, the Item data property is its default property. This means that any child item declared within an Item object without being assigned to a specific property is automatically assigned to the data property and becomes a child of the item as described above. So, the two code blocks below produce the same result, and you will almost always see the form shown below:

import QtQuick 2.0

Item {
    width: 100
    height: 100

    Rectangle {
        width: 50
        height: 50
        color: "red"
    }
}

Rather than the explicit data assignment:

import QtQuick 2.0

Item {
    width: 100
    height: 100

    data: [
        Rectangle {
            width: 50
            height: 50
            color: "red"
        }
    ]
}

An item's visual parent can be changed at any time by setting its parent property. Thus, an item's visual parent may not necessarily be the same as its object parent.

When an item becomes the child of another item:

  • The child's parent refers to its parent item
  • The parent's children and childrenRect properties take that child into account

Declaring an item as a child of another does not automatically mean that the child item will be appropriately positioned or sized to fit within its parent. Some QML types may have in-built behaviors that affect the positioning of child items — for example, a Row object automatically re-positions its children into a horizontal formation — but these are behaviors enforced by the types' own specific implementations. Additionally, a parent item will not automatically clip its children to visually contain them within the parent's visual bounds, unless its clip property is set to true.

Rectangle

http://doc.qt.io/qt-5/qml-qtquick-rectangle.html#details

Rectangle items are used to fill areas with solid color or gradients, and/or to provide a rectangular border.

Each Rectangle item is painted using either a solid fill color, specified using the color property, or a gradient, defined using a Gradient type and set using the gradient property. If both a color and a gradient are specified, the gradient is used.

You can add an optional border to a rectangle with its own color and thickness by setting the border.color and border.width properties. Set the color to "transparent" to paint a border without a fill color.

You can also create rounded rectangles using the radius property. Since this introduces curved edges to the corners of a rectangle, it may be appropriate to set the Item::antialiasing property to improve its appearance.

For example:

import QtQuick 2.0

Rectangle {
   width: 100
   height: 100
   color: "red"
   border.color: "black"
   border.width: 5
   radius: 10
}

Image

Image type displays an image from an URL specified in the source property. Image type can handle Qt supported URLs and image types (PNG, JPEG, SVG, ...).

The source image can naturally be smaller or bigger than the Image item. With the fillMode property, you can choose the strategy used when painting the image inside the item.

list of fillmodes here

By default, images are loaded from network resources asynchronously in a separate thread. This way slow networks wont block the UI. Local files are loaded synchronously by default, and this can be overridden by setting the asynchronous property to true. Asynchronous loading is beneficial if there are big files that are not needed be displayed right away in the UI.

To monitor the state of an image, Image has progress and status properties. They can be bound to visualizations in the UI, for example.

When using images with QML, they are often the greatest user of memory in the UI. To minimize memory usage of images that are not part of UI (like user provided resources), they should have their size bounded with the sourceSize property. sourceSize dictates the actual width and height of the loaded image, while the width and height properties hold the dimensions where the image will be scaled to.

import QtQuick 2.0

Image {
   anchors.fill: parent
   source: "bigImage.jpg"
   sourceSize.width: 1024
   sourceSize.height: 1024
}

Image data is cached and shared internally, so when using the same source the objects will use the same data.

BorderImage

The BorderImage type is used to form a border out of parts of an image by scaling or tiling.

BorderImage divides the source image into 9 regions like this:

borderimage region image

The regions are defined with the border property group. Regions formed from the source image are scaled or tiled to create the displayed border image in the following way:

The corners (regions 1, 3, 7, and 9) are not scaled at all.
Regions 2 and 8 are scaled according to horizontalTileMode.
Regions 4 and 6 are scaled according to verticalTileMode.
The middle (region 5) is scaled according to both horizontalTileMode and verticalTileMode.

Example usage with code here

When the width/height of the border regions 2, 4, 6, 8 cannot be repeated in exact multiples of the target width/height, the tilemode BorderImage.Round can be used to scale the regions to fit in the target.

Text

Text type can display plain or rich text (using HTML markup). To have user editable text you can use TextEdit, which is very similar to Text type.

import QtQuick 2.0

Text {
    text: "Hello <b>World</b>!"
    font.family: "Helvetica"
    font.pointSize: 24
    color: "red"
}

If the height and width are not explicitly set, Text will try to accomodate the dimensions to the text. To enable text wrapping, wrapMode needs to be set, otherwise the text will laid on one line.

To customize the font, the properties in group font can be changed:

To style the text, the property style can be used to change the style to either Raised, Outline or Sunken. Use styleColor to change the color of the added styling

Row {
    Text { font.pointSize: 24; text: "Normal" }
    Text { font.pointSize: 24; text: "Raised"; style: Text.Raised; styleColor: "#AAAAAA" }
    Text { font.pointSize: 24; text: "Outline";style: Text.Outline; styleColor: "green" }
    Text { font.pointSize: 24; text: "Sunken"; style: Text.Sunken; styleColor: "#AAAAAA" }
}

To scale text with other items, you can

Rectangle { 
    width: 400
    height: 400
    color: "lightblue" 
    
    
    Text { 
        x: parent.width * 0.25
        y: parent.height * 0.25 
        
        text: "Qt Quick"
        font {
            family: "Sans"
            pixelSize: parent.width * 0.1
        } 
    } 
}

You can also use FontMetrics to get the geometry of a certain font:

Rectangle {

    FontMetrics {
        id: metrics
        font.pointSize: 20
        font.family: "Courier"
    }

    width: 200
    height: metrics.height * 10
    
}

Use the function qsTr() to declare translatable strings inside the UI. Qt Quick has extensive internationalization and localization support you can read up on here

Instructions and description for the exercise of the topic

Exhaustive reference material mentioned in this topic

Further reading topics/links:

footy foot foot

Clone this wiki locally