Collapse all Symbian^3 Application Developer Library

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

CMnMapView
- CBase

Public Member Functions
	~CMnMapView ()
IMPORT_C void	AddLandmarksToShowL (const TDesC &, RArray < TPosLmItemId > &)
IMPORT_C void	AddLandmarksToShowL ( RPointerArray < CPosLandmark > &)
IMPORT_C void	AddLandmarksToShowL ( RArray < TPtrC8 > &)
IMPORT_C void	Cancel ()
IMPORT_C TCurrentLocationOption	CurrentLocationOption ()
IMPORT_C CMnMapView *	NewChainedL ( CMnProvider &)
IMPORT_C CMnMapView *	NewL ( CMnProvider &)
IMPORT_C TOptions	Options ()
IMPORT_C void	RemoveExitObserver ()
IMPORT_C void	ResetLandmarksToShow ()
IMPORT_C void	ResetMapArea ()
IMPORT_C CPosLandmark *	RetrieveSelectionResultL ()
IMPORT_C void	RetrieveSelectionResultL ( TInt &)
IMPORT_C void	RetrieveSelectionResultL ( TPosLmItemId &, HBufC *&)
IMPORT_C void	SelectFromMapL ( TRequestStatus &)
IMPORT_C TSelectionResultType	SelectionResultType ()
IMPORT_C void	SetCurrentLocationOption ( TCurrentLocationOption )
IMPORT_C void	SetCustomRequestTextL (const TDesC &)
IMPORT_C void	SetExitObserverL ( MAknServerAppExitObserver &)
IMPORT_C void	SetMapAreaL (const TCoordinate &, TReal )
IMPORT_C void	SetOptions ( TOptions )
IMPORT_C void	SetUseDefaultRequestText ()
IMPORT_C void	ShowCurrentLocationL ()
IMPORT_C void	ShowMapL ()

Private Member Functions
	CMnMapView ()
	CMnMapView (const CMnMapView &)
void	ConstructChainedL ( CMnProvider &)
void	ConstructCommonL ( CMnProvider &)
void	ConstructNewL ( CMnProvider &)
HBufC *	LoadResourceTextL ( RFs &, const TDesC &, TInt )
void	PostConstructL ()
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
enum	TCurrentLocationOption { ECurrentLocationDisabled , ECurrentLocationEnabled , ECurrentLocationShowAlways }
enum	TOption { EOptionNone , EOptionRestrictSelection }
enum	TSelectionResultType { 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 void	AddLandmarksToShowL	(	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 & aDatabaseUri	A database, to which belong landmarks, listed in aLandmarkIds parameter.
RArray < TPosLmItemId > & aLandmarkIds	IDs of landmarks to add to show list.

AddLandmarksToShowL(RPointerArray< CPosLandmark > &)

IMPORT_C void

AddLandmarksToShowL

(

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 > & aLandmarks

Array of landmarks to add to show list.

AddLandmarksToShowL(RArray< TPtrC8 > &)

IMPORT_C void

AddLandmarksToShowL

(

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 > & aPackedLandmarks

Array of landmarks to add to show list.

Cancel()

IMPORT_C void

Cancel

(

)

ConstructChainedL(CMnProvider &)

void

ConstructChainedL

(

CMnProvider &

aProvider

)

[private]

Parameters

CMnProvider & aProvider

ConstructCommonL(CMnProvider &)

void

ConstructCommonL

(

CMnProvider &

aProvider

)

[private]

Parameters

CMnProvider & aProvider

ConstructNewL(CMnProvider &)

void

ConstructNewL

(

CMnProvider &

aProvider

)

[private]

Parameters

CMnProvider & aProvider

CurrentLocationOption()

IMPORT_C TCurrentLocationOption

CurrentLocationOption

(

)

const

LoadResourceTextL(RFs &, const TDesC &, TInt)

HBufC *	LoadResourceTextL	(	RFs &	aFsSession,
			const TDesC &	aRscFile,
			TInt	aResourceId
		)	[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 & aProvider

Provider 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 & aProvider

Provider Application to be used for showing map.

Options()

IMPORT_C TOptions

Options

(

)

const

PostConstructL()

void

PostConstructL

(

)

[private]

RemoveExitObserver()

IMPORT_C void

RemoveExitObserver

(

)

ResetLandmarksToShow()

IMPORT_C void

ResetLandmarksToShow

(

)

ResetMapArea()

IMPORT_C void

ResetMapArea

(

)

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 void

RetrieveSelectionResultL

(

TInt &

aLandmarkIndex

)

leave: KErrNotFound Result is not available or is of other type. See SelectionResultType() for details.

SelectionResultType() RetrieveSelectionResultL() RetrieveSelectionResultL(TPosLmItemId&, HBufC*&)

Parameters

TInt & aLandmarkIndex

Index of a landmark passed as instance, which has been selected.

RetrieveSelectionResultL(TPosLmItemId &, HBufC *&)

IMPORT_C void	RetrieveSelectionResultL	(	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 & aLandmarkId	On return, ID of selected landmark in the database, specified by aDatabaseUri.
HBufC *& aDatabaseUri	On return, URI of the database of selected landmark. Client takes ownership.

SelectFromMapL(TRequestStatus &)

IMPORT_C void

SelectFromMapL

(

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

SelectionResultType()

IMPORT_C TSelectionResultType

SelectionResultType

(

)

const

SetCurrentLocationOption(TCurrentLocationOption)

IMPORT_C void

SetCurrentLocationOption

(

TCurrentLocationOption

aCurrentLocationOption

)

Parameters

TCurrentLocationOption aCurrentLocationOption

One of TCurrentLocationOption values.

SetCustomRequestTextL(const TDesC &)

IMPORT_C void

SetCustomRequestTextL

(

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 & aCustomText

Text to be shown as selection request to user.

SetExitObserverL(MAknServerAppExitObserver &)

IMPORT_C void

SetExitObserverL

(

MAknServerAppExitObserver &

aObserver

)

leave: KErrAlreadyExists if observer is already set.

Parameters

MAknServerAppExitObserver & aObserver

Exit observer.

SetMapAreaL(const TCoordinate &, TReal)

IMPORT_C void	SetMapAreaL	(	const TCoordinate &	aCentralPoint,
			TReal	aRadius
		)

Parameters

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

SetOptions(TOptions)

IMPORT_C void

SetOptions

(

TOptions

aOptions

)

Parameters

TOptions aOptions

Bitmap of TOption values.

SetUseDefaultRequestText()

IMPORT_C void

SetUseDefaultRequestText

(

)

ShowCurrentLocationL()

IMPORT_C void

ShowCurrentLocationL

(

)

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 void

ShowMapL

(

)

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]