1 aknview.h

     1 /*

     2 * Copyright (c) 2002 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * 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

     6 * which accompanies this distribution, and is available

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

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description: 

    15 *

    16 */

    17 

    18 // AknView.h

    19 //

    20 // Copyright (c) 1997-2001 Symbian Ltd.  All rights reserved.

    21 //

    22 

    23 #ifndef AKNVIEW_H

    24 #define AKNVIEW_H

    25 

    26 //  INCLUDES

    27 #include <babitflags.h>

    28 #include <coecntrl.h>

    29 #include <eikmobs.h>

    30 #include <coeaui.h>

    31 #include <coeview.h>

    32 #include <eikdef.h>

    33 #include <coemop.h>

    34 

    35 // FORWARD DECLARATIONS

    36 class CAknViewAppUi;

    37 class CEikStatusPane;

    38 class CEikButtonGroupContainer;

    39 class CAknControlStack;

    40 class CAknViewExtension;

    41 class CAknToolbar;

    42 

    43 // CLASS DECLARATION

    44 

    45 /**

    46  * This is an abstract base class for a Series 60 application view.

    47  *

    48  * @since Series 60 0.9

    49  */

    50 class CAknView : public CBase, public MCoeView, public MEikMenuObserver, 

    51                 public MObjectProvider

    52 	{

    53 public:

    54 

    55     /** 

    56      * Standard constructor.

    57      */

    58 	IMPORT_C CAknView();

    59 

    60     /** 

    61      * Standard destructor.

    62      */	

    63 	IMPORT_C ~CAknView();

    64 

    65     /** 

    66      * This is a second stage constructor initializing this view with standard 

    67      * values. Should be called from derived classes second stage construction

    68      * functions.  

    69      * @param aResId The numeric ID of the resource (@c iViewInfo) to be read. 

    70      *        If aResId=0, resource file is not accessed.

    71      */

    72 	IMPORT_C void BaseConstructL(TInt aResId=0);

    73 	

    74     /** 

    75      * Constructs invisible button group container and menu if they don't exist

    76      * yet. They are placed on the view stack. To be used by views which need 

    77      * to access the menu or cba before the view is activated for the first 

    78      * time.

    79      */	

    80 	IMPORT_C void ConstructMenuAndCbaEarlyL();		

    81 

    82     /** 

    83      * Activate any view in the product. Calls @c CCoeAppUi::ActivateViewL(

    84      * aViewId)

    85      * @param aViewId Identifies the view to activate.

    86      */

    87 	IMPORT_C void ActivateViewL(const TVwsViewId& aViewId);

    88 

    89     /** 

    90      * Activate any view, then passes the message text @c aCustomMessage of 

    91      * type @c aCustomMessageId. Calls @c CCoeAppUi::ActivateViewL(

    92      * aViewId,aCustomMessageId,aCustomMessage) 

    93      * @param aViewId Identifies the view to activate.

    94      * @param aCustomMessageId Specifies the message type.

    95      * @param aCustomMessage The message passed to the activated view.

    96      */

    97 	IMPORT_C void ActivateViewL(const TVwsViewId& aViewId,

    98 	                            TUid aCustomMessageId,

    99 	                            const TDesC8& aCustomMessage);

   100 

   101     /**

   102     * Returns views id, intended for overriding by sub classes.

   103     * @return id for this view.

   104     */

   105 	IMPORT_C virtual TUid Id() const =0;

   106 

   107     /** 

   108      * Event handler for status pane size changes.

   109      * @c CAknView provides an empty implementation for sub classes that do 

   110      * not want to handle this event.

   111      */

   112 	IMPORT_C virtual void HandleStatusPaneSizeChange();

   113 

   114     /** 

   115      * From @c MCoeView. The full view Id for this view. Calls @c Id()

   116      * @return View identification number.

   117      */

   118 	IMPORT_C TVwsViewId ViewId() const;

   119 

   120 	/** 

   121      * From @c MEikMenuObserver. This function processes user commands by 

   122      * handling @c aCommand values @c EAknSoftkeyOptions, @c EAknCmdExit, 

   123      * @c EEikCmdCanceled and passing the others to @c HandleCommandL() 

   124      * for sub class to decide the actions.  

   125      * @param aCommand ID of the command to respond to. 

   126      */	 

   127 	IMPORT_C virtual void ProcessCommandL(TInt aCommand);

   128 

   129     /** 

   130      * Command handling function intended for overriding by sub classes. 

   131      * Default implementation is empty.  

   132      * @param aCommand ID of the command to respond to. 

   133      */

   134 	IMPORT_C virtual void HandleCommandL(TInt aCommand);

   135 

   136     /** 

   137      * Menu bar accessor method. This returns the views menu if available, 

   138      * otherwise it returns the applications menu bar.

   139      * @return  @c CEikMenuBar pointer to views menu bar.

   140      */

   141 	IMPORT_C virtual CEikMenuBar* MenuBar() const;

   142 

   143 	/** 

   144      * Calculates the client rectangle of the view, taking the applications 

   145      * client rectangle and the views CBA into account.

   146      * Calls @c CEikAppUi::ClientRect() 

   147      * @return @c TRect the area of the screen available to the application 

   148      *          for drawing.

   149      */

   150 	IMPORT_C TRect ClientRect() const;

   151 

   152     /** 

   153      * This function causes the menu bar to disappear from the screen until it

   154      * is invoked again by the user.

   155      * Calls @c CEikAppUi::StopDisplayingMenuBar().

   156      */

   157 	IMPORT_C void StopDisplayingMenuBar();

   158 

   159     /** 

   160      * Determines whether the application is foreground. 

   161      * @return @c ETrue if view is foreground.

   162      */

   163 	IMPORT_C TBool IsForeground() const;

   164 

   165     /**

   166     * Called by the framework when view's rectangle changes. The default

   167     * implementation is empty. This function is not used yet.

   168     * @since Series 60 3.0

   169     */

   170     IMPORT_C virtual void HandleViewRectChange();

   171 	

   172     /**

   173     * Asks the view to redraw its area. Needs to be implemented only by

   174     * views used in split view architecture. The default implementation is

   175     * empty. This function is not used yet.

   176     * @since Series 60 3.0

   177     */

   178     IMPORT_C virtual void Redraw() const;

   179 

   180 

   181     /** 

   182      * Avkon view architecture system. Internal use only.

   183      * Calls @c DoActivateL.

   184      */	 

   185 	IMPORT_C virtual void AknViewActivatedL(const TVwsViewId& aPrevViewId,

   186 	                                        TUid aCustomMessageId,

   187 	                                        const TDesC8& aCustomMessage);

   188 

   189     /** 

   190      * Avkon view architecture system. Internal use only. Function is called 

   191      * by @c CAknViewAppUi::~CAknViewAppUi() for immediate view deactivation. 

   192      * Calls @c DoDeactivate.     

   193      */  

   194 	void AknViewDeactivated();

   195 

   196     /** 

   197      * Avkon view architecture system. Internal use only.

   198      */ 

   199 	void ProcessForegroundEventL(TBool aForeground);

   200 

   201 private: // formerly from @c MTopSetMember<CEikMenuBar>

   202 	IMPORT_C virtual void Reserved_MtsmPosition();

   203 	IMPORT_C virtual void Reserved_MtsmObject();

   204 

   205 protected:

   206 

   207     /** 

   208      * Accessor for the applications user interface as a @c CAknViewAppUi.

   209      * @return Pointer to user interface instance.

   210      */

   211 	IMPORT_C CAknViewAppUi* AppUi() const;

   212 

   213     /** 

   214      * Status pane accessor method.

   215      * @return Pointer to status pane. 

   216      */

   217 	IMPORT_C CEikStatusPane* StatusPane() const;

   218 

   219     /** 

   220      * Button group container (=CBA) accessor method. 

   221      * This returns the views CBA if there is one, and the applications user 

   222      * interfaces CBA otherwise.

   223      * @return Pointer to @c CEikButtonGroupContainer.

   224      */

   225 	IMPORT_C CEikButtonGroupContainer* Cba() const;

   226 

   227     /** 

   228      * Handles a view activation and passes the message of type 

   229      * @c aCustomMessageId. This function is intended for overriding by 

   230      * sub classes. This function is called by @c AknViewActivatedL().

   231      * Views should not launch waiting or modal notes or dialogs in

   232      * @c DoActivateL.

   233      * @param aPrevViewId Specifies the view previously active.

   234      * @param aCustomMessageId Specifies the message type.

   235      * @param aCustomMessage The activation message.

   236      */

   237 	IMPORT_C virtual void DoActivateL(const TVwsViewId& aPrevViewId,

   238 	                                  TUid aCustomMessageId,

   239 	                                  const TDesC8& aCustomMessage) = 0;

   240 

   241     /** 

   242      * View deactivation function intended for overriding by sub classes. 

   243      * This function is called by @c AknViewDeactivated().

   244      */

   245 	virtual void DoDeactivate() = 0;

   246 

   247 protected: // From MCoeView.

   248 

   249     /** 

   250      * From @c MCoeView. Takes any action required when this view is activated.

   251      * Handles this view activation event from view server. Calls 

   252      * @c CAknViewAppUi::ViewActivatedL()

   253      * @param aPrevViewId Specifies the view previously active.

   254      * @param aCustomMessageId Specifies the message type.

   255      * @param aCustomMessage Activation message.

   256      */

   257 	IMPORT_C void ViewActivatedL(const TVwsViewId& aPrevViewId,

   258 	                             TUid aCustomMessageId,

   259 	                             const TDesC8& aCustomMessage);

   260 

   261     /** 

   262      * From @c MCoeView. Takes any action that is required following 

   263      * deactivation of this view. Handles this view deactivation event from

   264      * viewserver. Calls @c CAknViewAppUi::ViewDeactivated()

   265      */

   266 	IMPORT_C void ViewDeactivated();

   267 

   268     /** 

   269      * From @c MCoeView. Screen device changed function from viewserver.

   270      * @return TVwsViewIdAndMessage created with default values.

   271      */

   272 	IMPORT_C TVwsViewIdAndMessage ViewScreenDeviceChangedL();

   273 

   274 protected: // from MObjectProvider

   275 

   276     /** 

   277      * From @c MObjectProvider. Gets an (@c MAknsControlContext) object whose 

   278      * type is encapsulated by the specified TTypeUid object. Calls 

   279      * @c SupplyMopObject( @c TTypeUid aId, 

   280      *      @c CEikButtonGroupContainer* iCba, @c CEikMenuBar* iMenu ). 

   281      * @param aId Encapsulates the @c Uid that identifies the type of object 

   282      *         required. 

   283      * @return Pointer to the @c MAknsControlContext object provided. Note that

   284      *          the pointer may be @c NULL. 

   285      */

   286 	IMPORT_C TTypeUid::Ptr MopSupplyObject(TTypeUid aId);

   287 

   288     /** 

   289      * From @c MObjectProvider. Gets the parent object provider.   

   290      * @return Pointer to the parent object provider (@c MObjectProvider) that

   291      *          is @c CAknViewAppUi* iAppUi, or @c NULL.

   292      */

   293 	IMPORT_C MObjectProvider* MopNext();

   294 

   295 protected: // From MEikMenuObserver.

   296 

   297     /** 

   298      * From @c MEikMenuObserver. Menu emphasising or de-emphasising function. 

   299      * @c CEikMenuBar objects call this on their observer. Updates the value of

   300      * the flags for the (@c aMenuControl) on the control stack. 

   301      * @param aMenuControl The control to be emphasised or de-emphasisied.

   302      * @param aEmphasis @c ETrue to emphasize the menu, @c EFalse to refuse the

   303      *          focus.

   304      */

   305 	IMPORT_C virtual void SetEmphasis(CCoeControl* aMenuControl,

   306 	                                  TBool aEmphasis);

   307 

   308     /** 

   309      * From @c MEikMenuObserver. Foreground event handling function intended 

   310      * for overriding by sub classes.  

   311      * @param aForeground Indicates the required focus state of the control.

   312      */	

   313 	IMPORT_C virtual void HandleForegroundEventL(TBool aForeground);

   314 

   315 private: // internal functions

   316 	void ConstructMenuAndCbaL(TBool aVisible);

   317 

   318 	/**

   319 	* Asserts that extension class object exists.

   320 	* @return Extension object.

   321 	*/

   322 	CAknViewExtension* Extension() const;

   323 	

   324 public: // new functions

   325 

   326     /**

   327 	* @since Series 60 3.1

   328 	* @return toolbar object.

   329 	*/

   330 	IMPORT_C CAknToolbar* Toolbar() const;

   331 	

   332 	/** 

   333      * This function causes toolbar to be hidden

   334      * @since Series 60 3.1

   335      */

   336 	IMPORT_C void StopDisplayingToolbar();

   337     

   338     /** 

   339      * Determines if the toolbar of this view is shown when the view is 

   340      * activated. 

   341      * @since S60 3.2

   342      * @return ETrue if toolbar is shown. 

   343      */

   344     IMPORT_C TBool ToolbarShownOnViewActivation() const; 

   345  

   346     /** 

   347      * Sets toolbar visibility status of this view according to value given. 

   348      * The value is used when view is activated. 

   349      * @since S60 3.2

   350      * @param aVisible to determine if toolbar should be shown. 

   351      */

   352     IMPORT_C void ShowToolbarOnViewActivation( TBool aVisible ); 

   353 

   354     /** 

   355      * Saves toolbar status of this view according to values given. 

   356      * The values are used when view is activated. 

   357      * @since S60 3.2

   358      * @param aVisible to determine if toolbar should be shown. 

   359      * @param aFocused ETrue if toolbar is focused, EFalse if not

   360      */

   361     void SaveToolbarStatus( TBool aVisible, TBool aFocused ); 

   362 

   363     /** 

   364      * Sets new toolbar for the view. Deletes old toolbar. If the old toolbar 

   365      * was shown before deleting, then the new toolbar will also be shown.

   366      * @since S60 5.0

   367      * @param aToolbar pointer to new toolbar

   368      */

   369     IMPORT_C void SetToolbar( CAknToolbar* aToolbar ); 

   370 

   371     /** 

   372      * Creates a new toolbar object with the resource id given and sets it for

   373      * the view. Deletes old toolbar. If the old toolbar was shown before

   374      * deleting, then the new toolbar will also be shown.  

   375      * @since S60 5.0

   376      * @param aResourceId Resource id of the new toolbar

   377      */

   378     IMPORT_C void CreateAndSetToolbarL( TInt aResourceId ); 

   379 

   380 		

   381 protected:  // Data

   382 	// The follow object is not owned by this class. iCoeEnv is protected in 

   383 	// keeping with @c CCoeAppUi & @c CCoeControl

   384 	CCoeEnv* iCoeEnv;

   385 

   386 private:

   387 	CAknViewAppUi* iAppUi;

   388 

   389 	// @c SAknViewInfo is the C++ image of resource structure AVKON_VIEW

   390 	struct SAknViewInfo

   391 		{

   392 	public:

   393         TUint8 iVersion;    // resource struct version

   394 		TInt iHotKeys;		// resource id

   395 		TInt iMenu;			// resource id

   396 		TInt iCba;			// resource id

   397         TInt iToolbar;      // resource id

   398         TInt iExtension;    // resource id

   399 		};

   400 

   401 	// The following member data are owned by this class

   402 	SAknViewInfo iViewInfo;

   403 	CEikMenuBar* iMenu;

   404 	CEikButtonGroupContainer* iCba;

   405 	TBitFlags iFlags;

   406     CAknViewExtension* iExtension;

   407 	};

   408 

   409 #endif      // AKNVIEW_H