diff -r 666f914201fb -r 2fe1408b6811 epoc32/include/w32adll.h
--- a/epoc32/include/w32adll.h	Tue Nov 24 13:55:44 2009 +0000
+++ b/epoc32/include/w32adll.h	Tue Mar 16 16:12:26 2010 +0000
@@ -1,1 +1,1086 @@
-w32adll.h
+// 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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
+// which accompanies this distribution, and is available
+// at the URL "http://www.symbianfoundation.org/legal/licencesv10.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;
+	virtual void ReplyBuf(const TDesC8 &aDes)=0;				// Reply a buffer to the client
+	virtual void ReplyBuf(const TDesC16 &aDes)=0;				// Reply a buffer to the client
+	/** 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().
+	
+	@param aGetEvents If ETrue, raw events are passed to the animation 
+	event handling code. If EFalse, events are not passed to the animation. */
+	virtual void GetRawEvents(TBool aGetEvents) const=0;
+	/** Posts a raw event, just as if it had come from the kernel.
+	
+	@param aRawEvent The raw event */
+	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 is to 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.
+	
+	@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.
+
+	WSERV1:	
+
+	The updates a sprite on the screen, possibly after the bitmap for a particular 
+	sprite member has been changed.
+	
+	Two types of redraw are possible. A full update takes the bitmap off the screen 
+	and then re-draws it. This is 'safe' in that the screen always reflects 
+	the contents of the sprite bitmap. However it can result in flicker. 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 is required if you have 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 is possible. Otherwise the aFullUpdate argument is ignored and a full 
+	update is always done.
+	
+	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 ETrue for a full update, EFalse otherwise.
+
+	WSERV2:
+
+	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 newer 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