// Copyright (c) 1995-2009 Nokia Corporation and/or its subsidiary(-ies).

// All rights reserved.

// This component and the accompanying materials are made available

// under the terms of "Eclipse Public License v1.0"

// which accompanies this distribution, and is available

// at the URL "http://www.eclipse.org/legal/epl-v10.html".

//

// Initial Contributors:

// Nokia Corporation - initial contribution.

//

// Contributors:

//

// Description:

// Header for writing animated DLL add ons

// 

//

#if !defined(__W32ADLL_H__)

#define __W32ADLL_H__

#if !defined(__W32STD_H__)

#include <w32std.h>

#endif

#if !defined(__BITSTD_H__)

#include <bitstd.h>

#endif

/**

@publishedAll

@deprecated

*/

const TUint KWservAnimDllUidValue8=268435858;

/**

@publishedAll

@deprecated

*/

const TUid KWservAnimDllUid8={KWservAnimDllUidValue8};

/**

@publishedAll

@released

*/

const TUint KWservAnimDllUidValue16=268450594;

/**

@publishedAll

@released

*/

const TUid KWservAnimDllUid16={KWservAnimDllUidValue16};

/**

@publishedAll

@released

*/

const TUint KWservAnimDllUidValue=KWservAnimDllUidValue16;

/**

@publishedAll

@released

*/

const TUid KWservAnimDllUid={KWservAnimDllUidValue};

//

// Contains functions callable from animated DLLs

//

class TWindowInfo

