• Home
• Felgo
• AppOverlay

AppOverlay

Displays a custom component as a modal overlay. More...

• List of all members, including inherited members

Properties

• animationDuration : int
• backgroundAnimationDuration : int
• backgroundCloseAnimation : Animation
• backgroundColor : color
• backgroundItem : Item
• backgroundOpenAnimation : Animation
• blockBackground : bool
• closeAnimation : Animation
• closeOnBackgroundClick : bool
• closeWithBackButton : bool
• contentItem : alias
• isAnimating : alias
• isClosing : alias
• isOpen : alias
• isOpening : alias
• item : alias
• keepBackgroundVisible : bool
• openAnimation : Animation
• sourceItem : var
• sourceItems : alias
• sourceUrl : url
• useLocalViewArea : bool
• useSafeArea : bool

Signals

• backgroundClicked()
• closed()
• closing(bool keepBackground)
• itemWillDestroy()
• opened()
• opening()

Methods

• void close(bool keepBackground)
• void open()
• void setSource(var source, var properties)

Detailed Description

The AppOverlay type allows to display any custom QML item or component as a fullscreen overlay. It automatically covers item creation, layouting and animations for opening and closing the overlay.

To show an overlay, specify the sourceItem or sourceUrl and call open().

Usage Examples

Open a QML Component as an Overlay

Set the AppOverlay::sourceItem property to show the specified item or component as a fullscreen overlay:

 import Felgo
 import QtQuick

 App {
   NavigationStack {
     AppPage {
       title: "Dynamic Overlay"

       AppButton {
         text: "Open Overlay"
         anchors.centerIn: parent
         onClicked: myOverlay.open()
       }

       AppOverlay {
         id: myOverlay
         sourceItem: overlayComponent
         onOpening: item.closeClicked.connect(myOverlay.close)
       }

       Component {
         id: overlayComponent
         Rectangle {
           id: item
           anchors.centerIn: parent
           color: Theme.backgroundColor
           width: dp(250)
           height: dp(130)

           signal closeClicked

           AppText {
             text: "Dynamic Overlay"
             y: dp(36)
             anchors.horizontalCenter: parent.horizontalCenter
           }

           AppButton {
             text: "Close"
             anchors.horizontalCenter: parent.horizontalCenter
             anchors.bottom: parent.bottom
             flat: true
             onClicked: item.closeClicked()
           }
         }
       }
     }
   }
 }

Alternatively, you can also configure the AppOverlay::sourceUrl property to lazy-load a component via url. The overlay covers dynamic item creation and destruction, as well as animations. When the AppOverlay::opening() signal fires, the dynamic AppOverlay::item is available and the opening animation starts.

When closing the overlay, the itemWillDestroy() signal notifies about the item's destruction. This is only the case when using a component as overlay source.

Lazy-Load a Felgo Dialog on Demand

The AppOverlay makes it easy to turn custom Dialog items into lazy-loaded dialogs. Define the overlay within the Page where you use the dialog, and create the object on-demand:

 import Felgo
 import QtQuick

 App {
   NavigationStack {
     AppPage {
       title: "On-Demand Dialog"

       AppButton {
         text: "Open"
         anchors.horizontalCenter: parent.horizontalCenter
         onClicked: myOverlay.open()
       }

       Component {
         id: dialogComponent
         Dialog {
           backgroundItem: null // no background, covered by overlay

           // custom Dialog configuration
           title: "Do you think this is awesome?"
           positiveActionLabel: "Yes"
           negativeActionLabel: "No"
           onCanceled: title = "Think again!"
           onAccepted: close()

           AppText {
             width: parent.width
             anchors.verticalCenter: parent.verticalCenter
             horizontalAlignment: Text.AlignHCenter
             text: "What do you say?"
           }
         }
       }

       AppOverlay {
         id: myOverlay
         sourceItem: dialogComponent
         useSafeArea: false // Dialog covers full screen

         // open/close the created Dialog item with the overlay
         openAnimation: ScriptAction { script: myOverlay.item.open() }
         closeAnimation: ScriptAction { script: myOverlay.item.close() }

         // close the overlay when the user closes the Dialog item
         onOpening: item.closing.connect(myOverlay.close)
         onItemWillDestroy: item.closing.disconnect(myOverlay.close)
       }
     }
   }
 }

