Code-cleanup, improvements to qdoc's, correction to qdoc macros used …

…for code snippets and new screenshots

bluetoothgatt/readme.txt

@@ -0,0 +1,38 @@
+Bluetooth GATT
+
+========================================================================
+Sample Description.
+
+The Bluetooth GATT example demonstrates how to use the Bluetooth functionality as
+provided by the BB10 platform to retrieve information from Bluetooth devices that
+offer the low-energy profile.
+
+You will learn how to:
+- How to use the BT Api to discover Bt devices and their details.
+- how to add actions to cross-cut menu
+- How to perform property binding
+- Register C++ classes for use in QML documents
+
+
+========================================================================
+Requirements:
+
+BlackBerry 10 Native SDK
+
+========================================================================
+Running the example:
+
+1. Clone the Sample repository.
+2. Launch BlackBerry 10 Native SDK, and from the File menu, select Import.
+3. Expand General, and select Existing Projects into Workspace. Click Next.
+4. Browse to the location of your sample directory, and then click OK.
+5. The sample project should display in the Projects section. 
+   Click Finish to import the project into your workspace.
+6. In the Project Explorer pane, Right-click the project (for example hellocascades) 
+   and select Build Project.
+7. In the Project Explorer pane, Right-click the project (for example hellocascades) 
+   and select Run As > BlackBerry C/C++ Application.
+8. The application will now install and launch on your device if not you might
+   have to set up your environment: 
+   http://developer.blackberry.com/cascades/documentation/getting_started/setting_up.html
+

docs/headlesserviceui.qdoc

@@ -0,0 +1,133 @@
+/****************************************************************************
+**
+** Copyright (C) 2013 Research In Motion Limited.
+** All rights reserved.
+** Contact: BlackBerry Ltd. (http://www.blackberry.com/company/contact/)
+**
+** This file is part of the examples of the BB10 Platform.
+**
+** GNU Free Documentation License
+** 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.
+**
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms
+** and conditions contained in a signed written agreement between you
+** and Research In Motion Limited.
+**
+****************************************************************************/
+
+/*!
+    \page headlesserviceui
+    \example headlesserviceui
+    \title headlesserviceUI Example
+
+    \section1 Description
+
+    The headlesserviceui example demonstrates how to launch a headless service counterpart and communicate with it
+    through the QSettings instance.
+
+    \image headlesserviceui-example.png
+
+    \section1 Overview
+    In this sample, we represent visually the status of the service and it's current state values.
+
+    \section1 UI
+    In this sample, we represent the running service through a colored rectangle (red for stopped, green for running)
+    and two labels indicating the initial flash count and the remaining flash count. A reset button is provided in addition
+	to allow the user to reset the service in order to restart the LED countdown.
+
+    The business logic of the application is encapsulated in the applicationui component
+    which is exposed as "_app" to the UI.
+
+    \snippet headlesserviceui/assets/main.qml 0
+
+    The following custom component "ColoredRectangle" is a Container with a image overlay to create an appealing visual
+    component to represent the service status; it allows you to change it's label and color dependent on status.
+
+    \snippet headlesserviceui/assets/main.qml 1
+
+    The following \c Labels convey the services flash count and remaining flash count to the user.
+
+    \snippet headlesserviceui/assets/main.qml 2
+
+    The reset \c Button is meant to stop the current LED request and start a new request with original request count.
+
+    \section1 applicationui
+    The buisiness logic of the headlesserviceUI is encapsulated in the applicationui component.
+
+    \snippet headlesserviceui/src/applicationui.hpp 0
+
+    Initialization of static QString const that represent the QSettings keys under which we will be retrieving and conveying the
+    headless service status information to the UI.
+
+	\snippet headlesserviceui/src/applicationui.cpp 0
+
+	When the isServiceRunning() method is invoked it queries the QString instance, initiated by the headless service, using the
+    "ServiceStatus" key in order to retrieve the service status string. Once it is determined that the service is in the running
+    state the initial flash count and remaining count is queried as well.
+
+    \snippet headlesserviceui/src/applicationui.cpp 1
+
+    The resetLED() writes a boolean to the QSettings file in order to communicate to the service to stop the current led request and
+	restart a new request with the same parameters. The setRemainingFlashCount() method emits a remainingFlashCountChanged() signal to 
+	the qml to change the label text representing the count, every time the count changes.
+
+    \snippet headlesserviceui/src/applicationui.cpp 2
+
+	The settingsChanged() method is invoked by the QFileSystemWatcher when the QSettings file has been altered by another process, it
+	then proceeds to invoke setRemainingFlashCount() in order to update the remaining flash count as described by the paragraph above this one.
+
+	\section1 headlesservice
+
+	 The HeadlesService example demonstrates how to create a long-running headless service and communicate with it's UI counterpart.
+    Make note that this is NOT a standalone, independantly deployable application, it is packaged with headlesserviceui sample
+    and deployed via it's bar file. This project does not contain an asset folder due to the fact that it's not allowed to have
+    a UI element to it.
+
+	In this sample, there is no UI portion since a headless service cannot have one. The primary goal of this service is to initiate
+    a led instance and manipulate its flash count/color while communicating the results of this back to the UI.
+
+	\section1 applicationheadless
+    The buisiness logic of the headless service is encapsulated in the applicationheadless component.
+
+	\snippet headlesservice/src/applicationheadless.hpp 0
+
+	This class represents the basic service of led manipulation by setting to Color X and initiating led with flash count N.
+
+	\snippet headlesservice/src/applicationheadless.cpp 0
+
+    Initialization of static QString const that represent the QSettings keys under which we will be storing and conveying the
+    Led status information to it's UI counterpart.
+
+    \snippet headlesservice/src/applicationheadless.cpp 1
+
+    The default constructor that initializes its member variables and logs the service PID. It is important to take a note that
+    the headless service should be using bb::Application for it's parent instead of the usual bb::cascades::Application instance.
+    This is due to the fact that the service is not a cascades application since it cannot have a UI portion to it, it's strictly
+    like any other background service you would code up.
+
+    \snippet headlesservice/src/applicationheadless.cpp 2
+
+    This initializer method creates the unique QSettings which will be used as the moderator for sharing information between the service
+    and its UI. It also does all the signal/slot connections to receive invocation requests and Led status updates.
+
+    \snippet headlesservice/src/applicationheadless.cpp 3
+
+    This method is invoked when a invocation request is received. It listens for the system start event in order to activate the led
+    functionality; this event is generated upon system start and/or when the application is installed initially. This is an example
+    of a system startup triggered service.
+
+    \snippet headlesservice/src/applicationheadless.cpp 4
+
+    These methods are invoked through Qt's signal/slot mechanism when updates are done to the led active state and flash count instance
+    variables.
+
+	\snippet headlesservice/src/applicationheadless.cpp 5
+
+	The settingsChanged() is invoked when the QFileSystemWatcher senses that the QSettings file has been altered. The main purpose of this
+	method is to reset the QSetting key values, stop the current LED request and initiate a new LED flash request when the requesting UI 
+	requests for the reset via the reset \c Button.
+*/

