mainpage.dox

演示如何使用Symbian系统的多视图（View）框架。

/*! \mainpage MultiViews Example
 *
 * \ref Intro_sec
 * \n\ref Arch_sec
 * \n\ref Design_sec
 *
 * <HR>
 *
 * \section Intro_sec 1. About this Example
 *
 * The MultiViews example demonstrates how to implement different user
 * interface views in an application, and how the different views can be
 * activated alternately at runtime.
 *
 * Each 'view' has:
 * - A Control Button Array (CBA) that defines the operation of the soft keys.
 * - A Menu bar, that is displayed on selecting the Options soft key.
 * - Operations which are invoked when the view is activated or deactivated.
 * - The ability to handle menu commands.
 * - A visual appearance on the display.
 *
 * \subsection Sub11 1.1 APIs demonstrated
 *
 * - CAknView
 * - CAknViewAppUi
 * - CCoeControl
 *
 * \subsection Sub12 1.2 Prerequisites
 *
 * The example makes use of the standard Symbian OS application framework
 * comprising the Application, Document, UI, and View classes. The reader
 * should be aware of this architecture before attempting to understand this
 * example.
 *
 * \subsection Sub13 1.3 Running this example
 *
 * When the application starts up, the following screen is displayed.
 *
 * \image html VIEW1.JPG
 *
 * The Options menu displays two choices, <b>Go to view 2</b> and <b>Exit</b>.
 *
 * \image html VIEW1_MENU.JPG
 *
 * - Select <b>Go to view 2</b> to switch to View 2.
 * - Select <b>Exit</b> at any time to exit the application.
 *
 * After selecting <b>Go to view 2</b> the screen below is displayed.
 *
 * \image html VIEW2.JPG
 *
 * The Options menu displays three choises.
 *
 * \image html VIEW2_MENU.JPG
 *
 * - Select <b>Go to View 1</b> to switch to View 1.
 * - Select <b>Say hello</b> to display a message box.
 * - Select <b>Exit</b> at any time to exit the application.
 *
 * Selecting <b>Say hello</b> displays the note shown on the following image.
 *
 * \image html VIEW2_COM1.JPG
 *
 * <HR>
 *
 * \section Arch_sec 2. Architecture
 *
 * This example exists as a complete application and has the Avkon
 * View-Switching architecture comprising the the Application, Document, UI,
 * and View classes.
 *
 * <HR>
 *
 * \section Design_sec 3. Design and Implementation
 *
 * The view properties listed in the \ref Intro_sec section are defined in
 * the Resource file, and the View and Container classes. The Resource file
 * contains entries of type AVKON_VIEW for each view. Each AVKON_VIEW
 * entry can define an Options menu bar and CBA keys. The View class is
 * derived from CAknView and defines the view activation and deactivation
 * behaviour, as well as the menu command handling. The Container class is
 * derived from CCoeControl. It is responsible for the drawing to the screen
 * and may contain other controls.
 *
 *
 * \subsection Sub31 3.1 Capabilities
 *
 * The application does not require any capabilities.
 * The program capabilities are defined in mmp-files as CAPABILITY NONE.
 *
 * \subsection Sub32 3.2 The resource file
 *
 * In this example the Resource file (MultiViews.rss) contains two
 * AVKON_VIEW entries, one for each view. The code snippets below show the
 * entries for the two views. The resource EIK_APP_INFO does not include
 * entries for the menu bar and CBA since this is defined on a per view basis.
 *
 * Resource entries for both views:
 * \code
 * RESOURCE EIK_APP_INFO
 * {
 * // no implementation required
 * }
 * .
 * .
 * .
 * RESOURCE AVKON_VIEW r_multiviews_view1
 * {
 * menubar = r_multiviews_menubar1;
 * cba = R_AVKON_SOFTKEYS_OPTIONS_EXIT;
 * }
 * .
 * .
 * .
 * RESOURCE AVKON_VIEW r_multiviews_view2
 * {
 * menubar = r_multiviews_menubar2;
 * cba = R_AVKON_SOFTKEYS_OPTIONS_EXIT;
 * }
 * \endcode
 *
 * \subsection Sub33 3.3 The View classes
 *
 * A view class defines objects which encapsulate such tasks as handling menu
 * options. The views' classes are defined in CMultiViewsView1
 * and CMultiViewsView2. The class hierarchy is illustrated in the following
 * diagram. The methods DoActivateL and DoDeactivate define the views'
 * activation and deactivation behaviour. HandleCommandL captures the menu
 * command invocations.
 *
 * MultiViews hierarchy diagram:
 * \image html VIEW_HIERARCHY.JPG
 *
 * \subsection Sub34 3.4 Container classes
 *
 * A container class defines objects which manage drawing to the screen. The
 * container's classes are defined in CMultiViewsContainer1 and
 * CMultiViewsContainer2 The class hierarchy is illustrated in the following
 * diagram.
 *
 * MultiViews container hierarchy:
 * \image html CONTAINER_HIERARCHY.JPG
 *
 * The Draw method draws the screen. In this example the containers simply
 * draw different coloured screens; in a more sophisticated example the
 * containers could be different dialogs. Switching between views is achieved
 * by calling ActivateLocalViewL on the CMultiViewsAppUi objects.
 *
 * \subsection Sub35 3.5 Creation and Activation of a View
 *
 * Normally an application's AppUI is derived from CAknAppUi. However, when
 * using CAknView it must be derived from CAknAppViewUi, because
 * CAknAppViewUi adds support for classes which are derived from
 * CAknView. The construction sequence of this class and the View classes
 * is illustrated in the sequence diagram below.
 * \image html CONSTRUCT.JPG
 *
 * -# The framework completes the construction of the App UI by calling its
 * ConstructL method.
 * -# The ConstructL method first calls the base class's BaseConstructL.
 * This performs such tasks as reading the resource file associated with the
 * application.
 * -# The application view CMultiViewsView1 is constructed, using the
 * standard Symbian OS two phase construction.
 * -# The construction sequence calls the base class's BaseConstructL. It
 * will read the R_MULTIVIEWS_VIEW1 resource defined for the view, as
 * described in the \ref Sub32 section.
 * -# The application view CMultiViewsView2 is constructed, using the
 * standard Symbian OS two phase construction.
 * -# The construction sequence calls the base class's BaseConstructL. It
 * will read the R_MULTIVIEWS_VIEW2 resource defined for the view.
 * -# AddViewL registers the view 1 with the AppUi.
 * -# AddViewL registers the view 2 with the AppUi.
 * -# SetDefaultViewL is called which will cause the specified view to be
 * activated on startup.
 * -# The framework calls the DoActivateL of view 1.
 * -# DoActivateL creates the Container object.
 *
 * Note that in order to receive key-related events, the application would have
 * to be modified as follows:
 *
 * - The containers would have to override the OfferKeyEventL method. The
 * body of this method would interpret the key event.
 * - After the call to NewL (message 11 above) the new container instance
 * would have be added to the App UI's control stack, by calling
 * AddToStackL.
 *
 * Also if the container contained other controls then it would be necessary to
 * call the container's method SetMopParent with the App Ui as parameter.
 *
 * \subsection Sub36 3.6 Command Invocation
 *
 * The following sequence diagram shows the sequence of events that occurs on
 * selecting the menu option to switch views.
 *
 * \image html DOACTIVATE.JPG
 *
 * -# Menu command Go To View 2 is selected and the view's HandleCommandL
 * method is called with the command parameter EMultiViewsSwitchToView2.
 * -# HandleCommandL calls ActivateLocalViewL with the id returned by
 * CMultiViewsView2::Id.
 * -# The framework calls the DoActivateL method of view 2.
 * -# The DoActivateL creates the Container 2 object.
 * -# The framework calls DoDeactivate on view 1.
 * -# DoDeactivate removes Container 1 from the app UI's control stack.
 * -# DoDeactivate deletes Container 1.
 *
 */