path: root/doc/qtcreator/src/qtquick/qtquick-properties.qdoc

/****************************************************************************
**
** Copyright (C) 2021 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the Qt Creator documentation.
**
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
**
****************************************************************************/

/*!
    \page qtquick-properties.html
    \previouspage quick-scalable-image.html
    \nextpage qtquick-positioning.html

    \title Specifying Component Properties

    The \l Properties view displays all the properties of the selected
    \l{glossary-component}{component}.

    \target basic-item
    \section1 Specifying Basic Component Properties

    All components share a set of properties that you can specify in the
    \uicontrol Properties view.

    \image qtquick-item-properties-common.png "Basic component properties"

    \section2 Type

    When you create a component using a \l{Component Types}{preset component},
    it has all the properties of the preset you used. If you realize later that
    another preset component with another set of default properties would be
    more suitable for your purposes, you can change the component type by
    double-clicking the \uicontrol Type field and entering the name of
    another preset component in the field.

    If you have specified values for properties that are not supported by the
    new component type, \QC offers to remove them for you. If you'd rather do
    this yourself, you can select the \inlineimage icons/action-icon.png
    (\uicontrol Actions) menu next to the property name, and then select
    \uicontrol Reset to remove the property values before trying again.

    \section2 ID

    Each component and each instance of a component has an \e ID that uniquely
    identifies it and enables other components' properties to be bound to it.
    You can specify IDs for components in the \uicontrol ID field.

    An ID must be unique, it must begin with a lower-case letter or an
    underscore character, and it can contain only letters, numbers, and
    underscore characters.

    For more technical information about IDs, see \l{The id Attribute}.

    The value of the \uicontrol {Custom ID} field specifies the name of an
    \l{Annotating Designs}{annotation}.

    \section2 2D Geometry

    In the \uicontrol Position group, you can set the position of a component on
    the x and y axis. The position of a component in the UI can be either
    absolute or relative to other components. For more information, see
    \l{Positioning Components}.

    In the 2D space, the z position of a component determines its position in
    relation to its sibling components in the component hierarchy. You can set
    it in the \uicontrol Z field in the \uicontrol Advanced tab.

    In the \uicontrol Size group, you can set the width and height of a
    component. You can also use the resize cursor to \l{Resizing 2D Components}
    {resize 2D components} in \uicontrol {Form Editor} or the scaling gizmo
    to \l{Scaling Components}{scale 3D components} in \uicontrol {3D Editor}.
    The values in the \uicontrol X and \uicontrol Y fields change accordingly.

    The component size and position can also be managed automatically
    when \l{Using Layouts}{using layouts}.

    The width and height of the root component in a component file determine
    the size of a component. The component size might also be zero (0,0)
    if its final size is determined by property bindings. For more
    information, see \l {Previewing Component Size}.

    \section3 Resetting Component Position and Size

    To return a component to its default position after moving it,
    select the \inlineimage qtcreator-reset-position-icon.png
    (\uicontrol {Reset Position}) button on the \l{Design Views}
    {Design mode toolbar}. To return it to its default size, select
    \inlineimage qtcreator-reset-size-icon.png
    (\uicontrol {Reset Size}) button.

    \section2 Visibility

    You can use the properties in the \uicontrol Visibility group to show and
    hide components.

    Deselect the \uicontrol {Is visible} check box to hide a component and all
    its child components, unless they have explicitly been set to be visible.
    This might have surprise effects when using property bindings. In such
    cases, it may be better to use the \uicontrol Opacity property instead.

    If this property is disabled, the component will no longer receive
    \l{Mouse Area}{mouse events} but will continue to receive key events
    and will retain the keyboard focus events, if it has been set by
    selecting the \uicontrol Enabled check box in the \uicontrol Advanced tab.

    The visibility value is only affected by changes to this property or the
    parent's visible property. It does not change, for example, if this
    component moves off-screen, or if the opacity changes to 0.

    In the \uicontrol Opacity field, specify the opacity of a component as a
    number between 0.0 (fully transparent) and 1.0 (fully opaque). The specified
    opacity is also applied individually to child components, sometimes with
    surprising effects.

    Changing a component's opacity does not affect whether the component
    receives user input events.

    You can \l{Creating Animations}{animate} the opacity value to make a
    component fade in and out.

    If the \uicontrol Clip check box is selected, the component and its children
    are clipped to the bounding rectangle of the component.

    \section1 Managing 2D Transformations

    You can assign any number of transformations, such as rotation and scaling,
    to a component in the \uicontrol Advanced tab of the \uicontrol Properties
    view. Each transformation is applied in order, one at a time.

    \image qtquick-item-properties-advanced.png "Advanced component properties"

    In the \uicontrol Origin field, select the origin point for scaling and
    rotation.

    Set the scale factor in the \uicontrol Scale field. A value of less than
    1.0 makes the component smaller, whereas a value greater than 1.0 makes
    it larger. A negative value causes the component to be mirrored in
    \uicontrol {Form Editor}.

    In the \uicontrol Rotation field, specify the rotation of the component
    in degrees clockwise around the origin point.

    Alternatively, you can move, resize, or rotate components by dragging them
    in \l{Form Editor}.

    For more information about transforming 3D components, see
    \l{Managing 3D Transformations} and \l{3D Editor}.

    \section1 Picking Colors

    To specify the color of the selected component in the color picker view (1),
    select the color picker icon (2) in the \uicontrol Properties view.

    \image qtquick-designer-color-picker.png "Color Picker view"

    You can use either a solid color (3) or a gradient (4). You can select the
    gradient in the \uicontrol {Gradient Picker} (5).

    The \uicontrol Original field displays the original color of the component,
    whereas the \uicontrol New field displays the current color. The
    \uicontrol Recent field displays the colors that you have last selected.

    \section1 Picking Gradients

    A gradient is defined by two or more colors, which will be blended
    seamlessly. The colors are specified as a set of gradient stops,
    each of which defines a position on the gradient bar from 0.0 to 1.0
    and a color. Drag the gradient stops along the gradient bar to set their
    values. Select the arrow below a gradient stop to see its value as
    a number.

    To add gradient stops, move the cursor over the gradient bar and point at
    it with the finger-shaped cursor. To remove gradient stops, pull them away
    from the gradient line.

    \image qtquick-designer-gradient-stops.gif

    Calculating gradients can be computationally expensive compared to the
    use of solid color fills or images. Consider using gradients only for
    static components in a UI.

    \if defined(qtdesignstudio)
    \section2 Setting Gradient Properties

    Select the arrow below the gradient button to set gradient properties
    for \l{Shapes}{Studio Components}.

    \image qtquick-designer-gradient-types.png "Gradients supported by Studio Components"

    \section3 Linear Gradients

    A \e {linear gradient} interpolates colors between start and end points.
    Outside these points, the gradient is either padded, reflected, or repeated
    depending on the spread type. Set start and end points for horizontal and
    vertical interpolation in the \uicontrol X1, \uicontrol X2, \uicontrol Y1,
    and \uicontrol Y2 fields.

    \image qtquick-designer-gradient-properties-linear.png "Linear gradient properties"

    \section3 Radial Gradients

    A \e {radial gradient} interpolates colors between a focal circle and a
    center circle. Points outside the cone defined by the two circles will
    be transparent. Outside the end points, the gradient is either padded,
    reflected, or repeated depending on the spread type.

    \image qtquick-designer-gradient-properties-radial.png "Radial gradient properties"

    You can set the center and focal radius in the \uicontrol {Center radius}
    and \uicontrol {Focal radius} fields. For simple radial gradients, set
    the focal radius to 0.

    You can set the center and focal points in the \uicontrol CenterX,
    \uicontrol CenterY, \uicontrol FocalX, and \uicontrol FocalY fields.
    To specify a simple radial gradient, set the focal X and focal Y to
    the value of center X and center Y, respectively.

    \section3 Conical Gradients

    A \e {conical gradient} interpolates colors counter-clockwise around a
    center point. Set the horizontal and vertical center point of the gradient
    in the \uicontrol CenterX and \uicontrol CenterY fields and the start angle
    in the \uicontrol Angle field.

    \image qtquick-designer-gradient-properties-conical.png "Conical gradient properties"
    \endif

    \section2 Selecting Web Gradients

    The \uicontrol {Gradient Picker} enables you to specify
    \l{https://webgradients.com/}{WebGradients} for components
    that support \l QGradient.

    To open the \uicontrol {Gradient Picker}, select the
    \uicontrol {Gradient Picker Dialog} icon in the \uicontrol Properties view.

    \image qtquick-designer-gradient-picker.png "Gradient Picker dialog"

    To apply a gradient on the selected component, select \uicontrol Apply.

    To save a gradient in the \uicontrol {User Presets} tab, select
    \uicontrol Save.

    By default, a linear gradient (4) is used, but you can select another
    supported gradient type in the \uicontrol Properties view.

    \section1 Marking Text Components for Translation

    To support translators, mark each text component that should be translated.
    In the \uicontrol Properties view, \uicontrol Text field, select \uicontrol tr (1).

    \image qmldesigner-text-property-tr.png "Text properties"

    By default, the text string is enclosed in a \c qsTr() call.

    \image qml-translate.png "Text marked for translation"

    If you use text IDs instead of plain text, change the default call to
    \c qsTrId(). Select \uicontrol Tools > \uicontrol Options >
    \uicontrol {Qt Quick} > \uicontrol {Qt Quick Designer}, and then select the
    \uicontrol {qsTrId()} radio button in the \uicontrol Internationalization
    group. For more information about text ID based translations, see
    \l {Qt Linguist Manual: Text ID Based Translations}.

    To preserve the context when editing the text or to change the context
    by setting a binding on the text property, change the default call to
    \c qsTranslate() by selecting the \uicontrol {qsTranslate()} radio button.

    For more information, see
    \l {Internationalization and Localization with Qt Quick}.

    \if defined(qtcreator)
    When you \l{Creating Qt Quick Projects}{create a new project}, you can
    automatically generate a translation source file (TS) for one language.
    You can add other languages later by editing the project file.
    \endif

    \section1 Specifying Developer Properties

    In the \uicontrol Advanced tab of the \uicontrol Properties view, you can
    manage the more advanced properties of components that are based on the
    \l Item component and that are mostly used by application developers.

    Select the \uicontrol Smooth check box to activate smooth sampling. Smooth
    sampling is performed using linear interpolation, while non-smooth sampling
    is performed using the nearest neighbor. Because smooth sampling has minimal
    impact on performance, it is activated by default.

    The value of the \uicontrol {Baseline offset} specifies the position of the
    component's baseline in local coordinates. The baseline of a \l Text
    component is the imaginary line on which the text sits. Controls containing
    text usually set their baseline to the baseline of their text. For non-text
    components, a default baseline offset of 0 is used.

    \section2 Managing Mouse and Keyboard Events

    Select the \uicontrol Enabled check box to allow the component to receive
    mouse and keyboard events. The children of the component inherit this
    behavior, unless you explicitly set this value for them.

    You can enable the \uicontrol Focus check box to specify that the component
    has active focus and the \uicontrol {Active focus on tab} check box to add
    the component to the \e {tab focus chain}. The tab focus chain traverses
    components by first visiting the parent, and then its children in the order
    they are defined. Pressing \key Tab on a component in the tab focus chain
    moves keyboard focus to the next component in the chain. Pressing back tab
    (usually, \key {Shift+Tab}) moves focus to the previous component.

    \section2 Using Layers

    Qt Quick makes use of a dedicated scene graph that is then traversed and
    rendered via a graphics API such as OpenGL ES, OpenGL, Vulkan, Metal, or
    Direct 3D. Using a scene graph for graphics rather than the traditional
    imperative painting systems, means that the scene to be rendered can be
    retained between frames and the complete set of primitives to render is
    known before rendering starts. This opens up for a number of optimizations,
    such as \l{Batching}{batch rendering} to minimize state changes and
    discarding obscured primitives.

    For example, a UI might contain a list of ten items where
    each item has a background color, an icon and a text. Using traditional
    drawing techniques, this would result in 30 draw calls and a similar
    amount of state changes. A scene graph, on the other hand, could reorganize
    the primitives to render such that all backgrounds are drawn in one call,
    then all icons, then all the text, reducing the total amount of draw calls
    to only 3. Batching and state change reduction like this can greatly
    improve performance on some hardware.

    You need a basic understanding of how components are rendered
    to be able to set layer properties. Rendering is described in
    \l {Qt Quick Scene Graph Default Renderer}.

    \image qtquick-item-properties-layer.png "Layer properties"

    Components are normally rendered directly into the window they belong to.
    However, by selecting the \uicontrol Enabled check box in the
    \uicontrol Layer group, you can delegate the component and its entire subtree
    into an offscreen surface. Only the offscreen surface, a texture, will
    then be drawn into the window. For more information, see \l{Item Layers}.

    When layering is enabled, you can use the component directly as a texture,
    in combination with the component you select in the \uicontrol Effect field.
    Typically, this component should be a shader effect with a source texture
    specified. You can use the effects in the \uicontrol Effects section
    of \uicontrol Library that are based on the components in the
    \l {Qt Graphical Effects} module.

    To enable the component to pass the layer's offscreen surface to the effect
    correctly, the \uicontrol {Sampler name} field is set to the source
    property of the texture.

    Note that when a component's layer is enabled, the scene graph will allocate
    memory in the GPU equal to width x height x 4. In memory constrained
    configurations, large layers should be used with care. Also, a component
    using a layer cannot be batched during rendering. This means that a
    scene with many layered components may have performance problems.

    By default, multisampling is enabled for the entire window if the scenegraph
    renderer is in use and the underlying graphics API supports it. By setting
    the value in the \uicontrol Samples field, you can request multisampling for
    a part of the scene. This way, multisampling is applied only to a particular
    subtree, which can lead to significant performance gain. Even then, enabling
    multisampling can be potentially expensive regardless of the layer's size,
    as it incurs a hardware and driver dependent performance and memory cost. If
    support for multisample renderbuffers and framebuffer blits is not
    available, the value is silently ignored.

    The value of the \uicontrol Format field specifies the internal OpenGL
    format of the texture. Depending on the OpenGL implementation, it might
    allow you to save some texture memory. However, use the \uicontrol RGB
    and \uicontrol Alpha values with caution, because the underlying hardware
    and driver might not support them.

    In the \uicontrol {Texture mirroring} field, specify whether the generated
    OpenGL texture should be mirrored by flipping it along the x or y axis.
    Custom mirroring can be useful if the generated texture is directly accessed
    by custom shaders. If no effect is specified for the layered component,
    mirroring has no effect on the UI representation of the component.

    The component will use linear interpolation for scaling if the
    \uicontrol Smooth check box is selected. To use a mipmap for downsampling,
    select the \uicontrol Mipmap check box. Mipmapping may improve the visual
    quality of downscaled components. For mipmapping of single Image components,
    select the \uicontrol Mipmap check box in the \l{Images}{image properties},
    instead.

    To use a texture with a size different from that of the component, specify
    the width and height of the texture in the \uicontrol {Texture size} field.

    The \uicontrol {Wrap mode} defines the OpenGL wrap modes associated with
    the texture. You can clamp the texture to edges or repeat it horizontally
    and vertically. Note that some OpenGL ES 2 implementations do not support
    the \uicontrol Repeat wrap mode with non-power-of-two textures.

    \section1 Editing Properties Inline

    You can double-click components in \l {Form Editor} to edit their
    text, color, or source properties inline. Because you can specify several
    of these properties for some components, such as \l {text-edit}{Text Edit},
    you can also right-click components to open the inline editors from the
    context menu.

    \image qmldesigner-inline-editing.png
*/