/** Animation window information.

Stores the window position and display mode for the animation.

During a redraw of the animation window, the redraw regions

can be retrieved by calling GetRedrawRegionAndRedrawShadowRegion().

@publishedAll 

@released

@see TWindowInfo::GetRedrawRegionAndRedrawShadowRegion() */

	{

public:

	/** The screen position. */

	TRect iScreenPos;

	/** The display mode.

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

	TDisplayMode iMode;

public:

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

	inline TWindowInfo() : iRegionPair(NULL) {}

public:

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

	struct TRegionPair

		{

		const TRegion* iRegion1;

		const TRegion* iRegion2;

		};

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

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

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

	@param aRedrawRegion The redraw region in screen coordinates.

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

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

		{

		if (iRegionPair)

			{

			aRedrawRegion=iRegionPair->iRegion1;

			aRedrawShadowRegion=iRegionPair->iRegion2;

			iRegionPair=NULL;

			}

		else

			{

			aRedrawRegion=NULL;

			aRedrawShadowRegion=NULL;

			}

		}

private:

	mutable const TRegionPair* iRegionPair;

	TAny *iFree2;

	friend class CWsAnim;

	};

class MEventHandler

/** Event handler interface.

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

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

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

called.

@publishedAll

@released */

	{

public:

	/** Handles raw events. 

	If the incoming event can be handled, the function should 

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

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

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

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

	@param aRawEvent The raw event to be processed

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

	chooses not to process it. */

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

	};

enum TAnimNotifications

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

	{

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

	EDirectScreenAccess = 0x0001,

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

	EHeartbeatTimer	= 0x0002,

	/** Notify when screen device changes.*/

	EScreenDeviceChange = 0x0004

	};

//Forward Declaration.

class MAnimGeneralFunctionsWindowExtension;    

class MAnimGeneralFunctionsEventExtension ;

class MAnimGeneralFunctions

/** General animation utility functions interface. 

The interface provides functions to set the animation timing, 

event functions, and other general functions.

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

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

classes via the CAnim::iFunctions pointer.

It is not intended for user derivation.

@publishedAll

@released */

	{

public:

	/** Animation synchronisation flags. 

	The animation can be synchronised to any of these values; 

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

	enum TAnimSync

		{

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

		set by SetSync(). */

		ESyncNone,

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

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

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

		ESyncFlash,

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

		ESyncSecond,

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

		ESyncMinute,

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

		ESyncDay,

		};

	enum

		{

		ENumberOfExtendedInterfaces=0,

		EWindowExtensionInterface,

		EEventExtentionInterface,

		EInterfaceCount, // Always keep at the end.

		};

	//Timing functions

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

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

	Note:

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

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

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

	client.

	Alternatively, use CFreeTimerWindowAnim, which allows you to deactivate the 

	graphics context yourself.

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

	function. */

	virtual void Animate(TDateTime *aDateTime)=0;

	/** Sets the synchronisation mode. 

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

	@param aSyncMode The synchronisation mode. */

	virtual void SetSync(TAnimSync aSyncMode)=0;

	/** Sets the repeat interval. 

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

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

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

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

	the window server panics the client.

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

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

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

	apply until the current countdown is complete. 

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

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

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

	is no longer called.

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

	function. */

	virtual void SetInterval(TInt aInterval)=0;

	/** Sets the next interval. 

	This function immediately resets the current countdown to the specified number 

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

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

	not at all).

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

	otherwise the window server panics the client.

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

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

	than 1, it automatically gets set to 1.

	@see SetInterval() */

	virtual void SetNextInterval(TInt aInterval)=0;

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

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

	virtual TDateTime SystemTime() const=0;

	/** Tests the flash cycle state. 

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

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

	virtual TBool FlashStateOn() const=0;

	/** Gets the current synchronisation mode.

	@return The current sync mode. */

	virtual TAnimSync Sync() const=0;

	//Other functions generally useful

	/** Gets a pointer to the screen device. 

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

	@return A pointer to the screen device. */

	virtual const CFbsScreenDevice *ScreenDevice()=0;

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

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

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

	@return A pointer to the duplicate bitmap. */

	virtual CFbsBitmap *DuplicateBitmapL(TInt aHandle)=0;

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

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

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

	@return A pointer to the duplicate font. */

	virtual CFbsFont *DuplicateFontL(TInt aHandle)=0;

	/** Closes a duplicate font.

	@param Pointer to the duplicate font.

	@see DuplicateFontL() */

	virtual void CloseFont(CFbsFont *)=0;

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

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

	virtual const RThread &Client()=0;

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

	from the client. 	

	@see RAnim::CommandReply()

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

	 */

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

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

	from the client. 	

	@see RAnim::CommandReply()

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

	 */

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

	/** Panics the client. 

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

	virtual void Panic() const=0;

	//Event functions

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

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

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

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

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

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

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

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

	@see RWindowBase::EnableAdvancedPointers() */

	virtual void GetRawEvents(TBool aGetEvents) const=0;

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

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

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

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

	1. Pointer Pressure and Proximity support on current platform.

	2. Multiple pointers support on current platform.

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

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

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

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

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

	@param aRawEvent The raw event 

	@see RWindowBase::EnableAdvancedPointers() */

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

	/** Posts a key event.

	The function is similar to PostRawEvent() but should be 

	used for posting key events. 

	@param aRawEvent The key event. */

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

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

	information to the client-side.

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

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

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

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

	CSpriteAnim's ConstructL, the it returns NULL. 

	@see RMessagePtr2 */

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

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

	@param aInterfaceId The ID of the interface to return.

	@return A pointer to the extension interface.

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

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

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

	*/

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

	/** Register to receive notifications.

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

	@return One of the system wide error codes

	*/

	virtual TInt RegisterForNotifications(TUint32 aNotifications)=0;

	/*

	Return number of ExtendedInterfaces. */

	inline TInt NumberOfExtendedInterfaces()

		{

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

		}

	/** Gets access to Window Extension utility functions.

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

	inline MAnimGeneralFunctionsWindowExtension* WindowExtension()

		{

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

		}

	/** Gets access to EventExtension utility functions. 

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

	inline MAnimGeneralFunctionsEventExtension* EventExtension()

		{

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

		}

	private:

	virtual void Reserved1() const;

	virtual void Reserved2() const;

	virtual void Reserved3() const;

	};

/* Structure for passing window configuration information. Currently transparancey

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

apprioriate.

@publishedAll

@released

*/

class TWindowConfig

	{

public:

	/** Transparency flags. 

	Used to represent transparency configuration of the window. */

	enum

		{

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

		ETransparencyEnabled=0x0001,

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

		EAlphaBlendedTransparency=0x0002,

		};

public:

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

	TInt iFlags;

private:

	TInt iReserved0;

	TInt iReserved1;

	TInt iReserved2;

	};

class MAnimGeneralFunctionsWindowExtension

/** General Window utility functions interface. 

The member functions define the interface for querying and manipulating 

the window and screen attributes.

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

and casting the result.

It is not intended for user derivation.

@publishedAll 

@released */

	{

public:

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

	focusability. */

	class TWindowGroupInfo

		{

	public:

		enum

			{

			/** Window is focusable flag. */

			EIsFocusable=0x0001,

			};

	public:

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

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

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

	public:

	/* Window group attributes. */

		TInt iId;

		TUint32 iFlags;

		TInt iOrdinalPriority;

		TInt iNameLength;

		TInt iParentId;

		};

public:

	/** Returns the total number of screens.

	@return The total number of screens. */

	virtual TInt Screens() const=0;

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

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

	virtual TInt FocusScreens() const=0;

	/** Changes the focused screen.

	@param aScreenNo New screen number. */

	virtual void SetFocusScreen(TInt aScreenNo)=0;

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

	@param aScreen The screen number.

	@return The number of window groups. */

	virtual TInt WindowGroups(TInt aScreen) const=0;

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

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

	function returns EFalse.

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

	of all group windows of all priorities on that screen.

	@param aInfo on return, complete window information.

	@param aScreen Screen number.

	@param aFullOrdinalPosition Ordinal position of the window.

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

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

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

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

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

	all group windows of all priorities on that screen.

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

	@param aWindowName On return, the window group name.

	@param aScreen The screen number.