// Copyright (C) 2024 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
    \page qtquick-properties-view.html
    \previouspage qtquick-navigator.html
    \nextpage qtquick-connection-view.html

    \ingroup studio-views

    \title Properties

    \brief Modify the properties of the selected component.

    The \uicontrol Properties view displays all the properties of the selected
    \l{glossary-component}{component}. The properties are grouped by type. The
    top part of the view displays properties that are common to all components,
    such as component type, ID, name, geometry, and visibility.

    \image {qtquick-item-properties-common.webp} {The basic component properties.}

    The bottom part of the view displays properties that have been defined for
    the component type. For example, the following image displays the predefined
    properties you can set for \l{basic-rectangle}{Rectangle} and \l Text
    components.

    \image qmldesigner-element-properties.webp {The Rectangle and Text tabs in the Properties view.}

    \section1 Custom properties

    Custom Properties are properties that the user has added to the component.

    There are two types of custom properties:

    \table
      \header
        \li Custom property type
        \li Description
      \row
        \li Local Custom Property
        \li A property that has been added for a \l{Preset components}{preset component}.
      \row
        \li Exposed Custom Property
        \li A property that has been added inside a component.
    \endtable

    \image {custom-properties.png} {The Local Custom Properties and Exposed Custom Properties settings in the Settings 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 \l{Working with states}{states} are highlighted
    with blue.

    This allows you to easily see which values are set in the component
    file for this component instance and which values are default
    characteristics of 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 Position and \uicontrol Size values are explicitly set
    and highlighted.

    \image {qmldesigner-properties-explicit-base.png} {Explicitly set properties.}

    In \uicontrol State1, only \uicontrol Position 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 component 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} {The Visibility property selected but not highlighted.}
            \li TRUE
            \li The component 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} {The Visibility property selected and highlighted.}
            \li TRUE (highlighted)
            \li The component is explicitly set to visible.
        \row
            \li \image {qmldesigner-boolean-false.png} {The Visibility property not selected and not highlighted.}
            \li FALSE
            \li The component 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} {The Visibility property not selected but highlighted.}
            \li FALSE (hightlighted)
            \li The component is explicitly set to hidden.
    \endtable

    \section1 Multiselection

    To modify the values of common properties of multiple components
    simultaneously, select the components in the \l Navigator, \l {2D}
    or \uicontrol{3D} view:

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

    You can \l{Locking Components}{lock other components} in
    \uicontrol Navigator to make multiselection easier.

    \section1 Editing properties in multiple views

    You can open multiple \uicontrol Properties views to edit the properties of multiple nodes
    simultaneously. You can lock each of the \uicontrol Properties views to prevent the subject node from
    changing by each selection.

    To edit properties in multiple views, you first need to enable
    \uicontrol {Multi Property Editor}:
      \list 1
        \li Select  \uicontrol Help > \uicontrol {About Plugins}, and then select
            \uicontrol {Multi Property Editor}.
        \li Restart \QDS.
      \endlist

    To edit the properties of multiple nodes simultaneously:
      \list 1
        \li In \uicontrol Navigator, select any node and open the
            \uicontrol {Properties} view to edit its properties.
        \li In \uicontrol Properties, to open another \uicontrol Properties view for editing
            properties of another node:
          \list 1
            \li Select \imagelockoff to prevent the subject node from changing.
            \li In \uicontrol Navigator, select another node.
            \li In \uicontrol Properties, select \imageplus to edit its properties
                in another \uicontrol Properties view.
          \endlist
        \li Edit the properties in each of the \uicontrol Properties views as needed.
                \image {opening-multiple-properties-views.webp} {Opening a new Properties view to edit the properties of another node.}
      \endlist

    \section1 Getting help for properties

    \list
        \li For information about setting common component properties, see
            \l{Specifying component properties}.
        \li For more information about the properties available for a
            component, select \key {F1} or see \l{Component types}
            and \l{Scalable layouts}.
    \endlist
*/
