/****************************************************************************
**
** Copyright (C) 2020 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 qtquick-navigator.html
    \nextpage qtquick-positioning.html

    \title Specifying Item Properties

    The \uicontrol Properties view displays all the properties of the selected
    item. The properties are grouped by type. The top part of the view displays
    properties that are common to all QML types, such as type name, id,
    position, size, and visibility.

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

    The bottom part of the view displays properties that have been defined for
    the QML type. For example, the following image displays the predefined
    properties you can set for \uicontrol Rectangle and \uicontrol Text items.

    \image qmldesigner-element-properties.png "Rectangle and Text properties"

    To modify the values of common properties of multiple items simultaneously,
    select the items in the \uicontrol Navigator or on the canvas:

    \list
        \li On Windows, press and hold \key Ctrl and \key Shift, and then click
            the items to select them.
        \li On \macos, press \key Shift to select a range of items or \key Cmd
            to select multiple single items.
    \endlist

    To return an item to its implicit position after moving it, select the
    \inlineimage qtcreator-reset-position-icon.png
    (\uicontrol {Reset Position}) button on the toolbar. To return it to its
    implicit size, select \inlineimage qtcreator-reset-size-icon.png
    (\uicontrol {Reset Size}) button.

    To set the visibility of the item, select \uicontrol Edit >
    \uicontrol Visibility in the context menu.

    For more information on the properties available for an item, press
    \key {F1}.

    \section1 Specifying Custom Properties

    Each predefined QML type has a set of properties that you can extend by
    defining additional properties for your own QML components. For more
    information, see \l{Specifying Dynamic Properties}.

    The properties you add for a QML type are displayed in the
    \uicontrol Properties view when you select a component
    of that type in \uicontrol Navigator or \uicontrol {Form Editor}.

    \image qtquick-custom-properties.png "Custom properties in Properties view"

    \section1 Viewing Changes in Properties

    The default values of properties are displayed in white color, while the
    values that you specify explicitly are highlighted with blue color. In
    addition, property changes in states are highlighted with blue.

    This allows you to easily see which values are set in the UI form or QML
    file and which values are default characteristics of a QML type or a
    component.

    When editing states, you can easily see which values are explicitly set in
    the current state and which values are derived from the base state.

    The following images illustrate this. In the base state, the \uicontrol Size
    (1) and \uicontrol Colors (2) values are explicitly set and highlighted.

    \image qmldesigner-properties-explicit-base.png "Explicitly set properties"

    In \uicontrol State1, only the color (1) is explicitly set and highlighted.

    \image qmldesigner-properties-explicit-state1.png "Explicitly set properties"

    Resetting a property sets it back to the default value and removes the value
    from the UI form or QML file.

    \note As a result, all boolean values can be visualized in four different
    ways.

    For example, visibility can be visualized as follows:

    \table
        \row
            \li \image qmldesigner-boolean-true.png
            \li TRUE
            \li The QML type is visible by default. The visibility might be
                overridden by the visibility set in the base state.
        \row
            \li \image qmldesigner-boolean-true-blue.png
            \li TRUE (highlighted)
            \li The QML type is explicitly set to visible.
        \row
            \li \image qmldesigner-boolean-false.png
            \li FALSE
            \li The QML type is hidden by default. The visibility might be
                overridden by the visibility set in the base state.
        \row
            \li \image qmldesigner-boolean-false-blue.png
            \li FALSE (hightlighted)
            \li The type is explicitly set to hidden.
    \endtable

    \section1 Picking Colors

    To specify the color of the selected item 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 item,
    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 items in a UI.

    \if defined(qtdesignstudio)
    \section2 Setting Gradient Properties

    Select the arrow below the gradient button to set gradient properties
    for 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 to
    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 QML types
    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 item, 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 Items for Translation

    To support translators, mark each text item 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

    \target basic-item
    \section1 Specifying Basic Item Properties

    All QML types share a set of properties that you can specify in
    \uicontrol Properties.

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

    \section2 Type

    When you create a component using a QML type, the component has all the
    properties of the type you used. If you realize later that another QML
    type with another set of predefined 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 QML type in the
    field.

    If you have specified values for properties that are not supported by
    the new 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 QML type and each instance of a QML type has an \e id that uniquely
    identifies it and enables other items' properties to be bound to it.
    You can specify ids for items 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 information, see \l{The id Attribute}.

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

    \section2 Geometry

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

    The z position of an item determines its position in relation to its
    sibling items in the type 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
    an item. You can also use the resize cursor to \l{Resizing 2D Items}
    {resize 2D items} in \uicontrol {Form Editor} or the scaling gizmo
    to \l{Scaling Items}{scale 3D items} in \uicontrol {3D Editor}. The
    values in the \uicontrol X and \uicontrol Y fields change accordingly.

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

    The width and height of the root item in a QML 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}.

    \section2 Visibility

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

    Deselect the \uicontrol {Is visible} check box to hide an item and all its
    child items, 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 item will no longer receive mouse events,
    but will continue to receive key events and will retain the keyboard focus
    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 item
    moves off-screen, or if the opacity changes to 0.

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

    Changing an item's opacity does not affect whether the item receives user
    input events.

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

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

    \section1 Managing 2D Transformations

    You can assign any number of transformations, such as rotation and scaling,
    to an item 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 item 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.

    \section1 Specifying Developer Properties

    In the \uicontrol Advanced tab of the \uicontrol Properties view, you can
    manage the more advanced properties of QML types that are based on the
    \l Item type and 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
    item's baseline in local coordinates. The baseline of a Text item 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 items, a default
    baseline offset of 0 is used.

    \section2 Managing Mouse and Keyboard Events

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

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

    \section2 Using Layers

    Qt Quick 2 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, if a user-interface contains a list of ten items where each
    item has a background color, an icon and a text. Using the 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 items are rendered in QML
    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"

    Items 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 item 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 item directly as a texture,
    in combination with the item you select in the \uicontrol Effect field.
    Typically, this item 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 QML types in the
    \l {Qt Graphical Effects} module.

    To enable the item 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 an item'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, an item
    using a layer cannot be batched during rendering. This means that a
    scene with many layered items 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 item, mirroring
    has no effect on the UI representation of the item.

    The item 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 items. For mipmapping of single Image items, select the
    \uicontrol Mipmap check box in the image properties, instead.

    To use a texture with a size different from that of the item, 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 objects on the canvas to edit their text, color,
    or source properties inline. Because you can specify several of these
    properties for some QML types, such as \l {text-edit}{Text Edit},
    you can also right-click objects to open the inline editors from a
    context-menu.

    \image qmldesigner-inline-editing.png
*/
