StackView.qml 41.5 KB
Newer Older
xuebingbing's avatar
xuebingbing committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996
/****************************************************************************
**
** Copyright (C) 2016 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the Qt Quick Controls module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** 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 Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 3 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL3 included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 3 requirements
** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 2.0 or (at your option) the GNU General
** Public license version 3 or any later version approved by the KDE Free
** Qt Foundation. The licenses are as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
** included in the packaging of this file. Please review the following
** information to ensure the GNU General Public License requirements will
** be met: https://www.gnu.org/licenses/gpl-2.0.html and
** https://www.gnu.org/licenses/gpl-3.0.html.
**
** $QT_END_LICENSE$
**
****************************************************************************/

import QtQuick 2.2
import QtQuick.Controls 1.2
import QtQuick.Controls.Private 1.0

/*!
    \qmltype StackView
    \inherits Item
    \ingroup views
    \ingroup controls
    \inqmlmodule QtQuick.Controls
    \since 5.1

    \brief Provides a stack-based navigation model.

    \image stackview.png

    StackView implements a stack-based navigation model, which can be used
    with a set of interlinked information pages. Items are pushed onto the stack
    as the user navigates deeper into the material, and popped off again when he
    chooses to go back.

    The \l{Qt Quick Controls - Touch Gallery}{touch gallery} example is a good
    starting point to understand how StackView works. The following snippet
    from the example shows how it can be used:

    \qml
    StackView {
        id: stack
        initialItem: view

        Component {
            id: view

            MouseArea {
                Text {
                    text: stack.depth
                    anchors.centerIn: parent
                }
                onClicked: stack.push(view)
            }
        }
    }
    \endqml

    \section1 Using StackView in an Application
    Using StackView in an application is typically a simple matter of adding
    the StackView as a child of a Window. The stack is usually anchored to the
    edges of the window, except at the top or bottom where it might be anchored
    to a status bar, or some other similar UI component. The stack can then be
    used by invoking its navigation methods. The first item to show in the StackView
    is the one that was assigned to \l initialItem.

    \note Items pushed onto the stack view have \l{Supported Attached Properties}{Stack attached properties}.

    \section1 Basic Navigation
    There are three primary navigation operations in StackView: push(), pop(), and
    replace (replace by specifying argument \c replace to push()).
    These correspond to classic stack operations where "push" adds an item to the
    top of a stack, "pop" removes the top item from the stack, and "replace" is like a
    pop followed by a push, in that it replaces the topmost item on the stack with
    a new item (but the applied transtition might be different). The topmost item
    in the stack corresponds to the one that is \l{StackView::currentItem} {currently}
    visible on the screen. That means that "push" is the logical equivalent of navigating
    forward or deeper into the application, "pop" is the equivalent of navigating back,
    and "replace" is the equivalent of replacing the current item.

    Sometimes it is necessary to go back more than a single step in the stack, for
    example, to return to a "main" item or some kind of section item in the application.
    For this use case, it is possible to specify an item as a parameter for pop().
    This is called an "unwind" operation as the stack gets unwound to the specified item.
    If the item is not found, then the stack unwinds until there is only a single item in
    the stack, which then becomes the current item. To explicitly unwind to the bottom
    of the stack, it is recommended to use \l{pop()} {pop(null)}, though technically any
    non-existent item will do.

    Given the stack [A, B, C]:

    \list
    \li \l{push()}{push(D)} => [A, B, C, D] - "push" transition animation between C and D
    \li pop() => [A, B] - "pop" transition animation between C and B
    \li \l{push()}{push(D, replace)} => [A, B, D] - "replace" transition between C and D
    \li \l{pop()}{pop(A)} => [A] - "pop" transition between C and A
    \endlist

    \note When the stack is empty, a push() will not perform a
    transition animation because there is nothing to transition from (typically during
    application start-up). A pop() on a stack with depth 1 or 0 is a no-operation.
    If all items need to be removed from the stack, a separate function clear() is
    available.

    Calling push() returns the item that was pushed onto the stack.
    Calling pop() returns the item that was popped off the stack. When pop() is
    called in an unwind operation, the top-most item (the first item that was
    popped, which will also be the one transitioning out) is returned.

    \section1 Deep Linking
    \e{Deep linking} means launching an application into a particular state. For example,
    a newspaper application could be launched into showing a particular article,
    bypassing the front item (and possibly a section item) that would normally have
    to be navigated through to get to the article concerned. In terms of StackView, deep
    linking means the ability to modify the state of the stack, so much so that it is
    possible to push a set of items to the top of the stack, or to completely reset
    the stack to a given state.

    The API for deep linking in StackView is the same as for basic navigation. Pushing
    an array instead of a single item, will involve that all the items in that array will
    be pushed onto the stack. The transition animation, however, will be conducted as
    if only the last item in the array was pushed onto the stack. The normal semantics
    of push() apply for deep linking, meaning that push() adds whatever is pushed onto
    the stack. Note also that only the last item of the array will be loaded.
    The rest will be lazy-loaded as needed when entering the screen upon subsequent
    calls to pop (or when requesting the item by using \a get).

    This gives us the following result, given the stack [A, B, C]:

    \list
    \li \l{push()}{push([D, E, F])} => [A, B, C, D, E, F] - "push" transition animation between C and F
    \li \l{push()}{push([D, E, F], replace)} => [A, B, D, E, F] - "replace" transition animation between C and F
    \li clear(); \l{push()}{push([D, E, F])} => [D, E, F] - no transition animation (since the stack was empty)
    \endlist

    \section1 Pushing items

    An item pushed onto the StackView can be either an Item, a URL, a string
    containing a URL, or a Component. To push it, assign it to a property "item"
    inside a property list, and pass it as an argument to \l{StackView::push}{push}:

    \code
    stackView.push({item: yourItem})
    \endcode

    The list can contain several properties that control how the item should be pushed:
    \list
    \li \c item: this property is required, and holds the item to be pushed.
    \li \c properties: a list of QML properties to be assigned to the item upon push. These
        properties will be copied into the item at load time, or when the item will become
        the current item (normally upon push).
    \li \c immediate: set this property to \c true to skip transition effects. When pushing
        an array, this property only needs to be set on the first element to make the
        whole operation immediate.
    \li \c replace: set this property to replace the current item on the stack. When pushing
        an array, you only need to set this property on the first element to replace
        as many elements on the stack as inside the array.
    \li \c destroyOnPop: set this boolean to \c true if StackView needs to destroy the item when
        it is popped off the stack. By default (if \a destroyOnPop is not specified), StackView
        will destroy items pushed as components or URLs. Items not destroyed will be re-parented
        back to the original parents they had before being pushed onto the stack and hidden.
        If you need to set this property, do it with care, so that items are not leaked.
    \endlist

    If the only argument needed is "item", the following short-hand notation can be applied:

    \code
    stackView.push(yourItem)
    \endcode

    You can push several items in one go by using an array of property lists. This is
    more efficient than pushing items one by one, as StackView can then load only the
    last item in the list. The rest will be loaded as they are about to become
    the current item (which happens when the stack is popped). The following example shows how
    to push an array of items:

    \code
    stackView.push([{item: yourItem1}, {item: yourItem2}])
    \endcode

    If an inline item is pushed, the item is temporarily re-parented into the StackView. When the item
    is later popped off, it gets re-parented back to its original owner again.
    If, however, an item is pushed as a component or a URL, the actual item will be created as an
    item from that component. This happens automatically when the item is about to become the current
    item in the stack. Ownership of the item will then normally be taken by the StackView, which will
    automatically destroy the item when it is later popped off. The component that declared the item, by
    contrast, remains in the ownership of the application and is not destroyed by the stack.
    This can be overridden by explicitly setting \c{destroyOnPop} in the list of arguments given to push.

    If the \c properties to be pushed are specified, they will be copied into the item at loading time
    (in case of a component or URL), or when the item becomes the current item (in case of an inline
    item). The following example shows how this can be done:

    \code
    stackView.push({item: someItem, properties: {fgcolor: "red", bgcolor: "blue"}})
    \endcode


    \note If an item is declared inside another item, and that parent gets destroyed,
    (even if a component was used), that child item will also be destroyed.
    This follows normal Qt parent-child destruction rules, but sometimes comes as a surprise
    for developers.

    \section1 Lifecycle
    An item's lifecycle in the StackView can have the following transitions:
    \list 1
    \li instantiation
    \li inactive
    \li activating
    \li active
    \li deactivating
    \li inactive
    \li destruction
    \endlist

    It can move any number of times between inactive and active. When an item is activated,
    it's visible on the screen and is considered to be the current item. An item
    in a StackView that is not visible is not activated, even if the item is currently the
    top-most item in the stack. When the stack becomes visible, the item that is top-most gets
    activated. Likewise if the stack is then hidden, the topmost item would be deactivated.
    Popping the item off the top of the stack at this point would not result in further
    deactivation since the item is not active.

    There is an attached \l{Stack::status}{Stack.status} property that tracks the lifecycle. This
    property is an enumeration with the following values: \c Stack.Inactive, \c Stack.Activating,
    \c Stack.Active and \c Stack.Deactivating. Combined with the normal \c Component.onComplete and
    \c Component.onDestruction signals, the entire lifecycle is thus:

    \list
    \li Created: Component.onCompleted()
    \li Activating: Stack.onStatusChanged (Stack.status is Stack.Activating)
    \li Acivated: Stack.onStatusChanged (Stack.status is Stack.Active)
    \li Deactivating: Stack.onStatusChanged (Stack.status is Stack.Deactivating)
    \li Deactivated: Stack.onStatusChanged (Stack.status is Stack.Inactive)
    \li Destruction: Component.onDestruction()
    \endlist

    \section1 Finding items
    Sometimes it is necessary to search for an item, for example, in order to unwind the stack to
    an item to which the application does not have a reference. This is facilitated using a
    function find() in StackView. The find() function takes a callback function as its
    only argument. The callback gets invoked for each item in the stack (starting at the top).
    If the callback returns true, then it signals that a match has been found and the find()
    function returns that item. If the callback fails to return true (no match is found),
    then find() returns \c null.

    The code below searches for an item in the stack that has a name "order_id" and then unwinds to
    that item. Note that since find() returns \c {null} if no item is found, and since pop unwinds to
    the bottom of the stack if null is given as the target item, the code works well even in
    case no matching item is found.

    \code
    stackView.pop(stackView.find(function(item) {
        return item.name == "order_id";
    }));
    \endcode

    You can also get to an item in the stack using \l {get()}{get(index)}. You should use
    this function if your item depends on another item in the stack, as the function will
    ensure that the item at the given index gets loaded before it is returned.

    \code
    previousItem = stackView.get(myItem.Stack.index - 1));
    \endcode

    \section1 Transitions

    A transition is performed whenever a item is pushed or popped, and consists of
    two items: enterItem and exitItem. The StackView itself will never move items
    around, but instead delegates the job to an external animation set provided
    by the style or the application developer. How items should visually enter and leave the stack
    (and the geometry they should end up with) is therefore completely controlled from the outside.

    When the transition starts, the StackView will search for a transition that
    matches the operation executed. There are three transitions to choose
    from: \l {StackViewDelegate::}{pushTransition}, \l {StackViewDelegate::}{popTransition},
    and \l {StackViewDelegate::}{replaceTransition}. Each implements how
    \c enterItem should animate in, and \c exitItem out. The transitions are
    collected inside a StackViewDelegate object assigned to
    \l {StackView::delegate}{delegate}. By default, popTransition and
    replaceTransition will be the same as pushTransition, unless you set them
    to something else.

    A simple fade transition could be implemented as:

    \qml
    StackView {
        delegate: StackViewDelegate {
            function transitionFinished(properties)
            {
                properties.exitItem.opacity = 1
            }

            pushTransition: StackViewTransition {
                PropertyAnimation {
                    target: enterItem
                    property: "opacity"
                    from: 0
                    to: 1
                }
                PropertyAnimation {
                    target: exitItem
                    property: "opacity"
                    from: 1
                    to: 0
                }
            }
        }
    }
    \endqml

    PushTransition needs to inherit from StackViewTransition, which is a ParallelAnimation that
    contains the properties \c enterItem and \c exitItem. These items should be assigned to the
    \c target property of animations within the transition. Since the same items instance can
    be pushed several times to a StackView, you should always override
    \l {StackViewDelegate::transitionFinished()}{StackViewDelegate.transitionFinished()}.
    Implement this function to reset any properties animated on the exitItem so that later
    transitions can expect the items to be in a default state.

    A more complex example could look like the following. Here, the items are lying on the side before
    being rotated to an upright position:

    \qml
    StackView {
        delegate: StackViewDelegate {
            function transitionFinished(properties)
            {
                properties.exitItem.x = 0
                properties.exitItem.rotation = 0
            }

            pushTransition: StackViewTransition {
                SequentialAnimation {
                    ScriptAction {
                        script: enterItem.rotation = 90
                    }
                    PropertyAnimation {
                        target: enterItem
                        property: "x"
                        from: enterItem.width
                        to: 0
                    }
                    PropertyAnimation {
                        target: enterItem
                        property: "rotation"
                        from: 90
                        to: 0
                    }
                }
                PropertyAnimation {
                    target: exitItem
                    property: "x"
                    from: 0
                    to: -exitItem.width
                }
            }
        }
    }
    \endqml

    \section2 Advanced usage

    When the StackView needs a new transition, it first calls
    \l {StackViewDelegate::getTransition()}{StackViewDelegate.getTransition()}.
    The base implementation of this function just looks for a property named \c properties.name inside
    itself (root), which is how it finds \c {property Component pushTransition} in the examples above.

    \code
    function getTransition(properties)
    {
        return root[properties.name]
    }
    \endcode

    You can override this function for your delegate if you need extra logic to decide which
    transition to return. You could for example introspect the items, and return different animations
    depending on the their internal state. StackView will expect you to return a Component that
    contains a StackViewTransition, or a StackViewTransition directly. The former is easier, as StackView will
    then create the transition and later destroy it when it's done, while avoiding any side effects
    caused by the transition being alive long after it has run. Returning a StackViewTransition directly
    can be useful if you need to write some sort of transition caching for performance reasons.
    As an optimization, you can also return \c null to signal that you just want to show/hide the items
    immediately without creating or running any transitions. You can also override this function if
    you need to alter the items in any way before the transition starts.

    \c properties contains the properties that will be assigned to the StackViewTransition before
    it runs. In fact, you can add more properties to this object during the call
    if you need to initialize additional properties of your custom StackViewTransition when the returned
    component is instantiated.

    The following example shows how you can decide which animation to use at runtime:

    \qml
    StackViewDelegate {
        function getTransition(properties)
        {
            return (properties.enterItem.Stack.index % 2) ? horizontalTransition : verticalTransition
        }

        function transitionFinished(properties)
        {
            properties.exitItem.x = 0
            properties.exitItem.y = 0
        }

        property Component horizontalTransition: StackViewTransition {
            PropertyAnimation {
                target: enterItem
                property: "x"
                from: target.width
                to: 0
                duration: 300
            }
            PropertyAnimation {
                target: exitItem
                property: "x"
                from: 0
                to: target.width
                duration: 300
            }
        }

        property Component verticalTransition: StackViewTransition {
            PropertyAnimation {
                target: enterItem
                property: "y"
                from: target.height
                to: 0
                duration: 300
            }
            PropertyAnimation {
                target: exitItem
                property: "y"
                from: 0
                to: target.height
                duration: 300
            }
        }
    }
    \endqml

    \section1 Supported Attached Properties

    Items in a StackView support these attached properties:
    \list
        \li \l{Stack::index}{Stack.index} - Contains the index of the item inside the StackView
        \li \l{Stack::view}{Stack.view} - Contains the StackView the item is in
        \li \l{Stack::status}{Stack.status} - Contains the status of the item
    \endlist
*/

