diff options
author | Tarja Sundqvist <tarja.sundqvist@qt.io> | 2017-08-14 11:31:03 +0300 |
---|---|---|
committer | Tarja Sundqvist <tarja.sundqvist@qt.io> | 2017-08-16 13:17:24 +0000 |
commit | 944b24946d2ccf547c0843e61cccb98a46f2a3aa (patch) | |
tree | 3c8f2e749d52fe8b14699d0573f3521a1f6c4002 | |
parent | 31424144d0e701f847e4957ec18c84856d10e8ca (diff) | |
download | neptune-ui-944b24946d2ccf547c0843e61cccb98a46f2a3aa.tar.gz |
Update Neptune UI API documentation according to Qt Style
Neptune UI API documentation updates:
* \qmlmodule pages created for Neptune UI components and Interfaces
* part of internal API: PopupInterface::updatePopup() and
NavigationUIScreen::widgetSurface()
* minor grammar fixes
Task-number: QTAUTO-532
Change-Id: I4e0e01b2a6e5818fefb9714cfd8123ea7742b662
Reviewed-by: Nedim Hadzic <nedim.hadzic@pelagicore.com>
-rw-r--r-- | doc/neptuneui-project.qdocconf | 13 | ||||
-rw-r--r-- | doc/src/neptuneui-index.qdoc | 36 | ||||
-rw-r--r-- | doc/src/neptuneui-toc.qdoc | 2 | ||||
-rw-r--r-- | imports/shared/service/notification/NotificationInterface.qml | 24 | ||||
-rw-r--r-- | imports/shared/service/popup/PopupInterface.qml | 26 | ||||
-rw-r--r-- | imports/shared/utils/AppUIScreen.qml | 39 | ||||
-rw-r--r-- | imports/shared/utils/NavigationUIScreen.qml | 24 | ||||
-rw-r--r-- | imports/shared/utils/UIScreen.qml | 17 |
8 files changed, 118 insertions, 63 deletions
diff --git a/doc/neptuneui-project.qdocconf b/doc/neptuneui-project.qdocconf index b69134b..1e679e3 100644 --- a/doc/neptuneui-project.qdocconf +++ b/doc/neptuneui-project.qdocconf @@ -18,12 +18,23 @@ qhp.NeptuneUI.filterAttributes = NeptuneUI $QT_VERSION qhp.NeptuneUI.customFilters.NeptuneUI.name = Neptune UI $QT_VERSION qhp.NeptuneUI.customFilters.NeptuneUI.filterAttributes = NeptuneUI $QT_VERSION -qhp.NeptuneUI.subprojects = manual +qhp.NeptuneUI.subprojects = manual components interfaces qhp.NeptuneUI.subprojects.manual.title = Neptune UI qhp.NeptuneUI.subprojects.manual.indexTitle = Neptune UI TOC qhp.NeptuneUI.subprojects.manual.selectors = manual +qhp.NeptuneUI.subprojects.components.title = Neptune UI Components +qhp.NeptuneUI.subprojects.components.indexTitle = Neptune UI Components +qhp.NeptuneUI.subprojects.components.selectors = qmlmodule:utils +qhp.NeptuneUI.subprojects.components.sortPages = true + +qhp.NeptuneUI.subprojects.interfaces.title = Neptune UI Interfaces +qhp.NeptuneUI.subprojects.interfaces.indexTitle = Neptune UI Interfaces +qhp.NeptuneUI.subprojects.interfaces.selectors = qmlmodule:service +qhp.NeptuneUI.subprojects.interfaces.sortPages = true + navigation.landingpage = "Neptune UI" navigation.homepage = "Qt Automotive Suite" +navigation.qmltypespage = "Neptune UI Components and Interfaces" macro.QAS = "Qt Automotive Suite" diff --git a/doc/src/neptuneui-index.qdoc b/doc/src/neptuneui-index.qdoc index efd88a5..884c3df 100644 --- a/doc/src/neptuneui-index.qdoc +++ b/doc/src/neptuneui-index.qdoc @@ -198,16 +198,17 @@ \l{Neptune UI Application Development} provides a set of best practices for developing applications with Neptune UI. - See \l{Neptune UI Components} for a list of all provided UI components. + See \l{Neptune UI Components and Interfaces} for a list of all + provided UI components and interfaces. */ /*! \page neptuneui-components.html - \title Neptune UI Components + \title Neptune UI Components and Interfaces \previouspage neptune-app-development.html \nextpage neptuneui-index.html - Neptune UI components: + Neptune UI components and interfaces: \list \li \l{UIScreen} \li \l{AppUIScreen} @@ -216,3 +217,32 @@ \li \l{PopupInterface} \endlist */ + +/*! + \qmlmodule utils 1.0 + \title Neptune UI Components + \brief List of Neptune UI Components. + + To import Neptune UI components, add the following import statement to your .qml file: + + \qml + import utils 1.0 + \endqml + + Neptune UI provides the following components: +*/ + +/*! + \qmlmodule service 1.0 + \title Neptune UI Interfaces + \brief List of Neptune UI Interfaces. + + To import Neptune UI interfaces, add the following import statement to your .qml file: + + \qml + import service 1.0 + \endqml + + Neptune UI provides the following interfaces: +*/ + diff --git a/doc/src/neptuneui-toc.qdoc b/doc/src/neptuneui-toc.qdoc index 7890eeb..12aae14 100644 --- a/doc/src/neptuneui-toc.qdoc +++ b/doc/src/neptuneui-toc.qdoc @@ -45,7 +45,7 @@ \list \li \l{Building and Running Neptune UI} \li \l{Neptune UI Application Development} - \li \l{Neptune UI Components} + \li \l{Neptune UI Components and Interfaces} \list \li \l{UIScreen} \li \l{AppUIScreen} diff --git a/imports/shared/service/notification/NotificationInterface.qml b/imports/shared/service/notification/NotificationInterface.qml index 82ea606..b6ad2f2 100644 --- a/imports/shared/service/notification/NotificationInterface.qml +++ b/imports/shared/service/notification/NotificationInterface.qml @@ -36,15 +36,18 @@ import QtApplicationManager 1.0 \qmltype NotificationInterface \inqmlmodule service \inherits Notification - \brief NotificationInterface provides an interface for requesting notifications. + \brief An interface for requesting notifications. - NotificationInterface inherits \l {https://doc.qt.io/QtApplicationManager/qml-qtapplicationmanager-notification.html} - {Notification} component and acts like an adapter for Neptune UI. Some properties are adopted - to match Neptune UI requirements. Properties \c timeout and \c category are modified and adopted for Neptune UI and - should not be used. By Neptune interaction design, notification should be dissmissed by user and - not by the timeout. + NotificationInterface inherits \l {Notification} from \l{Qt Application Manager} + and acts like an adapter for Neptune UI. + The NotificationInterface properties \c timeout and \c category are adopted + to match Neptune UI requirements and should not be used. In the Neptune UI + interaction, notifications should always be dismissed by an end user + instead of a time-out. - Example usage: + \section2 Example Usage + + The following example demonstrates the NotificationInterface usage: \qml @@ -56,10 +59,9 @@ import QtApplicationManager 1.0 } \endqml - As shown in example \c summary property will act like a title of the notification, while - \c body as notification description. Based on the \c priority notification will be queued. - It is important to set an absolute path for the \c icon property. Otherwise, an icon will - not be shown. + \c summary defines a notification title. \c body defines a notification + description. Notifications are queued based on a value in \c priority. + \c icon must contain an absolute icon path. Otherwise, the icon is not shown. */ Notification { diff --git a/imports/shared/service/popup/PopupInterface.qml b/imports/shared/service/popup/PopupInterface.qml index 6ecb0e2..219063f 100644 --- a/imports/shared/service/popup/PopupInterface.qml +++ b/imports/shared/service/popup/PopupInterface.qml @@ -36,15 +36,16 @@ import QtApplicationManager 1.0 \qmltype PopupInterface \inqmlmodule service \inherits Notification - \brief PopupInterface provides an interface for requesting popups. + \brief An interface for requesting popups. - PopupInterface inherits \l {https://doc.qt.io/QtApplicationManager/qml-qtapplicationmanager-notification.html} - {Notification} component and acts like an adapter for Neptune UI popups. Some properties are adopted - to match Neptune UI popup requirements. Properties \c timeout and \c category are modified and adopted for Neptune UI and - should not be used. By Neptune interaction design, popups should be dissmissed by user and - not by the timeout. + PopupInterface inherits \l{Notification} from \l{Qt Application Manager} and + acts like an adapter for Neptune UI popups. + The PopupInterface properties \c timeout and \c category are adopted + to match Neptune UI requirements and should not be used. In the Neptune UI + interaction, pop-ups should always be dismissed by an end user + instead of a time-out. - Example usage: + \section2 Example Usage \qml @@ -58,8 +59,8 @@ import QtApplicationManager 1.0 \endqml - Based on the \c priority popups will be queued. The \c actions property defines an array - of buttons for popup. + Pop-up notifications are queued based on a value in \c priority. \c actions + defines an array of buttons for a popup. */ Notification { @@ -71,7 +72,7 @@ Notification { /*! \qmlproperty string AppUIScreen::title - This property assigns title of the popup. + This property assigns a title for the popup. */ property string title: "" @@ -79,7 +80,7 @@ Notification { /*! \qmlproperty string AppUIScreen::subtitle - This property assigns subtitle of the popup. + This property assigns a subtitle for the popup. */ property string subtitle: "" @@ -92,6 +93,9 @@ Notification { root.updatePopup(); } + /*! + \internal + */ function updatePopup() { root.extended = { "title": root.title, diff --git a/imports/shared/utils/AppUIScreen.qml b/imports/shared/utils/AppUIScreen.qml index e58c069..f31791e 100644 --- a/imports/shared/utils/AppUIScreen.qml +++ b/imports/shared/utils/AppUIScreen.qml @@ -39,16 +39,17 @@ import utils 1.0 \qmltype AppUIScreen \inqmlmodule utils \inherits ApplicationManagerWindow - \brief AppUIScreen provides base item for developing the applications. + \brief A base QML item for developing applications. - AppUIScreen is a QML item which should be a root element for every - Neptune application. It provides APIs to interact with the system UI and - to position application visual elements. + AppUIScreen is a QML item which should be a root element in every + Neptune UI application. It provides APIs for interacting with a system UI and + for positioning the application's visual elements. - Check { Neptune Application Development } { Neptune Application Development } - for best practices on how to use the APIs. + See \l{Neptune UI Application Development} for best practices on how to use the APIs. - Example usage: + \section2 Example Usage + + The following example uses \l{AppUIScreen} as a root element: \qml @@ -78,7 +79,7 @@ ApplicationManagerWindow { /*! \qmlproperty Item AppUIScreen::content - This default property specifies the content area for application visual content. + A default property that specifies a content area for the application's visual content. */ default property alias content: content.children @@ -86,18 +87,24 @@ ApplicationManagerWindow { /*! \qmlproperty Item AppUIScreen::cluster - This property assigns visual content for the cluster window, if cluster - is available. + If a cluster is available, this property assigns visual content for the cluster window. */ property alias cluster: clusterContainer.children + /*! + \qmlsignal AppUIScreen::clusterKeyPressed(int key) + + This signal is emitted every time a key is pressed in a cluster. + + */ + signal clusterKeyPressed(int key) /*! \qmlsignal AppUIScreen::raiseApp() - The signal which is emitted every time application starts. + This signal is emitted every time an application is started. */ @@ -106,7 +113,8 @@ ApplicationManagerWindow { /*! \qmlsignal AppUIScreen::closeApp() - The signal is emitted every time application closes (back button clicked). + This signal is emitted every time an application is closed by clicking + the back button. */ @@ -115,10 +123,8 @@ ApplicationManagerWindow { /*! \qmlmethod AppUIScreen::back() - This method is called when an application needs to exit. - - When user clicks on back button of the application, this method - makes sure system UI screen is shown. + This method is called when an application needs to exit. It ensures the + system UI screen visibility when a back button is clicked. \qml AppUIScreen { @@ -137,7 +143,6 @@ ApplicationManagerWindow { } \endqml - \sa fullScreenContent */ diff --git a/imports/shared/utils/NavigationUIScreen.qml b/imports/shared/utils/NavigationUIScreen.qml index 13de612..eabf920 100644 --- a/imports/shared/utils/NavigationUIScreen.qml +++ b/imports/shared/utils/NavigationUIScreen.qml @@ -39,18 +39,17 @@ import utils 1.0 \qmltype NavigationUIScreen \inqmlmodule utils 1.0 \inherits AppUIScreen - \brief NavigationUIScreen provides base item for developing - navigation applciations. + \brief A base item for developing navigation applications. - NavigationUIScreen is a QML item which should be a root element for navigation - Neptune application. It provides APIs to interact with the system UI and - to position application visual elements. Main difference from \l AppUIScreen - is additional properties, which provide option to set the home page map widget. + NavigationUIScreen is a QML item which should be the root element in + Neptune UI navigation applications. It provides APIs for interacting with a system UI and + for positioning the application's visual elements. NavigationUIScreen extends + \l AppUIScreen with additional properties for setting a home page map widget. - Check { Neptune Application Development } { Neptune Application Development } - for best practices on how to use the APIs. + See \l{Neptune UI Application Development} for best practices on how to use the APIs. + + \section2 Example Usage - Example usage: \qml NavigationUIScreen { @@ -82,12 +81,15 @@ AppUIScreen { /*! \qmlproperty Item AppUIScreen::widget - This property specifies the content area for map widget, which - will be placed on the home page of the system UI. + This property specifies a content area for a map widget. The content + area will be placed in a system UI home page. */ property alias widget: widgetContainer.children + /*! + \internal + */ property var widgetSurface: ApplicationManagerWindow { width: Style.hspan(12) height: Style.vspan(19) diff --git a/imports/shared/utils/UIScreen.qml b/imports/shared/utils/UIScreen.qml index 2e9dde6..d8dbd6f 100644 --- a/imports/shared/utils/UIScreen.qml +++ b/imports/shared/utils/UIScreen.qml @@ -38,13 +38,13 @@ import controls 1.0 \qmltype UIScreen \inqmlmodule utils \inherits Page - \brief UIScreen provides base item for Neptune screens. + \brief A base item for all Neptune UI screens. - UIScreen is a QML item used to provide Neptune application screens. UIScreen - provides correct layout with back buttons, which provides getting to the previous + UIScreen is a QML item that provides Neptune UI application screens. UIScreen + has a layout with back buttons that provides access to a previous screen. - Example usage: + \section2 Example Usage \qml @@ -64,7 +64,7 @@ import controls 1.0 } \endqml - For each screen an application has, UIScreen should be used as a base. + For each screen an application has, UIScreen should be used as a base item. */ @@ -78,8 +78,9 @@ Page { /*! \qmlproperty bool UIScreen::hideBack - Defines if back button of the screen should be hidden. Default - value is false. + This property holds the visibility status of a back button. + If hideBack is set to \c true, the back button is hidden. Default + value is \c false. */ property bool hideBack: false @@ -87,7 +88,7 @@ Page { /*! \qmlsignal UIScreen::backScreen() - The signal is emitted when user clicks on back button. + The signal is emitted when a back button is selected. */ |