/****************************************************************************
**
** 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-navigator.html
    \previouspage quick-scalable-image.html
    \nextpage qtquick-properties.html

    \title Managing Item Hierarchy

    The \uicontrol Navigator view displays the items in the current QML file and
    their relationships. Items (1) are listed in a tree structure, below their
    parent (2). You can preview items by hovering the mouse over them (3).

    \image qmldesigner-navigator.png "Navigator with item preview"

    You can select items in the \uicontrol Navigator view to edit their
    properties in the \uicontrol Properties view. Items can access the
    properties of their parent item. To select items in the
    \uicontrol {Form Editor} view, right-click an item, and select another
    item in the \uicontrol Selection submenu.

    Typically, child items are located within the parent item in
    \uicontrol {Form Editor}. However, they do not necessarily have to
    fit inside the parent item. For example, you might want to make a
    mouse area larger than the rectangle or image beneath it.

    \image qmldesigner-element-size.png "Mouse area for a button"

    When you copy an item, all its child items are also copied. When
    you remove an item, the child items are also removed.

    Select context menu commands to apply commands to items. The availability
    of the commands depends on the item type. For example, you can change
    the source of an Image type by selecting \uicontrol {Change Source URL} in
    the context menu.

    \section1 Showing and Hiding Items

    To show and hide items in \uicontrol {Form Editor} when focusing on
    specific parts of the application, click \inlineimage icons/visibilityon.png
    in \uicontrol Navigator.

    To change the visibility of an item in the application code, select the
    \uicontrol Visibility check box in the \uicontrol Properties view or select
    \uicontrol Edit > \uicontrol Visibility in the context menu.

    You can also set the \uicontrol Opacity field to 0 in \uicontrol Properties
    to hide items in the UI that you want to apply animation to.

    As all properties, visibility and opacity are inherited from the parent
    item. To hide or show child items, edit the properties of the parent item.

    To hide invisible items in \uicontrol Navigator, click
    \inlineimage filtericon.png
    (\uicontrol {Filter Tree}) and select \uicontrol {Show only visible items}.

    \section1 Locking Items

    When designing complex applications, it is easy to accidentally modify
    the properties of an item in one of the \QC views in ways that lead to
    surprising results. For example, \uicontrol {Form Editor} can become
    crowded and other items can get in the way when you are trying to select
    or transform a particular item, so that you end up transforming more
    items than you wanted to.

    To lock items that you are not currently editing and their children,
    click \inlineimage icons/lockon.png
    in \uicontrol Navigator. Locked items cannot be handled in any \QC views.
    You can unlock the items when you want to edit them again.

    \image qtquick-designer-navigator-lock.gif "Locking items in Navigator"

    You cannot select locked items in \uicontrol {Form Editor} or
    \uicontrol {3D Editor} nor access their properties in
    \uicontrol Properties.

    If you attempt to \l{Adding States}{remove a state} that changes the
    properties of a locked item, you are prompted to confirm the removal.

    If you have \l{Editing Animation Curves}{added easing curves} to keyframe
    animations, you can lock and unlock them in the \uicontrol {Curve Editor}
    view. If you lock the items that contain the easing curves, the lock status
    is synchronized between \uicontrol Navigator and \uicontrol {Curve Editor}.

    \section1 Arranging Items

    You can view the order of items in a QML file in \uicontrol Navigator
    and \uicontrol {Text Editor}. The order of items in the file also
    determines the order in which they are drawn in \uicontrol {Form Editor}.
    By default, items that are located at the top of the file are listed at
    the bottom of the \uicontrol Navigator tree and behind overlapping items
    in \uicontrol {Form Editor}. To list the items in the order in which they
    appear in the file, as some other tools do, click \inlineimage filtericon.png
    (\uicontrol {Filter Tree}), and select \uicontrol {Reverse item order}.

    To move an item to the top or bottom of the tree within its parent,
    right-click it in \uicontrol Navigator or \uicontrol {Form Editor}
    and select \uicontrol Arrange > \uicontrol {Bring to Front} or
    \uicontrol {Send to Back}. To move an item up or down, select
    \uicontrol {Bring Forward} or \uicontrol {Send Backward}.

    To reverse the order of the selected items in \uicontrol Navigator and
    \uicontrol {Text Editor}, select \uicontrol Arrange > \uicontrol Reverse.

    \image qtquick-designer-navigator-arrange.gif "Reversing item order"

    You can also drag and drop the item to another position in the tree or use
    the arrow buttons to move the item in the tree. You can use the left and
    right arrow buttons to change the parent of the item.

    \image qmldesigner-navigator-arrows.png "Navigator buttons"

    When you drag and drop instances of QML types to \uicontrol {Form Editor},
    the new item is added as a child of the item
    beneath it. When you move the items, it is not possible to determine whether
    you want to adjust their position or attach them to a new parent item.
    Therefore, the parent item is not automatically changed. To change the
    parent of the item, press down the \key Shift key before you drag and drop
    the item into a new position. The topmost item under the cursor becomes the
    new parent of the item.

    \include qtquick-component-context-menu.qdocinc context-menu
*/
