/*

* 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 <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