Docs: updates to location qml. Example images.

5 files changed, 159 insertions, 14 deletions

diff --git a/doc/src/examples/camera.qdoc b/doc/src/examples/camera.qdoc
new file mode 100644
index 0000000000..dcf4dadfc8
--- /dev/null
+++ b/doc/src/examples/camera.qdoc
@@ -0,0 +1,79 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** 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.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+
+
+/*!
+
+\example camera
+\title  Camera Example
+\brief  The Camera Example shows how to use the API to capture a still image
+or video.
+
+
+
+The Camera Example demonstrates how you can use the QtMultimediaKit to implement
+some basic Camera functionality to take still images and record video clips
+with audio.
+
+A Camera class is created that will act as our Camera. It has a user interface,
+control functions, setting values and a means of defining the location where
+the image or video clip is to be saved. It will also store the image and video
+settings.
+
+The Camera class contains an instance of \l {QCamera}, the API class interface to
+the hardware. It also has an instance of \l {QCameraImageCapture} to take still images
+and an instance of \l {QMediaRecorder} to record video. It also contains the user
+interface object.
+
+The Camera constructor does some basic initialization. The camera object is
+set to '0', the user interface is initialized and UI signal are connected to
+slots that react to the triggering event. However, most of the work is done when
+the \i {setCamera()} function is called, passing in a \l {QByteArray}.
+
+\i {setCamera()} sets up various connections between the user interface and the functionality
+of the Camera class using signals and slots. It also instantiates and initializes the \l {QCamera},
+\l {QCameraImageCapture} and \l {QMediaRecorder} objects mentioned above. The still
+and video recording visual tabs are enabled and finally the
+\l {QCamera::start()}{start()} function of the \l{QCamera} object is called.
+
+Now that the camera is ready for user commands it waits for a suitable event.
+Such an event will be the key press of either the \l {Qt::Key_CameraFocus} or
+\l {Qt::Key_Camera} buttons on the application window. Camera focus will
+simply display the viewfinder and lock the camera settings. Key_Camera will
+either call \i {takeImage()} if the \l {QCamera::captureMode()}{captureMode()}
+is QCamera::CaptureStillImage, or if the capture mode is for video then one
+of two actions will occur. If the recording state shows that we are currently
+recording then the \i {stop()} function is called resulting in a call to
+\l {QCamera::stop()}, whereas if we are not recording then a video recording
+is started with a call to \l {QMediaRecorder::record()}.
+
+\image camera-example.png
+
+*/
+
+
diff --git a/doc/src/images/camera-example.png b/doc/src/images/camera-example.png
new file mode 100644
index 0000000000..12e1b5728b
--- /dev/null
+++ b/doc/src/images/camera-example.png
diff --git a/doc/src/plugins/qml-location.qdoc b/doc/src/plugins/qml-location.qdoc
index 5c5bc9d440..6da12f584c 100644
--- a/doc/src/plugins/qml-location.qdoc
+++ b/doc/src/plugins/qml-location.qdoc
@@ -78,15 +78,79 @@
 
     The Map element can be used be used to display a map of the world.  The
     bulk of the functionality is provided by a mapping plugin described
-    by the Plugin element associated with the Map.
+    by the plugin element associated with the Map.
 
-    Various map objects can be added to the map.  These map objects are
-    specified in terms of coordinates and meters.
+    \section2 Landmarks
 
+    Most maps have landmarks. Useful markers identified in the landscape either as destinations
+    or things that are noteworthy. In QtMobility the QML Location plugin supports
+    Landmarks on maps using the Location API. Landmarks can be imported into
+    the application and populate the map with associated position data, meta-data
+    and icon representations.
 