docs/listdecorators.qdoc

@@ -177,24 +177,6 @@
 
     \snippet listdecorators/src/GroupArtistDataModelDecorator.cpp 0
 
-    \section1 The GroupStyleDataQueryDecorator class
-    This class performs grouping of header items, resulting in all those items with similarly named headers to appear under one header.
-
-    \snippet listdecorators/src/GroupStyleDataQueryDecorator.hpp 0
-
-    The following method is a helper function to determine if the given \c HeaderDataItem's header title is the same as the given
-    header title for comparison.
-
-    \snippet listdecorators/src/GroupStyleDataQueryDecorator.cpp 0
-
-    The processHeaderResults() method is a re-implementation of it's base class counterpart in order to give it the grouping
-    capability. It traverses the header results, each item's header title is compared to the title of the next element, if both
-    titles are found to be the same than their child counts are combined under one HeaderDataItem. This simplifies the data in
-    the ListView by aggregating all items with similar headers under one header, creating a leaner list that reduces the
-    amount of scrolling one has to do.
-
-    \snippet listdecorators/src/GroupStyleDataQueryDecorator.cpp 1
-
     \section1 The SelectionDataModelDecorator class
     This class enriches the user interaction of the ListView, by giving it a new functionality - the ability to select multiple
     items.

docs/mavenartifacts.qdoc

