mainpage.dox

Animation Client/Server Symbian 程序.

 *
 * Note that the Command and CommandReply functions of the RAnim class are
 * protected, therefore anything deriving from this will need to publish a
 * public function to make these functions publicly accessible.
 *
 * The Close function requests the animation server free all the resources
 * belonging to an object.
 *
 * \subsection Sub432 4.3.2 Using the animation client
 *
 * This section describes a simple use case scenario for the Animation Client.
 * It demonstrates the Animation Client objects being:
 *
 * - Constructed
 * - Used to load and start the animation server, which starts the bouncing
 *   square animation
 * - Resetting the animation, so that the bouncing square jumps back to the
 *   top-left corner and moves off again
 * - Closed
 *
 * \subsection Sub4321 4.3.2.1 Construction
 *
 * Construction of an animation client is shown in the sequence diagram below.
 *
 * \image html client_seq1.jpg
 *
 * -# An animation client DLL object is created. A Window Server session is
 *    passed to it, so that the DLL is able to attach an animation server to
 *    this Window Server session.
 * -# An instance of RImageCommander is Constructed. The Constructor is passed a
 *    reference to an animation client DLL. In this example this is the
 *    RClientDll object created by (1).
 * -# To load a server-side animation DLL, Load is called upon the RClientDll
 *    object. This is passed the filename of the animation server DLL to load.
 *    Note that it is not necessary to put the DLL file extension on this
 *    filename. The location of the animation server DLL file may be different
 *    in the emulator and target builds.
 * -# A Window Server is loaded.
 * -# The Window Server creates an animation DLL object.
 * -# The client-side RImageCommander object is used to create an instance of
 *    the server-side CImage class. This is achieved by calling ImageConstruct.
 * -# The RImageCommander calls RAnim::Construct.
 * -# The RImageCommander constructs the image.
 * -# This causes the Window Server to call CServerDll::CreateInstanceL, and
 *    passes it an argument indicating what type of image should be created. A
 *    single instance of CServerDll may be used to create multiple animation
 *    images.
 * -# An instance of CImage is then Constructed.
 *
 * \subsection Sub4322 4.3.2.2 Sending a command
 *
 * Having successfully Constructed a server-side image, the user may wish to
 * send commands to it. In this example, the Reset command is sent to restart
 * animation at the top left of the display. This is achieved using the
 * ImageCommand function, and is shown in the sequence diagram below.
 *
 * \image html client_seq2.jpg
 *
 * -# The user selects Reset from the Options menu.
 * -# The RImageCommander calls RAnim::Command.
 * -# The RImageCommander then sends a message to the Window Server.
 * -# Sometime later the Window Server calls the Command function of the
 *    server-side CImage class, and passes an argument that indicates the type
 *    of command required. For this example this is set to KAnimationReset,
 *    which resets the animation.
 *
 * \subsection Sub4323 4.3.2.3 Destruction
 *
 * The final stage is when the image object needs to be destroyed and the
 * animation server closed down. This is done by calling Close operations on the
 * RImageCommander and RClientDll objects. The correct sequence is shown in the
 * diagram below.
 *
 * \image html client_seq3.jpg
 *
 * -# RImageCommander::Close is called.
 * -# The RImageCommander instructs the Window Server to destroy the relevant
 *    server-side CImage object.
 * -# The Window Server destroys the relevant server-side CImage object.
 * -# Once all the server-side images has been destroyed, the server-side DLL
 *    can be unloaded. This is achieved by calling RClientDll::Close.
 * -# The RClientDll instructs the Window Server to unload and destroy the
 *    server-side animation DLL.
 * -# The Window Server unloads and destroys the server-side animation DLL.
 *
 * \subsection Sub44 4.4 The animation server
 *
 * This section describes two possible implementations of the animation server.
 * The difference between them is the mechanism used to determine when each
 * individual image in the animation sequence is drawn. The two implementations
 * use, respectively:
 *
 * - The Window Server
 * - A timer
 *
 * The first implementation has the restriction that the image can't be redrawn
 * at a rate greater than twice per second, the rate set by a Window Server
 * limitation. The second implementation is more complicated than the first, but
 * has the advantage that the upper limit to the redraw rate is higher.
 *
 * Both implementations incorporate the two classes, CServerDll and CImage. The
 * second implementation has two extra timer classes, CTimeoutTimer and
 * MTimeoutNotify.
 *
 * \subsection Sub441 4.4.1 The animation server class hierarchy
 *
 * The classes necessary to create an animation server are summarised in the UML
 * class diagram below.
 *
 * \image html server_class.jpg
 *
 * An instance of CImage corresponds to a specific animated image on the screen.
 * In this example, it calculates the position for the bouncing square, and
 * draws it.
 *
 * An instance of CServerDll is a 'factory' object, which creates a new instance
 * of CImage. The two classes have to present a specific interface to the Window
 * Server, which they derive from two Symbian OS classes CAnimDll and CAnim. The
 * CreateCAnimDllL function is used to create the CServerDll object.
 *
 * \subsection Sub442 4.4.2 Animation server with restricted redraw rate
 *
 * There are four main tasks that have to be performed for the server-side
 * animation to work. These are:
 *
 * - Load and start the animation server.
 * - Start the bouncing square animation.
 * - Reset the running animation, so that the bouncing square jumps back to the
 *   top-left corner, and moves off again.
 * - Close the animation and the animation server.
 *
 * Loading and Constructing the animation server has already been discussed in
 * The animation client section. This section focuses on what occurs once the
 * animation server has been Constructed. The diagram below shows the events
 * that occur from the point where the CImage object is created, to when the
 * first call to Animate is made.
 *
 * \image html server_sync.jpg
 *
 * -# SetSync is called on the Window Server. This specifies the redraw rate of
 *    the image.
 * -# After a specified time, determined by the redraw rate, the Window Server
 *    calls the Animate function on the CImage object. Animate calculates the
 *    position of the bouncing square.
 * -# It then calls the Invalidate function, which informs the Window Server
 *    that the display needs to be updated.
 * -# The Window Server calls Redraw on all the animated objects that have been
 *    invalidated (in this case, there is only the CImage object).
 * -# The pen colour is set to white.
 * -# The Redraw function overwrites the last animation position with a white
 *    rectangle. This effectively erases the previous image.
 * -# The pen colour is set to black.
 * -# A rectangle is drawn at the new position calculated by (2).
 *
 * Steps 2 - 8 are repeated at the Redraw rate. With the limitations of the
 * Window Server, this occurs a maximum rate of twice a second.
 *
 * \subsection Sub443 4.4.3 Animation server with less restricted redraw rate
 *
 * The second implementation, where there is a higher upper limit to the redraw
 * rate, incorporates some extra member functions and variables in CImage, and
 * two extra classes, CTimeoutTimer and MTimeoutNotify. The UML class diagram
 * below shows the relationships between the CAnimDll and CImage classes and
 * various Symbian OS classes, and the timer classes.
 *
 * \image html server_async.jpg
 *
 * An instance of CTimeoutTimer is an active object, which can be programmed to
 * timeout after a specific interval. When it does time out, it calls the
 * TimedOut function on an 'observer' object. The timer observer must be
 * registered with the timer when the timer is created. The object must also be
 * an instance of a class derived from the mixin class MTimeoutNotify.
 *
 * Here, the registered observer is the CImage object, and so the timer calls
 * TimedOut on this. This, in turn calls Animate and puts a Redraw into effect.
 * The process is illustrated in more detail in the UML sequence diagram below.
 *
 * \image html server_async_seq.jpg
 *
 * -# The CImage object calls SetSync on the Window Server, with an argument
 *    ESyncNone. ESyncNone specifies that the Window Server should not initiate
 *    Animate calls on CImage.
 * -# The CImage object creates the CTimeoutTimer object.
 * -# It then calls the After function on it, which instructs it to call
 *    TimedOut on CImage after a set period of time has elapsed.
 * -# After the set period of time has elapsed, the timer calls TimedOut on
 *    CImage.
 * -# The CImage calls the After function, to schedule the next redraw period.
 * -# CImage calls the Window Server's Animate function.
 * -# This results in CImage::Animate being called. Note that it is not possible
 *    to call CImage::Animate directly, as the Window Server needs to perform
 *    some initialisation first.
 * -# Animate first calculates the position of the bouncing square. It then
 *    calls the animation Invalidate function, which informs the Window Server
 *    that the display needs to be updated.
 * -# The Window Server calls Redraw on all the animated objects that have been
 *    invalidated (in this case there is only the CImage object).
 * -# The pen colour is set to white.
 * -# The Redraw function overwrites the last animation position with a white
 *    rectangle. This effectively erases the previous image.
 * -# The pen colour is set to black.
 * -# A rectangle is drawn at the new position, calculated by (2).
 *
 * After the set period of time has elapsed, the timer calls TimedOut on CImage.
 * The whole redraw process is then repeated. By changing the timer period, it
 * is possible to alter how often the square is redrawn. Care should be
 * exercised, however, because if the timer period is too short then animation
 * can become jerky as the image is moved. This is because there is not
 * sufficient time to draw the new position before the square is moved again.
 * Note that the timer resolutions for the emulator and target builds are
 * different: 1/10 of a second for the emulator, and 1/64 of a second for the
 * target. Also, the target is able to cope with a much lower timer period (i.e.
 * more frequent redraws) than the emulator before it starts to have trouble
 * drawing the image.
 *
 * \subsection Sub45 4.5 Animation client classes R-Type Construction
 *
 * One slightly unusual feature of the Animation application is that the
 * animation client DLL and image commander classes are both R-Type classes.
 * This means that the objects these classes control are actually owned
 * elsewhere, in this case by the Window Server. Because these classes are
 * R-Types, their instances are Constructed automatically by their containing
 * object's Constructor. However, the Constructors need to take certain
 * parameters, in order to Construct correctly. The passing of these parameters
 * to the Constructor is achieved by explicitly calling the R-Type class's
 * Constructor in the owning class's Constructor list. An example of this is
 * shown when the GUI application UI Constructs the animation client.
 *
 * The Constructor performs the following tasks:
 *
 * - Call the base class Constructor for the UI.
 * - Call the Constructor for the animation client DLL (RAnimDll derived) class,
 *   passing it a reference to a Window Server session.
 * - Call the Constructor for the animation client image commander (RAnim
 *   derived) class, passing it a reference to the animation client DLL object
 *   Constructed in the previous step.
 *
 * These objects need to be Constructed in this manner to avoid calling the
 * default Constructors, which would not initialise the objects correctly. The
 * order in which the two R Class objects are Constructed is very important, as
 * Construction of the image commander takes the client DLL as a parameter.
 * However, the order of Construction is defined by the order of the member
 * variables within the class definition, not the Constructor initialisation
 * list. Therefore, the class definition must declare these variables in the
 * correct order, for the Construction to work correctly.
 *
 * \subsection Sub46 4.6 Animation client classes R-Type destruction
 *
 * Because the Animation Client classes are R-Types, they are automatically
 * destroyed by the class that owns them, and there is no need to destroy them
 * explicitly in the destructor. It is necessary to free whatever resources they
 * might be using, however. This is done by calling the Close function on each
 * of the R-Type objects, as performed by the UI's destructor.
 *
 * \subsection Sub47 4.7 The MMP file
 *
 * Each Symbian OS application has an associated MMP file. The MMP file defines
 * such things as which source files are to be compiled, which libraries to be
 * linked, and so on. To create an animation server DLL, it is necessary to
 * specify the target type and UID in the MMP. These should be set to the values
 * shown below.
 *
 * \code
 * TARGETTYPE ani
 * UID 0x10003b22
 * \endcode
 *
 */