1 w32adll.h

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

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

     4 // 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

     5 // which accompanies this distribution, and is available

     6 // at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 // Header for writing animated DLL add ons

    15 // 

    16 //

    17 

    18 #if !defined(__W32ADLL_H__)

    19 #define __W32ADLL_H__

    20 

    21 #if !defined(__W32STD_H__)

    22 #include <w32std.h>

    23 #endif

    24 

    25 #if !defined(__BITSTD_H__)

    26 #include <bitstd.h>

    27 #endif

    28 

    29 /**

    30 @publishedAll

    31 @deprecated

    32 */

    33 const TUint KWservAnimDllUidValue8=268435858;

    34 

    35 /**

    36 @publishedAll

    37 @deprecated

    38 */

    39 const TUid KWservAnimDllUid8={KWservAnimDllUidValue8};

    40 

    41 /**

    42 @publishedAll

    43 @released

    44 */

    45 const TUint KWservAnimDllUidValue16=268450594;

    46 

    47 /**

    48 @publishedAll

    49 @released

    50 */

    51 const TUid KWservAnimDllUid16={KWservAnimDllUidValue16};

    52 

    53 /**

    54 @publishedAll

    55 @released

    56 */

    57 const TUint KWservAnimDllUidValue=KWservAnimDllUidValue16;

    58 

    59 /**

    60 @publishedAll

    61 @released

    62 */

    63 const TUid KWservAnimDllUid={KWservAnimDllUidValue};

    64 

    65 //

    66 // Contains functions callable from animated DLLs

    67 //

    68 

    69 

    70 class TWindowInfo

    71 /** Animation window information.

    72 

    73 Stores the window position and display mode for the animation.

    74 During a redraw of the animation window, the redraw regions

    75 can be retrieved by calling GetRedrawRegionAndRedrawShadowRegion().

    76 

    77 @publishedAll 

    78 @released

    79 @see TWindowInfo::GetRedrawRegionAndRedrawShadowRegion() */

    80 	{

    81 public:

    82 	/** The screen position. */

    83 	TRect iScreenPos;

    84 	/** The display mode.

    85 	

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

    87 	TDisplayMode iMode;

    88 public:

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

    90 	inline TWindowInfo() : iRegionPair(NULL) {}

    91 public:

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

    93 	struct TRegionPair

    94 		{

    95 		const TRegion* iRegion1;

    96 		const TRegion* iRegion2;

    97 		};

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

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

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

   101 	@param aRedrawRegion The redraw region in screen coordinates.

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

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

   104 		{

   105 		if (iRegionPair)

   106 			{

   107 			aRedrawRegion=iRegionPair->iRegion1;

   108 			aRedrawShadowRegion=iRegionPair->iRegion2;

   109 			iRegionPair=NULL;

   110 			}

   111 		else

   112 			{

   113 			aRedrawRegion=NULL;

   114 			aRedrawShadowRegion=NULL;

   115 			}

   116 		}

   117 private:

   118 	mutable const TRegionPair* iRegionPair;

   119 	TAny *iFree2;

   120 	friend class CWsAnim;

   121 	};

   122 

   123 

   124 class MEventHandler

   125 /** Event handler interface.

   126 

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

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

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

   130 called.

   131 

   132 @publishedAll

   133 @released */

   134 	{

   135 public:

   136 	/** Handles raw events. 

   137 	

   138 	If the incoming event can be handled, the function should 

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

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

   141 	

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

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

   144 	

   145 	@param aRawEvent The raw event to be processed

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

   147 	chooses not to process it. */

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

   149 	};

   150 

   151 enum TAnimNotifications

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

   153 	{

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

   155 	EDirectScreenAccess = 0x0001,

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

   157 	EHeartbeatTimer	= 0x0002,

   158 	/** Notify when screen device changes.*/

   159 	EScreenDeviceChange = 0x0004

   160 	};

   161 //Forward Declaration.

   162 class MAnimGeneralFunctionsWindowExtension;    

   163 class MAnimGeneralFunctionsEventExtension ;

   164 

   165 class MAnimGeneralFunctions

   166 /** General animation utility functions interface. 

   167 

   168 The interface provides functions to set the animation timing, 

   169 event functions, and other general functions.

   170 

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

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

   173 classes via the CAnim::iFunctions pointer.

   174 

   175 It is not intended for user derivation.

   176 

   177 @publishedAll

   178 @released */

   179 	{

   180 public:

   181 	/** Animation synchronisation flags. 

   182 	

   183 	The animation can be synchronised to any of these values; 

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

   185 	enum TAnimSync

   186 		{

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

   188 		set by SetSync(). */

   189 		ESyncNone,

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

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

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

   193 		ESyncFlash,

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

   195 		ESyncSecond,

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

   197 		ESyncMinute,

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

   199 		ESyncDay,

   200 		};

   201 	enum

   202 		{

   203 		ENumberOfExtendedInterfaces=0,

   204 		EWindowExtensionInterface,

   205 		EEventExtentionInterface,

   206 		EInterfaceCount, // Always keep at the end.

   207 		};

   208 	//Timing functions

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

   210 	

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

   212 	

   213 	Note:

   214 	

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

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

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

   218 	client.

   219 	

   220 	Alternatively, use CFreeTimerWindowAnim, which allows you to deactivate the 

   221 	graphics context yourself.

   222 	

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

   224 	function. */

   225 	virtual void Animate(TDateTime *aDateTime)=0;

   226 	/** Sets the synchronisation mode. 

   227 	

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

   229 	

   230 	@param aSyncMode The synchronisation mode. */

   231 	virtual void SetSync(TAnimSync aSyncMode)=0;

   232 	/** Sets the repeat interval. 

   233 	

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

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

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

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

   238 	the window server panics the client.

   239 	

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

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

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

   243 	apply until the current countdown is complete. 

   244 	

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

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

   247 	

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

   249 	is no longer called.

   250 	

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

   252 	function. */

   253 	virtual void SetInterval(TInt aInterval)=0;

   254 	/** Sets the next interval. 

   255 	

   256 	This function immediately resets the current countdown to the specified number 

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

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

   259 	not at all).

   260 	

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

   262 	otherwise the window server panics the client.

   263 	

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

   265 	

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

   267 	than 1, it automatically gets set to 1.

   268 	@see SetInterval() */

   269 	virtual void SetNextInterval(TInt aInterval)=0;

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

   271 	

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

   273 	virtual TDateTime SystemTime() const=0;

   274 	/** Tests the flash cycle state. 

   275 	

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

   277 	

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

   279 	virtual TBool FlashStateOn() const=0;

   280 	/** Gets the current synchronisation mode.

   281 	

   282 	@return The current sync mode. */

   283 	virtual TAnimSync Sync() const=0;

   284 	//Other functions generally useful

   285 	/** Gets a pointer to the screen device. 

   286 	

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

   288 	

   289 	@return A pointer to the screen device. */

   290 	virtual const CFbsScreenDevice *ScreenDevice()=0;

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

   292 	

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

   294 	

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

   296 	@return A pointer to the duplicate bitmap. */

   297 	virtual CFbsBitmap *DuplicateBitmapL(TInt aHandle)=0;

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

   299 	

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

   301 	

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

   303 	@return A pointer to the duplicate font. */

   304 	virtual CFbsFont *DuplicateFontL(TInt aHandle)=0;

   305 	/** Closes a duplicate font.

   306 	

   307 	@param Pointer to the duplicate font.

   308 	@see DuplicateFontL() */

   309 	virtual void CloseFont(CFbsFont *)=0;

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

   311 	

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

   313 	virtual const RThread &Client()=0;

   314 	virtual void ReplyBuf(const TDesC8 &aDes)=0;				// Reply a buffer to the client

   315 	virtual void ReplyBuf(const TDesC16 &aDes)=0;				// Reply a buffer to the client

   316 	/** Panics the client. 

   317 	

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

   319 	virtual void Panic() const=0;

   320 	//Event functions

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

   322 	

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

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

   325 	

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

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

   328 	virtual void GetRawEvents(TBool aGetEvents) const=0;

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

   330 	

   331 	@param aRawEvent The raw event */

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

   333 	/** Posts a key event.

   334 	

   335 	The function is similar to PostRawEvent() but should be 

   336 	used for posting key events. 

   337 	

   338 	@param aRawEvent The key event. */

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

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

   341 	information to the client-side.

   342 

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

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

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

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

   347 	CSpriteAnim's ConstructL, the it returns NULL. 

   348 	@see RMessagePtr2 */

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

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

   351 	@param aInterfaceId The ID of the interface to return.

   352 	@return A pointer to the extension interface.

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

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

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

   356 	*/

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

   358 

   359 	/** Register to receive notifications.

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

   361 	@return One of the system wide error codes

   362 	*/

   363 	virtual TInt RegisterForNotifications(TUint32 aNotifications)=0;

   364 	/*

   365 	Return number of ExtendedInterfaces. */

   366 	inline TInt NumberOfExtendedInterfaces()

   367 		{

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

   369 		}

   370 	/** Gets access to Window Extension utility functions.

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

   372 	inline MAnimGeneralFunctionsWindowExtension* WindowExtension()

   373 		{

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

   375 		}

   376 	/** Gets access to EventExtension utility functions. 

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

   378 	inline MAnimGeneralFunctionsEventExtension* EventExtension()

   379 		{

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

   381 		}

   382 	private:

   383 	virtual void Reserved1() const;

   384 	virtual void Reserved2() const;

   385 	virtual void Reserved3() const;

   386 	};

   387 

   388 /* Structure for passing window configuration information. Currently transparancey

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

   390 apprioriate.

   391 

   392 @publishedAll

   393 @released

   394 */

   395 class TWindowConfig

   396 	{

   397 public:

   398 	/** Transparency flags. 

   399 	

   400 	Used to represent transparency configuration of the window. */

   401 	enum

   402 		{

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

   404 		ETransparencyEnabled=0x0001,

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

   406 		EAlphaBlendedTransparency=0x0002,

   407 		};

   408 public:

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

   410 	TInt iFlags;

   411 private:

   412 	TInt iReserved0;

   413 	TInt iReserved1;

   414 	TInt iReserved2;

   415 	};

   416 	

   417 class MAnimGeneralFunctionsWindowExtension

   418 /** General Window utility functions interface. 

   419 

   420 The member functions define the interface for querying and manipulating 

   421 the window and screen attributes.

   422 

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

   424 and casting the result.

   425 

   426 It is not intended for user derivation.

   427 

   428 @publishedAll 

   429 @released */

   430 	{

   431 public:

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

   433 	focusability. */

   434 	class TWindowGroupInfo

   435 		{

   436 	public:

   437 		enum

   438 			{

   439 			/** Window is focusable flag. */

   440 			EIsFocusable=0x0001,

   441 			};

   442 	public:

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

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

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

   446 	public:

   447 	/* Window group attributes. */

   448 		TInt iId;

   449 		TUint32 iFlags;

   450 		TInt iOrdinalPriority;

   451 		TInt iNameLength;

   452 		TInt iParentId;

   453 		};

   454 public:

   455 	/** Returns the total number of screens.

   456 	@return The total number of screens. */

   457 	virtual TInt Screens() const=0;

   458 

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

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

   461 	virtual TInt FocusScreens() const=0;

   462 

   463 	/** Changes the focused screen.

   464 	@param aScreenNo New screen number. */

   465 	virtual void SetFocusScreen(TInt aScreenNo)=0;

   466 

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

   468 

   469 	@param aScreen The screen number.

   470 	@return The number of window groups. */

   471 	virtual TInt WindowGroups(TInt aScreen) const=0;

   472 	

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

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

   475 	function returns EFalse.

   476 	

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

   478 	of all group windows of all priorities on that screen.

   479 

   480 	@param aInfo on return, complete window information.

   481 	@param aScreen Screen number.

   482 	@param aFullOrdinalPosition Ordinal position of the window.

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

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

   485 

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

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

   488 

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

   490 	all group windows of all priorities on that screen.

   491 

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

   493 

   494 	@param aWindowName On return, the window group name.

   495 	@param aScreen The screen number.

   496 	@param aFullOrdinalPosition The ordinal position of the window.

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

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

   499 	

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

   501 

   502 	@param aWindowGroupId The window group ID.

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

   504 	@param aOrdinalPriority The new ordinal priority of the window.

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

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

   507 

   508 	/** Accessor for window configuration.

   509 

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

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

   512 	

   513 private:

   514 	virtual void Reserved1() const;

   515 	virtual void Reserved2() const;

   516 	virtual void Reserved3() const;

   517 	};

   518 	

   519 class MAnimGeneralFunctionsEventExtension

   520 /** Event utility functions interface. 

   521 

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

   523 

   524 It is not intended for user derivation.

   525 */

   526 	{

   527 public:

   528 	/** Posts a key event.

   529 	

   530 	The function is similar to PostKeyEvent() but should be 

   531 used for posting repeated key events. 

   532 	

   533 	@param aRawEvent The key event.

   534 	@param aRepeats value */

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

   536 

   537 private:

   538 	virtual void Reserved1() const;

   539 	virtual void Reserved2() const;

   540 	};

   541 	

   542 class MAnimWindowFunctions

   543 /** Window utility functions interface. 

   544 

   545 The member functions define the interface for querying and manipulating 

   546 the window in which the animation takes place.

   547 

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

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

   550 and CFreeTimerWindowAnim derived classes via the iWindowFunctions pointer.

   551 

   552 It is not intended for user derivation.

   553 

   554 @publishedAll 

   555 @released */

   556 	{

   557 public:

   558 	/** Activates the graphics context.

   559 	

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

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

   562 	

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

   564 	Redraw() function. */

   565 	virtual void ActivateGc()=0;

   566 	/** Sets the rectangle that this animation is to draw to.

   567 	

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

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

   570 	window server knows which area the animation is operating in.

   571 	

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

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

   574 	/** Gets the window size.

   575 	

   576 	@return The window size, in pixels. */

   577 	virtual TSize WindowSize() const=0;

   578 	/** Tests whether to draw the animation. 

   579 	

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

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

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

   583 	ETrue if it is not safe to draw the animation.

   584 	

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

   586 	to continue drawing the animation, otherwise false. */

   587 	virtual TBool IsHidden()=0;

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

   589 	

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

   591 	

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

   593 	virtual void SetVisible(TBool aState)=0;

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

   595 	

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

   597 	which provides a non-immediate way to do drawing.

   598 	

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

   600 	the animation.

   601 	

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

   603 	to the origin of the window. */

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

   605 	/** Gets window information.

   606 	

   607 	@param aData The window information. */

   608 	virtual void Parameters(TWindowInfo &aData)=0;

   609 	/** Gets the visible region.

   610 

   611 	This region is the area of the visible window which 

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

   613 	then aRegion's error flag is set.

   614 	

   615 	@param aRegion The visible region. */

   616 	virtual void VisibleRegion(TRegion& aRegion)=0;

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

   618 private:

   619 	virtual void Reserved() const;

   620 	virtual void Reserved1() const;

   621 	virtual void Reserved2() const;

   622 	virtual void Reserved3() const;

   623 	};

   624 

   625 

   626 class MAnimFreeTimerWindowFunctions : public MAnimWindowFunctions

   627 /** Free timer animation utility functions interface.

   628 

   629 The class inherits functions from MAnimWindowFunctions, and defines the additional 

   630 interface required for window operations which support animations with their 

   631 own timers.

   632 

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

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

   635 derived classes via the WindowFunctions() member. 

   636 

   637 It is not intended for user derivation.

   638 

   639 @publishedAll 

   640 @released */

   641 	{

   642 public:

   643 	/** Deactivates the graphics context. 

   644 	

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

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

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

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

   649 	virtual void DeactivateGc()=0;

   650 	/** Forces the screen to update. */

   651 	virtual void Update()=0;

   652 private:

   653 	virtual void Reserved3() const;

   654 	};

   655 

   656 class MAnimSpriteFunctions

   657 /** Sprite animation utility functions interface.

   658 

   659 The interface includes functions for querying and manipulating a sprite.

   660 

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

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

   663 classes via the CSpriteAnim::iSpriteFunctions pointer. 

   664 

   665 It is not intended for user derivation.

   666 

   667 @publishedAll 

   668 @released */

   669 	{

   670 public:

   671 	/** Gets sprite member data.

   672 	

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

   674 	different amount of time.

   675 	

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

   677 	@return A pointer to the sprite member. */

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

   679 	/** Redraws part of a sprite.

   680 

   681 	WSERV1:	

   682 

   683 	The updates a sprite on the screen, possibly after the bitmap for a particular 

   684 	sprite member has been changed.

   685 	

   686 	Two types of redraw are possible. A full update takes the bitmap off the screen 

   687 	and then re-draws it. This is 'safe' in that the screen always reflects 

   688 	the contents of the sprite bitmap. However it can result in flicker. Use the 

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

   690 	then any flicker will only occur in this rectangle. 

   691 	

   692 	A full update is required if you have removed pixels from the mask, i.e. made 

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

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

   695 	update is possible. Otherwise the aFullUpdate argument is ignored and a full 

   696 	update is always done.

   697 	

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

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

   700 	

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

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

   703 	param aFullUpdate ETrue for a full update, EFalse otherwise.

   704 

   705 	WSERV2:

   706 

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

   708 	sprite member has been changed.

   709 	

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

   711 	then any flicker will only occur in this rectangle. 

   712 	

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

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

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

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

   717 	

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

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

   720 	

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

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

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

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

   725 	/** Turns a sprite on or off.

   726 	

   727 	In effect this makes the sprite bitmap visible.

   728 	

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

   730 	virtual void Activate(TBool aActive)=0;

   731 	/** Finishes constructing the sprite.

   732 	

   733 	It also sets the currently displayed sprite member to zero.

   734 	

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

   736 	virtual void SizeChangedL()=0;

   737 	/** Set the sprite's position.

   738 	

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

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

   741 private:

   742 	virtual void Reserved() const;

   743 public:

   744 	/** Returns the visibility of the sprite.

   745 	

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

   747 	

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

   749 	virtual TBool SpriteCanBeSeen() const = 0;

   750 private:

   751 	virtual void Reserved2() const;

   752 	virtual void Reserved3() const;

   753 	virtual void Reserved4() const;

   754 	};

   755 

   756 

   757 class CAnimGc : public CBitmapContext

   758 /** Animation graphics context. 

   759 

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

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

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

   763 the inherited CBitmapContext functions. 

   764 

   765 @publishedAll

   766 @released */

   767 	{

   768 public:

   769 	/** Sets the clipping region.

   770 	

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

   772 	

   773 	@param aRegion The clipping region. */

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

   775 	/** Cancels the clipping region.

   776 	

   777 	@see SetClippingRegion() */

   778 	virtual void CancelClippingRegion()=0;

   779 	};

   780 

   781 class CWsAnim; // Forward ref for friend declaration

   782 

   783 

   784 class CAnim : public CBase , public MEventHandler

   785 /** Server side animated object base interface.

   786 

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

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

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

   790 before the application.

   791 

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

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

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

   795 side animation class RAnim.

   796 

   797 You should derive from CWindowAnim, CFreeTimerWindowAnim or CSpriteAnim, 

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

   799 rather than directly from this class.

   800 

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

   802 function.

   803 

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

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

   806 member, which also provides other utility functions. 

   807 

   808 @publishedAll 

   809 @released */

   810 	{

   811 public:

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

   813 	

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

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

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

   817 	side function call.

   818 	

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

   820 	error codes for commands which might leave.

   821 	

   822 	@param aOpcode Opcode understood by the class.

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

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

   825 	passed in to RAnim::CommandReply().

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

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

   828 	However any value may be returned to the client side.

   829 	@see RAnim */

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

   831 	/** Implements client-side initiated commands. 

   832 	

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

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

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

   836 	side function call.

   837 	

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

   839 	which might leave.

   840 	

   841 	@param aOpcode Opcode understood by the class

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

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

   844 	passed in to RAnim::Command().

   845 	@see RAnim */

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

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

   848 	

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

   850 	

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

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

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

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

   855 	video images.

   856 	

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

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

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

   860 	

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

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

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

   864 	the second.

   865 	

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

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

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

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

   870 	into aDateTime will be NULL.

   871 	

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

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

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

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

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

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

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

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

   880 	should be reset.

   881 	

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

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

   884 	virtual void Animate(TDateTime *aDateTime)=0;

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

   886 private:

   887 	inline CAnim() {}

   888 	virtual void Reserved1() const {};

   889 	virtual void Reserved2() const {};

   890 	virtual void Reserved3() const {};

   891 protected:

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

   893 	

   894 	These are available to any CAnim derived class.

   895 	

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

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

   898 	@publishedAll

   899 	@released	*/

   900 	MAnimGeneralFunctions *iFunctions;

   901 	friend class CWsAnim;

   902 	friend class CWindowAnim;

   903 	friend class CSpriteAnim;

   904 	};

   905 

   906 

   907 class CWindowAnim : public CAnim

   908 /** Window animation interface. 

   909 

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

   911 animation can be provided by deriving from this class.

   912 

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

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

   915 the animation takes place, using its iWindowFunctions member.

   916 

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

   918 

   919 @publishedAll

   920 @released 

   921 @see CFreeTimerWindowAnim

   922 @see CSpriteAnim */

   923 	{

   924 public:

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

   926 	

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

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

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

   930 	to always know its focus state.

   931 	

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

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

   934 	RAnim::Construct().

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

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

   937 	/** Redraws the objects.

   938 	

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

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

   941 	virtual void Redraw()=0;

   942 	/** Notifies change of focus.

   943 	

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

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

   946 	and to change its appearance accordingly.

   947 	

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

   949 	virtual void FocusChanged(TBool aState)=0;

   950 protected:

   951 	/** Protected constructor.

   952 	

   953 	Prevents objects of this class being directly constructed. */

   954 	inline CWindowAnim() {}

   955 private:

   956 	virtual void ReservedW1() const {};

   957 	virtual void ReservedW2() const {};

   958 protected:

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

   960 	

   961 	These are available to any CWindowAnim-derived class.

   962 	

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

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

   965 	MAnimWindowFunctions *iWindowFunctions;

   966 	/** Pointer to the graphics context. */

   967 	CAnimGc *iGc;

   968 	friend class CWsAnim;

   969 	};

   970 

   971 

   972 class CFreeTimerWindowAnim : public CWindowAnim

   973 /** Free timer animation interface.

   974 

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

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

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

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

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

   980 flash cycle.

   981 

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

   983 additionally can access functions declared in the MAnimFreeTimerWindowFunctions 

   984 interface, using WindowFunctions(). 

   985 

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

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

   988 function after finishing the drawing.

   989 

   990 @publishedAll 

   991 @released 

   992 @see CSpriteAnim */

   993 	{

   994 protected:

   995 	inline MAnimFreeTimerWindowFunctions* WindowFunctions()

   996 	/** Gets the free timer utility functions.

   997 	

   998 	These functions include all the MAnimWindowFunctions, 

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

  1000 	screen to update.

  1001 	

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

  1003 		{return STATIC_CAST(MAnimFreeTimerWindowFunctions*,iWindowFunctions);}

  1004 private:

  1005 	virtual void ReservedF1() const {};

  1006 	};

  1007 

  1008 

  1009 class CSpriteAnim : public CAnim

  1010 /** Sprite animation interface.

  1011 

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

  1013 can be provided by deriving from this class.

  1014 

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

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

  1017 iSpriteFunctions member. 

  1018 

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

  1020 function.

  1021 

  1022 @publishedAll 

  1023 @released 

  1024 @see CFreeTimerWindowAnim

  1025 @see CWindowAnim */

  1026 	{

  1027 public:

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

  1029 	

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

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

  1032 	RAnim::Construct(). */

  1033 	virtual void ConstructL(TAny *aArgs)=0;

  1034 protected:

  1035 	inline CSpriteAnim() 

  1036 	/** Protected constructor.

  1037 	

  1038 	Ensures that only derived classes can be constructed. */

  1039 		{}

  1040 private:

  1041 	virtual void ReservedS1() const {};

  1042 	virtual void ReservedS2() const {};

  1043 protected:

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

  1045 	

  1046 	These are available to any CSpriteAnim-derived class.

  1047 	

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

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

  1050 	MAnimSpriteFunctions *iSpriteFunctions;

  1051 	friend class CWsAnim;

  1052 	};

  1053 

  1054 

  1055 class CAnimDll : public CBase

  1056 /** Animation DLL factory interface. 

  1057 

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

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

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

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

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

  1063 by the window server at the request of the client.

  1064 

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

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

  1067 

  1068 @publishedAll 

  1069 @released */

  1070 	{

  1071 public:

  1072 	/** Factory function for animation DLLs.

  1073 	

  1074 	It must be provided in the derived class.

  1075 	

  1076 	The parameter can be used to differentiate between multiple animation 

  1077 	classes contained in the same animation DLL.

  1078 	

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

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

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

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

  1083 	virtual CAnim *CreateInstanceL(TInt aType)=0;

  1084 	};

  1085 

  1086 #endif