CMnMapView Class Reference

class CMnMapView : public CBase

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 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 NewL or NewChainedL methods. They require instance of CMnProvider, defined in Map and Navigation Provider Discovery API.

Asynchronous operations can be cancelled by Cancel() . Only one asynchronous request can be issued at a time, otherwise client will be panicked with KMnPanicDuplicateRequest.

Since
3.1 mnclientlib.dll

Inherits from

Public Member Functions
~CMnMapView()
IMPORT_C voidAddLandmarksToShowL(const TDesC &, RArray< TPosLmItemId > &)
IMPORT_C voidAddLandmarksToShowL(RPointerArray< CPosLandmark > &)
IMPORT_C voidAddLandmarksToShowL(RArray< TPtrC8 > &)
IMPORT_C voidCancel()
IMPORT_C TCurrentLocationOptionCurrentLocationOption()
IMPORT_C CMnMapView *NewChainedL(CMnProvider &)
IMPORT_C CMnMapView *NewL(CMnProvider &)
IMPORT_C TOptionsOptions()
IMPORT_C voidRemoveExitObserver()
IMPORT_C voidResetLandmarksToShow()
IMPORT_C voidResetMapArea()
IMPORT_C CPosLandmark *RetrieveSelectionResultL()
IMPORT_C voidRetrieveSelectionResultL(TInt &)
IMPORT_C voidRetrieveSelectionResultL(TPosLmItemId &, HBufC *&)
IMPORT_C voidSelectFromMapL(TRequestStatus &)
IMPORT_C TSelectionResultTypeSelectionResultType()
IMPORT_C voidSetCurrentLocationOption(TCurrentLocationOption)
IMPORT_C voidSetCustomRequestTextL(const TDesC &)
IMPORT_C voidSetExitObserverL(MAknServerAppExitObserver &)
IMPORT_C voidSetMapAreaL(const TCoordinate &, TReal)
IMPORT_C voidSetOptions(TOptions)
IMPORT_C voidSetUseDefaultRequestText()
IMPORT_C voidShowCurrentLocationL()
IMPORT_C voidShowMapL()
Private Member Functions
CMnMapView()
CMnMapView(const CMnMapView &)
voidConstructChainedL(CMnProvider &)
voidConstructCommonL(CMnProvider &)
voidConstructNewL(CMnProvider &)
HBufC *LoadResourceTextL(RFs &, const TDesC &, TInt)
voidPostConstructL()
CMnMapView &operator=(const CMnMapView &)
Inherited Functions
CBase::CBase()
CBase::Delete(CBase *)
CBase::Extension_(TUint,TAny *&,TAny *)
CBase::operator new(TUint)
CBase::operator new(TUint,TAny *)
CBase::operator new(TUint,TLeave)
CBase::operator new(TUint,TLeave,TUint)
CBase::operator new(TUint,TUint)
CBase::~CBase()
Public Member Enumerations
enumTCurrentLocationOption { ECurrentLocationDisabled, ECurrentLocationEnabled, ECurrentLocationShowAlways }
enumTOption { EOptionNone, EOptionRestrictSelection }
enumTSelectionResultType { ESelectionNone, ESelectionFreeLandmark, ESelectionLandmarkIndex, ESelectionLinkedLandmark }
Public Member Type Definitions
typedef TUint32 TOptions
Private Attributes
TCoordinate iCentralPoint
TCurrentLocationOption iCurrentLocationOption
HBufC *iDefaultRequestText
CApaServerAppExitMonitor *iExitMonitor
TOptions iOptions
TReal iRadius
RMnMapViewServiceClient *iSession

Constructor & Destructor Documentation

CMnMapView()

CMnMapView()[private]

C++ constructor

CMnMapView(const CMnMapView &)

CMnMapView(const CMnMapView &)[private]

Parameters

const CMnMapView &

~CMnMapView()

~CMnMapView()[virtual]

Destructor

Member Functions Documentation

AddLandmarksToShowL(const TDesC &, RArray< TPosLmItemId > &)

IMPORT_C voidAddLandmarksToShowL(const TDesC &aDatabaseUri,
RArray< TPosLmItemId > &aLandmarkIds
)

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().