FocusScope {
    id: root

    /*! \qmlproperty int StackView::depth
        \readonly
        The number of items currently pushed onto the stack.
    */
    readonly property alias depth: root.__depth

    /*! \qmlproperty Item StackView::currentItem
        \readonly
        The currently top-most item in the stack.
    */
    readonly property alias currentItem: root.__currentItem

    /*! The first item that should be shown when the StackView is created.
        \a initialItem can take same value as the first argument to \l{StackView::push()}
        {StackView.push()}. Note that this is just a convenience for writing
        \c{Component.onCompleted: stackView.push(myInitialItem)}

        Examples:

        \list
        \li initialItem: Qt.resolvedUrl("MyItem.qml")
        \li initialItem: myItem
        \li initialItem: {"item" : Qt.resolvedUrl("MyRectangle.qml"), "properties" : {"color" : "red"}}
        \endlist
        \sa push
    */
    property var initialItem: null

    /*! \readonly
        \a busy is \c true if a transition is running, and \c false otherwise. */
    readonly property bool busy: __currentTransition !== null

    /*! The transitions to use when pushing or popping items.
        For better understanding on how to apply custom transitions, read \l{Transitions}.
        \sa {Transitions} */
    property StackViewDelegate delegate: StackViewSlideDelegate {}

    /*! \qmlmethod Item StackView::push(Item item)
        Pushes an item onto the stack.

        The function can also take a property list as argument - \c {Item StackView::push(jsobject dict)}, which
        should contain one or more of the following properties:
        \list
        \li \c item: this property is required, and holds the item you want to push.
        \li \c properties: a list of QML properties that should be assigned
            to the item upon push. These properties will be copied into the item when it is
            loaded (in case of a component or URL), or when it becomes the current item for the
            first time (normally upon push).
        \li \c immediate: set this property to \c true to skip transition effects. When pushing
            an array, you only need to set this property on the first element to make the
            whole operation immediate.
        \li \c replace: set this property to replace the current item on the stack. When pushing
            an array, you only need to set this property on the first element to replace
            as many elements on the stack as inside the array.
        \li \c destroyOnPop: set this property to specify if the item needs to be destroyed
            when its popped off the stack. By default (if \a destroyOnPop is not specified),
            StackView will destroy items pushed as components or URLs. Items
            not destroyed will be re-parented to the original parents they had before being
            pushed onto the stack, and hidden. If you need to set this property, do it with
            care, so that items are not leaked.
        \endlist

        You can also push an array of items (property lists) if you need to push several items
        in one go. A transition will then only occur between the current item and the last
        item in the list. Loading the other items will be deferred until needed.

        Examples:
        \list
        \li stackView.push({item:anItem})
        \li stackView.push({item:aURL, immediate: true, replace: true})
        \li stackView.push({item:aRectangle, properties:{color:"red"}})
        \li stackView.push({item:aComponent, properties:{color:"red"}})
        \li stackView.push({item:aComponent.createObject(), destroyOnPop:true})
        \li stackView.push([{item:anitem, immediate:true}, {item:aURL}])
        \endlist

        \note If the only argument needed is "item", you can apply the following short-
        hand notation: \c{stackView.push(anItem)}.

        Returns the item that became current.

        \sa initialItem
        \sa {Pushing items}
    */
    function push(item) {
        // Note: we support two different APIs in this function; The old meego API, and
        // the new "property list" API. Hence the reason for hiding the fact that you
        // can pass more arguments than shown in the signature:
        if (__recursionGuard(true))
            return
        var properties = arguments[1]
        var immediate = arguments[2]
        var replace = arguments[3]
        var arrayPushed = (item instanceof Array)
        var firstItem = arrayPushed ? item[0] : item
        immediate = (immediate || JSArray.stackView.length === 0)

        if (firstItem && firstItem.item && firstItem.hasOwnProperty("x") === false) {
            // Property list API used:
            immediate = immediate || firstItem.immediate
            replace = replace || firstItem.replace
        }

        // Create, and push, a new javascript object, called "element", onto the stack.
        // This element contains all the information necessary to construct the item, and
        // will, after loaded, also contain the loaded item:
        if (arrayPushed) {
            if (item.length === 0)
                return
            var outElement = replace ? JSArray.pop() : JSArray.current()
            for (var i=0; i<item.length; ++i)
                JSArray.push({itemComponent:item[i], loaded: false, index: __depth, properties: properties});
        } else {
            outElement = replace ? JSArray.pop() : JSArray.current()
            JSArray.push({itemComponent:item, loaded: false, index: __depth, properties: properties})
        }

        var currentElement = JSArray.current()
        var transition = {
            inElement: currentElement,
            outElement: outElement,
            immediate: immediate,
            replace: replace,
            push: true
        }
        __performTransition(transition)
        __recursionGuard(false)
        return __currentItem
    }

    /*! \qmlmethod Item StackView::pop(Item item = undefined)
        Pops one or more items off the stack.

        The function can also take a property list as argument - \c {Item StackView::pop(jsobject dict)},
        which can contain one or more of the following properties:
        \list
        \li \c item: if specified, all items down to (but not including) \a item will be
            popped off. If \a item is \c null, all items down to (but not including) the
            first item will be popped. If not specified, only the current item will be
            popped.
        \li \c immediate: set this property to \c true to skip transition effects.
        \endlist

        Examples:
        \list
        \li stackView.pop()
        \li stackView.pop({item:someItem, immediate: true})
        \li stackView.pop({immediate: true})
        \li stackView.pop(null)
        \endlist

        \note If the only argument needed is "item", you can apply the following short-
        hand notation: \c{stackView.pop(anItem)}.

        Returns the item that was popped off
        \sa clear()
    */
    function pop(item) {
        if (__depth <= 1)
            return null
        if (item && item.hasOwnProperty("x") === false) {
            // Property list API used:
            var immediate = (item.immediate === true)
            item = item.item
        } else {
            immediate = (arguments[1] === true)
        }

        if (item === __currentItem)
            return

        if (__recursionGuard(true))
            return

        var outElement = JSArray.pop()
        var inElement = JSArray.current()

        if (__depth > 1 && item !== undefined && item !== inElement.item) {
            // Pop from the top until we find 'item', and return the corresponding
            // element. Skip all non-loaded items (except the first), since no one
            // has any references to such items anyway:
            while (__depth > 1 && !JSArray.current().loaded)
                JSArray.pop()
            inElement = JSArray.current()
            while (__depth > 1 && item !== inElement.item) {
                JSArray.pop()
                __cleanup(inElement)
                while (__depth > 1 && !JSArray.current().loaded)
                    JSArray.pop()
                inElement = JSArray.current()
            }
        }

        var transition = {
            inElement: inElement,
            outElement: outElement,
            immediate: immediate,
            replace: false,
            push: false
        }
        __performTransition(transition)
        __recursionGuard(false)
        return outElement.item;
    }

    /*! \qmlmethod void StackView::clear()
        Remove all items from the stack. No animations will be applied. */
    function clear() {
        if (__recursionGuard(true))
            return
        if (__currentTransition)
            __currentTransition.animation.complete()
        __currentItem = null
        var count = __depth
        for (var i=0; i<count; ++i) {
            var element = JSArray.pop()
            if (element.item)
                __cleanup(element);
        }
        __recursionGuard(false)
    }

    /*! \qmlmethod Item StackView::find(function, bool onlySearchLoadedItems = false)
        Search for a specific item inside the stack. \a func will
        be called for each item in the stack (with the item as argument)
        until the function returns true. Return value will be the item found. For
        example:
        find(function(item, index) { return item.isTheOne })
        Set \a onlySearchLoadedItems to \c true to not load items that are
        not loaded into memory */
    function find(func, onlySearchLoadedItems) {
        for (var i=__depth-1; i>=0; --i) {
            var element = JSArray.stackView[i];
            if (onlySearchLoadedItems !== true)
                __loadElement(element)
            else if (!element.item)
                continue
            if (func(element.item))
                return element.item
        }
        return null;
    }

    /*! \qmlmethod Item StackView::get(int index, bool dontLoad = false)
        Returns the item at position \a index in
        the stack. If \a dontLoad is true, the
        item will not be forced to load (and \c null
        will be returned if not yet loaded) */
    function get(index, dontLoad)
    {
        if (index < 0 || index >= JSArray.stackView.length)
            return null
        var element = JSArray.stackView[index]
        if (dontLoad !== true) {
            __loadElement(element)
            return element.item
        } else if (element.item) {
            return element.item
        } else {
            return null
        }
    }

    /*! \qmlmethod void StackView::completeTransition()
        Immediately completes any ongoing transition.
        /sa Animation.complete
      */
    function completeTransition()
    {
        if (__recursionGuard(true))
            return
        if (__currentTransition)
            __currentTransition.animation.complete()
        __recursionGuard(false)
    }

    /********* DEPRECATED API *********/

    /*! \internal
        \deprecated Use Push() instead */
    function replace(item, properties, immediate) {
        push(item, properties, immediate, true)
    }

    /********* PRIVATE API *********/

    /*! \internal The currently top-most item on the stack. */
    property Item __currentItem: null
    /*! \internal The number of items currently pushed onto the stack. */
    property int __depth: 0
    /*! \internal Stores the transition info while a transition is ongoing */
    property var __currentTransition: null
    /*! \internal Stops the user from pushing items while preparing a transition */
    property bool __guard: false

    Component.onCompleted: {
        if (initialItem)
            push(initialItem)
    }

    Component.onDestruction: {
        if (__currentTransition)
            __currentTransition.animation.complete()
        __currentItem = null
    }

    /*! \internal */
    function __recursionGuard(use)
    {
        if (use && __guard) {
            console.warn("Warning: StackView: You cannot push/pop recursively!")
            console.trace()
            return true
        }
        __guard = use
    }

    /*! \internal */
    function __loadElement(element)
    {
        if (element.loaded) {
            if (!element.item) {
                element.item = invalidItemReplacement.createObject(root)
                element.item.text = "\nError: The item has been deleted outside StackView!"
            }
            return
        }
        if (!element.itemComponent) {
            element.item = invalidItemReplacement.createObject(root)
            element.item.text = "\nError: Invalid item (item was 'null'). "
                    + "This might indicate that the item was deleted outside StackView!"
            return
        }

        var comp = __resolveComponent(element.itemComponent, element)

        // Assign properties to item:
        if (!element.properties)
            element.properties = {}

        if (comp.hasOwnProperty("createObject")) {
            if (comp.status === Component.Error) {
                element.item = invalidItemReplacement.createObject(root)
                element.item.text = "\nError: Could not load: " + comp.errorString()
            } else {
                element.item = comp.createObject(root, element.properties)
                // Destroy items we create unless the user specified something else:
                if (!element.hasOwnProperty("destroyOnPop"))
                    element.destroyOnPop = true
            }
        } else {
            // comp is already an Item, so just re-parent it into the StackView:
            element.item = comp
            element.originalParent = parent
            element.item.parent = root
            for (var prop in element.properties) {
                if (element.item.hasOwnProperty(prop))
                    element.item[prop] = element.properties[prop];
            }
            // Do not destroy items we didn't create, unless the user specified something else:
            if (!element.hasOwnProperty("destroyOnPop"))
                element.destroyOnPop = false
        }

        element.item.Stack.__index = element.index
        element.item.Stack.__view = root
        // Let item fill all available space by default:
        element.item.width = Qt.binding(function() { return root.width })
        element.item.height = Qt.binding(function() { return root.height })
        element.loaded = true
    }

    /*! \internal */
    function __resolveComponent(unknownObjectType, element)
    {
        // We need this extra resolve function since we don't really
        // know what kind of object the user pushed. So we try to
        // figure it out by inspecting the object:
        if (unknownObjectType.hasOwnProperty("createObject")) {
            return unknownObjectType
        } else if (typeof unknownObjectType == "string") {
            return Qt.createComponent(unknownObjectType)
        } else if (unknownObjectType.hasOwnProperty("x")) {
            return unknownObjectType
        } else if (unknownObjectType.hasOwnProperty("item")) {
            // INVARIANT: user pushed a JS-object
            element.properties = unknownObjectType.properties
            if (!unknownObjectType.item)
                unknownObjectType.item = invalidItemReplacement
            if (unknownObjectType.hasOwnProperty("destroyOnPop"))
                element.destroyOnPop = unknownObjectType.destroyOnPop
            return __resolveComponent(unknownObjectType.item, element)
        } else {
            // We cannot determine the type, so assume its a URL:
            return Qt.createComponent(unknownObjectType)
        }
    }

    /*! \internal */
    function __cleanup(element) {
        // INVARIANT: element has been removed from JSArray. Destroy its
        // item, or re-parent it back to the parent it had before it was pushed:
        var item = element.item
        if (element.destroyOnPop) {
            item.destroy()
        } else {
            // Mark the item as no longer part of the StackView. It
            // might reenter on pop if pushed several times:
            item.visible = false
            __setStatus(item, Stack.Inactive)
            item.Stack.__view = null
            item.Stack.__index = -1
            if (element.originalParent)
                item.parent = element.originalParent
        }
    }

    /*! \internal */
    function __setStatus(item, status) {
        item.Stack.__status = status
    }

    /*! \internal */
    function __performTransition(transition)
    {
        // Animate item in "outElement" out, and item in "inElement" in. Set a guard to protect
        // the user from pushing new items on signals that will fire while preparing for the transition
        // (e.g Stack.onCompleted, Stack.onStatusChanged, Stack.onIndexChanged etc). Otherwise, we will enter
        // this function several times, which causes the items to be updated half-way.
        if (__currentTransition)
            __currentTransition.animation.complete()
        __loadElement(transition.inElement)

        transition.name = transition.replace ? "replaceTransition" : (transition.push ? "pushTransition" : "popTransition")
        var enterItem = transition.inElement.item
        transition.enterItem = enterItem

        // Since an item can be pushed several times, we need to update its properties:
        enterItem.parent = root
        enterItem.Stack.__view = root
        enterItem.Stack.__index = transition.inElement.index
        __currentItem = enterItem

        if (!transition.outElement) {
            // A transition consists of two items, but we got just one. So just show the item:
            enterItem.visible = true
            __setStatus(enterItem, Stack.Activating)
            __setStatus(enterItem, Stack.Active)
            return
        }

        var exitItem = transition.outElement.item
        transition.exitItem = exitItem
        if (enterItem === exitItem)
             return

        if (root.delegate) {
            transition.properties = {
                "name":transition.name,
                "enterItem":transition.enterItem,
                "exitItem":transition.exitItem,
                "immediate":transition.immediate }
            var anim = root.delegate.getTransition(transition.properties)
            if (anim.createObject) {
                anim = anim.createObject(null, transition.properties)
                anim.runningChanged.connect(function(){ if (anim.running === false) anim.destroy() })
            }
            transition.animation = anim
        }

        if (!transition.animation) {
            console.warn("Warning: StackView: no", transition.name, "found!")
            return
        }
        if (enterItem.anchors.fill || exitItem.anchors.fill)
            console.warn("Warning: StackView: cannot transition an item that is anchored!")

        __currentTransition = transition
        __setStatus(exitItem, Stack.Deactivating)
        enterItem.visible = true
        __setStatus(enterItem, Stack.Activating)
        transition.animation.runningChanged.connect(animationFinished)
        transition.animation.start()
        // NB! For empty animations, "animationFinished" is already
        // executed at this point, leaving __animation === null:
        if (transition.immediate === true && transition.animation)
            transition.animation.complete()
    }

    /*! \internal */
    function animationFinished()
    {
        if (!__currentTransition || __currentTransition.animation.running)
            return

        __currentTransition.animation.runningChanged.disconnect(animationFinished)
        __currentTransition.exitItem.visible = false
        __setStatus(__currentTransition.exitItem, Stack.Inactive);
        __setStatus(__currentTransition.enterItem, Stack.Active);
        __currentTransition.properties.animation = __currentTransition.animation
        root.delegate.transitionFinished(__currentTransition.properties)

        if (!__currentTransition.push || __currentTransition.replace)
            __cleanup(__currentTransition.outElement)

        __currentTransition = null
    }

    /*! \internal */
    property Component invalidItemReplacement: Component {
        Text {
            width: parent.width
            height: parent.height
            wrapMode: Text.WrapAtWordBoundaryOrAnywhere
        }
    }
}