# BottomEdge QML Type

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

Import Statement: | import Lomiri.Components 1.3
Since: | Lomiri.Components 1.3
Inherits: | StyledItem

- List of all members, including inherited members

## 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 Lomiri.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: LomiriColors.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 Lomiri.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 : LomiriColors.green
                }
                regions: [
                    BottomEdgeRegion {
                        from: 0.4
                        to: 0.6
                        property color color: LomiriColors.red
                    },
                    BottomEdgeRegion {
                        from: 0.6
                        to: 1.0
                        property color color: LomiriColors.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 : 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.

DragDirection | Description
--- | ---
Undefined | Default. The drag is not performed or the direction is not detected.
Upwards | The drag is performed from bottom up or it passed the drag threshold from from the last point the drag was going downwards.
Downwards | The 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:

Status | Description
--- | ---
Hidden | The bottom edge is hidden. This does not contain the hint states.
Revealed | The Bottom edge content is revealed. The state can be reached only if the hint is in "Active" state.
Committed | The 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.

Note: The corresponding handler is `onCollapseCompleted`.

collapseStarted()

Signal emitted when the content collapse is started.

Note: The corresponding handler is `onCollapseStarted`.

commitCompleted()

Signal emitted when the content commit is completed.

Note: The corresponding handler is `onCommitCompleted`.

commitStarted()

Signal emitted when the content commit is started.

Note: The corresponding handler is `onCommitStarted`.

## 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.