-    \section2 Map Elements
+    The main element is \l Landmark. Using \l Landmark we can specify the name,
+    phone number, some descriptive text, the radius of the landmark, the URL
+    for the representative icon and a URL for the real landmark.
+
+    This is simple but insufficient. We also need to be able to search for
+    landmarks, to categorize them, and importantly navigate to them.
+
+    Other plugin elements now come to our aid.
+
+    In order to search for Landmarks we need to set up filters that can be
+    used to define our search criteria.
+
+    For example, we can set up a filter to locate a particular landmark by
+    name using the \l LandmarkNameFilter
+
+    \snippet doc/src/snippets/declarative/declarative-landmark.qml   Landmark name filter
+
+    We can also search by proximity. That is, are we within a defined range
+    of any landmarks? Here is an example that uses a filter tied into the
+    current device location
+
+    \snippet doc/src/snippets/declarative/declarative-landmark.qml  Landmark proximity filter
+
+    \l PositionSource refreshes the coordinate once per second (1000 milliseconds)
+    and this new location is used to determine if the coordinate is within a
+    given radius of any landmark coordinate during the search. The result would
+    be a list of landmarks that are within the given radius, 1500 meters,
+    of our location.
+
+    If we want to combine filters the API gives us elements that can be combined
+    in a set-like way to create unions (logical OR) and intersections (logical AND)
+    of the results of different filters. In the examples above we had a
+    \l LandmarkNameFilter and we had a \l LandmarkProximityFilter. If we want
+    to combine them so that the result would show when the device is within
+    the desired radius then we use a \l LandmarkUnionFilter to combine the
+    two previous filters
+
+    \snippet doc/src/snippets/declarative/declarative-landmark.qml  LandmarkModel union filter
+
+    Generating a list of results for a filter is done by means of a \l LandmarkModel
+    element. This encapsulates the list of results and gives us desirable
+    features such as control over the sortOrder and sortBy functionality. Here
+    is a sample use of the element to provide a list of up to 50 items found
+    to be within a specified distance defined in the \i proximityFilter
+
+    \snippet doc/src/snippets/declarative/declarative-map.qml  LandmarkModel proximity filter
+
+    \note The \l {LandmarkAbstractModel::autoUpdate}{autoUpdate} property is
+    a boolean. It enables the model to be updated if any signals are
+    emitted that would change the model. For instance, a change in the
+    contents of a filter.
+
+    Landmarks can be organized into categories similar to tagging. New categories
+    cannot be defined at the QML level, they are either supplied by the backend database
+    or new ones are defined at the C++ layer. Landmarks are associated with
+    various categories by using the \l LandmarkCategoryModel element. This
+    element contains a Landmark element and a list of \l LandmarkCategory instances.
+
+    Searches can be made using a \l LandmarkCategoryFilter. The
+    \l LandmarkCategoryModel is first used to specify which \l Landmark we
+    are interested in, then the \l {LandmarkCategoryModel::categories}{categories}
+    property is populated with the categories associated with that landmark.
 
-    \annotatedlist qml-location-maps
 
 */
 
diff --git a/doc/src/snippets/declarative/declarative-map.qml b/doc/src/snippets/declarative/declarative-map.qml
index b81f03dcdd..9db86857a3 100644
--- a/doc/src/snippets/declarative/declarative-map.qml
+++ b/doc/src/snippets/declarative/declarative-map.qml
@@ -59,14 +59,14 @@ Item {
         topLeft: map.toCoordinate(Qt.point(0,0))
         bottomRight: map.toCoordinate(Qt.point(page.width, page.height))
     }
-    
+
      LandmarkProximityFilter {
          id: proximityFilter
          center: myPositionSource.position.coordinate
 	 //center: Coordinate {latitude: -27; longitude: 153}
          radius: 500000
      }
-       
+
     LandmarkModel {
         id: landmarkModelAll
         autoUpdate: true
@@ -76,7 +76,8 @@ Item {
             console.log("All landmark model changed, landmark count: " + count)
         }
     }
-    
+
+    //! [LandmarkModel proximity filter]
     LandmarkModel {
         id: landmarkModelNear
         autoUpdate: true
@@ -86,7 +87,8 @@ Item {
             console.log("Near landmark model changed, landmark count: " + count)
         }
     }
-    
+    //! [LandmarkModel proximity filter]
+
     Rectangle {
         id: dataArea
         anchors.fill: parent
@@ -100,7 +102,7 @@ Item {
             size.width: parent.width
             size.height: parent.height
             zoomLevel: 10
-            
+
             MapObjectView {
 	        id: allLandmarks
 		model: landmarkModelAll
@@ -110,7 +112,7 @@ Item {
 			radius: 1000
 		        center: Coordinate {
 	                    latitude: landmark.coordinate.latitude
-		            longitude: landmark.coordinate.longitude 
+		            longitude: landmark.coordinate.longitude
 	                }
 	            }
 	        }
@@ -140,10 +142,10 @@ Item {
 	            }
 		}
 	    }
-	    
+
             // center: Coordinate {latitude: -27; longitude: 153}
 	    center: myPositionSource.position.coordinate
-	    
+
             onZoomLevelChanged: {
                 console.log("Zoom changed")
                 updateFilters();
diff --git a/plugins/declarative/location/qdeclarativelandmarkcategory.cpp b/plugins/declarative/location/qdeclarativelandmarkcategory.cpp
index c551bdd3e3..bed68470c9 100644
--- a/plugins/declarative/location/qdeclarativelandmarkcategory.cpp
+++ b/plugins/declarative/location/qdeclarativelandmarkcategory.cpp
@@ -51,7 +51,7 @@ QTM_BEGIN_NAMESPACE
     This element is part of the \bold{QtMobility.location 1.1} module.
 
     The primary source for categories is the \l LandmarkCategoryModel.
-    To get \l Landmarks belonging to certain category (ies),
+    To get \l Landmarks belonging to certain category(ies),
     \l LandmarkCategoryFilter may be used. Currently saving of categories
     is not supported.