williamr@2: // Copyright (c) 1995-2009 Nokia Corporation and/or its subsidiary(-ies).
williamr@2: // All rights reserved.
williamr@2: // This component and the accompanying materials are made available
williamr@4: // under the terms of "Eclipse Public License v1.0"
williamr@2: // which accompanies this distribution, and is available
williamr@4: // at the URL "http://www.eclipse.org/legal/epl-v10.html".
williamr@2: //
williamr@2: // Initial Contributors:
williamr@2: // Nokia Corporation - initial contribution.
williamr@2: //
williamr@2: // Contributors:
williamr@2: //
williamr@2: // Description:
williamr@2: // Header for writing animated DLL add ons
williamr@2: // 
williamr@2: //
williamr@2: 
williamr@2: #if !defined(__W32ADLL_H__)
williamr@2: #define __W32ADLL_H__
williamr@2: 
williamr@2: #if !defined(__W32STD_H__)
williamr@2: #include <w32std.h>
williamr@2: #endif
williamr@2: 
williamr@2: #if !defined(__BITSTD_H__)
williamr@2: #include <bitstd.h>
williamr@2: #endif
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @deprecated
williamr@2: */
williamr@2: const TUint KWservAnimDllUidValue8=268435858;
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @deprecated
williamr@2: */
williamr@2: const TUid KWservAnimDllUid8={KWservAnimDllUidValue8};
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: const TUint KWservAnimDllUidValue16=268450594;
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: const TUid KWservAnimDllUid16={KWservAnimDllUidValue16};
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: const TUint KWservAnimDllUidValue=KWservAnimDllUidValue16;
williamr@2: 
williamr@2: /**
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: const TUid KWservAnimDllUid={KWservAnimDllUidValue};
williamr@2: 
williamr@2: //
williamr@2: // Contains functions callable from animated DLLs
williamr@2: //
williamr@2: 
williamr@2: 
williamr@2: class TWindowInfo
williamr@2: /** Animation window information.
williamr@2: 
williamr@2: Stores the window position and display mode for the animation.
williamr@2: During a redraw of the animation window, the redraw regions
williamr@2: can be retrieved by calling GetRedrawRegionAndRedrawShadowRegion().
williamr@2: 
williamr@2: @publishedAll 
williamr@2: @released
williamr@2: @see TWindowInfo::GetRedrawRegionAndRedrawShadowRegion() */
williamr@2: 	{
williamr@2: public:
williamr@2: 	/** The screen position. */
williamr@2: 	TRect iScreenPos;
williamr@2: 	/** The display mode.
williamr@2: 	
williamr@2: 	This is the minimum display mode that the screen has to be in to display this window. */
williamr@2: 	TDisplayMode iMode;
williamr@2: public:
williamr@2: 	/** Constructs an animation window information object. */
williamr@2: 	inline TWindowInfo() : iRegionPair(NULL) {}
williamr@2: public:
williamr@2: 	/** Stores a pair of region pointers. */
williamr@2: 	struct TRegionPair
williamr@2: 		{
williamr@2: 		const TRegion* iRegion1;
williamr@2: 		const TRegion* iRegion2;
williamr@2: 		};
williamr@2: 	/** Returns the current redraw region and redraw shadow region.
williamr@2: 	This function must only be called from an override of CWindowAnim's pure virtual Redraw function.
williamr@2: 	The region pointers retrieved must not be used beyond the end of the Redraw override.
williamr@2: 	@param aRedrawRegion The redraw region in screen coordinates.
williamr@2: 	@param aRedrawShadowRegion The redraw shadow region in screen coordinates. */
williamr@2: 	inline void GetRedrawRegionAndRedrawShadowRegion(const TRegion*& aRedrawRegion, const TRegion*& aRedrawShadowRegion) const
williamr@2: 		{
williamr@2: 		if (iRegionPair)
williamr@2: 			{
williamr@2: 			aRedrawRegion=iRegionPair->iRegion1;
williamr@2: 			aRedrawShadowRegion=iRegionPair->iRegion2;
williamr@2: 			iRegionPair=NULL;
williamr@2: 			}
williamr@2: 		else
williamr@2: 			{
williamr@2: 			aRedrawRegion=NULL;
williamr@2: 			aRedrawShadowRegion=NULL;
williamr@2: 			}
williamr@2: 		}
williamr@2: private:
williamr@2: 	mutable const TRegionPair* iRegionPair;
williamr@2: 	TAny *iFree2;
williamr@2: 	friend class CWsAnim;
williamr@2: 	};
williamr@2: 
williamr@2: 
williamr@2: class MEventHandler
williamr@2: /** Event handler interface.
williamr@2: 
williamr@2: The interface provides a function to handle raw events, e.g. key presses, 
williamr@2: pen events, power buttons etc. Raw events are passed to the OfferRawEvent() 
williamr@2: function when the MAnimGeneralFunctions::GetRawEvents() function has been 
williamr@2: called.
williamr@2: 
williamr@2: @publishedAll
williamr@2: @released */
williamr@2: 	{
williamr@2: public:
williamr@2: 	/** Handles raw events. 
williamr@2: 	
williamr@2: 	If the incoming event can be handled, the function should 
williamr@2: 	process it and then return true. If it cannot be processed the function should 
williamr@2: 	return false, and the event will be passed to other event handling code.
williamr@2: 	
williamr@2: 	This function must be implemented in every animation DLL. If event 
williamr@2: 	handling is not required, the function should simply return false.
williamr@2: 	
williamr@2: 	@param aRawEvent The raw event to be processed
williamr@2: 	@return ETrue if the raw event is handled by this function, EFalse if the function 
williamr@2: 	chooses not to process it. */
williamr@2: 	virtual TBool OfferRawEvent(const TRawEvent &aRawEvent)=0;
williamr@2: 	};
williamr@2: 
williamr@2: enum TAnimNotifications
williamr@2: /** Bit flags to be used by anims when registering for notifications */
williamr@2: 	{
williamr@2: 	/** Notify when direct screen access begins or ends.*/
williamr@2: 	EDirectScreenAccess = 0x0001,
williamr@2: 	/** Notify when the wserv heartbeat timer starts or stops. */
williamr@2: 	EHeartbeatTimer	= 0x0002,
williamr@2: 	/** Notify when screen device changes.*/
williamr@2: 	EScreenDeviceChange = 0x0004
williamr@2: 	};
williamr@2: //Forward Declaration.
williamr@2: class MAnimGeneralFunctionsWindowExtension;    
williamr@2: class MAnimGeneralFunctionsEventExtension ;
williamr@2: 
williamr@2: class MAnimGeneralFunctions
williamr@2: /** General animation utility functions interface. 
williamr@2: 
williamr@2: The interface provides functions to set the animation timing, 
williamr@2: event functions, and other general functions.
williamr@2: 
williamr@2: You do not have to create an object of this type. The class is implemented 
williamr@2: by the window server and provides utility functions to all CAnim-derived 
williamr@2: classes via the CAnim::iFunctions pointer.
williamr@2: 
williamr@2: It is not intended for user derivation.
williamr@2: 
williamr@2: @publishedAll
williamr@2: @released */
williamr@2: 	{
williamr@2: public:
williamr@2: 	/** Animation synchronisation flags. 
williamr@2: 	
williamr@2: 	The animation can be synchronised to any of these values; 
williamr@2: 	the Animate() call will take place at the start of the new unit (day, hour, etc...). */
williamr@2: 	enum TAnimSync
williamr@2: 		{
williamr@2: 		/** Not synchronised. Animate() is called after some number of flash cycles - 
williamr@2: 		set by SetSync(). */
williamr@2: 		ESyncNone,
williamr@2: 		/** Animate() every flash tick. This occurs twice a second, on the second and after 
williamr@2: 		7/12ths of a second, e.g. the function is called in a flash-on (7/12 seconds) - 
williamr@2: 		flash-off (5/12 seconds) cycle. */
williamr@2: 		ESyncFlash,
williamr@2: 		/** Animate() called as soon after every second as system activity allows. */
williamr@2: 		ESyncSecond,
williamr@2: 		/** Animate() called as soon after every minute as system activity allows. */
williamr@2: 		ESyncMinute,
williamr@2: 		/** Animate() called as soon after midnight every day as system activity allows. */
williamr@2: 		ESyncDay,
williamr@2: 		};
williamr@2: 	enum
williamr@2: 		{
williamr@2: 		ENumberOfExtendedInterfaces=0,
williamr@2: 		EWindowExtensionInterface,
williamr@2: 		EEventExtentionInterface,
williamr@2: 		EInterfaceCount, // Always keep at the end.
williamr@2: 		};
williamr@2: 	//Timing functions
williamr@2: 	/** Calls the DLL's Animate() function then deactivates the graphics context. 
williamr@2: 	
williamr@2: 	This allows users to do drawing from their own active object.
williamr@2: 	
williamr@2: 	Note:
williamr@2: 	
williamr@2: 	If the user calls the CAnim-derived classes' Animate() function directly, 
williamr@2: 	or otherwise does drawing from their own active object, then this will not 
williamr@2: 	deactivate the graphics context. This causes the window server to panic the 
williamr@2: 	client.
williamr@2: 	
williamr@2: 	Alternatively, use CFreeTimerWindowAnim, which allows you to deactivate the 
williamr@2: 	graphics context yourself.
williamr@2: 	
williamr@2: 	@param aDateTime The parameter passed into the animation DLL's Animate() 
williamr@2: 	function. */
williamr@2: 	virtual void Animate(TDateTime *aDateTime)=0;
williamr@2: 	/** Sets the synchronisation mode. 
williamr@2: 	
williamr@2: 	This determines the time intervals between calls to the Animate() function.
williamr@2: 	
williamr@2: 	@param aSyncMode The synchronisation mode. */
williamr@2: 	virtual void SetSync(TAnimSync aSyncMode)=0;
williamr@2: 	/** Sets the repeat interval. 
williamr@2: 	
williamr@2: 	If the synchronisation mode is TAnimSync::ESyncNone, then the Animate() function 
williamr@2: 	is called at intervals defined by some number of flash ticks. There are two 
williamr@2: 	flash ticks a second, with a 7/12 second - 5/12 second cycle. If the function 
williamr@2: 	is called when the synchronisation mode is not TAnimSync::ESyncNone, then 
williamr@2: 	the window server panics the client.
williamr@2: 	
williamr@2: 	If the new interval is greater than the current countdown, then the call does 
williamr@2: 	not affect the current countdown. For example, if the countdown has 10 flash 
williamr@2: 	ticks remaining, and the interval is set to 20, the new interval does not 
williamr@2: 	apply until the current countdown is complete. 
williamr@2: 	
williamr@2: 	However if the new interval is less the current countdown, then the new interval 
williamr@2: 	applies immediately i.e. the countdown is reset to the interval value.
williamr@2: 	
williamr@2: 	If the interval is set to zero the countdown stops, and the Animate() function 
williamr@2: 	is no longer called.
williamr@2: 	
williamr@2: 	@param aInterval The number of flash ticks between calls to the Animate() 
williamr@2: 	function. */
williamr@2: 	virtual void SetInterval(TInt aInterval)=0;
williamr@2: 	/** Sets the next interval. 
williamr@2: 	
williamr@2: 	This function immediately resets the current countdown to the specified number 
williamr@2: 	of flash ticks, irrespective of its current value. After the countdown expires, 
williamr@2: 	the interval returns to its usual rate. Note that this may be zero (i.e. 
williamr@2: 	not at all).
williamr@2: 	
williamr@2: 	To call this function, the synchronisation mode must be TAnimSync::ESyncNone, 
williamr@2: 	otherwise the window server panics the client.
williamr@2: 	
williamr@2: 	Note: there are two flash ticks a second, with a 7/12 second - 5/12 second cycle.
williamr@2: 	
williamr@2: 	@param aInterval The interval to the next Animate(). If the value is less 
williamr@2: 	than 1, it automatically gets set to 1.
williamr@2: 	@see SetInterval() */
williamr@2: 	virtual void SetNextInterval(TInt aInterval)=0;
williamr@2: 	/** Gets the system time as it was when Animate() was last called.
williamr@2: 	
williamr@2: 	@return The system time when Animate() was last called. */
williamr@2: 	virtual TDateTime SystemTime() const=0;
williamr@2: 	/** Tests the flash cycle state. 
williamr@2: 	
williamr@2: 	The flash cycle has 2 states: on (7/12 second) or off (5/12 second).
williamr@2: 	
williamr@2: 	@return ETrue if in the on part of the flash cycle, otherwise EFalse. */
williamr@2: 	virtual TBool FlashStateOn() const=0;
williamr@2: 	/** Gets the current synchronisation mode.
williamr@2: 	
williamr@2: 	@return The current sync mode. */
williamr@2: 	virtual TAnimSync Sync() const=0;
williamr@2: 	//Other functions generally useful
williamr@2: 	/** Gets a pointer to the screen device. 
williamr@2: 	
williamr@2: 	For example, this might be used to gain access to twips to pixel conversion functions.
williamr@2: 	
williamr@2: 	@return A pointer to the screen device. */
williamr@2: 	virtual const CFbsScreenDevice *ScreenDevice()=0;
williamr@2: 	/** Creates and duplicates a bitmap from a handle. 
williamr@2: 	
williamr@2: 	This function might be used to duplicate client side bitmaps on the server side.
williamr@2: 	
williamr@2: 	@param aHandle A handle to the bitmap to be duplicated.
williamr@2: 	@return A pointer to the duplicate bitmap. */
williamr@2: 	virtual CFbsBitmap *DuplicateBitmapL(TInt aHandle)=0;
williamr@2: 	/** Creates and duplicates a font from a handle.
williamr@2: 	
williamr@2: 	This function might be used to duplicate client side fonts on the server side.
williamr@2: 	
williamr@2: 	@param aHandle A handle to the font to be duplicated.
williamr@2: 	@return A pointer to the duplicate font. */
williamr@2: 	virtual CFbsFont *DuplicateFontL(TInt aHandle)=0;
williamr@2: 	/** Closes a duplicate font.
williamr@2: 	
williamr@2: 	@param Pointer to the duplicate font.
williamr@2: 	@see DuplicateFontL() */
williamr@2: 	virtual void CloseFont(CFbsFont *)=0;
williamr@2: 	/** Gets a reference to the calling client's thread.
williamr@2: 	
williamr@2: 	@return A reference to the calling client's thread. */
williamr@2: 	virtual const RThread &Client()=0;
williamr@4: 	/** Send a reply to the client process in response to a request
williamr@4: 	from the client. 	
williamr@4: 	
williamr@4: 	@see RAnim::CommandReply()
williamr@4: 	
williamr@4: 	@param aDes The data to be sent back to the client
williamr@4: 	 */
williamr@4: 	virtual void ReplyBuf(const TDesC8 &aDes)=0;
williamr@4: 	/** Send a reply to the client process in response to a request
williamr@4: 	from the client. 	
williamr@4: 	
williamr@4: 	@see RAnim::CommandReply()
williamr@4: 	
williamr@4: 	@param aDes The data to be sent back to the client
williamr@4: 	 */
williamr@4: 	virtual void ReplyBuf(const TDesC16 &aDes)=0;				
williamr@2: 	/** Panics the client. 
williamr@2: 	
williamr@2: 	This will result in the client thread being destroyed. */
williamr@2: 	virtual void Panic() const=0;
williamr@4: 	
williamr@2: 	//Event functions
williamr@4: 	
williamr@2: 	/** Switches animation raw event handling on and off.
williamr@2: 	
williamr@2: 	If raw event handling is switched on, then raw events, e.g. pointer, key, or power events
williamr@2: 	are all offered to the animation event handling code's MEventHandler::OfferRawEvent().
williamr@2: 	
williamr@4: 	If Animation works in a window for which advanced pointers have been enabled,
williamr@4: 	then after switching on raw event handling it will receive pointer events from all 
williamr@4: 	detected pointers. Otherwise it will receive events only from one emulated pointer.
williamr@4: 	
williamr@2: 	@param aGetEvents If ETrue, raw events are passed to the animation 
williamr@4: 	event handling code. If EFalse, events are not passed to the animation. 
williamr@4: 	@see RWindowBase::EnableAdvancedPointers() */
williamr@2: 	virtual void GetRawEvents(TBool aGetEvents) const=0;
williamr@2: 	/** Posts a raw event, just as if it had come from the kernel.
williamr@4: 	  
williamr@4: 	If aRawEvent has pointer-related type (move, switch on, down, up or out of range),
williamr@4: 	then its Z coordinate and iPointerNumber fields will be validated and may be
williamr@4: 	overwritten by WSERV in order to guarantee correct behaviour depending on:
williamr@4: 	1. Pointer Pressure and Proximity support on current platform.
williamr@4: 	2. Multiple pointers support on current platform.
williamr@4: 	3. Animation's awareness of these fields. If Animation works in a window
williamr@4: 	   for which advanced pointers have been enabled, it is assumed that it has
williamr@4: 	   initialized these fields. Otherwise WSERV will assume that these fields have
williamr@4: 	   not been provided and may overwrite them with most appropriate values.
williamr@4: 	For more information about event validation, please refer to System Documentation.
williamr@2: 	
williamr@4: 	@param aRawEvent The raw event 
williamr@4: 	@see RWindowBase::EnableAdvancedPointers() */
williamr@2: 	virtual void PostRawEvent(const TRawEvent &aRawEvent) const=0;
williamr@2: 	/** Posts a key event.
williamr@2: 	
williamr@2: 	The function is similar to PostRawEvent() but should be 
williamr@2: 	used for posting key events. 
williamr@2: 	
williamr@2: 	@param aRawEvent The key event. */
williamr@2: 	virtual void PostKeyEvent(const TKeyEvent &aRawEvent) const=0;
williamr@2: 	/** Get the address of an object which can retrieve information from and send
williamr@2: 	information to the client-side.
williamr@2: 
williamr@2: 	@return A pointer to RMessagePtr2. Complete must be called on the returned object (or a 
williamr@2: 	copy of it) if and only if Message is called from an override of CAnim's CommandReplyL which 
williamr@2: 	has been caused by a client-side RAnim::AsyncCommandReply call. If Message is called outside 
williamr@2: 	an override of CAnim's CommandReplyL or outside an override of CWindowAnim's ConstructL or 
williamr@2: 	CSpriteAnim's ConstructL, the it returns NULL. 
williamr@2: 	@see RMessagePtr2 */
williamr@2: 	virtual const RMessagePtr2* Message()=0; // replaces Reserved1
williamr@2: 	/**Returns an extension interface, maybe extended further in the future.
williamr@2: 	@param aInterfaceId The ID of the interface to return.
williamr@2: 	@return A pointer to the extension interface.
williamr@2: 	When aInterface=0 (ENumberOfExtendedInterfaces), the number of interfaces is returned (currently 2).
williamr@2: 	When aInterface=1 (EWindowExtensionInterface), a pointer to the Window Extension interface is returned.
williamr@2: 	When aInterface=2 (EEventExtentionInterface), a pointer to the Event Extension interface is returned.
williamr@2: 	*/
williamr@2: 	virtual TAny* ExtendedInterface(TInt aInterface)=0; // replaces Reserved2
williamr@2: 
williamr@2: 	/** Register to receive notifications.
williamr@2: 	@param aNotifications A bitset of TAnimNotifications values indicating which notifications are required
williamr@2: 	@return One of the system wide error codes
williamr@2: 	*/
williamr@2: 	virtual TInt RegisterForNotifications(TUint32 aNotifications)=0;
williamr@2: 	/*
williamr@2: 	Return number of ExtendedInterfaces. */
williamr@2: 	inline TInt NumberOfExtendedInterfaces()
williamr@2: 		{
williamr@2: 		return reinterpret_cast<TInt>(ExtendedInterface(ENumberOfExtendedInterfaces));
williamr@2: 		}
williamr@2: 	/** Gets access to Window Extension utility functions.
williamr@2: 	@return A pointer to a class containing functions for working with Window. */
williamr@2: 	inline MAnimGeneralFunctionsWindowExtension* WindowExtension()
williamr@2: 		{
williamr@2: 		return static_cast<MAnimGeneralFunctionsWindowExtension*>(ExtendedInterface(EWindowExtensionInterface));
williamr@2: 		}
williamr@2: 	/** Gets access to EventExtension utility functions. 
williamr@2: 	@return A pointer to a class containing functions for working with Event. */
williamr@2: 	inline MAnimGeneralFunctionsEventExtension* EventExtension()
williamr@2: 		{
williamr@2: 		return static_cast<MAnimGeneralFunctionsEventExtension*>(ExtendedInterface(EEventExtentionInterface));
williamr@2: 		}
williamr@2: 	private:
williamr@2: 	virtual void Reserved1() const;
williamr@2: 	virtual void Reserved2() const;
williamr@2: 	virtual void Reserved3() const;
williamr@2: 	};
williamr@2: 
williamr@2: /* Structure for passing window configuration information. Currently transparancey
williamr@2: related configuration information is supported, though this may be added to, as
williamr@2: apprioriate.
williamr@2: 
williamr@2: @publishedAll
williamr@2: @released
williamr@2: */
williamr@2: class TWindowConfig
williamr@2: 	{
williamr@2: public:
williamr@2: 	/** Transparency flags. 
williamr@2: 	
williamr@2: 	Used to represent transparency configuration of the window. */
williamr@2: 	enum
williamr@2: 		{
williamr@2: 		/** Transparency is enabled on the window. */
williamr@2: 		ETransparencyEnabled=0x0001,
williamr@2: 		/** Window transparency uses alpha blending channel. */
williamr@2: 		EAlphaBlendedTransparency=0x0002,
williamr@2: 		};
williamr@2: public:
williamr@2: 	/** Indicate configuration of window, using enumerations defined within this class. */
williamr@2: 	TInt iFlags;
williamr@2: private:
williamr@2: 	TInt iReserved0;
williamr@2: 	TInt iReserved1;
williamr@2: 	TInt iReserved2;
williamr@2: 	};
williamr@2: 	
williamr@2: class MAnimGeneralFunctionsWindowExtension
williamr@2: /** General Window utility functions interface. 
williamr@2: 
williamr@2: The member functions define the interface for querying and manipulating 
williamr@2: the window and screen attributes.
williamr@2: 
williamr@2: You obtain one by calling: iFunctions->ExtendedInterface(MAnimGeneralFunctions::EWindowExtensionInterface) 
williamr@2: and casting the result.
williamr@2: 
williamr@2: It is not intended for user derivation.
williamr@2: 
williamr@2: @publishedAll 
williamr@2: @released */
williamr@2: 	{
williamr@2: public:
williamr@2: 	/** Class contains the information pertaining to a window group: name, priority, 
williamr@2: 	focusability. */
williamr@2: 	class TWindowGroupInfo
williamr@2: 		{
williamr@2: 	public:
williamr@2: 		enum
williamr@2: 			{
williamr@2: 			/** Window is focusable flag. */
williamr@2: 			EIsFocusable=0x0001,
williamr@2: 			};
williamr@2: 	public:
williamr@2: 		/** Returns whether or not the window is focusable. 
williamr@2: 		@return ETrue if focusable, else returns EFalse. */
williamr@2: 		inline TBool IsFocusable() const {return iFlags&EIsFocusable;}
williamr@2: 	public:
williamr@2: 	/* Window group attributes. */
williamr@2: 		TInt iId;
williamr@2: 		TUint32 iFlags;
williamr@2: 		TInt iOrdinalPriority;
williamr@2: 		TInt iNameLength;
williamr@2: 		TInt iParentId;
williamr@2: 		};
williamr@2: public:
williamr@2: 	/** Returns the total number of screens.
williamr@2: 	@return The total number of screens. */
williamr@2: 	virtual TInt Screens() const=0;
williamr@2: 
williamr@2: 	/** Returns the number of the screen which is currently in focus.
williamr@2: 	@return The number of the screen which is currently in focus.*/
williamr@2: 	virtual TInt FocusScreens() const=0;
williamr@2: 
williamr@2: 	/** Changes the focused screen.
williamr@2: 	@param aScreenNo New screen number. */
williamr@2: 	virtual void SetFocusScreen(TInt aScreenNo)=0;
williamr@2: 
williamr@2: 	/** Returns the number of window groups available for the specified screen.
williamr@2: 
williamr@2: 	@param aScreen The screen number.
williamr@2: 	@return The number of window groups. */
williamr@2: 	virtual TInt WindowGroups(TInt aScreen) const=0;
williamr@2: 	
williamr@2: 	/** Takes a screen number and an ordinal position and returns the complete window 
williamr@2: 	group information of the specified window. If the window group does not exist, the 
williamr@2: 	function returns EFalse.
williamr@2: 	
williamr@2: 	Note: the ordinal position specified should be the total or full ordinal position 
williamr@2: 	of all group windows of all priorities on that screen.
williamr@2: 
williamr@2: 	@param aInfo on return, complete window information.
williamr@2: 	@param aScreen Screen number.
williamr@2: 	@param aFullOrdinalPosition Ordinal position of the window.
williamr@2: 	@return ETrue if window group information exists, EFalse otherwise.  */
williamr@2: 	virtual TBool WindowGroupInfo(TWindowGroupInfo& aInfo,TInt aScreen,TInt aFullOrdinalPosition) const=0;
williamr@2: 
williamr@2: 	/** Takes a screen number and an ordinal position and returns the window group name.
williamr@2: 	If the window group does not exist, the function returns false.
williamr@2: 
williamr@2: 	Note: the ordinal position specified should be the total or full ordinal position of 
williamr@2: 	all group windows of all priorities on that screen.
williamr@2: 
williamr@2: 	Note: if the name does not fit into the descriptor provided then it will be truncated.
williamr@2: 
williamr@2: 	@param aWindowName On return, the window group name.
williamr@2: 	@param aScreen The screen number.
williamr@2: 	@param aFullOrdinalPosition The ordinal position of the window.
williamr@2: 	@return ETrue if the window group name exists, EFalse otherwise. */
williamr@2: 	virtual TBool WindowGroupName(TPtrC& aWindowName,TInt aScreen,TInt aFullOrdinalPosition) const=0;
williamr@2: 	
williamr@2: 	/** Changes the ordinal position and priority of the window group with the specified ID.
williamr@2: 
williamr@2: 	@param aWindowGroupId The window group ID.
williamr@2: 	@param aPos The ordinal position to move the window to.
williamr@2: 	@param aOrdinalPriority The new ordinal priority of the window.
williamr@2: 	@return KErrNotFound if there is no window group with the specified ID, KErrNone otherwise. */
williamr@2: 	virtual TInt SetOrdinalPosition(TInt aWindowGroupId,TInt aPos,TInt aOrdinalPriority)=0;
williamr@4: 	
williamr@2: 	/** Accessor for window configuration.
williamr@2: 
williamr@2: 	@param aWindowConfig Gets filled in with window configuration details. */
williamr@2: 	virtual void WindowConfig(TWindowConfig& aWindowConfig) const=0;
williamr@2: private:
williamr@2: 	virtual void Reserved1() const;
williamr@2: 	virtual void Reserved2() const;
williamr@2: 	virtual void Reserved3() const;
williamr@2: 	};
williamr@2: 	
williamr@2: class MAnimGeneralFunctionsEventExtension
williamr@2: /** Event utility functions interface. 
williamr@2: 
williamr@2: The member functions define the interface for generate repeated key events .
williamr@2: 
williamr@2: It is not intended for user derivation.
williamr@2: */
williamr@2: 	{
williamr@2: public:
williamr@2: 	/** Posts a key event.
williamr@2: 	
williamr@2: 	The function is similar to PostKeyEvent() but should be 
williamr@2: used for posting repeated key events. 
williamr@2: 	
williamr@2: 	@param aRawEvent The key event.
williamr@2: 	@param aRepeats value */
williamr@2: 	virtual void PostKeyEvent(const TKeyEvent& aRawEvent, TInt aRepeats) const=0;
williamr@2: 
williamr@2: private:
williamr@2: 	virtual void Reserved1() const;
williamr@2: 	virtual void Reserved2() const;
williamr@2: 	};
williamr@2: 	
williamr@2: class MAnimWindowFunctions
williamr@2: /** Window utility functions interface. 
williamr@2: 
williamr@2: The member functions define the interface for querying and manipulating 
williamr@2: the window in which the animation takes place.
williamr@2: 
williamr@2: You do not have to create an object of this type. The class is implemented 
williamr@2: by the window server, and provides these utility functions to all CWindowAnim 
williamr@2: and CFreeTimerWindowAnim derived classes via the iWindowFunctions pointer.
williamr@2: 
williamr@2: It is not intended for user derivation.
williamr@2: 
williamr@2: @publishedAll 
williamr@2: @released */
williamr@2: 	{
williamr@2: public:
williamr@2: 	/** Activates the graphics context.
williamr@2: 	
williamr@2: 	This function should be called to enable drawing in the CAnim-derived classes'
williamr@2: 	Command(), CommandReplyL(), Animate(), or FocusChanged() functions.
williamr@2: 	
williamr@2: 	Note: this function is called automatically by the animation DLL framework in the 
williamr@2: 	Redraw() function. */
williamr@2: 	virtual void ActivateGc()=0;
williamr@4: 	/** Sets the rectangle that this animation will draw to. 
williamr@2: 	
williamr@2: 	This function must be called as part of the initialisation/construction of 
williamr@2: 	the CAnim-derived object, i.e. in CAnim::ConstructL(). This is so that the 
williamr@4: 	window server knows which area the animation is operating in. Anything that 
williamr@4: 	is drawn by the animation outside this rectangle may not be redrawn correctly
williamr@4: 	as the window server uses this rectangle to decide when the animation should
williamr@4: 	be redrawn.
williamr@2: 	
williamr@2: 	@param aRect The rectangle to be drawn to. */
williamr@2: 	virtual void SetRect(const TRect &aRect)=0;
williamr@2: 	/** Gets the window size.
williamr@2: 	
williamr@2: 	@return The window size, in pixels. */
williamr@2: 	virtual TSize WindowSize() const=0;
williamr@2: 	/** Tests whether to draw the animation. 
williamr@2: 	
williamr@2: 	If the window is completely hidden, there is normally no need to draw 
williamr@2: 	the animation. However in some conditions the animation should be drawn even 
williamr@2: 	if it is obscured. The window server is aware of these cases, and returns 
williamr@2: 	ETrue if it is not safe to draw the animation.
williamr@2: 	
williamr@2: 	@return True if the window is completely hidden and there is no requirement 
williamr@2: 	to continue drawing the animation, otherwise false. */
williamr@2: 	virtual TBool IsHidden()=0;
williamr@2: 	/** Sets the visibility of the window the animation is drawing to.
williamr@2: 	
williamr@2: 	This does the same as RWindowBase::SetVisible().
williamr@2: 	
williamr@2: 	@param aState True for visible, false otherwise. */
williamr@2: 	virtual void SetVisible(TBool aState)=0;
williamr@2: 	/** Forces a redraw of a rectangular part of the window.
williamr@2: 	
williamr@2: 	The function causes a redraw message on the part of the window specified, 
williamr@2: 	which provides a non-immediate way to do drawing.
williamr@2: 	
williamr@2: 	It can be used to redraw the whole of the window, not just the part used by 
williamr@2: 	the animation.
williamr@2: 	
williamr@2: 	@param aRect The rectangle to be redrawn. These co-ordinates are relative 
williamr@2: 	to the origin of the window. */
williamr@2: 	virtual void Invalidate(const TRect &aRect)=0;
williamr@2: 	/** Gets window information.
williamr@2: 	
williamr@2: 	@param aData The window information. */
williamr@2: 	virtual void Parameters(TWindowInfo &aData)=0;
williamr@2: 	/** Gets the visible region.
williamr@2: 
williamr@2: 	This region is the area of the visible window which 
williamr@2: 	is currently unshadowed. If there is not enough memory to calculate this region 
williamr@2: 	then aRegion's error flag is set.
williamr@2: 	
williamr@2: 	@param aRegion The visible region. */
williamr@2: 	virtual void VisibleRegion(TRegion& aRegion)=0;
williamr@2: 	//virtual void CopyScreen(CFbsBitGc *aBitmapGc,TRect aRect)=0;
williamr@2: private:
williamr@2: 	virtual void Reserved() const;
williamr@2: 	virtual void Reserved1() const;
williamr@2: 	virtual void Reserved2() const;
williamr@2: 	virtual void Reserved3() const;
williamr@2: 	};
williamr@2: 
williamr@2: 
williamr@2: class MAnimFreeTimerWindowFunctions : public MAnimWindowFunctions
williamr@2: /** Free timer animation utility functions interface.
williamr@2: 
williamr@2: The class inherits functions from MAnimWindowFunctions, and defines the additional 
williamr@2: interface required for window operations which support animations with their 
williamr@2: own timers.
williamr@2: 
williamr@2: You do NOT have to create an object of this type. The class is implemented 
williamr@2: by the window server, and provides utility functions to all CFreeTimerWindowAnim 
williamr@2: derived classes via the WindowFunctions() member. 
williamr@2: 
williamr@2: It is not intended for user derivation.
williamr@2: 
williamr@2: @publishedAll 
williamr@2: @released */
williamr@2: 	{
williamr@2: public:
williamr@2: 	/** Deactivates the graphics context. 
williamr@2: 	
williamr@2: 	This function is used in the context of a CFreeTimerWindowAnim derived class 
williamr@2: 	when writing animation DLLs with their own timer. Within the timer's RunL(), 
williamr@2: 	the ActivateGc() function should be called prior to drawing to the window. 
williamr@2: 	DeactivateGc() should be called after drawing is finished. */
williamr@2: 	virtual void DeactivateGc()=0;
williamr@2: 	/** Forces the screen to update. */
williamr@2: 	virtual void Update()=0;
williamr@2: private:
williamr@2: 	virtual void Reserved3() const;
williamr@2: 	};
williamr@2: 
williamr@2: class MAnimSpriteFunctions
williamr@2: /** Sprite animation utility functions interface.
williamr@2: 
williamr@2: The interface includes functions for querying and manipulating a sprite.
williamr@2: 
williamr@2: You do NOT have to create an object of this type. The class is implemented 
williamr@2: by the window server, and provides utility functions to all CSpriteAnim derived 
williamr@2: classes via the CSpriteAnim::iSpriteFunctions pointer. 
williamr@2: 
williamr@2: It is not intended for user derivation.
williamr@2: 
williamr@2: @publishedAll 
williamr@2: @released */
williamr@2: 	{
williamr@2: public:
williamr@2: 	/** Gets sprite member data.
williamr@2: 	
williamr@2: 	Each member of the sprite is effectively a bitmap, which is displayed for a 
williamr@2: 	different amount of time.
williamr@2: 	
williamr@2: 	@param aMember The index of the sprite member for which information is required.
williamr@2: 	@return A pointer to the sprite member. */
williamr@2: 	virtual TSpriteMember *GetSpriteMember(TInt aMember) const=0;
williamr@2: 	/** Redraws part of a sprite.
williamr@2: 	Updates a sprite on the screen, possibly after the bitmap for a particular 
williamr@2: 	sprite member has been changed.
williamr@2: 	
williamr@2: 	Use the	aRect parameter to specify the (small) part of the sprite which has been changed, 
williamr@2: 	then any flicker will only occur in this rectangle. 
williamr@2: 	
williamr@2: 	A full update used to be required if you had removed pixels from the mask, i.e. made 
williamr@2: 	pixels in the sprite transparent when they were not before. If drawing is 
williamr@2: 	additive, e.g. you are using a mask or the draw mode is EDrawModePEN, a partial 
williamr@4: 	update used to be possible. But current versions of the window-server always do full back to front rendering.
williamr@2: 	
williamr@2: 	Note: if the sprite member aMember is not visible then there is no need for a change 
williamr@2: 	to the display, so the aRect and aFullUpdate parameters are ignored.
williamr@2: 	
williamr@2: 	@param aMember The index of the sprite member that is to be updated.
williamr@2: 	@param aRect The part of the sprite member which has changed.
williamr@2: 	@param aFullUpdate	Not used. Wserv now always do full back to front rendering. */
williamr@2: 	virtual void UpdateMember(TInt aMember,const TRect& aRect,TBool aFullUpdate)=0;
williamr@2: 	/** Turns a sprite on or off.
williamr@2: 	
williamr@2: 	In effect this makes the sprite bitmap visible.
williamr@2: 	
williamr@2: 	@param aActive ETrue to turn sprite on. EFalse to turn it off. */
williamr@2: 	virtual void Activate(TBool aActive)=0;
williamr@2: 	/** Finishes constructing the sprite.
williamr@2: 	
williamr@2: 	It also sets the currently displayed sprite member to zero.
williamr@2: 	
williamr@2: 	This function must be called after members change size. */
williamr@2: 	virtual void SizeChangedL()=0;
williamr@2: 	/** Set the sprite's position.
williamr@2: 	
williamr@2: 	@param aPos The new position of the sprite. */
williamr@2: 	virtual void SetPosition(const TPoint &aPos)=0;
williamr@2: private:
williamr@2: 	virtual void Reserved() const;
williamr@2: public:
williamr@2: 	/** Returns the visibility of the sprite.
williamr@2: 	
williamr@2: 	A sprite can be seen if it is neither obscured by another window nor hidden.
williamr@2: 	
williamr@2: 	@return ETrue if the sprite can be seen, EFalse otherwise. */
williamr@2: 	virtual TBool SpriteCanBeSeen() const = 0;
williamr@2: private:
williamr@2: 	virtual void Reserved2() const;
williamr@2: 	virtual void Reserved3() const;
williamr@2: 	virtual void Reserved4() const;
williamr@2: 	};
williamr@2: 
williamr@2: 
williamr@2: class CAnimGc : public CBitmapContext
williamr@2: /** Animation graphics context. 
williamr@2: 
williamr@2: An object of this type is linked into CAnim by the window server, which allows 
williamr@2: you to draw to the animation window. The object's functions allow you to set 
williamr@2: and cancel the clipping region, and to draw to the visible window using 
williamr@2: the inherited CBitmapContext functions. 
williamr@2: 
williamr@2: @publishedAll
williamr@2: @released */
williamr@2: 	{
williamr@2: public:
williamr@2: 	/** Sets the clipping region.
williamr@2: 	
williamr@2: 	Only the parts of the animation which are within the clipping region are drawn.
williamr@2: 	
williamr@2: 	@param aRegion The clipping region. */
williamr@2: 	virtual TInt SetClippingRegion(const TRegion &aRegion)=0;
williamr@2: 	/** Cancels the clipping region.
williamr@2: 	
williamr@2: 	@see SetClippingRegion() */
williamr@2: 	virtual void CancelClippingRegion()=0;
williamr@2: 	};
williamr@2: 
williamr@2: class CWsAnim; // Forward ref for friend declaration
williamr@2: 
williamr@2: 
williamr@2: class CAnim : public CBase , public MEventHandler
williamr@2: /** Server side animated object base interface.
williamr@2: 
williamr@2: Animations implement this interface, which is called by the window server 
williamr@2: to pass commands from clients, perform a step in the animation, or to pass 
williamr@2: window server events (if required) so that the animation can handle them 
williamr@2: before the application.
williamr@2: 
williamr@2: The functions are all pure virtual, and must be implemented in 
williamr@2: the derived class to provide server side behaviour. The functions will be 
williamr@2: called by the window server with optional arguments passed in from the client 
williamr@2: side animation class RAnim.
williamr@2: 
williamr@2: You should derive from CWindowAnim, CFreeTimerWindowAnim or CSpriteAnim, 
williamr@2: depending on whether the animation is to draw to a sprite or a window,
williamr@2: rather than directly from this class.
williamr@2: 
williamr@2: The derived class is constructed in the DLL factory class CAnimDll::CreateInstanceL() 
williamr@2: function.
williamr@2: 
williamr@2: The operation to perform an animation step is called by the window server 
williamr@2: on a timer. The timing properties are set through an MAnimGeneralFunctions 
williamr@2: member, which also provides other utility functions. 
williamr@2: 
williamr@2: @publishedAll 
williamr@2: @released */
williamr@2: 	{
williamr@2: public:
williamr@2: 	/** Implements client-side initiated commands, returning a value. 
williamr@2: 	
williamr@2: 	The window server calls this function in response to application calls to 
williamr@2: 	the client side command function RAnim::CommandReplyL(). The arguments passed 
williamr@2: 	to the function by the window server are the same as were used on the client 
williamr@2: 	side function call.
williamr@2: 	
williamr@2: 	This function returns values to the client side, and should be used to return 
williamr@2: 	error codes for commands which might leave.
williamr@2: 	
williamr@2: 	@param aOpcode Opcode understood by the class.
williamr@2: 	@param aArgs Arguments packaged on the client side, for example as a struct 
williamr@2: 	of a type determined by the aOpcode argument. These mirror the aArgs argument 
williamr@2: 	passed in to RAnim::CommandReply().
williamr@2: 	@return Value passed back to client side function when this function completes. 
williamr@2: 	Typically this would be KErrNone or another of the system-wide error codes. 
williamr@2: 	However any value may be returned to the client side.
williamr@2: 	@see RAnim */
williamr@2: 	virtual TInt CommandReplyL(TInt aOpcode, TAny *aArgs)=0;
williamr@2: 	/** Implements client-side initiated commands. 
williamr@2: 	
williamr@2: 	The window server calls this function in response to application calls to 
williamr@2: 	the client side command function RAnim::Command(). The arguments passed to 
williamr@2: 	the function by the window server are the same as were used on the client 
williamr@2: 	side function call.
williamr@2: 	
williamr@2: 	Because this function does not return errors, it is not safe for commands 
williamr@2: 	which might leave.
williamr@2: 	
williamr@2: 	@param aOpcode Opcode understood by the class
williamr@2: 	@param aArgs Arguments packaged on the client side, for example as a struct 
williamr@2: 	of a type determined by the aOpcode argument. These mirror the aArgs argument 
williamr@2: 	passed in to RAnim::Command().
williamr@2: 	@see RAnim */
williamr@2: 	virtual void Command(TInt aOpcode, TAny *aArgs)=0;
williamr@2: 	/** Main animation function, called by the window server. 
williamr@2: 	
williamr@2: 	The drawing code which implements a given animation should be provided here.
williamr@2: 	
williamr@2: 	This function is called at a frequency determined by the SetSync() helper 
williamr@2: 	function. Note that if sync is not set, then this function will never be 
williamr@2: 	called. This effect can be exploited to use the animation framework, with 
williamr@2: 	its server side speed, for what are strictly not animations, e.g. for streaming 
williamr@2: 	video images.
williamr@2: 	
williamr@2: 	The aDateTime parameter will be null if the current time (as determined by 
williamr@2: 	the window server) matches the time implied by the sync period, modulo normalisation, 
williamr@2: 	otherwise it will contain a valid (non-normalised) time.
williamr@2: 	
williamr@2: 	Normalisation is to some specified granularity, for example if one minute 
williamr@2: 	is specified as the animation frequency, then in effect the window server 
williamr@2: 	will decide whether the implied time is correct to the minute, but not to 
williamr@2: 	the second.
williamr@2: 	
williamr@2: 	Implied time is the time implied by the (normalised) actual time of the previous 
williamr@2: 	animation call plus the sync interval. For example if the last call was at 
williamr@2: 	time 't' and the sync interval is 1 second then if the time at this call 
williamr@2: 	is t + 1 second, then actual time and implied time match and the value placed 
williamr@2: 	into aDateTime will be NULL.
williamr@2: 	
williamr@2: 	Cases in which the two may not match include, for example, system time having 
williamr@2: 	been reset between animation calls (perhaps British Summer Time or other daylight 
williamr@2: 	saving time has just come into effect). The intention is that when system 
williamr@2: 	time changes, a mechanism is provided to alert the animation code and allow 
williamr@2: 	it to reset itself. The assumption is that somewhere in its initialisation 
williamr@2: 	code, the animation will have performed a CAnimFunctions utility call to set 
williamr@2: 	a base time, which is then implicitly tracked by incrementing by a suitable 
williamr@2: 	interval; when aDateTime is non-NULL after a call to Animate(), base time 
williamr@2: 	should be reset.
williamr@2: 	
williamr@2: 	@param aDateTime Null if the current time w.r.t. the window server matches 
williamr@2: 	the time implied by the synch period. Otherwise a valid (non-normalised) time. */
williamr@2: 	virtual void Animate(TDateTime *aDateTime)=0;
williamr@2: 	virtual void HandleNotification(const TWsEvent& /*aEvent*/) {};
williamr@2: private:
williamr@2: 	inline CAnim() {}
williamr@2: 	virtual void Reserved1() const {};
williamr@2: 	virtual void Reserved2() const {};
williamr@2: 	virtual void Reserved3() const {};
williamr@2: protected:
williamr@2: 	/** Pointer to a class containing functions implemented by the window server. 
williamr@2: 	
williamr@2: 	These are available to any CAnim derived class.
williamr@2: 	
williamr@2: 	Note that this value is automatically set for you by the animation framework. 
williamr@2: 	You do not need to assign a value to this pointer. 
williamr@2: 	@publishedAll
williamr@2: 	@released	*/
williamr@2: 	MAnimGeneralFunctions *iFunctions;
williamr@2: 	friend class CWsAnim;
williamr@2: 	friend class CWindowAnim;
williamr@2: 	friend class CSpriteAnim;
williamr@2: 	};
williamr@2: 
williamr@2: 
williamr@2: class CWindowAnim : public CAnim
williamr@2: /** Window animation interface. 
williamr@2: 
williamr@2: This interface is provided to create animations other than sprites. A window 
williamr@2: animation can be provided by deriving from this class.
williamr@2: 
williamr@2: The interface inherits from CAnim and has access to its functions. It additionally 
williamr@2: can access an interface for querying and manipulating the window in which 
williamr@2: the animation takes place, using its iWindowFunctions member.
williamr@2: 
williamr@2: The derived class is constructed in the DLL factory class CAnimDll::CreateInstanceL().
williamr@2: 
williamr@2: @publishedAll
williamr@2: @released 
williamr@2: @see CFreeTimerWindowAnim
williamr@2: @see CSpriteAnim */
williamr@2: 	{
williamr@2: public:
williamr@2: 	/** Server side construction and initialisation of an animation class. 
williamr@2: 	
williamr@2: 	Note: the aHasFocus argument allows the animation to start in a known focus state. 
williamr@2: 	For example, an animation may or may not have focus, depending on how it was 
williamr@2: 	started. Together with the FocusChanged() function, this allows an animation 
williamr@2: 	to always know its focus state.
williamr@2: 	
williamr@2: 	@param aArgs Packaged arguments which may be required during construction. 
williamr@2: 	These are transferred from the aParams argument of the client side constructor's 
williamr@2: 	RAnim::Construct().
williamr@2: 	@param aHasFocus Specifies whether or not the animation has window server focus. */
williamr@2: 	virtual void ConstructL(TAny *aArgs, TBool aHasFocus)=0;
williamr@2: 	/** Redraws the objects.
williamr@2: 	
williamr@2: 	The function is called by the window server when it needs to redraw the object. 
williamr@2: 	The object must provide all the low level drawing code. */
williamr@2: 	virtual void Redraw()=0;
williamr@2: 	/** Notifies change of focus.
williamr@2: 	
williamr@2: 	The function is called by the window server to notify a change of focus, 
williamr@2: 	allowing the animation code to track whether it does or does not have focus, 
williamr@2: 	and to change its appearance accordingly.
williamr@2: 	
williamr@2: 	@param aState Indicates whether the focus has or has not changed. */
williamr@2: 	virtual void FocusChanged(TBool aState)=0;
williamr@2: protected:
williamr@2: 	/** Protected constructor.
williamr@2: 	
williamr@2: 	Prevents objects of this class being directly constructed. */
williamr@2: 	inline CWindowAnim() {}
williamr@2: private:
williamr@2: 	virtual void ReservedW1() const {};
williamr@2: 	virtual void ReservedW2() const {};
williamr@2: protected:
williamr@2: 	/** Pointer to a class containing functions implemented by the window server.
williamr@2: 	
williamr@2: 	These are available to any CWindowAnim-derived class.
williamr@2: 	
williamr@2: 	Note that this and the iGc pointer are automatically set for you by the 
williamr@2: 	animation framework - you do not need to assign a value to them.*/
williamr@2: 	MAnimWindowFunctions *iWindowFunctions;
williamr@2: 	/** Pointer to the graphics context. */
williamr@2: 	CAnimGc *iGc;
williamr@2: 	friend class CWsAnim;
williamr@2: 	};
williamr@2: 
williamr@2: 
williamr@2: class CFreeTimerWindowAnim : public CWindowAnim
williamr@2: /** Free timer animation interface.
williamr@2: 
williamr@2: This interface allows animations to have their own timers or other active 
williamr@2: objects, and to draw to the window when the timer completes. The implication 
williamr@2: of this is that animations derived from this class can have an extremely short 
williamr@2: user-defined time between calls to the Animate() function, unlike the 
williamr@2: other animation classes, which are tied to the (approximately) half second 
williamr@2: flash cycle.
williamr@2: 
williamr@2: The interface inherits from CWindowAnim and has access to its functions. It 
williamr@2: additionally can access functions declared in the MAnimFreeTimerWindowFunctions 
williamr@2: interface, using WindowFunctions(). 
williamr@2: 
williamr@2: In order to draw to the window inside the RunL() of your own timer, you will 
williamr@2: need call the ActivateGc() function before doing any drawing, and the DeactivateGc() 
williamr@2: function after finishing the drawing.
williamr@2: 
williamr@2: @publishedAll 
williamr@2: @released 
williamr@2: @see CSpriteAnim */
williamr@2: 	{
williamr@2: protected:
williamr@2: 	inline MAnimFreeTimerWindowFunctions* WindowFunctions()
williamr@2: 	/** Gets the free timer utility functions.
williamr@2: 	
williamr@2: 	These functions include all the MAnimWindowFunctions, 
williamr@2: 	and additional functions to deactivate the graphics context and to force the 
williamr@2: 	screen to update.
williamr@2: 	
williamr@2: 	@return A pointer to the free timer utility functions. */
williamr@2: 		{return STATIC_CAST(MAnimFreeTimerWindowFunctions*,iWindowFunctions);}
williamr@2: private:
williamr@2: 	virtual void ReservedF1() const {};
williamr@2: 	};
williamr@2: 
williamr@2: 
williamr@2: class CSpriteAnim : public CAnim
williamr@2: /** Sprite animation interface.
williamr@2: 
williamr@2: Sprites are bitmaps that can overlay a window or the screen. A sprite animation 
williamr@2: can be provided by deriving from this class.
williamr@2: 
williamr@2: The interface inherits from CAnim and has access to its functions. It additionally 
williamr@2: can access an interface for querying and manipulating a sprite, using its 
williamr@2: iSpriteFunctions member. 
williamr@2: 
williamr@2: The derived class is constructed in the DLL factory class CAnimDll::CreateInstanceL() 
williamr@2: function.
williamr@2: 
williamr@2: @publishedAll 
williamr@2: @released 
williamr@2: @see CFreeTimerWindowAnim
williamr@2: @see CWindowAnim */
williamr@2: 	{
williamr@2: public:
williamr@2: 	/** Server side construction and initialisation of an animation class. 
williamr@2: 	
williamr@2: 	@param aArgs Packaged arguments which may be required during construction. 
williamr@2: 	These are transferred from the aParams argument of the client side constructor's 
williamr@2: 	RAnim::Construct(). */
williamr@2: 	virtual void ConstructL(TAny *aArgs)=0;
williamr@2: protected:
williamr@2: 	inline CSpriteAnim() 
williamr@2: 	/** Protected constructor.
williamr@2: 	
williamr@2: 	Ensures that only derived classes can be constructed. */
williamr@2: 		{}
williamr@2: private:
williamr@2: 	virtual void ReservedS1() const {};
williamr@2: 	virtual void ReservedS2() const {};
williamr@2: protected:
williamr@2: 	/** Pointer to a class containing functions implemented by the window server.
williamr@2: 	
williamr@2: 	These are available to any CSpriteAnim-derived class.
williamr@2: 	
williamr@2: 	Note that this value is automatically set for you by the animation framework. 
williamr@2: 	You do not need to assign a value to this pointer. */
williamr@2: 	MAnimSpriteFunctions *iSpriteFunctions;
williamr@2: 	friend class CWsAnim;
williamr@2: 	};
williamr@2: 
williamr@2: 
williamr@2: class CAnimDll : public CBase
williamr@2: /** Animation DLL factory interface. 
williamr@2: 
williamr@2: An animation DLL class must be a derived class of CAnimDll, and can be thought 
williamr@2: of as a server side factory class. CAnimDll consists of a single pure virtual 
williamr@2: factory function, CreateInstanceL(TInt aType), which is used to create new 
williamr@2: instances of animation objects of type CAnim contained in the DLL. Animation 
williamr@2: DLL objects are created by the CreateCAnimDllL() function, which is called 
williamr@2: by the window server at the request of the client.
williamr@2: 
williamr@2: For efficiency reasons, it makes sense to collect multiple animation classes 
williamr@2: into a single DLL, even if they are otherwise logically quite separate classes. 
williamr@2: 
williamr@2: @publishedAll 
williamr@2: @released */
williamr@2: 	{
williamr@2: public:
williamr@2: 	/** Factory function for animation DLLs.
williamr@2: 	
williamr@2: 	It must be provided in the derived class.
williamr@2: 	
williamr@2: 	The parameter can be used to differentiate between multiple animation 
williamr@2: 	classes contained in the same animation DLL.
williamr@2: 	
williamr@2: 	@param aType Identifies an animation class to be constructed. This is the 
williamr@2: 	same value as the aType argument of the client side animation constructor 
williamr@2: 	RAnim::Construct(). It is passed from the client side by the animation framework.
williamr@2: 	@return Pointer to a CAnim-derived animation class object. */
williamr@2: 	virtual CAnim *CreateInstanceL(TInt aType)=0;
williamr@2: 	};
williamr@2: 
williamr@2: #endif