From 281469e947e6b09a44c296a26db474db815f6238 Mon Sep 17 00:00:00 2001 From: J-P Nurmi Date: Mon, 31 Oct 2016 17:01:57 +0100 Subject: Doc: fix review findings for Popup Change-Id: I8494ffe1a46a05a01d31787783b5f8e9cc810f36 Task-number: QTBUG-55904 Reviewed-by: Mitch Curtis --- src/quicktemplates2/qquickpopup.cpp | 148 +++++++++++++++++++++++++++++++++--- 1 file changed, 137 insertions(+), 11 deletions(-) (limited to 'src/quicktemplates2/qquickpopup.cpp') diff --git a/src/quicktemplates2/qquickpopup.cpp b/src/quicktemplates2/qquickpopup.cpp index d343fad6..6273e4ef 100644 --- a/src/quicktemplates2/qquickpopup.cpp +++ b/src/quicktemplates2/qquickpopup.cpp @@ -57,13 +57,13 @@ QT_BEGIN_NAMESPACE \brief The base type of popup-like user interface controls. Popup is the base type of popup-like user interface controls. It can be - used with Window or ApplicationWindow. + used with \l Window or \l ApplicationWindow. \qml import QtQuick.Window 2.2 import QtQuick.Controls 2.0 - Window { + ApplicationWindow { id: window width: 400 height: 400 @@ -91,8 +91,79 @@ QT_BEGIN_NAMESPACE scene, it is recommended to use ApplicationWindow. ApplicationWindow also provides background dimming effects. - Popup lays out its content in a similar fashion to \l Control. For more - information, see the \l {Control Layout} section of the documentation. + Popup does not provide a layout of its own, but requires you to position + its contents, for instance by creating a \l RowLayout or a \l ColumnLayout. + + Items declared as children of a Popup are automatically parented to the + Popups's \l contentItem. Items created dynamically need to be explicitly + parented to the contentItem. + + \section1 Popup Layout + + The following diagram illustrates the layout of a typical popup: + + \image qtquickcontrols2-popup.png + + The \l implicitWidth and \l implicitHeight of a popup are typically based + on the implicit sizes of the background and the content item plus any + \l padding. These properties determine how large the popup will be when no + explicit \l width or \l height is specified. + + The \l background item fills the entire width and height of the popup, + unless an explicit size has been given for it. + + The geometry of the \l contentItem is determined by the \l padding. + + \section1 Popup Sizing + + If only a single item is used within a Popup, it will resize to fit the + implicit size of its contained item. This makes it particularly suitable + for use together with layouts. + + \code + Popup { + ColumnLayout { + anchors.fill: parent + CheckBox { text: qsTr("E-mail") } + CheckBox { text: qsTr("Calendar") } + CheckBox { text: qsTr("Contacts") } + } + } + \endcode + + Sometimes there might be two items within the popup: + + \code + Popup { + SwipeView { + // ... + } + PageIndicator { + anchors.horizontalCenter: parent.horizontalCenter + anchors.bottom: parent.bottom + } + } + \endcode + + In this case, Popup cannot calculate a sensible implicit size. Since we're + anchoring the \l PageIndicator over the \l SwipeView, we can simply set the + content size to the view's implicit size: + + \code + Popup { + contentWidth: view.implicitWidth + contentHeight: view.implicitHeight + + SwipeView { + id: view + // ... + } + PageIndicator { + anchors.horizontalCenter: parent.horizontalCenter + anchors.bottom: parent.bottom + } + } + \endcode \sa {Popup Controls}, {Customizing Popup}, ApplicationWindow */ @@ -1060,8 +1131,9 @@ void QQuickPopup::setImplicitHeight(qreal height) This property holds the content width. It is used for calculating the total implicit width of the Popup. - \note If only a single item is used within the Popup, the implicit width - of its contained item is used as the content width. + For more information, see \l {Popup Sizing}. + + \sa contentHeight */ qreal QQuickPopup::contentWidth() const { @@ -1085,8 +1157,9 @@ void QQuickPopup::setContentWidth(qreal width) This property holds the content height. It is used for calculating the total implicit height of the Popup. - \note If only a single item is used within the Popup, the implicit height - of its contained item is used as the content height. + For more information, see \l {Popup Sizing}. + + \sa contentWidth */ qreal QQuickPopup::contentHeight() const { @@ -1459,6 +1532,28 @@ void QQuickPopup::resetLocale() \qmlproperty font QtQuick.Controls::Popup::font This property holds the font currently set for the popup. + + Popup propagates explicit font properties to its children. If you change a specific + property on a popup's font, that property propagates to all of the popup's children, + overriding any system defaults for that property. + + \code + Popup { + font.family: "Courier" + + Column { + Label { + text: qsTr("This will use Courier...") + } + + Switch { + text: qsTr("... and so will this") + } + } + } + \endcode + + \sa Control::font, ApplicationWindow::font */ QFont QQuickPopup::font() const { @@ -1798,7 +1893,10 @@ void QQuickPopup::setVisible(bool visible) /*! \qmlproperty real QtQuick.Controls::Popup::opacity - This property holds the opacity of the popup. The default value is \c 1.0. + This property holds the opacity of the popup. Opacity is specified as a number between + \c 0.0 (fully transparent) and \c 1.0 (fully opaque). The default value is \c 1.0. + + \sa visible */ qreal QQuickPopup::opacity() const { @@ -1816,6 +1914,10 @@ void QQuickPopup::setOpacity(qreal opacity) \qmlproperty real QtQuick.Controls::Popup::scale This property holds the scale factor of the popup. The default value is \c 1.0. + + A scale of less than \c 1.0 causes the popup to be rendered at a smaller size, + and a scale greater than \c 1.0 renders the popup at a larger size. A negative + scale causes the popup to be mirrored when rendered. */ qreal QQuickPopup::scale() const { @@ -1891,8 +1993,20 @@ void QQuickPopup::setTransformOrigin(TransformOrigin origin) /*! \qmlproperty Transition QtQuick.Controls::Popup::enter - This property holds the transition that is applied to the content item + This property holds the transition that is applied to the popup item when the popup is opened and enters the screen. + + The following example animates the opacity of the popup when it enters + the screen: + \code + Popup { + enter: Transition { + NumberAnimation { property: "opacity"; from: 0.0; to: 1.0 } + } + } + \endcode + + \sa exit */ QQuickTransition *QQuickPopup::enter() const { @@ -1912,8 +2026,20 @@ void QQuickPopup::setEnter(QQuickTransition *transition) /*! \qmlproperty Transition QtQuick.Controls::Popup::exit - This property holds the transition that is applied to the content item + This property holds the transition that is applied to the popup item when the popup is closed and exits the screen. + + The following example animates the opacity of the popup when it exits + the screen: + \code + Popup { + exit: Transition { + NumberAnimation { property: "opacity"; from: 1.0; to: 0.0 } + } + } + \endcode + + \sa enter */ QQuickTransition *QQuickPopup::exit() const { -- cgit v1.2.3