Ubuntu.Components.BottomEdge

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

Properties

• activeRegion : BottomEdgeRegion
• contentComponent : Component
• contentItem : Item
• contentUrl : url
• dragDirection : DragDirection
• dragProgress : real
• hint : BottomEdgeHint
• preloadContent : bool
• regions : list<BottomEdgeRegion>
• status : Status

Signals

• collapseCompleted()
• collapseStarted()
• commitCompleted()
• commitStarted()

Methods

• void collapse()
• void commit()

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

Specifies the current active region.

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

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

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.

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

Defaults to Undefined

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

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

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.

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.

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

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

Signal Documentation

Signal emitted when the content collapse is completed.

Signal emitted when the content collapse is started.

Signal emitted when the content commit is completed.

Signal emitted when the content commit is started.

Method Documentation

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.

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.