@@ -0,0 +1,138 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Research In Motion Limited.
+** All rights reserved.
+** Contact: Research In Motion Ltd. (http://www.rim.com/company/contact/)
+**
+** This file is part of the examples of the BB10 Platform.
+**
+** GNU Free Documentation License
+** 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.
+**
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms
+** and conditions contained in a signed written agreement between you
+** and Research In Motion Limited.
+**
+****************************************************************************/
+
+/*!
+    \page mavenartifacts
+    \example mavenartifacts
+    \title Maven Artifact search Example
+
+    \section1 Description
+
+    The Maven Artifacts example demonstrates how to access a RESTful service that responds with JSON
+    data and then display the results on the screen.
+
+    \image mavenartifacts-example.png
+
+    \section1 Overview
+    In this example we'll learn how to use the \c QNetworkAccessManager and \c JsonDataAccess classes to
+    download artifacts from the RESTful webservice and parse them into a model to visualize them in a \c ListView.
+
+    The business logic of this application is encapsulated in the \c App class, which
+    is exported to QML under the name '_artifactline'.
+
+    \section1 UI
+    The UI of this sample consists of a \c TextField to enter the artifact name and a \c Button to start
+    the lookup for artifacts containing the given name. Whenever the user clicks the button, the requestArtifact()
+    method of the \c App object is invoked. The button is disabled while the lookup is in progress.
+
+    \snippet mavenartifacts/assets/main.qml 1
+
+    If an error occurs during the lookup, the 'error' property of the \c App object becomes 'true', which
+    makes the \c Label below the button visible. It will show the error message as provided by the \c App object.
+
+    \snippet mavenartifacts/assets/main.qml 2
+
+    If the lookup is successful, the \c App object emits the ArtifactsLoaded() signal. After the UI is initialized,
+    we connect the pushPane() function against this signal.
+
+    \snippet mavenartifacts/assets/main.qml 0
+
+    The pushPane() function will push a page, that shows the artifacts in a \c ListView, on the navigation pane.
+    Since we want to have two different visual representations of the list, we have two different pages. One
+    uses the standard list item component and the other uses a custom list item component.
+
+    \snippet mavenartifacts/assets/main.qml 4
+
+    Both pages are loaded through \c{ComponentDefinition}s and the user can select which one is used through
+    a \c SegmentedControl at the bottom of the screen.
+
+    \snippet mavenartifacts/assets/main.qml 3
+
+    The standard appearance is implemented in StandardTimelineView.qml and uses the \c StandardListItem as
+    \c ListItemComponent. As data model the \c ListView uses the model provided by the \c App object.
+
+    \snippet mavenartifacts/assets/StandardTimelineView.qml 0
+
+    The page looks like the following:
+
+    \image mavenartifacts-example1.png
+
+    The custom appearance is implemented in CustomTimelineView.qml and uses a custom control as \c ListItemComponent,
+    consisting of two \c{Label}s below each other.
+
+    \snippet mavenartifacts/assets/CustomTimelineView.qml 0
+
+    The page looks like the following:
+
+    \image mavenartifacts-example2.png
+
+    \section1 The App class
+    The \c App class encapsulates the business logic of this application. It provides methods to trigger the lookup
+    of artifacts, a property of type bb::cascades::DataModel that contains the found artifacts and further properties to
+    report the current state of the object (e.g. error or in-progress).
+
+    \snippet mavenartifacts/src/app.hpp 0
+
+    Inside the constructor the model is initialized and the UI is loaded from main.qml file.
+
+    \snippet mavenartifacts/src/app.cpp 0
+
+    Before a new request is issued, the reset() method is called, which clears any previous error information.
+
+    \snippet mavenartifacts/src/app.cpp 1
+
+    When the user clicks the 'Timeline' button, the requestArtifact() method is invoked with the artifact name as parameter.
+    If no lookup is currently running, we do a sanity check on the artifact name and if everything is ok execute the lookup.
+    The lookup on the network is encapsulated in a \c ArtifactRequest object, which provides a signal complete() to notify
+    us when the raw JSON data has been retrieved. We connect a custom slot against this signal and start the request.
+    Afterwards we change the 'active' property of the \c App object to signal the UI that a lookup is in progress.
+
+    \snippet mavenartifacts/src/app.cpp 2
+
+    When the network lookup is finished, the onArtifactsline() slot is invoked. There we first check whether an error occurred.
+    In case of an error we update the 'error' and 'errorMessage' property of the \c App object and inform the UI about the
+    change. Otherwise we call the helper method parseResponse().
+
+    \snippet mavenartifacts/src/app.cpp 3
+
+    The parseResponse() method uses the \c JsonDataAccess class to parse the raw JSON data into a list of QVariantMaps, which
+    can be inserted directly into our model.
+
+    \snippet mavenartifacts/src/app.cpp 4
+
+    \section1 The ArtifactRequest class
+    The \c ArtifactRequest class encapsulates the retrieval of data from the maven central webservice. It basically provides
+    a method to trigger the lookup and a signal to notify when the lookup is finished.
+
+    \snippet mavenartifacts/src/ArtifactRequest.hpp 0
+
+    In requestArtifactline() we create a new \c QNetworkAccessManager object, which will do the low-level HTTP network communication.
+    It expects an URL as input parameter, which we assemble here from the REST API and the artifact name.
+    Calling \c{QNetworkAccessManager}'s get() method returns a \c QNetworkReply object, which acts as a handle to follow the
+    status and progress of the network operation. We connect against its finished() signal to know when all data have been received.
+
+    \snippet mavenartifacts/src/ArtifactRequest.cpp 0
+
+    Inside the connected slot we check whether an error occurred and read the data from the \c QNetworkReply if the download
+    was successful. At the end we emit the complete() signal with the JSON data or an error message as parameter.
+
+    \snippet mavenartifacts/src/ArtifactRequest.cpp 1
+*/

docs/pages.qdoc

@@ -42,7 +42,7 @@
       \o \l{paymentservice}{Payment Service}
       \o \l{bpstoqml}{BPS to QML}
       \o \l{xandos}{XandOs Game}
-	  \o \l{headlesserviceui} {Headless service example}
+      \o \l{headlesserviceui} {Headless service example}
       \endlist
     \o \bold {Device and Communication}
       \list
@@ -64,6 +64,7 @@
       \o \l{nfcreceiver}{NFC Receiver}
       \o \l{nfcsender}{NFC Sender}
       \o \l{nfcshare}{NFC Share}
+      \o \l{mavenartifacts}{Maven Artifacts}
       \endlist
     \o \bold {App Integration}
       \list