Ubuntu.Components.BottomEdge

A component to handle bottom edge gesture and content. More...

Import Statement: import Ubuntu.Components 1.3
Since: Ubuntu.Components 1.3
Inherits:

StyledItem

Properties

Signals

Methods

Detailed Description

The component provides bottom edge content handling. The bottom egde feature is typically composed of a hint and some content. The contentUrl is committed (i.e. fully shown) when the drag is completed after it has been dragged for a certain amount, that is 30% of the height of the BottomEdge. The contentUrl can be anything, defined by contentUrl or contentComponent.

As the name suggests, the component automatically anchors to the bottom of its parent and takes the width of the parent. The drag is detected within the parent area, and the height drives till what extent the bottom edge content should be exposed on commit call. The content is centered into a panel which is dragged from the bottom of the BottomEdge. The content must specify its width and height.

import QtQuick 2.4
import Ubuntu.Components 1.3
MainView {
width: units.gu(40)
height: units.gu(70)
Page {
id: page
title: "BottomEdge"
BottomEdge {
height: parent.height - units.gu(20)
hint.text: "My bottom edge"
contentComponent: Rectangle {
width: page.width
height: page.height
color: UbuntuColors.green
}
}
}
}

Note: The content is specified either through contentUrl or contentComponent, where contentComponent has precedence over contentUrl.

There can be situations when the content depends on the progress of the drag. There are two possibilities to follow this, depending on the use case. The dragProgress provides live updates about the fraction of the drag.

BottomEdge {
id: bottomEdge
height: parent.height
hint.text: "progression"
contentComponent: Rectangle {
width: bottomEdge.width
height: bottomEdge.height
color: Qt.rgba(0.5, 1, bottomEdge.dragProgress, 1);
}
}

The other use case is when the content needs to be completely different in certain regions of the area. These regions can be defined through BottomEdgeRegion elements listed in the regions property.

import QtQuick 2.4
import Ubuntu.Components 1.3
MainView {
width: units.gu(40)
height: units.gu(70)
Page {
title: "BottomEdge"
BottomEdge {
id: bottomEdge
height: parent.height - units.gu(20)
hint.text: "My bottom edge"
contentComponent: Rectangle {
width: bottomEdge.width
height: bottomEdge.height
color: bottomEdge.activeRegion ?
bottomEdge.activeRegion.color : UbuntuColors.green
}
regions: [
BottomEdgeRegion {
from: 0.4
to: 0.6
property color color: UbuntuColors.red
},
BottomEdgeRegion {
from: 0.6
to: 1.0
property color color: UbuntuColors.silk
}
]
}
}
}

Note: Custom regions override the default declared ones. Therefore there must be one region which has its to limit set to 1.0 otherwise the content will not be committed at all.

Note: Regions can also be declared as child elements the same way as resources.

The BottomEdge takes ownership over the custom BottomEdgeRegions, therefore we cannot 'reuse' regions declared in other BottomEdge components, as those will be destroyed together with the reusing BottomEdge component. The following scenario only works if the customRegion is not used in any other regions.

Page {
BottomEdge {
id: bottomEdge
hint.text: "reusing regions"
// put your content and setup here
regions: [customRegion]
}
BottomEdgeRegion {
id: customRegion
from: 0.2
}
}

Page As Content

BottomEdge accepts any component to be set as content. Also it can detect whether the content has a PageHeader component declared, and will inject a collapse navigation action automatically. In case the content has no header, the collapse must be provided by the content itself by calling the collapse function.

BottomEdge {
id: bottomEdge
height: parent.height
hint.text: "Sample collapse"
contentComponent: Rectangle {
width: bottomEdge.width
height: bottomEdge.height
color: Qt.rgba(0.5, 1, bottomEdge.dragProgress, 1);
Button {
text: "Collapse"
onClicked: bottomEdge.collapse()
}
}
}

Alternatively you can put a PageHeader component in your custom content as follows:

BottomEdge {
id: bottomEdge
height: parent.height
hint.text: "Injected collapse"
contentComponent: Rectangle {
width: bottomEdge.width
height: bottomEdge.height
color: Qt.rgba(0.5, 1, bottomEdge.dragProgress, 1);
PageHeader {
title: "Fancy content"
}
}
}

Styling

Similar to the other components the default style is expected to be defined in the theme's BottomEdgeStyle. However the style is not parented to the BottomEdge itself, but to the BottomEdge's parent item. When loaded, the style does not fill the parent but its bottom anchor is set to the bottom of the BottomEdge. Beside this the hint is also parented to the style instance. Custom styles are expected to implement the BottomEgdeStyle API.

See also BottomEdgeRegion.

Property Documentation

[read-only] activeRegion : BottomEdgeRegion

Specifies the current active region.


contentComponent : Component

The property holds the component defining the content of the bottom edge. The property behaves the same way as Loader's sourceComponent property.


[read-only] contentItem : Item

The property holds the item created either from contentUrl or contentComponent properties.


contentUrl : http://doc.qt.io/qt-5/qml-url.html">url

The property holds the url to the document defining the content of the bottom edge. The property behaves the same way as Loader's source property.


[read-only] dragDirection : DragDirection

The property reports the current direction of the drag. The direction is flipped when the drag passes the drag threshold.

DragDirectionDescription
UndefinedDefault. The drag is not performed or the direction is not detected.
UpwardsThe drag is performed from bottom up or it passed the drag threshold from from the last point the drag was going downwards.
DownwardsThe drag is performed from up to bottom or it passed the drag threshold from from the last point the drag was going upwards.

Defaults to Undefined


[read-only] dragProgress : real

The property specifies the proggress of the drag within [0..1] interval.


hint : BottomEdgeHint

The property holds the component to display the hint for the bottom edge element.


preloadContent : bool

If set, all the contents set in the component and in regions will be loaded in the background, so it will be available before it is revealed.


regions : list<BottomEdgeRegion>

The property holds the custom regions configured for the BottomEdge. The default configuration contains one region, which commits the content when reached. The defaults can be restored by setting an empty list to the property or by calling regions.clear(). See BottomEdgeRegion.


[read-only] status : Status

The property reports the actual state of the bottom edge. It can have the following values:

StatusDescription
HiddenThe bottom edge is hidden. This does not contain the hint states.
RevealedThe Bottom edge content is revealed. The state can be reached only if the hint is in "Active" state.
CommittedThe bottom edge content is fully exposed.

Note: Once Commited status is set, no further draging is possible on the content.


Signal Documentation

collapseCompleted()

Signal emitted when the content collapse is completed.


collapseStarted()

Signal emitted when the content collapse is started.


commitCompleted()

Signal emitted when the content commit is completed.


commitStarted()

Signal emitted when the content commit is started.


Method Documentation

void collapse()

The function forces the bottom edge content to be hidden. Emits collapseStarted and collapseCompleted signals to notify the start and the completion of the collapse operation.


void commit()

The function forces the bottom edge content to be fully exposed. Emits commitStarted and commitCompleted signals to notify the start and the completion of the commit operation. It is safe to call commit() multiple times.