leave
KErrLocked Asynchronous request (SelectFromMapL) is outstanding.

Parameters

const TDesC & aDatabaseUriA database, to which belong landmarks, listed in aLandmarkIds parameter.
RArray< TPosLmItemId > & aLandmarkIdsIDs of landmarks to add to show list.

AddLandmarksToShowL(RPointerArray< CPosLandmark > &)

IMPORT_C voidAddLandmarksToShowL(RPointerArray< CPosLandmark > &aLandmarks)

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.

leave
KErrLocked Asynchronous request (SelectFromMapL) is outstanding.

Parameters

RPointerArray< CPosLandmark > & aLandmarksArray of landmarks to add to show list.

AddLandmarksToShowL(RArray< TPtrC8 > &)

IMPORT_C voidAddLandmarksToShowL(RArray< TPtrC8 > &aPackedLandmarks)

Landmarks are passed as packed instances (see 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.

leave
KErrLocked Asynchronous request (SelectFromMapL) is outstanding.

Parameters

RArray< TPtrC8 > & aPackedLandmarksArray of landmarks to add to show list.

Cancel()

IMPORT_C voidCancel()

ConstructChainedL(CMnProvider &)

voidConstructChainedL(CMnProvider &aProvider)[private]

Parameters

CMnProvider & aProvider

ConstructCommonL(CMnProvider &)

voidConstructCommonL(CMnProvider &aProvider)[private]

Parameters

CMnProvider & aProvider

ConstructNewL(CMnProvider &)

voidConstructNewL(CMnProvider &aProvider)[private]

Parameters

CMnProvider & aProvider

CurrentLocationOption()

IMPORT_C TCurrentLocationOptionCurrentLocationOption()const

LoadResourceTextL(RFs &, const TDesC &, TInt)

HBufC *LoadResourceTextL(RFs &aFsSession,
const TDesC &aRscFile,
TIntaResourceId
)[private]

Parameters

RFs & aFsSession
const TDesC & aRscFile
TInt aResourceId

NewChainedL(CMnProvider &)

IMPORT_C CMnMapView *NewChainedL(CMnProvider &aProvider)[static]
leave
KErrNotSupported Selected Provider Application does not support map view services (CMnProvider::EServiceMapView ).

Parameters

CMnProvider & aProviderProvider Application to be used for showing map.

NewL(CMnProvider &)

IMPORT_C CMnMapView *NewL(CMnProvider &aProvider)[static]
leave
KErrNotSupported Selected Provider Application does not support map view services (CMnProvider::EServiceMapView ).

Parameters

CMnProvider & aProviderProvider Application to be used for showing map.

Options()

IMPORT_C TOptionsOptions()const

PostConstructL()

voidPostConstructL()[private]

RemoveExitObserver()

IMPORT_C voidRemoveExitObserver()

ResetLandmarksToShow()

IMPORT_C voidResetLandmarksToShow()

ResetMapArea()

IMPORT_C voidResetMapArea()

RetrieveSelectionResultL()

IMPORT_C CPosLandmark *RetrieveSelectionResultL()
leave
KErrNotFound Result is not available or is of other type. See SelectionResultType() for details.
SelectionResultType() RetrieveSelectionResultL(TInt&) RetrieveSelectionResultL(TPosLmItemId&, HBufC*&)

RetrieveSelectionResultL(TInt &)

IMPORT_C voidRetrieveSelectionResultL(TInt &aLandmarkIndex)
leave
KErrNotFound Result is not available or is of other type. See SelectionResultType() for details.
SelectionResultType() RetrieveSelectionResultL() RetrieveSelectionResultL(TPosLmItemId&, HBufC*&)

Parameters

TInt & aLandmarkIndexIndex of a landmark passed as instance, which has been selected.

RetrieveSelectionResultL(TPosLmItemId &, HBufC *&)

IMPORT_C voidRetrieveSelectionResultL(TPosLmItemId &aLandmarkId,
HBufC *&aDatabaseUri
)
leave
KErrNotFound Result is not available or is of other type. See SelectionResultType() for details.
SelectionResultType() RetrieveSelectionResultL() RetrieveSelectionResultL(TInt&)

Parameters

TPosLmItemId & aLandmarkIdOn return, ID of selected landmark in the database, specified by aDatabaseUri.
HBufC *& aDatabaseUriOn return, URI of the database of selected landmark. Client takes ownership.

SelectFromMapL(TRequestStatus &)

IMPORT_C voidSelectFromMapL(TRequestStatus &aStatus)

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.

panic
"MnClientPanic"-KMnPanicDuplicateRequest if new asynchronous request is issued before previous one is completed.

Parameters

TRequestStatus & aStatusStatus 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.

SelectionResultType()

IMPORT_C TSelectionResultTypeSelectionResultType()const

SetCurrentLocationOption(TCurrentLocationOption)

IMPORT_C voidSetCurrentLocationOption(TCurrentLocationOptionaCurrentLocationOption)

Parameters

TCurrentLocationOption aCurrentLocationOptionOne of TCurrentLocationOption values.

SetCustomRequestTextL(const TDesC &)

IMPORT_C voidSetCustomRequestTextL(const TDesC &aCustomText)

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.

Parameters

const TDesC & aCustomTextText to be shown as selection request to user.

SetExitObserverL(MAknServerAppExitObserver &)

IMPORT_C voidSetExitObserverL(MAknServerAppExitObserver &aObserver)
leave
KErrAlreadyExists if observer is already set.

Parameters

MAknServerAppExitObserver & aObserverExit observer.

SetMapAreaL(const TCoordinate &, TReal)

IMPORT_C voidSetMapAreaL(const TCoordinate &aCentralPoint,
TRealaRadius
)

Parameters

const TCoordinate & aCentralPointPoint on the Earth to be shown in the center of map view. This setting is ignored, when ShowCurrentLocationL() is called.
TReal aRadiusRadius 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.

SetOptions(TOptions)

IMPORT_C voidSetOptions(TOptionsaOptions)

Parameters

TOptions aOptionsBitmap of TOption values.

SetUseDefaultRequestText()

IMPORT_C voidSetUseDefaultRequestText()

ShowCurrentLocationL()

IMPORT_C voidShowCurrentLocationL()

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)

