From e1b1191e8df727f546bdbbb7da6b14e897c70e7c Mon Sep 17 00:00:00 2001 From: Mitch Curtis Date: Thu, 22 Sep 2016 13:44:52 +0200 Subject: Popup: fix some of the documentation review findings Change-Id: I69b60faab1588a45e005ba721c9796680bad6ac1 Task-number: QTBUG-55904 Reviewed-by: J-P Nurmi --- src/quicktemplates2/qquickpopup.cpp | 86 ++++++++++++++++++++++++++++++++++--- 1 file changed, 79 insertions(+), 7 deletions(-) (limited to 'src/quicktemplates2/qquickpopup.cpp') diff --git a/src/quicktemplates2/qquickpopup.cpp b/src/quicktemplates2/qquickpopup.cpp index 6deda711..a3d68266 100644 --- a/src/quicktemplates2/qquickpopup.cpp +++ b/src/quicktemplates2/qquickpopup.cpp @@ -91,7 +91,10 @@ QT_BEGIN_NAMESPACE scene, it is recommended to use ApplicationWindow. ApplicationWindow also provides background dimming effects. - \sa {Popup Controls}, ApplicationWindow + Popup lays out its content in a similar fashion to \l Control. For more + information, see the \l {Control Layout} section of the documentation. + + \sa {Popup Controls}, {Customizing Popup}, ApplicationWindow */ /*! @@ -820,6 +823,8 @@ QQuickPopup::~QQuickPopup() \qmlmethod void QtQuick.Controls::Popup::open() Opens the popup. + + \sa visible */ void QQuickPopup::open() { @@ -835,6 +840,8 @@ void QQuickPopup::open() \qmlmethod void QtQuick.Controls::Popup::close() Closes the popup. + + \sa visible */ void QQuickPopup::close() { @@ -850,6 +857,8 @@ void QQuickPopup::close() \qmlproperty real QtQuick.Controls::Popup::x This property holds the x-coordinate of the popup. + + \sa y, z */ qreal QQuickPopup::x() const { @@ -867,6 +876,8 @@ void QQuickPopup::setX(qreal x) \qmlproperty real QtQuick.Controls::Popup::y This property holds the y-coordinate of the popup. + + \sa x, z */ qreal QQuickPopup::y() const { @@ -910,7 +921,14 @@ void QQuickPopup::setPosition(const QPointF &pos) \qmlproperty real QtQuick.Controls::Popup::z This property holds the z-value of the popup. Z-value determines - the stacking order of popups. The default z-value is \c 0. + the stacking order of popups. + + If two visible popups have the same z-value, the last one that + was opened will be on top. + + The default z-value is \c 0. + + \sa x, y */ qreal QQuickPopup::z() const { @@ -1075,7 +1093,8 @@ void QQuickPopup::setContentHeight(qreal height) \qmlproperty real QtQuick.Controls::Popup::availableWidth \readonly - This property holds the width available after deducting horizontal padding. + This property holds the width available to the \l contentItem after + deducting horizontal padding from the \l {Item::}{width} of the popup. \sa padding, leftPadding, rightPadding */ @@ -1089,7 +1108,8 @@ qreal QQuickPopup::availableWidth() const \qmlproperty real QtQuick.Controls::Popup::availableHeight \readonly - This property holds the height available after deducting vertical padding. + This property holds the height available to the \l contentItem after + deducting vertical padding from the \l {Item::}{height} of the popup. \sa padding, topPadding, bottomPadding */ @@ -1265,6 +1285,8 @@ void QQuickPopup::resetBottomMargin() This property holds the default padding. + \include qquickpopup-padding.qdocinc + \sa availableWidth, availableHeight, topPadding, leftPadding, rightPadding, bottomPadding */ qreal QQuickPopup::padding() const @@ -1290,6 +1312,8 @@ void QQuickPopup::resetPadding() This property holds the top padding. + \include qquickpopup-padding.qdocinc + \sa padding, bottomPadding, availableHeight */ qreal QQuickPopup::topPadding() const @@ -1315,6 +1339,8 @@ void QQuickPopup::resetTopPadding() This property holds the left padding. + \include qquickpopup-padding.qdocinc + \sa padding, rightPadding, availableWidth */ qreal QQuickPopup::leftPadding() const @@ -1340,6 +1366,8 @@ void QQuickPopup::resetLeftPadding() This property holds the right padding. + \include qquickpopup-padding.qdocinc + \sa padding, leftPadding, availableWidth */ qreal QQuickPopup::rightPadding() const @@ -1365,6 +1393,8 @@ void QQuickPopup::resetRightPadding() This property holds the bottom padding. + \include qquickpopup-padding.qdocinc + \sa padding, topPadding, availableHeight */ qreal QQuickPopup::bottomPadding() const @@ -1492,6 +1522,14 @@ void QQuickPopup::setParentItem(QQuickItem *parent) \note If the background item has no explicit size specified, it automatically follows the popup's size. In most cases, there is no need to specify width or height for a background item. + + \note Most popups use the implicit size of the background item to calculate + the implicit size of the popup itself. If you replace the background item + with a custom one, you should also consider providing a sensible implicit + size for it (unless it is an item like \l Image which has its own implicit + size). + + \sa {Customizing Popup} */ QQuickItem *QQuickPopup::background() const { @@ -1518,6 +1556,17 @@ void QQuickPopup::setBackground(QQuickItem *background) popup is made visible, the content item is automatically reparented to the \l {ApplicationWindow::overlay}{overlay item} of its application window. + + \note The content item is automatically resized to fit within the + \l padding of the popup. + + \note Most popups use the implicit size of the content item to calculate + the implicit size of the popup itself. If you replace the content item + with a custom one, you should also consider providing a sensible implicit + size for it (unless it is an item like \l Text which has its own implicit + size). + + \sa {Customizing Popup} */ QQuickItem *QQuickPopup::contentItem() const { @@ -1537,7 +1586,13 @@ void QQuickPopup::setContentItem(QQuickItem *item) This property holds the list of content data. - \sa Item::data + The list contains all objects that have been declared in QML as children + of the popup. + + \note Unlike \c contentChildren, \c contentData does include non-visual QML + objects. + + \sa Item::data, contentChildren */ QQmlListProperty QQuickPopup::contentData() { @@ -1554,7 +1609,13 @@ QQmlListProperty QQuickPopup::contentData() This property holds the list of content children. - \sa Item::children + The list contains all items that have been declared in QML as children + of the popup. + + \note Unlike \c contentData, \c contentChildren does not include non-visual + QML objects. + + \sa Item::children, contentData */ QQmlListProperty QQuickPopup::contentChildren() { @@ -1589,7 +1650,14 @@ void QQuickPopup::setClip(bool clip) /*! \qmlproperty bool QtQuick.Controls::Popup::focus - This property holds whether the popup has focus. The default value is \c false. + This property holds whether the popup wants focus. + + When the popup actually receives focus, \l activeFocus will be \c true. + For more information, see \l {Keyboard Focus in Qt Quick}. + + The default value is \c false. + + \sa activeFocus */ bool QQuickPopup::hasFocus() const { @@ -1611,6 +1679,8 @@ void QQuickPopup::setFocus(bool focus) \readonly This property holds whether the popup has active focus. + + \sa focus, {Keyboard Focus in Qt Quick} */ bool QQuickPopup::hasActiveFocus() const { @@ -1685,6 +1755,8 @@ void QQuickPopup::resetDim() \qmlproperty bool QtQuick.Controls::Popup::visible This property holds whether the popup is visible. The default value is \c false. + + \sa open(), close() */ bool QQuickPopup::isVisible() const { -- cgit v1.2.3