Note: The Dialog::outsideTouchable property is still responsible for handling touch events on the background. The Dialog item covers the full screen even when removing the backgroundItem. AppOverlay::blockBackground or AppOverlay::closeOnBackgroundClick do not have any effect, as the the Dialog grabs all touch events.

Create a Custom Overlay Item

To design a custom overlay you can specify your overlay content inline:

 import Felgo
 import QtQuick

 App {
   NavigationStack {
     AppPage {
       title: "Custom Overlay"

       AppButton {
         text: "Open Overlay"
         anchors.centerIn: parent
         onClicked: myOverlay.open()
       }

       AppOverlay {
         id: myOverlay

         Rectangle {
           anchors.centerIn: parent
           color: Theme.backgroundColor
           width: dp(250)
           height: dp(130)

           AppText {
             text: "Custom Overlay"
             y: dp(36)
             anchors.horizontalCenter: parent.horizontalCenter
           }

           AppButton {
             text: "Close"
             anchors.horizontalCenter: parent.horizontalCenter
             anchors.bottom: parent.bottom
             flat: true
             onClicked: myOverlay.close()
           }
         }
       }
     }
   }
 }

Similar to the sourceItem, all overlay children are placed within the AppOverlay::contentItem container. They are thus aligned and animated depending on the overlay settings, Using a sourceItem instead of nested items is only required if a single overlay is reused to display different sources. Changing the source allows to load a different item then. Inline children are never destroyed and always a part of the overlay.

Customize the Overlay and Animations

The AppOverlay provides many properties to customize the background style and behavior, as well as animations. For example, you can hide the background and animate the content item's scale instead of the opacity:

 import Felgo
 import QtQuick

 App {
   NavigationStack {
     AppPage {
       title: "Customized Overlay"

       AppButton {
         text: "Open Overlay"
         anchors.centerIn: parent
         onClicked: myOverlay.open()
       }

       AppOverlay {
         id: myOverlay
         backgroundItem: null // remove background item

         // specify overlay content
         Rectangle {
           anchors.centerIn: parent
           color: "lightyellow"
           width: dp(250)
           height: dp(130)

           AppText {
             text: "Custom Overlay"
             y: dp(36)
             anchors.horizontalCenter: parent.horizontalCenter
           }

           AppButton {
             text: "Close"
             anchors.horizontalCenter: parent.horizontalCenter
             anchors.bottom: parent.bottom
             flat: true
             onClicked: myOverlay.close()
           }
         }

         // set custom animation
         animationDuration: 300
         openAnimation: NumberAnimation {
           duration: myOverlay.animationDuration
           property: "scale"
           from: 0
           to: 1
         }
         closeAnimation:  NumberAnimation {
           duration: myOverlay.animationDuration
           property: "scale"
           from: 1
           to: 0
         }
       }
     }
   }
 }

Apart from the backgroundItem slot that specifies the used background, you can also control the touch behavior when interacting with the background area. The AppOverlay::closeOnBackgroundClick setting decides whether touching the background automatically closes the overlay. To not handle touches and allow app interactions below the background, deactivate AppOverlay::blockBackground.

Safe Area Handling and Fullscreen Overlays

Display notches and cutouts can cover parts of your fullscreen content. The AppOverlay automatically handles this issue and only places your content within the safe area of the screen. Deactivate AppOverlay::useSafeArea to let your content cover the full screen:

 import Felgo
 import QtQuick

 App {
   NavigationStack {
     AppPage {
       title: "Fullscreen Overlay"

       AppButton {
         text: "Show Image"
         anchors.centerIn: parent
         onClicked: mediaOverlay.open()
       }

       AppOverlay {
         id: mediaOverlay
         useSafeArea: false // let image cover the full screen

         Rectangle {
           anchors.fill: parent
           color: "white"
           Image {
             anchors.fill: parent
             fillMode: Image.PreserveAspectFit
             source: "https://felgo.com/web-assets/felgo-logo.png"
           }
         }

         MouseArea {
           anchors.fill: parent
           onClicked: mediaOverlay.close()
         }
       }

     }
   }
 }