ShowMapL()

IMPORT_C voidShowMapL()

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

operator=(const CMnMapView &)

CMnMapView &operator=(const CMnMapView &)[private]

Parameters

const CMnMapView &

Member Enumerations Documentation

Enum TCurrentLocationOption

Enumerators

ECurrentLocationDisabled

Current location is not shown (default).

ECurrentLocationEnabled

Current location is shown only if it's within visible area

ECurrentLocationShowAlways

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.

Enum TOption

Enumerators

EOptionNone

Default value

EOptionRestrictSelection

Defines that only landmarks specified by AddLandmarksToShowL are allowed to be selected by user.

Enum TSelectionResultType

Enumerators

ESelectionNone

Undefined result

ESelectionFreeLandmark

Free location has been selected. Use RetrieveSelectionResultL() to get result of selection.

ESelectionLandmarkIndex

One of landmarks passed by instance has been selected. Use RetrieveSelectionResultL(TInt&) to get result of selection.

ESelectionLinkedLandmark

One of landmarks passed as landmark ID and database URI has been selected. Use RetrieveSelectionResultL(TPosLmItemId&, HBufC*&) to get result of selection.

Member Type Definitions Documentation

Typedef TOptions

typedef TUint32 TOptions

Type for bitmap of flags defined by TOption

Member Data Documentation

TCoordinate iCentralPoint

TCoordinate iCentralPoint[private]

TCurrentLocationOption iCurrentLocationOption

TCurrentLocationOption iCurrentLocationOption[private]

HBufC * iDefaultRequestText

HBufC *iDefaultRequestText[private]

CApaServerAppExitMonitor * iExitMonitor

CApaServerAppExitMonitor *iExitMonitor[private]

TOptions iOptions

TOptions iOptions[private]

TReal iRadius

TReal iRadius[private]

RMnMapViewServiceClient * iSession

RMnMapViewServiceClient *iSession[private]