// Copyright (c) 1995-2009 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:

 // Header for writing animated DLL add ons

 // 

 //

 #if !defined(__W32ADLL_H__)

 #define __W32ADLL_H__

 #if !defined(__W32STD_H__)

 #include <w32std.h>

 #endif

 #if !defined(__BITSTD_H__)

 #include <bitstd.h>

 #endif

 /**

 @publishedAll

 @deprecated

 */

 const TUint KWservAnimDllUidValue8=268435858;

 /**

 @publishedAll

 @deprecated

 */

 const TUid KWservAnimDllUid8={KWservAnimDllUidValue8};

 /**

 @publishedAll

 @released

 */

 const TUint KWservAnimDllUidValue16=268450594;

 /**

 @publishedAll

 @released

 */

 const TUid KWservAnimDllUid16={KWservAnimDllUidValue16};

 /**

 @publishedAll

 @released

 */

 const TUint KWservAnimDllUidValue=KWservAnimDllUidValue16;

 /**

 @publishedAll

 @released

 */

 const TUid KWservAnimDllUid={KWservAnimDllUidValue};

 //

 // Contains functions callable from animated DLLs

 //

 class TWindowInfo

 /** Animation window information.

 Stores the window position and display mode for the animation.

 During a redraw of the animation window, the redraw regions

 can be retrieved by calling GetRedrawRegionAndRedrawShadowRegion().

 @publishedAll 

 @released

 @see TWindowInfo::GetRedrawRegionAndRedrawShadowRegion() */

 	{

 public:

 	/** The screen position. */

 	TRect iScreenPos;

 	/** The display mode.

 	This is the minimum display mode that the screen has to be in to display this window. */

 	TDisplayMode iMode;

 public:

 	/** Constructs an animation window information object. */

 	inline TWindowInfo() : iRegionPair(NULL) {}

 public:

 	/** Stores a pair of region pointers. */

 	struct TRegionPair

 		{

 		const TRegion* iRegion1;

 		const TRegion* iRegion2;

 		};

 	/** Returns the current redraw region and redraw shadow region.

 	This function must only be called from an override of CWindowAnim's pure virtual Redraw function.

 	The region pointers retrieved must not be used beyond the end of the Redraw override.

 	@param aRedrawRegion The redraw region in screen coordinates.

 	@param aRedrawShadowRegion The redraw shadow region in screen coordinates. */

 	inline void GetRedrawRegionAndRedrawShadowRegion(const TRegion*& aRedrawRegion, const TRegion*& aRedrawShadowRegion) const

 		{

 		if (iRegionPair)

 			{

 			aRedrawRegion=iRegionPair->iRegion1;

 			aRedrawShadowRegion=iRegionPair->iRegion2;

 			iRegionPair=NULL;

 			}

 		else

 			{

 			aRedrawRegion=NULL;

 			aRedrawShadowRegion=NULL;

 			}

 		}

 private:

 	mutable const TRegionPair* iRegionPair;

 	TAny *iFree2;

 	friend class CWsAnim;

 	};

 class MEventHandler

 /** Event handler interface.

 The interface provides a function to handle raw events, e.g. key presses, 

 pen events, power buttons etc. Raw events are passed to the OfferRawEvent() 

 function when the MAnimGeneralFunctions::GetRawEvents() function has been 

 called.

 @publishedAll

 @released */

 	{

 public:

 	/** Handles raw events. 

 	If the incoming event can be handled, the function should 

 	process it and then return true. If it cannot be processed the function should 

 	return false, and the event will be passed to other event handling code.

 	This function must be implemented in every animation DLL. If event 

 	handling is not required, the function should simply return false.

 	@param aRawEvent The raw event to be processed

 	@return ETrue if the raw event is handled by this function, EFalse if the function 

 	chooses not to process it. */

 	virtual TBool OfferRawEvent(const TRawEvent &aRawEvent)=0;

 	};

 enum TAnimNotifications

 /** Bit flags to be used by anims when registering for notifications */

 	{

 	/** Notify when direct screen access begins or ends.*/

 	EDirectScreenAccess = 0x0001,

 	/** Notify when the wserv heartbeat timer starts or stops. */

 	EHeartbeatTimer	= 0x0002,

 	/** Notify when screen device changes.*/

 	EScreenDeviceChange = 0x0004

 	};

 //Forward Declaration.

 class MAnimGeneralFunctionsWindowExtension;    

 class MAnimGeneralFunctionsEventExtension ;

 class MAnimGeneralFunctions

 /** General animation utility functions interface. 

 The interface provides functions to set the animation timing, 

 event functions, and other general functions.

 You do not have to create an object of this type. The class is implemented 

 by the window server and provides utility functions to all CAnim-derived 

 classes via the CAnim::iFunctions pointer.

 It is not intended for user derivation.

 @publishedAll

 @released */

 	{

 public:

 	/** Animation synchronisation flags. 

 	The animation can be synchronised to any of these values; 

 	the Animate() call will take place at the start of the new unit (day, hour, etc...). */

 	enum TAnimSync

 		{

 		/** Not synchronised. Animate() is called after some number of flash cycles - 

 		set by SetSync(). */

 		ESyncNone,

 		/** Animate() every flash tick. This occurs twice a second, on the second and after 

 		7/12ths of a second, e.g. the function is called in a flash-on (7/12 seconds) - 

 		flash-off (5/12 seconds) cycle. */

 		ESyncFlash,

 		/** Animate() called as soon after every second as system activity allows. */

 		ESyncSecond,

 		/** Animate() called as soon after every minute as system activity allows. */

 		ESyncMinute,

 		/** Animate() called as soon after midnight every day as system activity allows. */

 		ESyncDay,

 		};

 	enum

 		{

 		ENumberOfExtendedInterfaces=0,

 		EWindowExtensionInterface,

 		EEventExtentionInterface,

 		EInterfaceCount, // Always keep at the end.

 		};

 	//Timing functions

 	/** Calls the DLL's Animate() function then deactivates the graphics context. 

 	This allows users to do drawing from their own active object.

 	Note:

 	If the user calls the CAnim-derived classes' Animate() function directly, 

 	or otherwise does drawing from their own active object, then this will not 

 	deactivate the graphics context. This causes the window server to panic the 

 	client.

 	Alternatively, use CFreeTimerWindowAnim, which allows you to deactivate the 

 	graphics context yourself.

 	@param aDateTime The parameter passed into the animation DLL's Animate() 

 	function. */

 	virtual void Animate(TDateTime *aDateTime)=0;

 	/** Sets the synchronisation mode. 

 	This determines the time intervals between calls to the Animate() function.

 	@param aSyncMode The synchronisation mode. */

 	virtual void SetSync(TAnimSync aSyncMode)=0;

 	/** Sets the repeat interval. 

 	If the synchronisation mode is TAnimSync::ESyncNone, then the Animate() function 

 	is called at intervals defined by some number of flash ticks. There are two 

 	flash ticks a second, with a 7/12 second - 5/12 second cycle. If the function 

 	is called when the synchronisation mode is not TAnimSync::ESyncNone, then 

 	the window server panics the client.

 	If the new interval is greater than the current countdown, then the call does 

 	not affect the current countdown. For example, if the countdown has 10 flash 

 	ticks remaining, and the interval is set to 20, the new interval does not 

 	apply until the current countdown is complete. 

 	However if the new interval is less the current countdown, then the new interval 

 	applies immediately i.e. the countdown is reset to the interval value.

 	If the interval is set to zero the countdown stops, and the Animate() function 

 	is no longer called.

 	@param aInterval The number of flash ticks between calls to the Animate() 

 	function. */

 	virtual void SetInterval(TInt aInterval)=0;

 	/** Sets the next interval. 

 	This function immediately resets the current countdown to the specified number 

 	of flash ticks, irrespective of its current value. After the countdown expires, 

 	the interval returns to its usual rate. Note that this may be zero (i.e. 

 	not at all).

 	To call this function, the synchronisation mode must be TAnimSync::ESyncNone, 

 	otherwise the window server panics the client.

 	Note: there are two flash ticks a second, with a 7/12 second - 5/12 second cycle.

 	@param aInterval The interval to the next Animate(). If the value is less 

 	than 1, it automatically gets set to 1.

 	@see SetInterval() */

 	virtual void SetNextInterval(TInt aInterval)=0;

 	/** Gets the system time as it was when Animate() was last called.

 	@return The system time when Animate() was last called. */

 	virtual TDateTime SystemTime() const=0;

 	/** Tests the flash cycle state. 

 	The flash cycle has 2 states: on (7/12 second) or off (5/12 second).

 	@return ETrue if in the on part of the flash cycle, otherwise EFalse. */

 	virtual TBool FlashStateOn() const=0;

 	/** Gets the current synchronisation mode.

 	@return The current sync mode. */

 	virtual TAnimSync Sync() const=0;

 	//Other functions generally useful

 	/** Gets a pointer to the screen device. 

 	For example, this might be used to gain access to twips to pixel conversion functions.

 	@return A pointer to the screen device. */

 	virtual const CFbsScreenDevice *ScreenDevice()=0;

 	/** Creates and duplicates a bitmap from a handle. 

 	This function might be used to duplicate client side bitmaps on the server side.

 	@param aHandle A handle to the bitmap to be duplicated.

 	@return A pointer to the duplicate bitmap. */

 	virtual CFbsBitmap *DuplicateBitmapL(TInt aHandle)=0;

 	/** Creates and duplicates a font from a handle.

 	This function might be used to duplicate client side fonts on the server side.

 	@param aHandle A handle to the font to be duplicated.

 	@return A pointer to the duplicate font. */

 	virtual CFbsFont *DuplicateFontL(TInt aHandle)=0;

 	/** Closes a duplicate font.

 	@param Pointer to the duplicate font.

 	@see DuplicateFontL() */

 	virtual void CloseFont(CFbsFont *)=0;

 	/** Gets a reference to the calling client's thread.

 	@return A reference to the calling client's thread. */

 	virtual const RThread &Client()=0;

 	/** Send a reply to the client process in response to a request

 	from the client. 	

 	@see RAnim::CommandReply()

 	@param aDes The data to be sent back to the client

 	 */

 	virtual void ReplyBuf(const TDesC8 &aDes)=0;

 	/** Send a reply to the client process in response to a request

 	from the client. 	

 	@see RAnim::CommandReply()

 	@param aDes The data to be sent back to the client

 	 */

 	virtual void ReplyBuf(const TDesC16 &aDes)=0;				

 	/** Panics the client. 

 	This will result in the client thread being destroyed. */

 	virtual void Panic() const=0;

 	//Event functions

 	/** Switches animation raw event handling on and off.

 	If raw event handling is switched on, then raw events, e.g. pointer, key, or power events

 	are all offered to the animation event handling code's MEventHandler::OfferRawEvent().

 	If Animation works in a window for which advanced pointers have been enabled,

 	then after switching on raw event handling it will receive pointer events from all 

 	detected pointers. Otherwise it will receive events only from one emulated pointer.

 	@param aGetEvents If ETrue, raw events are passed to the animation 

 	event handling code. If EFalse, events are not passed to the animation. 

 	@see RWindowBase::EnableAdvancedPointers() */

 	virtual void GetRawEvents(TBool aGetEvents) const=0;

 	/** Posts a raw event, just as if it had come from the kernel.

 	If aRawEvent has pointer-related type (move, switch on, down, up or out of range),

 	then its Z coordinate and iPointerNumber fields will be validated and may be

 	overwritten by WSERV in order to guarantee correct behaviour depending on:

 	1. Pointer Pressure and Proximity support on current platform.

 	2. Multiple pointers support on current platform.

 	3. Animation's awareness of these fields. If Animation works in a window

 	   for which advanced pointers have been enabled, it is assumed that it has

 	   initialized these fields. Otherwise WSERV will assume that these fields have

 	   not been provided and may overwrite them with most appropriate values.

 	For more information about event validation, please refer to System Documentation.

 	@param aRawEvent The raw event 

 	@see RWindowBase::EnableAdvancedPointers() */

 	virtual void PostRawEvent(const TRawEvent &aRawEvent) const=0;

 	/** Posts a key event.

 	The function is similar to PostRawEvent() but should be 

 	used for posting key events. 

 	@param aRawEvent The key event. */

 	virtual void PostKeyEvent(const TKeyEvent &aRawEvent) const=0;

 	/** Get the address of an object which can retrieve information from and send

 	information to the client-side.

 	@return A pointer to RMessagePtr2. Complete must be called on the returned object (or a 

 	copy of it) if and only if Message is called from an override of CAnim's CommandReplyL which 

 	has been caused by a client-side RAnim::AsyncCommandReply call. If Message is called outside 

 	an override of CAnim's CommandReplyL or outside an override of CWindowAnim's ConstructL or 

 	CSpriteAnim's ConstructL, the it returns NULL. 

 	@see RMessagePtr2 */

 	virtual const RMessagePtr2* Message()=0; // replaces Reserved1

 	/**Returns an extension interface, maybe extended further in the future.

 	@param aInterfaceId The ID of the interface to return.

 	@return A pointer to the extension interface.

 	When aInterface=0 (ENumberOfExtendedInterfaces), the number of interfaces is returned (currently 2).

 	When aInterface=1 (EWindowExtensionInterface), a pointer to the Window Extension interface is returned.

 	When aInterface=2 (EEventExtentionInterface), a pointer to the Event Extension interface is returned.

 	*/

 	virtual TAny* ExtendedInterface(TInt aInterface)=0; // replaces Reserved2

 	/** Register to receive notifications.

 	@param aNotifications A bitset of TAnimNotifications values indicating which notifications are required

 	@return One of the system wide error codes

 	*/

 	virtual TInt RegisterForNotifications(TUint32 aNotifications)=0;

 	/*

 	Return number of ExtendedInterfaces. */

 	inline TInt NumberOfExtendedInterfaces()

 		{

 		return reinterpret_cast<TInt>(ExtendedInterface(ENumberOfExtendedInterfaces));

 		}

 	/** Gets access to Window Extension utility functions.

 	@return A pointer to a class containing functions for working with Window. */

 	inline MAnimGeneralFunctionsWindowExtension* WindowExtension()

 		{

 		return static_cast<MAnimGeneralFunctionsWindowExtension*>(ExtendedInterface(EWindowExtensionInterface));

 		}

 	/** Gets access to EventExtension utility functions. 

 	@return A pointer to a class containing functions for working with Event. */

 	inline MAnimGeneralFunctionsEventExtension* EventExtension()

 		{

 		return static_cast<MAnimGeneralFunctionsEventExtension*>(ExtendedInterface(EEventExtentionInterface));

 		}

 	private:

 	virtual void Reserved1() const;

 	virtual void Reserved2() const;

 	virtual void Reserved3() const;

 	};

 /* Structure for passing window configuration information. Currently transparancey

 related configuration information is supported, though this may be added to, as

 apprioriate.

 @publishedAll

 @released

 */

 class TWindowConfig

 	{

 public:

 	/** Transparency flags. 

 	Used to represent transparency configuration of the window. */

 	enum

 		{

 		/** Transparency is enabled on the window. */

 		ETransparencyEnabled=0x0001,

 		/** Window transparency uses alpha blending channel. */

 		EAlphaBlendedTransparency=0x0002,

 		};

 public:

 	/** Indicate configuration of window, using enumerations defined within this class. */

 	TInt iFlags;

 private:

 	TInt iReserved0;

 	TInt iReserved1;

 	TInt iReserved2;

 	};

 class MAnimGeneralFunctionsWindowExtension

 /** General Window utility functions interface. 

 The member functions define the interface for querying and manipulating 

 the window and screen attributes.

 You obtain one by calling: iFunctions->ExtendedInterface(MAnimGeneralFunctions::EWindowExtensionInterface) 

 and casting the result.

 It is not intended for user derivation.

 @publishedAll 

 @released */

 	{

 public:

 	/** Class contains the information pertaining to a window group: name, priority, 

 	focusability. */

 	class TWindowGroupInfo

 		{

 	public:

 		enum

 			{

 			/** Window is focusable flag. */

 			EIsFocusable=0x0001,

 			};

 	public:

 		/** Returns whether or not the window is focusable. 

 		@return ETrue if focusable, else returns EFalse. */

 		inline TBool IsFocusable() const {return iFlags&EIsFocusable;}

 	public:

 	/* Window group attributes. */

 		TInt iId;

 		TUint32 iFlags;

 		TInt iOrdinalPriority;

 		TInt iNameLength;

 		TInt iParentId;

 		};

 public:

 	/** Returns the total number of screens.

 	@return The total number of screens. */

 	virtual TInt Screens() const=0;

 	/** Returns the number of the screen which is currently in focus.

 	@return The number of the screen which is currently in focus.*/

 	virtual TInt FocusScreens() const=0;

 	/** Changes the focused screen.

 	@param aScreenNo New screen number. */

 	virtual void SetFocusScreen(TInt aScreenNo)=0;

 	/** Returns the number of window groups available for the specified screen.

 	@param aScreen The screen number.

 	@return The number of window groups. */

 	virtual TInt WindowGroups(TInt aScreen) const=0;

 	/** Takes a screen number and an ordinal position and returns the complete window 

 	group information of the specified window. If the window group does not exist, the 

 	function returns EFalse.

 	Note: the ordinal position specified should be the total or full ordinal position 

 	of all group windows of all priorities on that screen.

 	@param aInfo on return, complete window information.

 	@param aScreen Screen number.

 	@param aFullOrdinalPosition Ordinal position of the window.

 	@return ETrue if window group information exists, EFalse otherwise.  */

 	virtual TBool WindowGroupInfo(TWindowGroupInfo& aInfo,TInt aScreen,TInt aFullOrdinalPosition) const=0;

 	/** Takes a screen number and an ordinal position and returns the window group name.

 	If the window group does not exist, the function returns false.

 	Note: the ordinal position specified should be the total or full ordinal position of 

 	all group windows of all priorities on that screen.

 	Note: if the name does not fit into the descriptor provided then it will be truncated.

 	@param aWindowName On return, the window group name.

 	@param aScreen The screen number.

 	@param aFullOrdinalPosition The ordinal position of the window.

 	@return ETrue if the window group name exists, EFalse otherwise. */

 	virtual TBool WindowGroupName(TPtrC& aWindowName,TInt aScreen,TInt aFullOrdinalPosition) const=0;

 	/** Changes the ordinal position and priority of the window group with the specified ID.

 	@param aWindowGroupId The window group ID.

 	@param aPos The ordinal position to move the window to.

 	@param aOrdinalPriority The new ordinal priority of the window.

 	@return KErrNotFound if there is no window group with the specified ID, KErrNone otherwise. */

 	virtual TInt SetOrdinalPosition(TInt aWindowGroupId,TInt aPos,TInt aOrdinalPriority)=0;

 	/** Accessor for window configuration.

 	@param aWindowConfig Gets filled in with window configuration details. */

 	virtual void WindowConfig(TWindowConfig& aWindowConfig) const=0;

 private:

 	virtual void Reserved1() const;

 	virtual void Reserved2() const;

 	virtual void Reserved3() const;

 	};

 class MAnimGeneralFunctionsEventExtension

 /** Event utility functions interface. 

 The member functions define the interface for generate repeated key events .

 It is not intended for user derivation.

 */

 	{

 public:

 	/** Posts a key event.

 	The function is similar to PostKeyEvent() but should be 

 used for posting repeated key events. 

 	@param aRawEvent The key event.

 	@param aRepeats value */

 	virtual void PostKeyEvent(const TKeyEvent& aRawEvent, TInt aRepeats) const=0;

 private:

 	virtual void Reserved1() const;

 	virtual void Reserved2() const;

 	};

 class MAnimWindowFunctions

 /** Window utility functions interface. 

 The member functions define the interface for querying and manipulating 

 the window in which the animation takes place.

 You do not have to create an object of this type. The class is implemented 

 by the window server, and provides these utility functions to all CWindowAnim 

 and CFreeTimerWindowAnim derived classes via the iWindowFunctions pointer.

 It is not intended for user derivation.

 @publishedAll 

 @released */

 	{

 public:

 	/** Activates the graphics context.

 	This function should be called to enable drawing in the CAnim-derived classes'

 	Command(), CommandReplyL(), Animate(), or FocusChanged() functions.

 	Note: this function is called automatically by the animation DLL framework in the 

 	Redraw() function. */

 	virtual void ActivateGc()=0;

 	/** Sets the rectangle that this animation will draw to. 

 	This function must be called as part of the initialisation/construction of 

 	the CAnim-derived object, i.e. in CAnim::ConstructL(). This is so that the 

 	window server knows which area the animation is operating in. Anything that 

 	is drawn by the animation outside this rectangle may not be redrawn correctly

 	as the window server uses this rectangle to decide when the animation should

 	be redrawn.

 	@param aRect The rectangle to be drawn to. */

 	virtual void SetRect(const TRect &aRect)=0;

 	/** Gets the window size.

 	@return The window size, in pixels. */

 	virtual TSize WindowSize() const=0;

 	/** Tests whether to draw the animation. 

 	If the window is completely hidden, there is normally no need to draw 

 	the animation. However in some conditions the animation should be drawn even 

 	if it is obscured. The window server is aware of these cases, and returns 

 	ETrue if it is not safe to draw the animation.

 	@return True if the window is completely hidden and there is no requirement 

 	to continue drawing the animation, otherwise false. */

 	virtual TBool IsHidden()=0;

 	/** Sets the visibility of the window the animation is drawing to.

 	This does the same as RWindowBase::SetVisible().

 	@param aState True for visible, false otherwise. */

 	virtual void SetVisible(TBool aState)=0;

 	/** Forces a redraw of a rectangular part of the window.

 	The function causes a redraw message on the part of the window specified, 

 	which provides a non-immediate way to do drawing.

 	It can be used to redraw the whole of the window, not just the part used by 

 	the animation.

 	@param aRect The rectangle to be redrawn. These co-ordinates are relative 

 	to the origin of the window. */

 	virtual void Invalidate(const TRect &aRect)=0;

 	/** Gets window information.

 	@param aData The window information. */

 	virtual void Parameters(TWindowInfo &aData)=0;

 	/** Gets the visible region.

 	This region is the area of the visible window which 

 	is currently unshadowed. If there is not enough memory to calculate this region 

 	then aRegion's error flag is set.

 	@param aRegion The visible region. */

 	virtual void VisibleRegion(TRegion& aRegion)=0;

 	//virtual void CopyScreen(CFbsBitGc *aBitmapGc,TRect aRect)=0;

 private:

 	virtual void Reserved() const;

 	virtual void Reserved1() const;

 	virtual void Reserved2() const;

 	virtual void Reserved3() const;

 	};

 class MAnimFreeTimerWindowFunctions : public MAnimWindowFunctions

 /** Free timer animation utility functions interface.

 The class inherits functions from MAnimWindowFunctions, and defines the additional 

 interface required for window operations which support animations with their 

 own timers.

 You do NOT have to create an object of this type. The class is implemented 

 by the window server, and provides utility functions to all CFreeTimerWindowAnim 

 derived classes via the WindowFunctions() member. 

 It is not intended for user derivation.

 @publishedAll 

 @released */

 	{

 public:

 	/** Deactivates the graphics context. 

 	This function is used in the context of a CFreeTimerWindowAnim derived class 

 	when writing animation DLLs with their own timer. Within the timer's RunL(), 

 	the ActivateGc() function should be called prior to drawing to the window. 

 	DeactivateGc() should be called after drawing is finished. */

 	virtual void DeactivateGc()=0;

 	/** Forces the screen to update. */

 	virtual void Update()=0;

 private:

 	virtual void Reserved3() const;

 	};

 class MAnimSpriteFunctions

 /** Sprite animation utility functions interface.

 The interface includes functions for querying and manipulating a sprite.

 You do NOT have to create an object of this type. The class is implemented 

 by the window server, and provides utility functions to all CSpriteAnim derived 

 classes via the CSpriteAnim::iSpriteFunctions pointer. 

 It is not intended for user derivation.

 @publishedAll 

 @released */

 	{

 public:

 	/** Gets sprite member data.

 	Each member of the sprite is effectively a bitmap, which is displayed for a 

 	different amount of time.

 	@param aMember The index of the sprite member for which information is required.

 	@return A pointer to the sprite member. */

 	virtual TSpriteMember *GetSpriteMember(TInt aMember) const=0;

 	/** Redraws part of a sprite.

 	Updates a sprite on the screen, possibly after the bitmap for a particular 

 	sprite member has been changed.

 	Use the	aRect parameter to specify the (small) part of the sprite which has been changed, 

 	then any flicker will only occur in this rectangle. 

 	A full update used to be required if you had removed pixels from the mask, i.e. made 

 	pixels in the sprite transparent when they were not before. If drawing is 

 	additive, e.g. you are using a mask or the draw mode is EDrawModePEN, a partial 

 	update used to be possible. But current versions of the window-server always do full back to front rendering.

 	Note: if the sprite member aMember is not visible then there is no need for a change 

 	to the display, so the aRect and aFullUpdate parameters are ignored.

 	@param aMember The index of the sprite member that is to be updated.

 	@param aRect The part of the sprite member which has changed.

 	@param aFullUpdate	Not used. Wserv now always do full back to front rendering. */

 	virtual void UpdateMember(TInt aMember,const TRect& aRect,TBool aFullUpdate)=0;

 	/** Turns a sprite on or off.

 	In effect this makes the sprite bitmap visible.

 	@param aActive ETrue to turn sprite on. EFalse to turn it off. */

 	virtual void Activate(TBool aActive)=0;

 	/** Finishes constructing the sprite.

 	It also sets the currently displayed sprite member to zero.

 	This function must be called after members change size. */

 	virtual void SizeChangedL()=0;

 	/** Set the sprite's position.

 	@param aPos The new position of the sprite. */

 	virtual void SetPosition(const TPoint &aPos)=0;

 private:

 	virtual void Reserved() const;

 public:

 	/** Returns the visibility of the sprite.

 	A sprite can be seen if it is neither obscured by another window nor hidden.

 	@return ETrue if the sprite can be seen, EFalse otherwise. */

 	virtual TBool SpriteCanBeSeen() const = 0;

 private:

 	virtual void Reserved2() const;

 	virtual void Reserved3() const;

 	virtual void Reserved4() const;

 	};

 class CAnimGc : public CBitmapContext

 /** Animation graphics context. 

 An object of this type is linked into CAnim by the window server, which allows 

 you to draw to the animation window. The object's functions allow you to set 

 and cancel the clipping region, and to draw to the visible window using 

 the inherited CBitmapContext functions. 

 @publishedAll

 @released */

 	{

 public:

 	/** Sets the clipping region.

 	Only the parts of the animation which are within the clipping region are drawn.

 	@param aRegion The clipping region. */

 	virtual TInt SetClippingRegion(const TRegion &aRegion)=0;

 	/** Cancels the clipping region.

 	@see SetClippingRegion() */

 	virtual void CancelClippingRegion()=0;

 	};

 class CWsAnim; // Forward ref for friend declaration

 class CAnim : public CBase , public MEventHandler

 /** Server side animated object base interface.

 Animations implement this interface, which is called by the window server 

 to pass commands from clients, perform a step in the animation, or to pass 

 window server events (if required) so that the animation can handle them 

 before the application.

 The functions are all pure virtual, and must be implemented in 

 the derived class to provide server side behaviour. The functions will be 

 called by the window server with optional arguments passed in from the client 

 side animation class RAnim.

 You should derive from CWindowAnim, CFreeTimerWindowAnim or CSpriteAnim, 

 depending on whether the animation is to draw to a sprite or a window,

 rather than directly from this class.

 The derived class is constructed in the DLL factory class CAnimDll::CreateInstanceL() 

 function.

 The operation to perform an animation step is called by the window server 

 on a timer. The timing properties are set through an MAnimGeneralFunctions 

 member, which also provides other utility functions. 

 @publishedAll 

 @released */

 	{

 public:

 	/** Implements client-side initiated commands, returning a value. 

 	The window server calls this function in response to application calls to 

 	the client side command function RAnim::CommandReplyL(). The arguments passed 

 	to the function by the window server are the same as were used on the client 

 	side function call.

 	This function returns values to the client side, and should be used to return 

 	error codes for commands which might leave.

 	@param aOpcode Opcode understood by the class.

 	@param aArgs Arguments packaged on the client side, for example as a struct 

 	of a type determined by the aOpcode argument. These mirror the aArgs argument 

 	passed in to RAnim::CommandReply().

 	@return Value passed back to client side function when this function completes. 

 	Typically this would be KErrNone or another of the system-wide error codes. 

 	However any value may be returned to the client side.

 	@see RAnim */

 	virtual TInt CommandReplyL(TInt aOpcode, TAny *aArgs)=0;

 	/** Implements client-side initiated commands. 

 	The window server calls this function in response to application calls to 

 	the client side command function RAnim::Command(). The arguments passed to 

 	the function by the window server are the same as were used on the client 

 	side function call.

 	Because this function does not return errors, it is not safe for commands 

 	which might leave.

 	@param aOpcode Opcode understood by the class

 	@param aArgs Arguments packaged on the client side, for example as a struct 

 	of a type determined by the aOpcode argument. These mirror the aArgs argument 

 	passed in to RAnim::Command().

 	@see RAnim */

 	virtual void Command(TInt aOpcode, TAny *aArgs)=0;

 	/** Main animation function, called by the window server. 

 	The drawing code which implements a given animation should be provided here.

 	This function is called at a frequency determined by the SetSync() helper 

 	function. Note that if sync is not set, then this function will never be 

 	called. This effect can be exploited to use the animation framework, with 

 	its server side speed, for what are strictly not animations, e.g. for streaming 

 	video images.

 	The aDateTime parameter will be null if the current time (as determined by 

 	the window server) matches the time implied by the sync period, modulo normalisation, 

 	otherwise it will contain a valid (non-normalised) time.

 	Normalisation is to some specified granularity, for example if one minute 

 	is specified as the animation frequency, then in effect the window server 

 	will decide whether the implied time is correct to the minute, but not to 

 	the second.

 	Implied time is the time implied by the (normalised) actual time of the previous 

 	animation call plus the sync interval. For example if the last call was at 

 	time 't' and the sync interval is 1 second then if the time at this call 

 	is t + 1 second, then actual time and implied time match and the value placed 

 	into aDateTime will be NULL.

 	Cases in which the two may not match include, for example, system time having 

 	been reset between animation calls (perhaps British Summer Time or other daylight 

 	saving time has just come into effect). The intention is that when system 

 	time changes, a mechanism is provided to alert the animation code and allow 

 	it to reset itself. The assumption is that somewhere in its initialisation 

 	code, the animation will have performed a CAnimFunctions utility call to set 

 	a base time, which is then implicitly tracked by incrementing by a suitable 

 	interval; when aDateTime is non-NULL after a call to Animate(), base time 

 	should be reset.

 	@param aDateTime Null if the current time w.r.t. the window server matches 

 	the time implied by the synch period. Otherwise a valid (non-normalised) time. */

 	virtual void Animate(TDateTime *aDateTime)=0;

 	virtual void HandleNotification(const TWsEvent& /*aEvent*/) {};

 private:

 	inline CAnim() {}

 	virtual void Reserved1() const {};

 	virtual void Reserved2() const {};

 	virtual void Reserved3() const {};

 protected:

 	/** Pointer to a class containing functions implemented by the window server. 

 	These are available to any CAnim derived class.

 	Note that this value is automatically set for you by the animation framework. 

 	You do not need to assign a value to this pointer. 

 	@publishedAll

 	@released	*/

 	MAnimGeneralFunctions *iFunctions;

 	friend class CWsAnim;

 	friend class CWindowAnim;

 	friend class CSpriteAnim;

 	};

 class CWindowAnim : public CAnim

 /** Window animation interface. 

 This interface is provided to create animations other than sprites. A window 

 animation can be provided by deriving from this class.

 The interface inherits from CAnim and has access to its functions. It additionally 

 can access an interface for querying and manipulating the window in which 

 the animation takes place, using its iWindowFunctions member.

 The derived class is constructed in the DLL factory class CAnimDll::CreateInstanceL().

 @publishedAll

 @released 

 @see CFreeTimerWindowAnim

 @see CSpriteAnim */

 	{

 public:

 	/** Server side construction and initialisation of an animation class. 

 	Note: the aHasFocus argument allows the animation to start in a known focus state. 

 	For example, an animation may or may not have focus, depending on how it was 

 	started. Together with the FocusChanged() function, this allows an animation 

 	to always know its focus state.

 	@param aArgs Packaged arguments which may be required during construction. 

 	These are transferred from the aParams argument of the client side constructor's 

 	RAnim::Construct().

 	@param aHasFocus Specifies whether or not the animation has window server focus. */

 	virtual void ConstructL(TAny *aArgs, TBool aHasFocus)=0;

 	/** Redraws the objects.

 	The function is called by the window server when it needs to redraw the object. 

 	The object must provide all the low level drawing code. */

 	virtual void Redraw()=0;

 	/** Notifies change of focus.

 	The function is called by the window server to notify a change of focus, 

 	allowing the animation code to track whether it does or does not have focus, 

 	and to change its appearance accordingly.

 	@param aState Indicates whether the focus has or has not changed. */

 	virtual void FocusChanged(TBool aState)=0;

 protected:

 	/** Protected constructor.

 	Prevents objects of this class being directly constructed. */

 	inline CWindowAnim() {}

 private:

 	virtual void ReservedW1() const {};

 	virtual void ReservedW2() const {};

 protected:

 	/** Pointer to a class containing functions implemented by the window server.

 	These are available to any CWindowAnim-derived class.

 	Note that this and the iGc pointer are automatically set for you by the 

 	animation framework - you do not need to assign a value to them.*/

 	MAnimWindowFunctions *iWindowFunctions;

 	/** Pointer to the graphics context. */

 	CAnimGc *iGc;

 	friend class CWsAnim;

 	};

 class CFreeTimerWindowAnim : public CWindowAnim

 /** Free timer animation interface.

 This interface allows animations to have their own timers or other active 

 objects, and to draw to the window when the timer completes. The implication 

 of this is that animations derived from this class can have an extremely short 

 user-defined time between calls to the Animate() function, unlike the 

 other animation classes, which are tied to the (approximately) half second 

 flash cycle.

 The interface inherits from CWindowAnim and has access to its functions. It 

 additionally can access functions declared in the MAnimFreeTimerWindowFunctions 

 interface, using WindowFunctions(). 

 In order to draw to the window inside the RunL() of your own timer, you will 

 need call the ActivateGc() function before doing any drawing, and the DeactivateGc() 

 function after finishing the drawing.

 @publishedAll 

 @released 

 @see CSpriteAnim */

 	{

 protected:

 	inline MAnimFreeTimerWindowFunctions* WindowFunctions()

 	/** Gets the free timer utility functions.

 	These functions include all the MAnimWindowFunctions, 

 	and additional functions to deactivate the graphics context and to force the 

 	screen to update.

 	@return A pointer to the free timer utility functions. */

 		{return STATIC_CAST(MAnimFreeTimerWindowFunctions*,iWindowFunctions);}

 private:

 	virtual void ReservedF1() const {};

 	};

 class CSpriteAnim : public CAnim

 /** Sprite animation interface.

 Sprites are bitmaps that can overlay a window or the screen. A sprite animation 

 can be provided by deriving from this class.

 The interface inherits from CAnim and has access to its functions. It additionally 

 can access an interface for querying and manipulating a sprite, using its 

 iSpriteFunctions member. 

 The derived class is constructed in the DLL factory class CAnimDll::CreateInstanceL() 

 function.

 @publishedAll 

 @released 

 @see CFreeTimerWindowAnim

 @see CWindowAnim */

 	{

 public:

 	/** Server side construction and initialisation of an animation class. 

 	@param aArgs Packaged arguments which may be required during construction. 

 	These are transferred from the aParams argument of the client side constructor's 

 	RAnim::Construct(). */

 	virtual void ConstructL(TAny *aArgs)=0;

 protected:

 	inline CSpriteAnim() 

 	/** Protected constructor.

 	Ensures that only derived classes can be constructed. */

 		{}

 private:

 	virtual void ReservedS1() const {};

 	virtual void ReservedS2() const {};

 protected:

 	/** Pointer to a class containing functions implemented by the window server.

 	These are available to any CSpriteAnim-derived class.

 	Note that this value is automatically set for you by the animation framework. 

 	You do not need to assign a value to this pointer. */

 	MAnimSpriteFunctions *iSpriteFunctions;

 	friend class CWsAnim;

 	};

 class CAnimDll : public CBase

 /** Animation DLL factory interface. 

 An animation DLL class must be a derived class of CAnimDll, and can be thought 

 of as a server side factory class. CAnimDll consists of a single pure virtual 

 factory function, CreateInstanceL(TInt aType), which is used to create new 

 instances of animation objects of type CAnim contained in the DLL. Animation 

 DLL objects are created by the CreateCAnimDllL() function, which is called 

 by the window server at the request of the client.

 For efficiency reasons, it makes sense to collect multiple animation classes 

 into a single DLL, even if they are otherwise logically quite separate classes. 

 @publishedAll 

 @released */

 	{

 public:

 	/** Factory function for animation DLLs.

 	It must be provided in the derived class.

 	The parameter can be used to differentiate between multiple animation 

 	classes contained in the same animation DLL.

 	@param aType Identifies an animation class to be constructed. This is the 

 	same value as the aType argument of the client side animation constructor 

 	RAnim::Construct(). It is passed from the client side by the animation framework.

 	@return Pointer to a CAnim-derived animation class object. */

 	virtual CAnim *CreateInstanceL(TInt aType)=0;

 	};

 #endif