In addition to alignment with the safe area or the full screen, the overlay also supports to display content within the local item that surrounds the overlay. The following example overlays an Image within the Page boundaries. The backgroundItem still darkends the full screen:

 import Felgo
 import QtQuick

 App {
   NavigationStack {
     AppPage {
       title: "Page Overlay"

       AppButton {
         text: "Show Image"
         anchors.centerIn: parent
         onClicked: mediaOverlay.open()
       }

       AppOverlay {
         id: mediaOverlay
         // let image cover overlay parent, this is the page content in this example
         useLocalViewArea: true

         Rectangle {
           anchors.fill: parent
           color: "white"
           Image {
             anchors.fill: parent
             fillMode: Image.PreserveAspectFit
             source: "https://felgo.com/web-assets/felgo-logo.png"
           }
         }

         MouseArea {
           anchors.fill: parent
           onClicked: mediaOverlay.close()
         }
       }

     }
   }
 }

Showing a Sequence of Overlays

The keepBackgroundVisible property provides the possibility to only fade the content when switching between different overlay sources. This allows to show a sequence of overlays while keeping the background visible and the screen locked.

To fully close the overlay after such a sequence, deactivate keepBackgroundVisible before the final close() call:

 import Felgo
 import QtQuick

 App {
   NavigationStack {
     AppPage {
       title: "Overlay Sequence"

       AppButton {
         text: "Show Overlay Sequence"
         anchors.centerIn: parent
         onClicked: overlayGroup.open()
       }

       Component {
         id: firstMessage
         AppText {
           anchors.centerIn: parent
           text: "First Message"
         }
       }

       Component {
         id: secondMessage
         AppText {
           anchors.centerIn: parent
           text: "Second Message"
         }
       }

       Component {
         id: lastMessage
         AppText {
           anchors.centerIn: parent
           text: "Last Message"
         }
       }

       AppOverlay {
         id: overlayGroup

         property var messages: [firstMessage, secondMessage, lastMessage]
         property int currentIndex: 0

         sourceItem: messages[currentIndex]
         backgroundColor: "lightgrey"

         // the overlay does not hide the background by default
         keepBackgroundVisible: true

         // when opening the last message, configure the overlay to fully hide
         onOpening: {
           if(sourceItem === lastMessage) {
             keepBackgroundVisible = false
           }
         }

         // when a message is closed, open the next one
         onClosed: {
           // open next message if not the last one
           if(sourceItem !== lastMessage) {
             currentIndex++
             open()
           }
           // sequence done, reset the overlay to original
           else {
             currentIndex = 0
             keepBackgroundVisible = true
           }
         }
       } // AppOverlay
     }
   }
 }

Alternatively, you can also overwrite the default close behavior to keep the background visible during the sequence:

 import Felgo
 import QtQuick

 App {
   NavigationStack {
     AppPage {
       title: "Overlay Sequence"

       AppButton {
         text: "Show Overlay Sequence"
         anchors.centerIn: parent
         onClicked: overlayGroup.open()
       }

       Component {
         id: firstMessage
         AppText {
           anchors.centerIn: parent
           text: "First Message"
         }
       }

       Component {
         id: secondMessage
         AppText {
           anchors.centerIn: parent
           text: "Second Message"
         }
       }

       Component {
         id: lastMessage
         AppText {
           anchors.centerIn: parent
           text: "Last Message"
         }
       }

       AppOverlay {
         id: overlayGroup

         property var messages: [firstMessage, secondMessage, lastMessage]
         property int currentIndex: 0

         sourceItem: messages[currentIndex]
         backgroundColor: "lightgrey"

         // do not automatically close the overlay when clicking the background
         closeOnBackgroundClick: false

         onBackgroundClicked: {
           // if its the last message, fully close the overlay, otherwise keep the background
           close(sourceItem !== lastMessage)
         }

         // when a message is closed, open the next one
         onClosed: {
           // open next message if not the last one
           if(sourceItem !== lastMessage) {
             currentIndex++
             open()
           }
           // sequence done, reset the overlay to original
           else {
             currentIndex = 0
           }
         }
       } // AppOverlay
     }
   }
 }

Deactivate the closeOnBackgroundClick property and use the backgroundClicked() signal to add custom handler code. To keep the background while closing, pass true for the optional parameter of the close() function.

Property Documentation

Signal Documentation

Method Documentation