1.1 --- a/epoc32/include/w32adll.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/w32adll.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,1086 @@
1.4 -w32adll.h
1.5 +// Copyright (c) 1995-2009 Nokia Corporation and/or its subsidiary(-ies).
1.6 +// All rights reserved.
1.7 +// This component and the accompanying materials are made available
1.8 +// 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
1.9 +// which accompanies this distribution, and is available
1.10 +// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.11 +//
1.12 +// Initial Contributors:
1.13 +// Nokia Corporation - initial contribution.
1.14 +//
1.15 +// Contributors:
1.16 +//
1.17 +// Description:
1.18 +// Header for writing animated DLL add ons
1.19 +//
1.20 +//
1.21 +
1.22 +#if !defined(__W32ADLL_H__)
1.23 +#define __W32ADLL_H__
1.24 +
1.25 +#if !defined(__W32STD_H__)
1.26 +#include <w32std.h>
1.27 +#endif
1.28 +
1.29 +#if !defined(__BITSTD_H__)
1.30 +#include <bitstd.h>
1.31 +#endif
1.32 +
1.33 +/**
1.34 +@publishedAll
1.35 +@deprecated
1.36 +*/
1.37 +const TUint KWservAnimDllUidValue8=268435858;
1.38 +
1.39 +/**
1.40 +@publishedAll
1.41 +@deprecated
1.42 +*/
1.43 +const TUid KWservAnimDllUid8={KWservAnimDllUidValue8};
1.44 +
1.45 +/**
1.46 +@publishedAll
1.47 +@released
1.48 +*/
1.49 +const TUint KWservAnimDllUidValue16=268450594;
1.50 +
1.51 +/**
1.52 +@publishedAll
1.53 +@released
1.54 +*/
1.55 +const TUid KWservAnimDllUid16={KWservAnimDllUidValue16};
1.56 +
1.57 +/**
1.58 +@publishedAll
1.59 +@released
1.60 +*/
1.61 +const TUint KWservAnimDllUidValue=KWservAnimDllUidValue16;
1.62 +
1.63 +/**
1.64 +@publishedAll
1.65 +@released
1.66 +*/
1.67 +const TUid KWservAnimDllUid={KWservAnimDllUidValue};
1.68 +
1.69 +//
1.70 +// Contains functions callable from animated DLLs
1.71 +//
1.72 +
1.73 +
1.74 +class TWindowInfo
1.75 +/** Animation window information.
1.76 +
1.77 +Stores the window position and display mode for the animation.
1.78 +During a redraw of the animation window, the redraw regions
1.79 +can be retrieved by calling GetRedrawRegionAndRedrawShadowRegion().
1.80 +
1.81 +@publishedAll
1.82 +@released
1.83 +@see TWindowInfo::GetRedrawRegionAndRedrawShadowRegion() */
1.84 + {
1.85 +public:
1.86 + /** The screen position. */
1.87 + TRect iScreenPos;
1.88 + /** The display mode.
1.89 +
1.90 + This is the minimum display mode that the screen has to be in to display this window. */
1.91 + TDisplayMode iMode;
1.92 +public:
1.93 + /** Constructs an animation window information object. */
1.94 + inline TWindowInfo() : iRegionPair(NULL) {}
1.95 +public:
1.96 + /** Stores a pair of region pointers. */
1.97 + struct TRegionPair
1.98 + {
1.99 + const TRegion* iRegion1;
1.100 + const TRegion* iRegion2;
1.101 + };
1.102 + /** Returns the current redraw region and redraw shadow region.
1.103 + This function must only be called from an override of CWindowAnim's pure virtual Redraw function.
1.104 + The region pointers retrieved must not be used beyond the end of the Redraw override.
1.105 + @param aRedrawRegion The redraw region in screen coordinates.
1.106 + @param aRedrawShadowRegion The redraw shadow region in screen coordinates. */
1.107 + inline void GetRedrawRegionAndRedrawShadowRegion(const TRegion*& aRedrawRegion, const TRegion*& aRedrawShadowRegion) const
1.108 + {
1.109 + if (iRegionPair)
1.110 + {
1.111 + aRedrawRegion=iRegionPair->iRegion1;
1.112 + aRedrawShadowRegion=iRegionPair->iRegion2;
1.113 + iRegionPair=NULL;
1.114 + }
1.115 + else
1.116 + {
1.117 + aRedrawRegion=NULL;
1.118 + aRedrawShadowRegion=NULL;
1.119 + }
1.120 + }
1.121 +private:
1.122 + mutable const TRegionPair* iRegionPair;
1.123 + TAny *iFree2;
1.124 + friend class CWsAnim;
1.125 + };
1.126 +
1.127 +
1.128 +class MEventHandler
1.129 +/** Event handler interface.
1.130 +
1.131 +The interface provides a function to handle raw events, e.g. key presses,
1.132 +pen events, power buttons etc. Raw events are passed to the OfferRawEvent()
1.133 +function when the MAnimGeneralFunctions::GetRawEvents() function has been
1.134 +called.
1.135 +
1.136 +@publishedAll
1.137 +@released */
1.138 + {
1.139 +public:
1.140 + /** Handles raw events.
1.141 +
1.142 + If the incoming event can be handled, the function should
1.143 + process it and then return true. If it cannot be processed the function should
1.144 + return false, and the event will be passed to other event handling code.
1.145 +
1.146 + This function must be implemented in every animation DLL. If event
1.147 + handling is not required, the function should simply return false.
1.148 +
1.149 + @param aRawEvent The raw event to be processed
1.150 + @return ETrue if the raw event is handled by this function, EFalse if the function
1.151 + chooses not to process it. */
1.152 + virtual TBool OfferRawEvent(const TRawEvent &aRawEvent)=0;
1.153 + };
1.154 +
1.155 +enum TAnimNotifications
1.156 +/** Bit flags to be used by anims when registering for notifications */
1.157 + {
1.158 + /** Notify when direct screen access begins or ends.*/
1.159 + EDirectScreenAccess = 0x0001,
1.160 + /** Notify when the wserv heartbeat timer starts or stops. */
1.161 + EHeartbeatTimer = 0x0002,
1.162 + /** Notify when screen device changes.*/
1.163 + EScreenDeviceChange = 0x0004
1.164 + };
1.165 +//Forward Declaration.
1.166 +class MAnimGeneralFunctionsWindowExtension;
1.167 +class MAnimGeneralFunctionsEventExtension ;
1.168 +
1.169 +class MAnimGeneralFunctions
1.170 +/** General animation utility functions interface.
1.171 +
1.172 +The interface provides functions to set the animation timing,
1.173 +event functions, and other general functions.
1.174 +
1.175 +You do not have to create an object of this type. The class is implemented
1.176 +by the window server and provides utility functions to all CAnim-derived
1.177 +classes via the CAnim::iFunctions pointer.
1.178 +
1.179 +It is not intended for user derivation.
1.180 +
1.181 +@publishedAll
1.182 +@released */
1.183 + {
1.184 +public:
1.185 + /** Animation synchronisation flags.
1.186 +
1.187 + The animation can be synchronised to any of these values;
1.188 + the Animate() call will take place at the start of the new unit (day, hour, etc...). */
1.189 + enum TAnimSync
1.190 + {
1.191 + /** Not synchronised. Animate() is called after some number of flash cycles -
1.192 + set by SetSync(). */
1.193 + ESyncNone,
1.194 + /** Animate() every flash tick. This occurs twice a second, on the second and after
1.195 + 7/12ths of a second, e.g. the function is called in a flash-on (7/12 seconds) -
1.196 + flash-off (5/12 seconds) cycle. */
1.197 + ESyncFlash,
1.198 + /** Animate() called as soon after every second as system activity allows. */
1.199 + ESyncSecond,
1.200 + /** Animate() called as soon after every minute as system activity allows. */
1.201 + ESyncMinute,
1.202 + /** Animate() called as soon after midnight every day as system activity allows. */
1.203 + ESyncDay,
1.204 + };
1.205 + enum
1.206 + {
1.207 + ENumberOfExtendedInterfaces=0,
1.208 + EWindowExtensionInterface,
1.209 + EEventExtentionInterface,
1.210 + EInterfaceCount, // Always keep at the end.
1.211 + };
1.212 + //Timing functions
1.213 + /** Calls the DLL's Animate() function then deactivates the graphics context.
1.214 +
1.215 + This allows users to do drawing from their own active object.
1.216 +
1.217 + Note:
1.218 +
1.219 + If the user calls the CAnim-derived classes' Animate() function directly,
1.220 + or otherwise does drawing from their own active object, then this will not
1.221 + deactivate the graphics context. This causes the window server to panic the
1.222 + client.
1.223 +
1.224 + Alternatively, use CFreeTimerWindowAnim, which allows you to deactivate the
1.225 + graphics context yourself.
1.226 +
1.227 + @param aDateTime The parameter passed into the animation DLL's Animate()
1.228 + function. */
1.229 + virtual void Animate(TDateTime *aDateTime)=0;
1.230 + /** Sets the synchronisation mode.
1.231 +
1.232 + This determines the time intervals between calls to the Animate() function.
1.233 +
1.234 + @param aSyncMode The synchronisation mode. */
1.235 + virtual void SetSync(TAnimSync aSyncMode)=0;
1.236 + /** Sets the repeat interval.
1.237 +
1.238 + If the synchronisation mode is TAnimSync::ESyncNone, then the Animate() function
1.239 + is called at intervals defined by some number of flash ticks. There are two
1.240 + flash ticks a second, with a 7/12 second - 5/12 second cycle. If the function
1.241 + is called when the synchronisation mode is not TAnimSync::ESyncNone, then
1.242 + the window server panics the client.
1.243 +
1.244 + If the new interval is greater than the current countdown, then the call does
1.245 + not affect the current countdown. For example, if the countdown has 10 flash
1.246 + ticks remaining, and the interval is set to 20, the new interval does not
1.247 + apply until the current countdown is complete.
1.248 +
1.249 + However if the new interval is less the current countdown, then the new interval
1.250 + applies immediately i.e. the countdown is reset to the interval value.
1.251 +
1.252 + If the interval is set to zero the countdown stops, and the Animate() function
1.253 + is no longer called.
1.254 +
1.255 + @param aInterval The number of flash ticks between calls to the Animate()
1.256 + function. */
1.257 + virtual void SetInterval(TInt aInterval)=0;
1.258 + /** Sets the next interval.
1.259 +
1.260 + This function immediately resets the current countdown to the specified number
1.261 + of flash ticks, irrespective of its current value. After the countdown expires,
1.262 + the interval returns to its usual rate. Note that this may be zero (i.e.
1.263 + not at all).
1.264 +
1.265 + To call this function, the synchronisation mode must be TAnimSync::ESyncNone,
1.266 + otherwise the window server panics the client.
1.267 +
1.268 + Note: there are two flash ticks a second, with a 7/12 second - 5/12 second cycle.
1.269 +
1.270 + @param aInterval The interval to the next Animate(). If the value is less
1.271 + than 1, it automatically gets set to 1.
1.272 + @see SetInterval() */
1.273 + virtual void SetNextInterval(TInt aInterval)=0;
1.274 + /** Gets the system time as it was when Animate() was last called.
1.275 +
1.276 + @return The system time when Animate() was last called. */
1.277 + virtual TDateTime SystemTime() const=0;
1.278 + /** Tests the flash cycle state.
1.279 +
1.280 + The flash cycle has 2 states: on (7/12 second) or off (5/12 second).
1.281 +
1.282 + @return ETrue if in the on part of the flash cycle, otherwise EFalse. */
1.283 + virtual TBool FlashStateOn() const=0;
1.284 + /** Gets the current synchronisation mode.
1.285 +
1.286 + @return The current sync mode. */
1.287 + virtual TAnimSync Sync() const=0;
1.288 + //Other functions generally useful
1.289 + /** Gets a pointer to the screen device.
1.290 +
1.291 + For example, this might be used to gain access to twips to pixel conversion functions.
1.292 +
1.293 + @return A pointer to the screen device. */
1.294 + virtual const CFbsScreenDevice *ScreenDevice()=0;
1.295 + /** Creates and duplicates a bitmap from a handle.
1.296 +
1.297 + This function might be used to duplicate client side bitmaps on the server side.
1.298 +
1.299 + @param aHandle A handle to the bitmap to be duplicated.
1.300 + @return A pointer to the duplicate bitmap. */
1.301 + virtual CFbsBitmap *DuplicateBitmapL(TInt aHandle)=0;
1.302 + /** Creates and duplicates a font from a handle.
1.303 +
1.304 + This function might be used to duplicate client side fonts on the server side.
1.305 +
1.306 + @param aHandle A handle to the font to be duplicated.
1.307 + @return A pointer to the duplicate font. */
1.308 + virtual CFbsFont *DuplicateFontL(TInt aHandle)=0;
1.309 + /** Closes a duplicate font.
1.310 +
1.311 + @param Pointer to the duplicate font.
1.312 + @see DuplicateFontL() */
1.313 + virtual void CloseFont(CFbsFont *)=0;
1.314 + /** Gets a reference to the calling client's thread.
1.315 +
1.316 + @return A reference to the calling client's thread. */
1.317 + virtual const RThread &Client()=0;
1.318 + virtual void ReplyBuf(const TDesC8 &aDes)=0; // Reply a buffer to the client
1.319 + virtual void ReplyBuf(const TDesC16 &aDes)=0; // Reply a buffer to the client
1.320 + /** Panics the client.
1.321 +
1.322 + This will result in the client thread being destroyed. */
1.323 + virtual void Panic() const=0;
1.324 + //Event functions
1.325 + /** Switches animation raw event handling on and off.
1.326 +
1.327 + If raw event handling is switched on, then raw events, e.g. pointer, key, or power events
1.328 + are all offered to the animation event handling code's MEventHandler::OfferRawEvent().
1.329 +
1.330 + @param aGetEvents If ETrue, raw events are passed to the animation
1.331 + event handling code. If EFalse, events are not passed to the animation. */
1.332 + virtual void GetRawEvents(TBool aGetEvents) const=0;
1.333 + /** Posts a raw event, just as if it had come from the kernel.
1.334 +
1.335 + @param aRawEvent The raw event */
1.336 + virtual void PostRawEvent(const TRawEvent &aRawEvent) const=0;
1.337 + /** Posts a key event.
1.338 +
1.339 + The function is similar to PostRawEvent() but should be
1.340 + used for posting key events.
1.341 +
1.342 + @param aRawEvent The key event. */
1.343 + virtual void PostKeyEvent(const TKeyEvent &aRawEvent) const=0;
1.344 + /** Get the address of an object which can retrieve information from and send
1.345 + information to the client-side.
1.346 +
1.347 + @return A pointer to RMessagePtr2. Complete must be called on the returned object (or a
1.348 + copy of it) if and only if Message is called from an override of CAnim's CommandReplyL which
1.349 + has been caused by a client-side RAnim::AsyncCommandReply call. If Message is called outside
1.350 + an override of CAnim's CommandReplyL or outside an override of CWindowAnim's ConstructL or
1.351 + CSpriteAnim's ConstructL, the it returns NULL.
1.352 + @see RMessagePtr2 */
1.353 + virtual const RMessagePtr2* Message()=0; // replaces Reserved1
1.354 + /**Returns an extension interface, maybe extended further in the future.
1.355 + @param aInterfaceId The ID of the interface to return.
1.356 + @return A pointer to the extension interface.
1.357 + When aInterface=0 (ENumberOfExtendedInterfaces), the number of interfaces is returned (currently 2).
1.358 + When aInterface=1 (EWindowExtensionInterface), a pointer to the Window Extension interface is returned.
1.359 + When aInterface=2 (EEventExtentionInterface), a pointer to the Event Extension interface is returned.
1.360 + */
1.361 + virtual TAny* ExtendedInterface(TInt aInterface)=0; // replaces Reserved2
1.362 +
1.363 + /** Register to receive notifications.
1.364 + @param aNotifications A bitset of TAnimNotifications values indicating which notifications are required
1.365 + @return One of the system wide error codes
1.366 + */
1.367 + virtual TInt RegisterForNotifications(TUint32 aNotifications)=0;
1.368 + /*
1.369 + Return number of ExtendedInterfaces. */
1.370 + inline TInt NumberOfExtendedInterfaces()
1.371 + {
1.372 + return reinterpret_cast<TInt>(ExtendedInterface(ENumberOfExtendedInterfaces));
1.373 + }
1.374 + /** Gets access to Window Extension utility functions.
1.375 + @return A pointer to a class containing functions for working with Window. */
1.376 + inline MAnimGeneralFunctionsWindowExtension* WindowExtension()
1.377 + {
1.378 + return static_cast<MAnimGeneralFunctionsWindowExtension*>(ExtendedInterface(EWindowExtensionInterface));
1.379 + }
1.380 + /** Gets access to EventExtension utility functions.
1.381 + @return A pointer to a class containing functions for working with Event. */
1.382 + inline MAnimGeneralFunctionsEventExtension* EventExtension()
1.383 + {
1.384 + return static_cast<MAnimGeneralFunctionsEventExtension*>(ExtendedInterface(EEventExtentionInterface));
1.385 + }
1.386 + private:
1.387 + virtual void Reserved1() const;
1.388 + virtual void Reserved2() const;
1.389 + virtual void Reserved3() const;
1.390 + };
1.391 +
1.392 +/* Structure for passing window configuration information. Currently transparancey
1.393 +related configuration information is supported, though this may be added to, as
1.394 +apprioriate.
1.395 +
1.396 +@publishedAll
1.397 +@released
1.398 +*/
1.399 +class TWindowConfig
1.400 + {
1.401 +public:
1.402 + /** Transparency flags.
1.403 +
1.404 + Used to represent transparency configuration of the window. */
1.405 + enum
1.406 + {
1.407 + /** Transparency is enabled on the window. */
1.408 + ETransparencyEnabled=0x0001,
1.409 + /** Window transparency uses alpha blending channel. */
1.410 + EAlphaBlendedTransparency=0x0002,
1.411 + };
1.412 +public:
1.413 + /** Indicate configuration of window, using enumerations defined within this class. */
1.414 + TInt iFlags;
1.415 +private:
1.416 + TInt iReserved0;
1.417 + TInt iReserved1;
1.418 + TInt iReserved2;
1.419 + };
1.420 +
1.421 +class MAnimGeneralFunctionsWindowExtension
1.422 +/** General Window utility functions interface.
1.423 +
1.424 +The member functions define the interface for querying and manipulating
1.425 +the window and screen attributes.
1.426 +
1.427 +You obtain one by calling: iFunctions->ExtendedInterface(MAnimGeneralFunctions::EWindowExtensionInterface)
1.428 +and casting the result.
1.429 +
1.430 +It is not intended for user derivation.
1.431 +
1.432 +@publishedAll
1.433 +@released */
1.434 + {
1.435 +public:
1.436 + /** Class contains the information pertaining to a window group: name, priority,
1.437 + focusability. */
1.438 + class TWindowGroupInfo
1.439 + {
1.440 + public:
1.441 + enum
1.442 + {
1.443 + /** Window is focusable flag. */
1.444 + EIsFocusable=0x0001,
1.445 + };
1.446 + public:
1.447 + /** Returns whether or not the window is focusable.
1.448 + @return ETrue if focusable, else returns EFalse. */
1.449 + inline TBool IsFocusable() const {return iFlags&EIsFocusable;}
1.450 + public:
1.451 + /* Window group attributes. */
1.452 + TInt iId;
1.453 + TUint32 iFlags;
1.454 + TInt iOrdinalPriority;
1.455 + TInt iNameLength;
1.456 + TInt iParentId;
1.457 + };
1.458 +public:
1.459 + /** Returns the total number of screens.
1.460 + @return The total number of screens. */
1.461 + virtual TInt Screens() const=0;
1.462 +
1.463 + /** Returns the number of the screen which is currently in focus.
1.464 + @return The number of the screen which is currently in focus.*/
1.465 + virtual TInt FocusScreens() const=0;
1.466 +
1.467 + /** Changes the focused screen.
1.468 + @param aScreenNo New screen number. */
1.469 + virtual void SetFocusScreen(TInt aScreenNo)=0;
1.470 +
1.471 + /** Returns the number of window groups available for the specified screen.
1.472 +
1.473 + @param aScreen The screen number.
1.474 + @return The number of window groups. */
1.475 + virtual TInt WindowGroups(TInt aScreen) const=0;
1.476 +
1.477 + /** Takes a screen number and an ordinal position and returns the complete window
1.478 + group information of the specified window. If the window group does not exist, the
1.479 + function returns EFalse.
1.480 +
1.481 + Note: the ordinal position specified should be the total or full ordinal position
1.482 + of all group windows of all priorities on that screen.
1.483 +
1.484 + @param aInfo on return, complete window information.
1.485 + @param aScreen Screen number.
1.486 + @param aFullOrdinalPosition Ordinal position of the window.
1.487 + @return ETrue if window group information exists, EFalse otherwise. */
1.488 + virtual TBool WindowGroupInfo(TWindowGroupInfo& aInfo,TInt aScreen,TInt aFullOrdinalPosition) const=0;
1.489 +
1.490 + /** Takes a screen number and an ordinal position and returns the window group name.
1.491 + If the window group does not exist, the function returns false.
1.492 +
1.493 + Note: the ordinal position specified should be the total or full ordinal position of
1.494 + all group windows of all priorities on that screen.
1.495 +
1.496 + Note: if the name does not fit into the descriptor provided then it will be truncated.
1.497 +
1.498 + @param aWindowName On return, the window group name.
1.499 + @param aScreen The screen number.
1.500 + @param aFullOrdinalPosition The ordinal position of the window.
1.501 + @return ETrue if the window group name exists, EFalse otherwise. */
1.502 + virtual TBool WindowGroupName(TPtrC& aWindowName,TInt aScreen,TInt aFullOrdinalPosition) const=0;
1.503 +
1.504 + /** Changes the ordinal position and priority of the window group with the specified ID.
1.505 +
1.506 + @param aWindowGroupId The window group ID.
1.507 + @param aPos The ordinal position to move the window to.
1.508 + @param aOrdinalPriority The new ordinal priority of the window.
1.509 + @return KErrNotFound if there is no window group with the specified ID, KErrNone otherwise. */
1.510 + virtual TInt SetOrdinalPosition(TInt aWindowGroupId,TInt aPos,TInt aOrdinalPriority)=0;
1.511 +
1.512 + /** Accessor for window configuration.
1.513 +
1.514 + @param aWindowConfig Gets filled in with window configuration details. */
1.515 + virtual void WindowConfig(TWindowConfig& aWindowConfig) const=0;
1.516 +
1.517 +private:
1.518 + virtual void Reserved1() const;
1.519 + virtual void Reserved2() const;
1.520 + virtual void Reserved3() const;
1.521 + };
1.522 +
1.523 +class MAnimGeneralFunctionsEventExtension
1.524 +/** Event utility functions interface.
1.525 +
1.526 +The member functions define the interface for generate repeated key events .
1.527 +
1.528 +It is not intended for user derivation.
1.529 +*/
1.530 + {
1.531 +public:
1.532 + /** Posts a key event.
1.533 +
1.534 + The function is similar to PostKeyEvent() but should be
1.535 +used for posting repeated key events.
1.536 +
1.537 + @param aRawEvent The key event.
1.538 + @param aRepeats value */
1.539 + virtual void PostKeyEvent(const TKeyEvent& aRawEvent, TInt aRepeats) const=0;
1.540 +
1.541 +private:
1.542 + virtual void Reserved1() const;
1.543 + virtual void Reserved2() const;
1.544 + };
1.545 +
1.546 +class MAnimWindowFunctions
1.547 +/** Window utility functions interface.
1.548 +
1.549 +The member functions define the interface for querying and manipulating
1.550 +the window in which the animation takes place.
1.551 +
1.552 +You do not have to create an object of this type. The class is implemented
1.553 +by the window server, and provides these utility functions to all CWindowAnim
1.554 +and CFreeTimerWindowAnim derived classes via the iWindowFunctions pointer.
1.555 +
1.556 +It is not intended for user derivation.
1.557 +
1.558 +@publishedAll
1.559 +@released */
1.560 + {
1.561 +public:
1.562 + /** Activates the graphics context.
1.563 +
1.564 + This function should be called to enable drawing in the CAnim-derived classes'
1.565 + Command(), CommandReplyL(), Animate(), or FocusChanged() functions.
1.566 +
1.567 + Note: this function is called automatically by the animation DLL framework in the
1.568 + Redraw() function. */
1.569 + virtual void ActivateGc()=0;
1.570 + /** Sets the rectangle that this animation is to draw to.
1.571 +
1.572 + This function must be called as part of the initialisation/construction of
1.573 + the CAnim-derived object, i.e. in CAnim::ConstructL(). This is so that the
1.574 + window server knows which area the animation is operating in.
1.575 +
1.576 + @param aRect The rectangle to be drawn to. */
1.577 + virtual void SetRect(const TRect &aRect)=0;
1.578 + /** Gets the window size.
1.579 +
1.580 + @return The window size, in pixels. */
1.581 + virtual TSize WindowSize() const=0;
1.582 + /** Tests whether to draw the animation.
1.583 +
1.584 + If the window is completely hidden, there is normally no need to draw
1.585 + the animation. However in some conditions the animation should be drawn even
1.586 + if it is obscured. The window server is aware of these cases, and returns
1.587 + ETrue if it is not safe to draw the animation.
1.588 +
1.589 + @return True if the window is completely hidden and there is no requirement
1.590 + to continue drawing the animation, otherwise false. */
1.591 + virtual TBool IsHidden()=0;
1.592 + /** Sets the visibility of the window the animation is drawing to.
1.593 +
1.594 + This does the same as RWindowBase::SetVisible().
1.595 +
1.596 + @param aState True for visible, false otherwise. */
1.597 + virtual void SetVisible(TBool aState)=0;
1.598 + /** Forces a redraw of a rectangular part of the window.
1.599 +
1.600 + The function causes a redraw message on the part of the window specified,
1.601 + which provides a non-immediate way to do drawing.
1.602 +
1.603 + It can be used to redraw the whole of the window, not just the part used by
1.604 + the animation.
1.605 +
1.606 + @param aRect The rectangle to be redrawn. These co-ordinates are relative
1.607 + to the origin of the window. */
1.608 + virtual void Invalidate(const TRect &aRect)=0;
1.609 + /** Gets window information.
1.610 +
1.611 + @param aData The window information. */
1.612 + virtual void Parameters(TWindowInfo &aData)=0;
1.613 + /** Gets the visible region.
1.614 +
1.615 + This region is the area of the visible window which
1.616 + is currently unshadowed. If there is not enough memory to calculate this region
1.617 + then aRegion's error flag is set.
1.618 +
1.619 + @param aRegion The visible region. */
1.620 + virtual void VisibleRegion(TRegion& aRegion)=0;
1.621 + //virtual void CopyScreen(CFbsBitGc *aBitmapGc,TRect aRect)=0;
1.622 +private:
1.623 + virtual void Reserved() const;
1.624 + virtual void Reserved1() const;
1.625 + virtual void Reserved2() const;
1.626 + virtual void Reserved3() const;
1.627 + };
1.628 +
1.629 +
1.630 +class MAnimFreeTimerWindowFunctions : public MAnimWindowFunctions
1.631 +/** Free timer animation utility functions interface.
1.632 +
1.633 +The class inherits functions from MAnimWindowFunctions, and defines the additional
1.634 +interface required for window operations which support animations with their
1.635 +own timers.
1.636 +
1.637 +You do NOT have to create an object of this type. The class is implemented
1.638 +by the window server, and provides utility functions to all CFreeTimerWindowAnim
1.639 +derived classes via the WindowFunctions() member.
1.640 +
1.641 +It is not intended for user derivation.
1.642 +
1.643 +@publishedAll
1.644 +@released */
1.645 + {
1.646 +public:
1.647 + /** Deactivates the graphics context.
1.648 +
1.649 + This function is used in the context of a CFreeTimerWindowAnim derived class
1.650 + when writing animation DLLs with their own timer. Within the timer's RunL(),
1.651 + the ActivateGc() function should be called prior to drawing to the window.
1.652 + DeactivateGc() should be called after drawing is finished. */
1.653 + virtual void DeactivateGc()=0;
1.654 + /** Forces the screen to update. */
1.655 + virtual void Update()=0;
1.656 +private:
1.657 + virtual void Reserved3() const;
1.658 + };
1.659 +
1.660 +class MAnimSpriteFunctions
1.661 +/** Sprite animation utility functions interface.
1.662 +
1.663 +The interface includes functions for querying and manipulating a sprite.
1.664 +
1.665 +You do NOT have to create an object of this type. The class is implemented
1.666 +by the window server, and provides utility functions to all CSpriteAnim derived
1.667 +classes via the CSpriteAnim::iSpriteFunctions pointer.
1.668 +
1.669 +It is not intended for user derivation.
1.670 +
1.671 +@publishedAll
1.672 +@released */
1.673 + {
1.674 +public:
1.675 + /** Gets sprite member data.
1.676 +
1.677 + Each member of the sprite is effectively a bitmap, which is displayed for a
1.678 + different amount of time.
1.679 +
1.680 + @param aMember The index of the sprite member for which information is required.
1.681 + @return A pointer to the sprite member. */
1.682 + virtual TSpriteMember *GetSpriteMember(TInt aMember) const=0;
1.683 + /** Redraws part of a sprite.
1.684 +
1.685 + WSERV1:
1.686 +
1.687 + The updates a sprite on the screen, possibly after the bitmap for a particular
1.688 + sprite member has been changed.
1.689 +
1.690 + Two types of redraw are possible. A full update takes the bitmap off the screen
1.691 + and then re-draws it. This is 'safe' in that the screen always reflects
1.692 + the contents of the sprite bitmap. However it can result in flicker. Use the
1.693 + aRect parameter to specify the (small) part of the sprite which has been changed,
1.694 + then any flicker will only occur in this rectangle.
1.695 +
1.696 + A full update is required if you have removed pixels from the mask, i.e. made
1.697 + pixels in the sprite transparent when they were not before. If drawing is
1.698 + additive, e.g. you are using a mask or the draw mode is EDrawModePEN, a partial
1.699 + update is possible. Otherwise the aFullUpdate argument is ignored and a full
1.700 + update is always done.
1.701 +
1.702 + Note: if the sprite member aMember is not visible then there is no need for a change
1.703 + to the display, so the aRect and aFullUpdate parameters are ignored.
1.704 +
1.705 + param aMember The index of the sprite member that is to be updated.
1.706 + param aRect The part of the sprite member which has changed.
1.707 + param aFullUpdate ETrue for a full update, EFalse otherwise.
1.708 +
1.709 + WSERV2:
1.710 +
1.711 + Updates a sprite on the screen, possibly after the bitmap for a particular
1.712 + sprite member has been changed.
1.713 +
1.714 + Use the aRect parameter to specify the (small) part of the sprite which has been changed,
1.715 + then any flicker will only occur in this rectangle.
1.716 +
1.717 + A full update used to be required if you had removed pixels from the mask, i.e. made
1.718 + pixels in the sprite transparent when they were not before. If drawing is
1.719 + additive, e.g. you are using a mask or the draw mode is EDrawModePEN, a partial
1.720 + update used to be possible. But newer versions of the window-server always do full back to front rendering.
1.721 +
1.722 + Note: if the sprite member aMember is not visible then there is no need for a change
1.723 + to the display, so the aRect and aFullUpdate parameters are ignored.
1.724 +
1.725 + @param aMember The index of the sprite member that is to be updated.
1.726 + @param aRect The part of the sprite member which has changed.
1.727 + @param aFullUpdate Not used. Wserv now always do full back to front rendering. */
1.728 + virtual void UpdateMember(TInt aMember,const TRect& aRect,TBool aFullUpdate)=0;
1.729 + /** Turns a sprite on or off.
1.730 +
1.731 + In effect this makes the sprite bitmap visible.
1.732 +
1.733 + @param aActive ETrue to turn sprite on. EFalse to turn it off. */
1.734 + virtual void Activate(TBool aActive)=0;
1.735 + /** Finishes constructing the sprite.
1.736 +
1.737 + It also sets the currently displayed sprite member to zero.
1.738 +
1.739 + This function must be called after members change size. */
1.740 + virtual void SizeChangedL()=0;
1.741 + /** Set the sprite's position.
1.742 +
1.743 + @param aPos The new position of the sprite. */
1.744 + virtual void SetPosition(const TPoint &aPos)=0;
1.745 +private:
1.746 + virtual void Reserved() const;
1.747 +public:
1.748 + /** Returns the visibility of the sprite.
1.749 +
1.750 + A sprite can be seen if it is neither obscured by another window nor hidden.
1.751 +
1.752 + @return ETrue if the sprite can be seen, EFalse otherwise. */
1.753 + virtual TBool SpriteCanBeSeen() const = 0;
1.754 +private:
1.755 + virtual void Reserved2() const;
1.756 + virtual void Reserved3() const;
1.757 + virtual void Reserved4() const;
1.758 + };
1.759 +
1.760 +
1.761 +class CAnimGc : public CBitmapContext
1.762 +/** Animation graphics context.
1.763 +
1.764 +An object of this type is linked into CAnim by the window server, which allows
1.765 +you to draw to the animation window. The object's functions allow you to set
1.766 +and cancel the clipping region, and to draw to the visible window using
1.767 +the inherited CBitmapContext functions.
1.768 +
1.769 +@publishedAll
1.770 +@released */
1.771 + {
1.772 +public:
1.773 + /** Sets the clipping region.
1.774 +
1.775 + Only the parts of the animation which are within the clipping region are drawn.
1.776 +
1.777 + @param aRegion The clipping region. */
1.778 + virtual TInt SetClippingRegion(const TRegion &aRegion)=0;
1.779 + /** Cancels the clipping region.
1.780 +
1.781 + @see SetClippingRegion() */
1.782 + virtual void CancelClippingRegion()=0;
1.783 + };
1.784 +
1.785 +class CWsAnim; // Forward ref for friend declaration
1.786 +
1.787 +
1.788 +class CAnim : public CBase , public MEventHandler
1.789 +/** Server side animated object base interface.
1.790 +
1.791 +Animations implement this interface, which is called by the window server
1.792 +to pass commands from clients, perform a step in the animation, or to pass
1.793 +window server events (if required) so that the animation can handle them
1.794 +before the application.
1.795 +
1.796 +The functions are all pure virtual, and must be implemented in
1.797 +the derived class to provide server side behaviour. The functions will be
1.798 +called by the window server with optional arguments passed in from the client
1.799 +side animation class RAnim.
1.800 +
1.801 +You should derive from CWindowAnim, CFreeTimerWindowAnim or CSpriteAnim,
1.802 +depending on whether the animation is to draw to a sprite or a window,
1.803 +rather than directly from this class.
1.804 +
1.805 +The derived class is constructed in the DLL factory class CAnimDll::CreateInstanceL()
1.806 +function.
1.807 +
1.808 +The operation to perform an animation step is called by the window server
1.809 +on a timer. The timing properties are set through an MAnimGeneralFunctions
1.810 +member, which also provides other utility functions.
1.811 +
1.812 +@publishedAll
1.813 +@released */
1.814 + {
1.815 +public:
1.816 + /** Implements client-side initiated commands, returning a value.
1.817 +
1.818 + The window server calls this function in response to application calls to
1.819 + the client side command function RAnim::CommandReplyL(). The arguments passed
1.820 + to the function by the window server are the same as were used on the client
1.821 + side function call.
1.822 +
1.823 + This function returns values to the client side, and should be used to return
1.824 + error codes for commands which might leave.
1.825 +
1.826 + @param aOpcode Opcode understood by the class.
1.827 + @param aArgs Arguments packaged on the client side, for example as a struct
1.828 + of a type determined by the aOpcode argument. These mirror the aArgs argument
1.829 + passed in to RAnim::CommandReply().
1.830 + @return Value passed back to client side function when this function completes.
1.831 + Typically this would be KErrNone or another of the system-wide error codes.
1.832 + However any value may be returned to the client side.
1.833 + @see RAnim */
1.834 + virtual TInt CommandReplyL(TInt aOpcode, TAny *aArgs)=0;
1.835 + /** Implements client-side initiated commands.
1.836 +
1.837 + The window server calls this function in response to application calls to
1.838 + the client side command function RAnim::Command(). The arguments passed to
1.839 + the function by the window server are the same as were used on the client
1.840 + side function call.
1.841 +
1.842 + Because this function does not return errors, it is not safe for commands
1.843 + which might leave.
1.844 +
1.845 + @param aOpcode Opcode understood by the class
1.846 + @param aArgs Arguments packaged on the client side, for example as a struct
1.847 + of a type determined by the aOpcode argument. These mirror the aArgs argument
1.848 + passed in to RAnim::Command().
1.849 + @see RAnim */
1.850 + virtual void Command(TInt aOpcode, TAny *aArgs)=0;
1.851 + /** Main animation function, called by the window server.
1.852 +
1.853 + The drawing code which implements a given animation should be provided here.
1.854 +
1.855 + This function is called at a frequency determined by the SetSync() helper
1.856 + function. Note that if sync is not set, then this function will never be
1.857 + called. This effect can be exploited to use the animation framework, with
1.858 + its server side speed, for what are strictly not animations, e.g. for streaming
1.859 + video images.
1.860 +
1.861 + The aDateTime parameter will be null if the current time (as determined by
1.862 + the window server) matches the time implied by the sync period, modulo normalisation,
1.863 + otherwise it will contain a valid (non-normalised) time.
1.864 +
1.865 + Normalisation is to some specified granularity, for example if one minute
1.866 + is specified as the animation frequency, then in effect the window server
1.867 + will decide whether the implied time is correct to the minute, but not to
1.868 + the second.
1.869 +
1.870 + Implied time is the time implied by the (normalised) actual time of the previous
1.871 + animation call plus the sync interval. For example if the last call was at
1.872 + time 't' and the sync interval is 1 second then if the time at this call
1.873 + is t + 1 second, then actual time and implied time match and the value placed
1.874 + into aDateTime will be NULL.
1.875 +
1.876 + Cases in which the two may not match include, for example, system time having
1.877 + been reset between animation calls (perhaps British Summer Time or other daylight
1.878 + saving time has just come into effect). The intention is that when system
1.879 + time changes, a mechanism is provided to alert the animation code and allow
1.880 + it to reset itself. The assumption is that somewhere in its initialisation
1.881 + code, the animation will have performed a CAnimFunctions utility call to set
1.882 + a base time, which is then implicitly tracked by incrementing by a suitable
1.883 + interval; when aDateTime is non-NULL after a call to Animate(), base time
1.884 + should be reset.
1.885 +
1.886 + @param aDateTime Null if the current time w.r.t. the window server matches
1.887 + the time implied by the synch period. Otherwise a valid (non-normalised) time. */
1.888 + virtual void Animate(TDateTime *aDateTime)=0;
1.889 + virtual void HandleNotification(const TWsEvent& /*aEvent*/) {};
1.890 +private:
1.891 + inline CAnim() {}
1.892 + virtual void Reserved1() const {};
1.893 + virtual void Reserved2() const {};
1.894 + virtual void Reserved3() const {};
1.895 +protected:
1.896 + /** Pointer to a class containing functions implemented by the window server.
1.897 +
1.898 + These are available to any CAnim derived class.
1.899 +
1.900 + Note that this value is automatically set for you by the animation framework.
1.901 + You do not need to assign a value to this pointer.
1.902 + @publishedAll
1.903 + @released */
1.904 + MAnimGeneralFunctions *iFunctions;
1.905 + friend class CWsAnim;
1.906 + friend class CWindowAnim;
1.907 + friend class CSpriteAnim;
1.908 + };
1.909 +
1.910 +
1.911 +class CWindowAnim : public CAnim
1.912 +/** Window animation interface.
1.913 +
1.914 +This interface is provided to create animations other than sprites. A window
1.915 +animation can be provided by deriving from this class.
1.916 +
1.917 +The interface inherits from CAnim and has access to its functions. It additionally
1.918 +can access an interface for querying and manipulating the window in which
1.919 +the animation takes place, using its iWindowFunctions member.
1.920 +
1.921 +The derived class is constructed in the DLL factory class CAnimDll::CreateInstanceL().
1.922 +
1.923 +@publishedAll
1.924 +@released
1.925 +@see CFreeTimerWindowAnim
1.926 +@see CSpriteAnim */
1.927 + {
1.928 +public:
1.929 + /** Server side construction and initialisation of an animation class.
1.930 +
1.931 + Note: the aHasFocus argument allows the animation to start in a known focus state.
1.932 + For example, an animation may or may not have focus, depending on how it was
1.933 + started. Together with the FocusChanged() function, this allows an animation
1.934 + to always know its focus state.
1.935 +
1.936 + @param aArgs Packaged arguments which may be required during construction.
1.937 + These are transferred from the aParams argument of the client side constructor's
1.938 + RAnim::Construct().
1.939 + @param aHasFocus Specifies whether or not the animation has window server focus. */
1.940 + virtual void ConstructL(TAny *aArgs, TBool aHasFocus)=0;
1.941 + /** Redraws the objects.
1.942 +
1.943 + The function is called by the window server when it needs to redraw the object.
1.944 + The object must provide all the low level drawing code. */
1.945 + virtual void Redraw()=0;
1.946 + /** Notifies change of focus.
1.947 +
1.948 + The function is called by the window server to notify a change of focus,
1.949 + allowing the animation code to track whether it does or does not have focus,
1.950 + and to change its appearance accordingly.
1.951 +
1.952 + @param aState Indicates whether the focus has or has not changed. */
1.953 + virtual void FocusChanged(TBool aState)=0;
1.954 +protected:
1.955 + /** Protected constructor.
1.956 +
1.957 + Prevents objects of this class being directly constructed. */
1.958 + inline CWindowAnim() {}
1.959 +private:
1.960 + virtual void ReservedW1() const {};
1.961 + virtual void ReservedW2() const {};
1.962 +protected:
1.963 + /** Pointer to a class containing functions implemented by the window server.
1.964 +
1.965 + These are available to any CWindowAnim-derived class.
1.966 +
1.967 + Note that this and the iGc pointer are automatically set for you by the
1.968 + animation framework - you do not need to assign a value to them.*/
1.969 + MAnimWindowFunctions *iWindowFunctions;
1.970 + /** Pointer to the graphics context. */
1.971 + CAnimGc *iGc;
1.972 + friend class CWsAnim;
1.973 + };
1.974 +
1.975 +
1.976 +class CFreeTimerWindowAnim : public CWindowAnim
1.977 +/** Free timer animation interface.
1.978 +
1.979 +This interface allows animations to have their own timers or other active
1.980 +objects, and to draw to the window when the timer completes. The implication
1.981 +of this is that animations derived from this class can have an extremely short
1.982 +user-defined time between calls to the Animate() function, unlike the
1.983 +other animation classes, which are tied to the (approximately) half second
1.984 +flash cycle.
1.985 +
1.986 +The interface inherits from CWindowAnim and has access to its functions. It
1.987 +additionally can access functions declared in the MAnimFreeTimerWindowFunctions
1.988 +interface, using WindowFunctions().
1.989 +
1.990 +In order to draw to the window inside the RunL() of your own timer, you will
1.991 +need call the ActivateGc() function before doing any drawing, and the DeactivateGc()
1.992 +function after finishing the drawing.
1.993 +
1.994 +@publishedAll
1.995 +@released
1.996 +@see CSpriteAnim */
1.997 + {
1.998 +protected:
1.999 + inline MAnimFreeTimerWindowFunctions* WindowFunctions()
1.1000 + /** Gets the free timer utility functions.
1.1001 +
1.1002 + These functions include all the MAnimWindowFunctions,
1.1003 + and additional functions to deactivate the graphics context and to force the
1.1004 + screen to update.
1.1005 +
1.1006 + @return A pointer to the free timer utility functions. */
1.1007 + {return STATIC_CAST(MAnimFreeTimerWindowFunctions*,iWindowFunctions);}
1.1008 +private:
1.1009 + virtual void ReservedF1() const {};
1.1010 + };
1.1011 +
1.1012 +
1.1013 +class CSpriteAnim : public CAnim
1.1014 +/** Sprite animation interface.
1.1015 +
1.1016 +Sprites are bitmaps that can overlay a window or the screen. A sprite animation
1.1017 +can be provided by deriving from this class.
1.1018 +
1.1019 +The interface inherits from CAnim and has access to its functions. It additionally
1.1020 +can access an interface for querying and manipulating a sprite, using its
1.1021 +iSpriteFunctions member.
1.1022 +
1.1023 +The derived class is constructed in the DLL factory class CAnimDll::CreateInstanceL()
1.1024 +function.
1.1025 +
1.1026 +@publishedAll
1.1027 +@released
1.1028 +@see CFreeTimerWindowAnim
1.1029 +@see CWindowAnim */
1.1030 + {
1.1031 +public:
1.1032 + /** Server side construction and initialisation of an animation class.
1.1033 +
1.1034 + @param aArgs Packaged arguments which may be required during construction.
1.1035 + These are transferred from the aParams argument of the client side constructor's
1.1036 + RAnim::Construct(). */
1.1037 + virtual void ConstructL(TAny *aArgs)=0;
1.1038 +protected:
1.1039 + inline CSpriteAnim()
1.1040 + /** Protected constructor.
1.1041 +
1.1042 + Ensures that only derived classes can be constructed. */
1.1043 + {}
1.1044 +private:
1.1045 + virtual void ReservedS1() const {};
1.1046 + virtual void ReservedS2() const {};
1.1047 +protected:
1.1048 + /** Pointer to a class containing functions implemented by the window server.
1.1049 +
1.1050 + These are available to any CSpriteAnim-derived class.
1.1051 +
1.1052 + Note that this value is automatically set for you by the animation framework.
1.1053 + You do not need to assign a value to this pointer. */
1.1054 + MAnimSpriteFunctions *iSpriteFunctions;
1.1055 + friend class CWsAnim;
1.1056 + };
1.1057 +
1.1058 +
1.1059 +class CAnimDll : public CBase
1.1060 +/** Animation DLL factory interface.
1.1061 +
1.1062 +An animation DLL class must be a derived class of CAnimDll, and can be thought
1.1063 +of as a server side factory class. CAnimDll consists of a single pure virtual
1.1064 +factory function, CreateInstanceL(TInt aType), which is used to create new
1.1065 +instances of animation objects of type CAnim contained in the DLL. Animation
1.1066 +DLL objects are created by the CreateCAnimDllL() function, which is called
1.1067 +by the window server at the request of the client.
1.1068 +
1.1069 +For efficiency reasons, it makes sense to collect multiple animation classes
1.1070 +into a single DLL, even if they are otherwise logically quite separate classes.
1.1071 +
1.1072 +@publishedAll
1.1073 +@released */
1.1074 + {
1.1075 +public:
1.1076 + /** Factory function for animation DLLs.
1.1077 +
1.1078 + It must be provided in the derived class.
1.1079 +
1.1080 + The parameter can be used to differentiate between multiple animation
1.1081 + classes contained in the same animation DLL.
1.1082 +
1.1083 + @param aType Identifies an animation class to be constructed. This is the
1.1084 + same value as the aType argument of the client side animation constructor
1.1085 + RAnim::Construct(). It is passed from the client side by the animation framework.
1.1086 + @return Pointer to a CAnim-derived animation class object. */
1.1087 + virtual CAnim *CreateInstanceL(TInt aType)=0;
1.1088 + };
1.1089 +
1.1090 +#endif