mainpage.dox

Animation Client/Server Symbian 程序.

/*! \mainpage Animation Example
 *
 * \ref Intro_sec
 * \n\ref Arch_sec
 * \n\ref UI_sec
 * \n\ref Design_sec
 *
 * <HR>
 *
 * \section Intro_sec 1. About this Example
 *
 * This tutorial explains the Animation application example, which is a simple,
 * but complete, application demonstrating the use of the animation
 * client/server architecture. The structure of the tutorial is based on the
 * architecture of the application, which is shown in the UML component diagram
 * below.
 *
 * \image html component.jpg
 *
 * The tutorial starts by listing the pre-requisites the user should know before
 * starting this example, and describes how to build and run the example. The
 * documentation goes on to discuss how to implement an animation client/server,
 * which is split into the following sections:
 *
 * - The application GUI.
 * - The animation client.
 * - The animation server.
 *
 * The example describes the basic principles of animation. It goes on to detail
 * the design and implementation of the GUI and the animation client. Two
 * different possible animation server implementations are described, one being
 * more complicated, but more flexible, than the other.
 *
 * In the example application a small square moves continuously across the
 * screen at a constant speed. Whenever it reaches the edge of the window, it
 * bounces off in another direction.
 *
 * The Options menu presents the user with two options, as follows:
 *
 * - Select \b Reset to return the square back to the top left corner of the
 *   display.
 * - Select \b Exit at any time, to exit the application.
 *
 * <HR>
 *
 * \subsection Sub11 1.1 Prerequisites
 *
 * This example exists as a complete application, and has the standard Symbian
 * OS application architecture employing the Application, Document, UI, and View
 * classes. The example makes use of several other Symbian OS concepts which the
 * reader should be aware of before attempting to understand this example. These
 * are:
 *
 * - Client/server architecture.
 * - Familiarity with the Window Server.
 * - How to draw to a graphics context.
 *
 * <HR>
 *
 *
 * \section UI_sec 2. User interface
 *
 * When the application starts up, the following screen appears.
 *
 * \image html animation1.jpg
 *
 * The small square moves continuously across the screen at a constant speed.
 * Whenever it reaches the edge of the window, it bounces off in another
 * direction.
 *
 * The \b Options menu presents the user with two options, as follows:
 *
 * \image html animation2.jpg
 *
 * - Select \b Reset to return the square back to the top left corner of the
 *   display.
 * - Select \b Exit at any time, to exit the application.
 *
 * \section Arch_sec 3. Architecture
 *
 * The application is split into a client and a server, with the server doing
 * the work of creating, controlling and deleting animated images directly, in
 * the same high priority process as the Window Server. The client simply acts
 * as a way for objects which are not in the same address space and thread as
 * the Window Server to create and control images via the server. Redrawing
 * images can be controlled by the Window Server, but this only allows a limited
 * choice of redraw rates. Using a timer active object provides a wider choice
 * of redraw rates.
 *
 *
 * \section Design_sec 4. Design and Implementation
 *
 * This section starts by giving an overview of the process required to animate
 * an image. It then details the design and implementation of each of the
 * following three components required to animate an image: the application GUI,
 * the animation client, and the animation server.
 *
 * \subsection Sub41 4.1 The animation process
 *
 * The image of the bouncing square is made to appear to move by repeatedly
 * being drawn, erased and redrawn at regularly spaced positions on the screen,
 * at regular time intervals. The frequency at which redraws are done is called
 * the redraw rate. Redraws could be invoked under the direct control of
 * application code, in the form of an active object regulated by a timer.
 * However, because this would run on the client-side of the Window Server, it
 * would suffer from the (relatively) lower priority of the client thread. Also,
 * active objects are not pre-emptively scheduled. This means that a window
 * update might be delayed or blocked altogether by another, already running,
 * client-side active object. This would result in a varying redraw rate, and
 * make the animation spasmodic, or stop it completely for a time.
 *
 * To achieve smoother animation, the drawing process can be controlled by the
 * Window Server itself, in conjunction with some special application objects
 * called the Animation Server. The Animation Server runs in the same thread as
 * the Window Server. It draws, erases and redraws individual still images, one
 * for each step of the animation, at intervals determined by the Window Server.
 * This is illustrated in the UML sequence diagram below.
 *
 * \image html general_seq1.jpg
 *
 * This is the first animation scenario, an animation server with restricted
 * redraw rate. The Window Server calls the Animate function on the Animation
 * Server at regular intervals. The Animate function can be programmed to erase
 * the existing image and draw the next one in the animation sequence. The
 * redraw rate is set by a call to the SetSync function on the Window Server,
 * just after the Animation Server is created.
 *
 * However, the Window Server only allows a limited choice of redraw rates. The
 * maximum rate is just two Animate calls per second. If a faster or
 * non-standard redraw rate is required, a more refined mechanism must be used.
 * One such refinement is illustrated by the UML sequence diagram below.
 *
 * \image html general_seq2.jpg
 *
 * This is the second animation scenario, an animation server with less
 * restricted redraw rate. Here the Animation Server has a built-in timer, which
 * periodically invokes a function in the Animation Server which calls the
 * Animate function on the Window Server. This, in turn, calls the Animate
 * function on the Animation Server, which erases the existing image and draws
 * the next one in the animation sequence. The process repeats at the rate
 * determined by the Animation Server's timer period. This is the animation
 * mechanism used in this example application.
 *
 * \subsection Sub42 4.2 The GUI package implementation
 *
 * This section describes a typical use case scenario for the Animation
 * application. The scenario is as follows:
 *
 * - A GUI is Constructed. This, in turn, creates an animation client DLL object
 *   and image commander object. These objects create an animation server DLL
 *   object, which starts the square bouncing around the screen.
 * - The user issues a Reset command, and the square is set back to the top left
 *   corner.
 * - The user closes the application, and all the animation client and server
 *   objects are closed and destroyed.
 *
 * \subsection Sub421 4.2.1 Construction
 *
 * GUI Construction is illustrated in the sequence diagram below.
 *
 * \image html gui_seq1.jpg
 *
 * -# The framework creates the GUI, which results in a call to the class
 *    Constructor.
 * -# Construction of the GUI causes the RClientDll object to be Constructed.
 * -# Construction of the GUI causes the RImageCommander object to be
 *    Constructed. Both RClientDll and RImageCommander classes are R-Type
 *    classes, which means they need special consideration when being
 *    Constructed and deleted. More information on how to Construct/destroy
 *    R-Type class objects is included in section 4.5 and section 4.6.
 * -# The framework calls the GUI ConstructL function to complete Construction.
 * -# SetUpClientDLL is called.
 * -# This, in turn, completes the Construction of the RClientDll object. Load
 *    is called on the RClientDll object and passed the name of the animation
 *    server to be loaded.
 * -# SetupImageCommander is called.
 * -# Calling SetupImageCommanderL results in a call to ImageConstruct upon the
 *    RImageCommander object, and completes Construction of the server-side
 *    image that will be animated.
 *
 * \subsection Sub422 4.2.2 Sending a command
 *
 * The next diagram illustrates the events that occur when the user selects
 * Reset from the Options menu.
 *
 * \image html gui_seq2.jpg
 *
 * -# The user interacts with the application, causing the HandleCommandL
 *    function to be called.
 * -# If \b Reset has been selected, the GUI informs the client by calling the
 *    ImageCommand function.
 *
 * \subsection Sub423 4.2.3 Destruction
 *
 * The final sequence diagram illustrates what occurs when the GUI objects are
 * destroyed.
 *
 * \image html gui_seq3.jpg
 *
 * -# The user closes the application.
 * -# The GUI destructor calls the Close function of the RClientDll object.
 * -# The GUI destructor calls the Close function of the RImageCommander object.
 * -# The RImageCommander object is destroyed.
 * -# The RClientDll object is destroyed.
 *
 * \subsection Sub43 4.3 The animation client
 *
 * The previous section has shown how the GUI manipulates the RClientDll and
 * RImageCommander objects. This section describes how these classes are
 * implemented in terms of the animation server. RClientDll and RImageCommander
 * provide client-side interfaces to the animation server, which allow the
 * user-interface code to (indirectly) control images on the server-side. The
 * animation server itself is described later.
 *
 * An instance of RClientDll is an object used to load and destroy the animation
 * server. An instance of RImageCommander is an object which can be used to
 * create, via the animation server, a new animated image. It can then be used
 * to dynamically control this image's behaviour. Typically, each different kind
 * of animated image requires an instance of RImageCommander to create,
 * manipulate and destroy it. RImageCommander instances must be created after
 * the RClientDll object.
 *
 * \subsection Sub431 4.3.1 The animation client class hierarchy
 *
 * The RClientDll and RImageCommander classes derive much of their functionality
 * from the Symbian OS classes RAnimDll and RAnim respectively. The UML class
 * diagram below shows the relationships between the animation client package
 * classes and the Symbian OS classes.
 *
 * \image html clientclass.jpg
 *
 * The RClientDll class is derived from the Symbian OS RAnimDll base class.
 * Every instance of RClientDll is linked to a Window Server session, that is an
 * instance of class RWsSession. This is the session that the animation server
 * will interact with when the server is loaded.
 *
 * The RImageCommander class is derived from the Symbian OS RAnim class. Every
 * instance of RImageCommander is attached to an instance of a RClientDll class.
 * The link is made when the RImageCommander object is created.
 *
 * RImageCommander derives three important functions from RAnim:
 *
 * - Construct
 * - Command
 * - Close
 *
 * The Construct function causes a new animation image to be created by the
 * animation server.
 *
 * The Command function passes a 'command', in the form of an integer operation
 * code, to the animation server. The animation server can be programmed to
 * interpret this in whatever way is appropriate. Typically, a command will
 * relate to dynamically controlling the animated image's behaviour.
 *
 * The Command function does not return a value, and is a buffered operation.
 * The fact that it does not return a value means that it should only be used
 * for actions that cannot leave or fail, because should the action fail, there
 * is no way for the server to signal this to the client. The fact that the
 * action is buffered means that completion of the action is asynchronous to the
 * request. This means a latency will be introduced between the request and an
 * action being performed.
 *
 * There is another RAnim function, CommandReply, which is similar to Command
 * but it does return a value, and is unbuffered. As this function returns a
 * value, it may be used for actions that can fail. Through the return value,
 * the client-side can be informed of any failures, and respond accordingly. The
 * fact that the action is unbuffered means that it will generally not return
 * until the requested action has been completed. For this reason, it is
 * recommended that any actions performed are relatively short.