--- a/locsrv_plat/map_and_navigation_api/inc/mnmapview.h Thu Aug 19 10:20:18 2010 +0300
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,393 +0,0 @@
-/*
-* Copyright (c) 2005-2006 Nokia Corporation and/or its subsidiary(-ies).
-* All rights reserved.
-* This component and the accompanying materials are made available
-* under the terms of "Eclipse Public License v1.0"
-* which accompanies this distribution, and is available
-* at the URL "http://www.eclipse.org/legal/epl-v10.html".
-*
-* Initial Contributors:
-* Nokia Corporation - initial contribution.
-*
-* Contributors:
-*
-* Description: CMnMapView class
-*
-*/
-
-
-#ifndef MN_MAPVIEW_H
-#define MN_MAPVIEW_H
-
-#include <e32base.h>
-#include <EPos_Landmarks.h>
-#include <lbsposition.h>
-
-class RFs;
-class CApaServerAppExitMonitor;
-class MAknServerAppExitObserver;
-class CMnProvider;
-class CPosLandmark;
-class RMnMapViewServiceClient;
-
-/** @brief Provides access to map view features.
- *
- * The ShowMapL() method allows to show map of some area, which can be specified
- * by SetMapAreaL(). ShowCurrentLocationL() opens a map with current location
- * in the center. SelectFromMapL() allows to ask user to select some location
- * from the map. Client can request that some landmarks should be drawn on the map,
- * when it is shown, by using AddLandmarksToShowL.
- * Subsequent calls to this method will add landmarks to show list. To reset the
- * list, call @ref ResetLandmarksToShow.
- *
- * Two overloads of AddLandmarksToShowL exist for linked and not linked landmarks.
- * The linked landmark is the one, which has its landmark ID set.
- * Linked landmarks are sent to Provider Application along with their
- * landmark database URI, which allows Provider Application to get full category
- * information of the landmark.
- *
- * To create an instance of the class, use @ref NewL or @ref NewChainedL methods. They
- * require instance of CMnProvider, defined in Map and Navigation Provider Discovery API.
- *
- * Asynchronous operations can be cancelled by @ref Cancel().
- * Only one asynchronous request can be issued at a time, otherwise client
- * will be panicked with KMnPanicDuplicateRequest.
- *
- * @since 3.1
- * @lib mnclientlib.dll
- * @ingroup MapNavAPI
- */
-class CMnMapView : public CBase
- {
- public :
-
- /** Type for bitmap of flags defined by TOption */
- typedef TUint32 TOptions;
-
- /** @brief Map view options */
- enum TOption
- {
- /** Default value */
- EOptionNone,
- /** Defines that only landmarks specified by AddLandmarksToShowL
- * are allowed to be selected by user. */
- EOptionRestrictSelection
- };
-
- /** @brief Defines whether current location shall be marked on map */
- enum TCurrentLocationOption
- {
- /** Current location is not shown (default). */
- ECurrentLocationDisabled,
- /** Current location is shown only if it's within visible area */
- ECurrentLocationEnabled,
- /** Current location is visible always. Provider Application selects
- appropriate zoom (and position, if area center is not specified)
- to make sure current location is visible. */
- ECurrentLocationShowAlways
- };
-
- /** @brief Defines type of selection result */
- enum TSelectionResultType
- {
- /** Undefined result */
- ESelectionNone,
- /** Free location has been selected.
- * Use @ref RetrieveSelectionResultL() to
- * get result of selection. */
- ESelectionFreeLandmark,
- /** One of landmarks passed by instance has been selected.
- * Use @ref RetrieveSelectionResultL(TInt&) to
- * get result of selection. */
- ESelectionLandmarkIndex,
- /** One of landmarks passed as landmark ID and database URI has been selected.
- * Use @ref RetrieveSelectionResultL(TPosLmItemId&, HBufC*&) to
- * get result of selection. */
- ESelectionLinkedLandmark
- };
-
- /** Destructor */
- virtual ~CMnMapView();
-
- /** @brief Creates new instance of the class. Provider Application
- * will be executed standalone.
- *
- * @param[in] aProvider Provider Application to be used for showing map.
- * @return Pointer to new instance of the class.
- *
- * @leave KErrNotSupported Selected Provider Application does not support
- * map view services (@ref CMnProvider::EServiceMapView).
- */
- IMPORT_C static CMnMapView* NewL( CMnProvider& aProvider );
-
- /** @brief Creates new instance of the class. Provider Application
- * will be executed chained (unless Provider Application defines that
- * it should be started in background).
- *
- * @param[in] aProvider Provider Application to be used for showing map.
- * @return Pointer to new instance of the class.
- *
- * @leave KErrNotSupported Selected Provider Application does not support
- * map view services (@ref CMnProvider::EServiceMapView).
- */
- IMPORT_C static CMnMapView* NewChainedL( CMnProvider& aProvider );
-
- /** @brief Shows map on the screen.
- *
- * This method completes as soon as request reaches Provider
- * Application. Map is shown then in Provider Application's process.
- *
- * If map area is specified by SetMapAreaL(), then this area of map
- * will be visible, when it is shown.
- * Otherwise, if only list of landmarks to show is specified,
- * then area covering all landmarks is visible.
- * If Current Location Option is set to @ref
- * ECurrentLocationShowAlways, then it may modify visible area.
- *
- * If neither area nor landmarks are specified, and current location
- * option is not "always", then simply last shown map (as determined by selected
- * provider application) is shown. If map was never shown before, then
- * Provider Application shows map from its default position.
- */
- IMPORT_C void ShowMapL();
-
- /** @brief Shows map on the screen, with current location in the center.
- *
- * This method completes as soon as request reaches Provider
- * Application. Map is shown then in Provider Application's process.
- *
- * Same options are applied to this method as to ShowMapL()
- * (with the exception that area center point is ignored)
- */
- IMPORT_C void ShowCurrentLocationL();
-
- /** @brief Shows map on the screen and asks user to select a position.
- *
- * If EOptionsRestrictSelection option is set, then user can select
- * only those landmarks, which are specified with one of AddLandmarksToShowL
- * overrides. Otherwise any location is allowed to be selected.
- *
- * User is shown a view with default selection request text. This text
- * can be overridden with SetCustomRequestTextL().
- *
- * See SelectionResultType() for how to retrieve selection result.
- *
- * This is asynchronous request and can be cancelled with Cancel().
- *
- * This method can leave in case of memory lack or other system error.
- * If it leaves, no asynchronous request is outstanding.
- *
- * @param[out] aStatus Status of asynchronous operation. Contains error code,
- * when request is completed: KErrNone, if user has made
- * selection, KErrCancel - if request is cancelled, or user
- * refused to make selection. KErrArgument if no landmarks to
- * be shown are specified and ERestrictSelection is set.
- * Otherwise any of system-wide error codes.
- *
- * @panic "MnClientPanic"-KMnPanicDuplicateRequest if new asynchronous request
- * is issued before previous one is completed.
- */
- IMPORT_C void SelectFromMapL( TRequestStatus& aStatus );
-
- /** @brief Adds linked landmarks to the list of landmarks to be shown on map.
- *
- * Landmarks are passed along with URL of the database, where they reside.
- * This allows to utilize category information from landmarks.
- * If landmarks from several databases shall be shown, call this method
- * for every such database. All landmarks are added to a single list.
- * To clear that list, call ResetLandmarksToShow().
- *
- * @param[in] aDatabaseUri A database, to which belong landmarks, listed
- * in aLandmarkIds parameter.
- * @param[in] aLandmarkIds IDs of landmarks to add to show list.
- *
- * @leave KErrLocked Asynchronous request (SelectFromMapL) is outstanding.
- */
- IMPORT_C void AddLandmarksToShowL(
- const TDesC& aDatabaseUri,
- RArray<TPosLmItemId>& aLandmarkIds );
-
- /** @brief Adds landmarks to the list of landmarks to be shown on map.
- *
- * Landmarks are passed as instances. This variant is
- * for passing landmarks, which are not stored in databases.
- *
- * All landmarks are added to a single list.
- * To clear that list, call ResetLandmarksToShow().
- *
- * With large amount of landmarks, it is recommended to use overload,
- * which accepts linked landmarks, if possible.
- *
- * @param[in] aLandmarks Array of landmarks to add to show list.
- *
- * @leave KErrLocked Asynchronous request (SelectFromMapL) is outstanding.
- */
- IMPORT_C void AddLandmarksToShowL( RPointerArray<CPosLandmark>& aLandmarks );
-
- /** @brief Adds landmarks to the list of landmarks to be shown on map.
- *
- * Landmarks are passed as packed instances (see @p PosLandmarkSeriazation from
- * Landmarks API). This overload is for passing landmarks, which are not stored
- * in databases. It is more efficient than
- * AddLandmarksToShowL( RPointerArray<CPosLandmark>& ) in terms of memory usage,
- * if client already possess landmarks in packed form.
- *
- * All landmarks are added to a single list.
- * To clear that list, call ResetLandmarksToShow().
- *
- * With large amount of landmarks, it is recommended to use overload,
- * which accepts linked landmarks, if possible.
- *
- * @param[in] aPackedLandmarks Array of landmarks to add to show list.
- *
- * @leave KErrLocked Asynchronous request (SelectFromMapL) is outstanding.
- */
- IMPORT_C void AddLandmarksToShowL( RArray<TPtrC8>& aPackedLandmarks );
-
- /** @brief Clears the list of landmarks to be shown on map.
- * This call has no effect during the time when asynchronous request
- * (SelectFromMapL) is outstanding.
- */
- IMPORT_C void ResetLandmarksToShow();
-
- /** @brief Defines the map area to be shown.
- * @param[in] aCentralPoint Point on the Earth to be shown in the center
- * of map view. This setting is ignored, when
- * ShowCurrentLocationL() is called.
- * @param aRadius Radius in meters of the area around central point,
- * which should be visible, when map is shown.
- * If this setting is too small, then
- * Provider Application selects smallest possible
- * radius (maximum zoom).
- * If NaN, then Provider Application automatically
- * selects appropriate zoom. This setting is ignored if
- * ECurrentLocationShowAlways is set.
- */
- IMPORT_C void SetMapAreaL( const TCoordinate& aCentralPoint, TReal aRadius );
-
- /** @brief Clears map area setting. */
- IMPORT_C void ResetMapArea();
-
- /** @brief Specifies custom request text for SelectFromMapL() request.
- *
- * If not specified, than default request text will be used (as
- * defined in UI specification).
- * New setting will have effect only for next map display request.
- *
- * @param[in] aCustomText Text to be shown as selection request to user.
- */
- IMPORT_C void SetCustomRequestTextL(const TDesC& aCustomText);
-
- /** @brief Specifies that default request text shall be used
- * starting from next SelectFromMapL() request.
- */
- IMPORT_C void SetUseDefaultRequestText();
-
- /** @brief Specifies how current location is shown on map.
- * New setting will have effect only for next map display request.
- * @param aCurrentLocationOption One of TCurrentLocationOption values.
- */
- IMPORT_C void SetCurrentLocationOption(
- TCurrentLocationOption aCurrentLocationOption );
-
- /** @brief Retrieves current state of current location option.
- * @return One of TCurrentLocationOption values.
- */
- IMPORT_C TCurrentLocationOption CurrentLocationOption() const;
-
- /** @brief Sets map view options.
- * New settings will have effect only for next map display request.
- * @param aOptions Bitmap of TOption values.
- */
- IMPORT_C void SetOptions( TOptions aOptions );
-
- /** @brief Retrieves current map view options.
- * @return Bitmap of TOption values.
- */
- IMPORT_C TOptions Options() const;
-
- /** @brief Returns type of selection result
- * @return One of @ref TSelectionResultType values.
- */
- IMPORT_C TSelectionResultType SelectionResultType() const;
-
- /** @brief Retrieves selection result as landmark instance.
- * @return Landmark with information about selected location. Client takes ownership.
- * @leave KErrNotFound Result is not available or is of other type.
- * See @ref SelectionResultType() for details.
- *
- * @see SelectionResultType()
- * @see RetrieveSelectionResultL(TInt&)
- * @see RetrieveSelectionResultL(TPosLmItemId&, HBufC*&)
- */
- IMPORT_C CPosLandmark* RetrieveSelectionResultL();
-
- /** @brief Retrieves selection result as index of given landmark instance.
- * @param[out] aLandmarkIndex Index of a landmark passed as instance,
- * which has been selected.
- * @leave KErrNotFound Result is not available or is of other type.
- * See @ref SelectionResultType() for details.
- *
- * @see SelectionResultType()
- * @see RetrieveSelectionResultL()
- * @see RetrieveSelectionResultL(TPosLmItemId&, HBufC*&)
- */
- IMPORT_C void RetrieveSelectionResultL( TInt& aLandmarkIndex );
-
- /** @brief Retrieves ID of selected landmark.
- * @param[out] aLandmarkId On return, ID of selected landmark in the database,
- * specified by aDatabaseUri.
- * @param[out] aDatabaseUri On return, URI of the database of selected landmark.
- Client takes ownership.
- * @leave KErrNotFound Result is not available or is of other type.
- * See @ref SelectionResultType() for details.
- *
- * @see SelectionResultType()
- * @see RetrieveSelectionResultL()
- * @see RetrieveSelectionResultL(TInt&)
- */
- IMPORT_C void RetrieveSelectionResultL( TPosLmItemId& aLandmarkId, HBufC*& aDatabaseUri );
-
- /** @brief Cancels current outstanding asynchronous request. */
- IMPORT_C void Cancel();
-
- /** @brief Sets observer of provider application lifetime.
- * Client will receive exit event from provider application.
- * By default exit events from provider application are not monitored.
- * @param[in] aObserver Exit observer.
- * @leave KErrAlreadyExists if observer is already set.
- */
- IMPORT_C void SetExitObserverL( MAknServerAppExitObserver& aObserver );
-
- /** @brief Removes observer of provider application lifetime. */
- IMPORT_C void RemoveExitObserver();
-
- private :
- /** C++ constructor */
- CMnMapView();
- CMnMapView( const CMnMapView& ); //prevent default copy constructor
- CMnMapView& operator=( const CMnMapView& ); //prevent default assignment operator
-
- void ConstructCommonL( CMnProvider& aProvider );
- void ConstructNewL( CMnProvider& aProvider );
- void ConstructChainedL( CMnProvider& aProvider );
- void PostConstructL();
-
- HBufC* LoadResourceTextL(
- RFs& aFsSession,
- const TDesC& aRscFile,
- TInt aResourceId );
-
- private :
- TOptions iOptions;
- TCurrentLocationOption iCurrentLocationOption;
- TCoordinate iCentralPoint;
- TReal iRadius;
-
- HBufC* iDefaultRequestText;
-
- RMnMapViewServiceClient* iSession;
- CApaServerAppExitMonitor* iExitMonitor;
- };
-
-#endif // MN_MAPVIEW_H