/*
* Copyright (c) 2007 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: CMnMapImage class
*
*/
#ifndef MN_MAPIMAGE_H_
#define MN_MAPIMAGE_H_
#include <e32base.h>
#include <lbsposition.h>
#include <mnmapimageparams.h>
class CApaServerAppExitMonitor;
class MAknServerAppExitObserver;
class CMnProvider;
class RMnMapImageServiceClient;
class CMnMapImage;
class CFbsBitmap;
class CMnCoordinateConverterBase;
/** Abstract class to be inherited by classes, which want to receive
* notification, when image rendering is completed.
* @see CMnMapImage
* @since 5.0 */
class MMnMapImageRenderCallback
{
public:
/** This callback is called when CMnMapImage has completed rendering
* map image. It is not called if rendering was cancelled by client.
* @param aStatus Result of the rendering operation:
* - @p KErrNone - rendering was completed successfully.
* - @p KErrNotSupported - rendering is not possible in specified area
* or one of mandatory options are not supported (see @ref TShowOption).
* - Other system-wide error codes also possible.
* @param aMapImage Instance of CMnMapImage, through which the request has
* been issued. */
virtual void HandleRenderingCompletedL( TInt aStatus, CMnMapImage& aMapImage ) = 0;
};
/** Provides access to map image rendering features.
*
* The RenderL() method allows to get bitmap image of some area, which is specified
* by SetCenterPoint() and SetScale(). Size of the bitmap is defined by SetSize().
*
* To create an instance of the class, use @ref NewL method. It
* requires instance of CMnProvider, defined in Map and Navigation Provider Discovery API.
*
* Only one asynchronous request can be issued at a time, otherwise client
* will be panicked with KMnPanicDuplicateRequest.
*
* @since 5.0
* @lib mnclientlib.dll
* @ingroup MapNavAPI
*/
class CMnMapImage : public CBase
{
public:
/** Creates new instance of the class. Provider Application
* will be executed standalone.
*
* @param[in] aProvider Provider Application to be used for map rendering.
* @return Pointer to new instance of the class.
*
* @leave KErrNotSupported Selected Provider Application does not support
* map image services (@ref CMnProvider::EServiceMapImage). */
IMPORT_C static CMnMapImage* NewL( CMnProvider& aProvider );
/** Destructor */
virtual ~CMnMapImage();
enum TShowOption
{
/** No options set, just plain image is requested. */
EShowOptionNone = 0x00,
/** Texts such as street, city, country names should be drawn */
EShowOptionText = 0x01,
/** POIs should be marked on the map */
EShowOptionPois = 0x02,
/** Landmarks should be marked on the map */
EShowOptionLandmarks = 0x04,
/** Current location should be marked on the map.
* Client must have Location capability, otherwise
* this option will be ignored. */
EShowOptionCurrentLocation = 0x08,
/** Country borders should be shown */
EShowOptionCountryBorders = 0x10,
/** If this flag is set, it is required to draw
* items specified by other flags, otherwise all
* of them are optional. */
EShowOptionsMandatory = 0xF000
};
/** Type for bitmap of options defined in @ref TShowOption */
typedef TUint32 TShowOptions;
/** Returns what types of map images are supported by provider
* application given at construction (see NewL()).
* @return Bitmap of values defined by @ref TMapImageType. */
IMPORT_C TMnMapImageParams::TMapImageTypes SupportedImageTypes();
/** Returns map image parameters object.
* Client can modify it, but all modification will be
* applied only for next and following RenderL requests.
* @return Modifiable map image parameters object */
IMPORT_C TMnMapImageParams& MapImageParams();
/** @overload
* @return Non-modifiable map image parameters object */
IMPORT_C const TMnMapImageParams& MapImageParams() const;
/** Sets all map image drawing parameters at once.
* New options will be applied only for next and following
* RenderL requests.
* @param aImageParams Image parameters to take into use for
* following RenderL requests */
IMPORT_C void SetMapImageParams( TMnMapImageParams& aImageParams );
/** Specifies the origin of image in the target bitmap, see
* RenderL(). By default it is TPoint( 0, 0 ), i.e. left top
* corner of the bitmap.
* This setting takes effect only from next RenderL request.
* @param[in] aOrigin Origin of the map in the target bitmap.*/
IMPORT_C void SetTargetOrigin( const TPoint& aOrigin );
/** Returns current setting of map image origin in target bitmap.
* @returns Origin of map image in the target bitmap.*/
IMPORT_C TPoint TargetOrigin();
/** Sets additional options to be used in rendering. Renderer will
* take them into account if possible.
* This setting takes effect only from next RenderL request.
* @param[in] aOptions Bitmap of options defined in @ref TOption. */
IMPORT_C void SetShowOptions( const TShowOptions& aOptions );
/** Returns additional options set to be used in rendering.
* @return Bitmap of options defined in @ref TShowOption. */
IMPORT_C TShowOptions ShowOptions() const;
/** Intiates rendering of map image.
* This is asynchronous request, which completion is informed via
* aStatus parameter. Client should use active object to wait for completion.
*
* This function may leave if some error occurs during initiating of the request.
* If so, then no asynchronous request will be left ongoing.
*
* @param[in,out] aBitmap Bitmap object, which the map image will be drawn into.
* Its size in pixels must be sufficient to fit the image
* defined by @ref SetSize() taking @ref SetTargetOrigin()
* into account as well.
* @param[out] aStatus This status will be completed, when rendering is finished.
* - @p KErrNone - rendering was completed successfully.
* - @p KErrNotSupported - rendering is not possible in specified area
* or one of mandatory options are not supported (see @ref TShowOption).
* - Other system-wide error codes also possible.
*
* @leave KErrArgument
* - If target bitmap size is too small.
* - If requested image type is not supported by provider application
*
* @panic "MnPanicClient"-KMnPanicDuplicateRequest if request is already
* ongoing. */
IMPORT_C void RenderL( CFbsBitmap& aBitmap, TRequestStatus& aStatus );
/** Intiates rendering of map image.
* This is asynchronous request, which completion is informed via aCallback.
*
* Client must provide callback as class derived from MMnMapImageRenderCallback.
* This is asynchronous request also. An active object will be executed to handle
* completion of rendering request, so client must have active scheduler installed.
*
* This function may leave if some error occurs during initiating of the request.
* If so, then no asynchronous request will be left ongoing.
*
* @param[in,out] aBitmap Bitmap object, which the map image will be drawn into.
* Its size in pixels must be sufficient to fit the image
* defined by @ref SetSize() taking @ref SetTargetOrigin()
* into account as well.
* @param[in] aCallback Callback object to call when rendering is completed.
* See @ref MMnMapImageRenderCallback::HandleRenderingCompletedL for details
* on possible operation result error codes.
*
* @leave KErrArgument
* - If target bitmap size is too small.
* - If requested image type is not supported by provider application
*
* @panic "MnPanicClient"-KMnPanicDuplicateRequest if request is already
* ongoing. */
IMPORT_C void RenderL( CFbsBitmap& aBitmap, MMnMapImageRenderCallback& aCallback );
/** Cancels current ongoing asynchronous rendering request.
* Note that callback, set in @ref RenderL(CFbsBitmap&, MMnMapImageRenderCallback&)
* is <i>not</i> called, if request is cancelled. */
IMPORT_C void CancelRendering();
/** Calculates coordinate in pixels of the point corresponding to given
* world coordinate.
*
* Given world coordinate is allowed to be beyond
* image borders. In that case negative values in result value
* describe point to the left of left border and/or above top border of the
* image and values bigger than width or height describe point to the right
* of right image border or below its bottom border.
*
* Sometimes such calculation is not possible (e.e given world coordinate
* is not part of the image) and this function returns @c KErrUnknown.
*
* Map image parameters are necessary be set in order for this function
* to operate successfully. Default values are not sufficient, so client
* is responsible to override them before calling this method. Note though,
* that it is not required to call RenderL before calling this method.
*
* @param[in] aWorldCoordinate World coordinate (in WGS-84)
* @param[out] aImagePoint On successful return, coordinate of corresponding
* pixel in image relative to image top left corner.
* @return Error code of the operation:
* - @c KErrNone if calculation is successful
* - @c KErrArgument if map image parameters in are invalid.
* - @c KErrUnknown if calculation is not possible */
IMPORT_C TInt GetImageCoordinate(
const TCoordinate& aWorldCoordinate,
TPoint& aImagePoint ) const;
/** Calculates world coordinate of the given image point.
*
* Given image point coordinate must be within the rectangle
* ( TPoint( 0, 0 ), @ref Size() ).
*
* Map image parameters are necessary be set in order for this function
* to operate successfully. Default values are not sufficient, so client
* is responsible to override them before calling this method. Note though,
* that it is not required to call RenderL before calling this method.
*
* Sometimes such calculation is not possible (e.g. given image coordinate
* does not match any world coordinate) and this function returns @c KErrUnknown.
*
* @param[in] aImagePoint Coordinate of a point on map image in pixels,
* relative to image top left corner.
* @param[out] aWorldCoordinate On successful return, corresponding
* world coordinate (in WGS-84).
* @return Error code of the operation:
* - @c KErrNone if calculation is successful
* - @c KErrArgument if image coordinate is out of bounds
* - @c KErrArgument if map image parameters in are invalid.
* - @c KErrUnknown if calculation is not possible */
IMPORT_C TInt GetWorldCoordinate(
const TPoint& aImagePoint,
TCoordinate& aWorldCoordinate ) const;
/** 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 );
/** Removes observer of provider application lifetime. */
IMPORT_C void RemoveExitObserver();
protected:
CMnMapImage();
void ConstructL( CMnProvider& aProvider );
private:
TUint32 iProviderFeatures;
TPoint iTargetOrigin;
TMnMapImageParams iMapImageParams;
TShowOptions iShowOptions;
RMnMapImageServiceClient* iSession;
CApaServerAppExitMonitor* iExitMonitor;
CActive* iActiveCallback;
CMnCoordinateConverterBase* iCoordConverter;
};
#endif /*MN_MAPIMAGE_H_*/