From f043b64c37d35775f5d6498a5d9dfe42cd28b0d7 Mon Sep 17 00:00:00 2001 From: Nico Vertriest Date: Mon, 30 May 2016 16:17:05 +0200 Subject: Doc: Updated doc on usage Controls 2. Change-Id: If256dafc53d63b174b5cfd03eb91635e062d7c69 Reviewed-by: Venugopal Shivashankar Reviewed-by: Mitch Curtis --- .../doc/src/qtquickcontrols2-containers.qdoc | 14 ++++++++--- .../doc/src/qtquickcontrols2-delegates.qdoc | 10 ++++++++ .../doc/src/qtquickcontrols2-indicators.qdoc | 7 +++--- .../controls/doc/src/qtquickcontrols2-input.qdoc | 28 ++++++++++++++++++++-- .../controls/doc/src/qtquickcontrols2-menus.qdoc | 12 +++++++++- .../doc/src/qtquickcontrols2-navigation.qdoc | 20 ++++++++++++---- .../controls/doc/src/qtquickcontrols2-popups.qdoc | 4 +++- 7 files changed, 81 insertions(+), 14 deletions(-) (limited to 'src/imports/controls/doc/src') diff --git a/src/imports/controls/doc/src/qtquickcontrols2-containers.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-containers.qdoc index 1786a4f1..c7a68968 100644 --- a/src/imports/controls/doc/src/qtquickcontrols2-containers.qdoc +++ b/src/imports/controls/doc/src/qtquickcontrols2-containers.qdoc @@ -41,7 +41,8 @@ \image qtquickcontrols2-applicationwindow-wireframe.png - \l ApplicationWindow contains optional header and footer items. + \l ApplicationWindow creates the root window of an application, and makes + it easy to add an optional header and footer to that window. \section1 Frame Control @@ -62,19 +63,26 @@ \image qtquickcontrols2-page-wireframe.png \l Page provides page-specific header and footer items. + It is perfectly possible to use ApplicationWindow for setting the header + and the footer, but if you have a header and footer which varies per + screen, then it is better to use \l Page. \section1 Pane Control \image qtquickcontrols2-pane.png \l Pane provides a background color that matches with the application - style and theme. + style and theme. Pane does not provide a layout of its own, but requires + you to position its contents, for instance by using a \l RowLayout or + a \l ColumnLayout. \section1 StackView Control \image qtquickcontrols2-stackview-wireframe.png - \l StackView organizes content pages into a stack. + \l StackView organizes content pages into a stack using a last-in-first-out + principle: the last item to be "pushed" onto the stack is the first one to + be removed, and the top-most item is always the one that is visible. \section1 SwipeView Control diff --git a/src/imports/controls/doc/src/qtquickcontrols2-delegates.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-delegates.qdoc index 3c8d5ea7..41e9ced4 100644 --- a/src/imports/controls/doc/src/qtquickcontrols2-delegates.qdoc +++ b/src/imports/controls/doc/src/qtquickcontrols2-delegates.qdoc @@ -52,5 +52,15 @@ \l RadioDelegate presents a checkable control that can be toggled on (checked) or off (unchecked). Radio delegates are typically used to select one option from a set of options. + + \b {See also} \l {RadioButton Control}. + + \section1 SwitchDelegate Control + + \image qtquickcontrols2-switchdelegate.gif + + \l SwitchDelegate presents a switchable delegate that can be toggled on or off. + + \b {See also} \l {Switch Control}. */ diff --git a/src/imports/controls/doc/src/qtquickcontrols2-indicators.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-indicators.qdoc index dcc0ff9e..0d6818ce 100644 --- a/src/imports/controls/doc/src/qtquickcontrols2-indicators.qdoc +++ b/src/imports/controls/doc/src/qtquickcontrols2-indicators.qdoc @@ -47,8 +47,8 @@ \image qtquickcontrols2-pageindicator.png - \l PageIndicator is used to indicate the currently active page in - a container of multiple pages. + \l BusyIndicator can be used to show that an operation is in progress, + and that the UI has to wait for the operation to complete. \section1 ScrollBar Control @@ -63,5 +63,6 @@ \image qtquickcontrols2-scrollindicator.png \l ScrollIndicator is a non-interactive indicator that indicates the - current scroll position in a \l Flickable. + current scroll position, and can be used to scroll to a specific position in a + \l {Flickable}. */ diff --git a/src/imports/controls/doc/src/qtquickcontrols2-input.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-input.qdoc index 60b2250f..e9aa3646 100644 --- a/src/imports/controls/doc/src/qtquickcontrols2-input.qdoc +++ b/src/imports/controls/doc/src/qtquickcontrols2-input.qdoc @@ -42,13 +42,30 @@ \image qtquickcontrols2-combobox.png - \l ComboBox is used to select a value from a drop-down list. + \l ComboBox is used to select a value from a static multiple-line drop-down list. + It is not possible to add new values, and only one option can be selected. + + Recommendations: + \list + \li If the number of values is very large, consider applying a filter. + \li If the list is very limited, consider using RadioButton. This has the + advantage that the user can see all options at the same time. + \li Select a default value, the value that will be chosen most often. + \endlist + + \b {See also} \l {CheckBox Control}, \l {Tumbler Control}. \section1 Dial Control \image qtquickcontrols2-dial.png - \l Dial is a circular dial that is rotated to set a value. + \l Dial is similar to a traditional dial knob that is found on devices such + as stereos or industrial equipment. + + The dial is rotated by clicking and dragging, with the handle indicating the + value of the dial. + + \b {See also} \l {Tumbler Control}. \section1 TextArea Control @@ -62,6 +79,8 @@ \l TextField is a single line text editor. + \b {See also} \l {Tumbler Control}. + \section1 Slider Control \image qtquickcontrols2-slider.png @@ -75,9 +94,14 @@ \l RangeSlider is used to select a range specified by two values, by sliding each handle along a track. + + \b {See also} \l {Slider Control}. + \section1 Tumbler Control \image qtquickcontrols2-tumbler.png \l Tumbler is a spinnable wheel of items that can be selected. + + \b {See also} \l {ComboBox Control}. */ diff --git a/src/imports/controls/doc/src/qtquickcontrols2-menus.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-menus.qdoc index d54b360c..22b96e96 100644 --- a/src/imports/controls/doc/src/qtquickcontrols2-menus.qdoc +++ b/src/imports/controls/doc/src/qtquickcontrols2-menus.qdoc @@ -39,5 +39,15 @@ \image qtquickcontrols2-menu.png - \l Menu is a traditional menu. + \l Menu control can be used for context menus; for example, after + right-clicking. It can also be used for popup menus; for example, a + menu that is shown after clicking a button. + + \l MenuItem is an item in the Menu control. Each item in a menu: + \list + \li displays text to the user + \li allows checking/unchecking + \li is highlighted (for example, on keyboard navigation) + \li performs some action on activation + \endlist */ diff --git a/src/imports/controls/doc/src/qtquickcontrols2-navigation.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-navigation.qdoc index 8ddc2f3a..9180d480 100644 --- a/src/imports/controls/doc/src/qtquickcontrols2-navigation.qdoc +++ b/src/imports/controls/doc/src/qtquickcontrols2-navigation.qdoc @@ -40,17 +40,29 @@ \image qtquickcontrols2-stackview-wireframe.png - \l StackView provides a stack-based navigation model. + \l StackView provides a stack-based navigation model which can be used + with a set of interlinked pages. StackView works according to a last-in + first-out principle: the page pushed last on the stack is the one visible. + Popping a page removes the last page and makes the previous one visible. \section1 SwipeView Control \image qtquickcontrols2-swipeview-wireframe.png - \l SwipeView provides a swipe-based navigation model. + \l SwipeView provides a navigation model that simplifies horizontal paged + scrolling. The page indicator on the bottom shows which is the presently + active page. - \section1 TabBar and TabButton Controls + \section1 TabBar \image qtquickcontrols2-tabbar-wireframe.png - \l TabBar and \l TabButton provide a tab-based navigation model. + \l TabBar is a bar with icons or text that allows the user to switch + between different subtasks, views, or modes. + + \section1 TabButton Control + + \image qtquickcontrols2-tabbutton.png + + \l TabButton is a button with a layout suitable for a TabBar control. */ diff --git a/src/imports/controls/doc/src/qtquickcontrols2-popups.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-popups.qdoc index 2ea21f3f..c93f13e4 100644 --- a/src/imports/controls/doc/src/qtquickcontrols2-popups.qdoc +++ b/src/imports/controls/doc/src/qtquickcontrols2-popups.qdoc @@ -53,6 +53,8 @@ The \l Menu control displays a vertical list of items that can be selected. It can be used for offering a list of actions that can be taken in a given context. + \b {See also} \l {Drawer Control}. + \section1 Popup Control \image qtquickcontrols2-popup-settings.png @@ -76,7 +78,7 @@ \image qtquickcontrols2-tooltip.png \l ToolTip shows a short piece of text that informs the user of a control's - function. + function. It is typically placed above or below the parent control. Recommendations: \list -- cgit v1.2.3 From d400ab8290eaae7c3d3e74ea99a9136247d87e4f Mon Sep 17 00:00:00 2001 From: Nico Vertriest Date: Tue, 24 May 2016 10:54:42 +0200 Subject: Doc: Collect a list of guidelines pages Change-Id: Ie64486275b7fc39005cc6f86f33f04444474c07e Reviewed-by: Venugopal Shivashankar --- .../controls/doc/src/qtquickcontrols2-buttons.qdoc | 6 +++ .../doc/src/qtquickcontrols2-delegates.qdoc | 7 ++++ .../doc/src/qtquickcontrols2-guidelines.qdoc | 44 ++++++++++++++++++++++ .../controls/doc/src/qtquickcontrols2-index.qdoc | 1 + .../doc/src/qtquickcontrols2-indicators.qdoc | 7 ++++ .../controls/doc/src/qtquickcontrols2-input.qdoc | 7 ++++ .../controls/doc/src/qtquickcontrols2-menus.qdoc | 2 + .../doc/src/qtquickcontrols2-navigation.qdoc | 2 + .../controls/doc/src/qtquickcontrols2-popups.qdoc | 7 ++++ .../doc/src/qtquickcontrols2-qmltypes.qdoc | 5 +++ 10 files changed, 88 insertions(+) create mode 100644 src/imports/controls/doc/src/qtquickcontrols2-guidelines.qdoc (limited to 'src/imports/controls/doc/src') diff --git a/src/imports/controls/doc/src/qtquickcontrols2-buttons.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-buttons.qdoc index ef084fcf..48b0097d 100644 --- a/src/imports/controls/doc/src/qtquickcontrols2-buttons.qdoc +++ b/src/imports/controls/doc/src/qtquickcontrols2-buttons.qdoc @@ -28,6 +28,8 @@ /*! \page qtquickcontrols2-buttons.html \title Button Controls + \ingroup qtquickcontrols2-guidelines + \brief Guidelines for button controls Qt Quick Controls 2 offers a selection of button-like controls. @@ -162,4 +164,8 @@ \b {See also} \l ToolButton + \section1 Related Information + \list + \li \l {Qt Quick Controls 2 Guidelines} + \endlist */ diff --git a/src/imports/controls/doc/src/qtquickcontrols2-delegates.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-delegates.qdoc index 41e9ced4..0ecfdf42 100644 --- a/src/imports/controls/doc/src/qtquickcontrols2-delegates.qdoc +++ b/src/imports/controls/doc/src/qtquickcontrols2-delegates.qdoc @@ -28,6 +28,8 @@ /*! \page qtquickcontrols2-delegates.html \title Delegate Controls + \ingroup qtquickcontrols2-guidelines + \brief Guidelines for delegate controls Qt Quick Controls 2 offers a selection of controls that are used as delegates in views. @@ -62,5 +64,10 @@ \l SwitchDelegate presents a switchable delegate that can be toggled on or off. \b {See also} \l {Switch Control}. + + \section1 Related Information + \list + \li \l {Qt Quick Controls 2 Guidelines} + \endlist */ diff --git a/src/imports/controls/doc/src/qtquickcontrols2-guidelines.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-guidelines.qdoc new file mode 100644 index 00000000..87ba4cf1 --- /dev/null +++ b/src/imports/controls/doc/src/qtquickcontrols2-guidelines.qdoc @@ -0,0 +1,44 @@ +/**************************************************************************** +** +** Copyright (C) 2016 The Qt Company Ltd. +** Contact: http://www.qt.io/licensing/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see http://www.qt.io/terms-conditions. For further +** information use the contact form at http://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page qtquickcontrols2-guidelines.html + \title Qt Quick Controls 2 Guidelines + + Qt Quick Controls 2 offers a selection of controls that can be used to + build complete interfaces in Qt Quick. + + Below you will find practical guidelines on how and when to use + the controls. + + \annotatedlist qtquickcontrols2-guidelines + + \section1 Related Information + \list + \li \l{Qt Quick Controls 2 QML Types}{All Qt Quick Controls 2 QML Types} + \endlist +*/ diff --git a/src/imports/controls/doc/src/qtquickcontrols2-index.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-index.qdoc index 3f4467d5..171239ce 100644 --- a/src/imports/controls/doc/src/qtquickcontrols2-index.qdoc +++ b/src/imports/controls/doc/src/qtquickcontrols2-index.qdoc @@ -62,6 +62,7 @@ \section1 Important Concepts in Qt Quick Controls 2 \list + \li \l{Qt Quick Controls 2 Guidelines} \li \l{Styling Qt Quick Controls 2} \li \l{Customizing Qt Quick Controls 2} \li \l{High-DPI Support in Qt Quick Controls 2} diff --git a/src/imports/controls/doc/src/qtquickcontrols2-indicators.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-indicators.qdoc index 0d6818ce..010ff444 100644 --- a/src/imports/controls/doc/src/qtquickcontrols2-indicators.qdoc +++ b/src/imports/controls/doc/src/qtquickcontrols2-indicators.qdoc @@ -28,6 +28,8 @@ /*! \page qtquickcontrols2-indicators.html \title Indicator Controls + \ingroup qtquickcontrols2-guidelines + \brief Guidelines for indicator controls Qt Quick Controls 2 offers a selection of indicator-like controls. @@ -65,4 +67,9 @@ \l ScrollIndicator is a non-interactive indicator that indicates the current scroll position, and can be used to scroll to a specific position in a \l {Flickable}. + + \section1 Related Information + \list + \li \l {Qt Quick Controls 2 Guidelines} + \endlist */ diff --git a/src/imports/controls/doc/src/qtquickcontrols2-input.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-input.qdoc index e9aa3646..681a9d89 100644 --- a/src/imports/controls/doc/src/qtquickcontrols2-input.qdoc +++ b/src/imports/controls/doc/src/qtquickcontrols2-input.qdoc @@ -28,6 +28,8 @@ /*! \page qtquickcontrols2-input.html \title Input Controls + \ingroup qtquickcontrols2-guidelines + \brief Guidelines for input controls Qt Quick Controls 2 offers a variety of input controls for both numeric and textual input. @@ -104,4 +106,9 @@ \l Tumbler is a spinnable wheel of items that can be selected. \b {See also} \l {ComboBox Control}. + + \section1 Related Information + \list + \li \l {Qt Quick Controls 2 Guidelines} + \endlist */ diff --git a/src/imports/controls/doc/src/qtquickcontrols2-menus.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-menus.qdoc index 22b96e96..faa8c3bc 100644 --- a/src/imports/controls/doc/src/qtquickcontrols2-menus.qdoc +++ b/src/imports/controls/doc/src/qtquickcontrols2-menus.qdoc @@ -28,6 +28,8 @@ /*! \page qtquickcontrols2-menus.html \title Menu Controls + \ingroup qtquickcontrols2-guidelines + \brief Guidelines for menu controls \annotatedlist qtquickcontrols2-menus diff --git a/src/imports/controls/doc/src/qtquickcontrols2-navigation.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-navigation.qdoc index 9180d480..a2bd15a6 100644 --- a/src/imports/controls/doc/src/qtquickcontrols2-navigation.qdoc +++ b/src/imports/controls/doc/src/qtquickcontrols2-navigation.qdoc @@ -28,6 +28,8 @@ /*! \page qtquickcontrols2-navigation.html \title Navigation Controls + \ingroup qtquickcontrols2-guidelines + \brief Guidelines for navigation controls Qt Quick Controls 2 offers a selection of navigation models. diff --git a/src/imports/controls/doc/src/qtquickcontrols2-popups.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-popups.qdoc index c93f13e4..aa2efb90 100644 --- a/src/imports/controls/doc/src/qtquickcontrols2-popups.qdoc +++ b/src/imports/controls/doc/src/qtquickcontrols2-popups.qdoc @@ -28,6 +28,8 @@ /*! \page qtquickcontrols2-popups.html \title Popup Controls + \ingroup qtquickcontrols2-guidelines + \brief Guidelines for popup controls \annotatedlist qtquickcontrols2-popups @@ -89,4 +91,9 @@ \li Keep the tooltip text short so that it does not cover other content while being displayed. \endlist + + \section1 Related Information + \list + \li \l {Qt Quick Controls 2 Guidelines} + \endlist */ diff --git a/src/imports/controls/doc/src/qtquickcontrols2-qmltypes.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-qmltypes.qdoc index 13a7f24e..52da41a7 100644 --- a/src/imports/controls/doc/src/qtquickcontrols2-qmltypes.qdoc +++ b/src/imports/controls/doc/src/qtquickcontrols2-qmltypes.qdoc @@ -48,4 +48,9 @@ For more information on the Qt Quick Controls 2 module, see the \l {Qt Quick Controls 2} module documentation. + + \section1 Related Information + \list + \li \l {Qt Quick Controls 2 Guidelines} + \endlist */ -- cgit v1.2.3