1 aknviewappui.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:  Base class for view architecture-based applications.

    15 *

    16 */

    17 

    18 #ifndef __AKNVIEWAPPUI_H__

    19 #define __AKNVIEWAPPUI_H__

    20 

    21 // INCLUDES

    22 #include <aknappui.h>

    23 

    24 // FORWARD DECLARATIONS

    25 class CAknView;

    26 class CAknViewShutter;

    27 class CAknLocalScreenClearer;

    28 class CAknViewAppUiExtension;

    29 class CAknViewNavigator;

    30 

    31 // MACROS

    32 #define iAvkonViewAppUi ((CAknViewAppUi*)CEikonEnv::Static()->EikAppUi())

    33 

    34 // CLASS DECLARATION

    35 

    36 /**

    37 *  Base class for view architecture-based applications.

    38 *

    39 *  @since Series 60 0.9

    40 */

    41 class CAknViewAppUi : public CAknAppUi

    42     {

    43 public:

    44 	NONSHARABLE_CLASS(CViewActivationItem) : public CBase

    45 		{

    46 	public:

    47 

    48         /**

    49         * Two-phased constructor.

    50         * @param aNewView Application view.

    51         * @param aCustomMessageId Message ID.

    52         * @param aCustomMessage Message contents.

    53         * @param aPrevViewId The UID of the previously active view.

    54         * @return Pointer to new @c CViewActivationItem object.

    55         */

    56 		static CViewActivationItem* NewLC(CAknView* aNewView, 

    57 		                                  TUid aCustomMessageId, 

    58 		                                  const TDesC8& aCustomMessage, 

    59 		                                  const TVwsViewId& aPrevViewId);

    60 		

    61 		/**

    62         * Destructor.

    63         */

    64 		~CViewActivationItem();

    65 	private:

    66 		CViewActivationItem(CAknView* aNewView, 

    67 		                    TUid aCustomMessageId,

    68 		                    const TVwsViewId& aPrevViewId);

    69 		                    

    70 		void ConstructL(const TDesC8& aCustomMessage);

    71 	public:

    72 		

    73 		// Application view.

    74 		CAknView* iNewView;

    75 		

    76 		// Message ID.

    77 		TUid iCustomMessageId;

    78 		

    79 		// Message contents.

    80 		HBufC8* iCustomMessage;

    81 		

    82 		// The UID of the previously active view.

    83 		TVwsViewId iPrevViewId;

    84 		};

    85 

    86         /**

    87         * Container class used to hold information about one split view.

    88         */

    89         NONSHARABLE_CLASS(TAknSplitViewContainer)

    90             {

    91             public:

    92                 /**

    93                 * Checks is a view is part of the split view.

    94                 * @param aViewId UID of the view to be checked.

    95                 * @return ETrue if the given view belongs to the split view.

    96                 */

    97                 TBool IsPartOf( const TUid aViewId );

    98 

    99             public:

   100                 // view uids

   101                 TUid iViewIds[2];

   102                 // ETrue if a view's activation failed

   103                 TBool iFailed[2];

   104                 // drawing areas

   105                 TRect iViewRect[2];

   106                 // the size of the leftmost view

   107                 TInt iLeftViewSize;

   108             };

   109 

   110     	typedef CArrayPtrFlat<CViewActivationItem> CAknViewActivationQueue;

   111     	typedef CArrayPtrFlat<CAknView> CAknViews;

   112 

   113 public:

   114 

   115     /**

   116     * Initialises this app UI with standard values.

   117     * @param aAppUiFlags Application user interface flags.

   118     */

   119 	IMPORT_C void BaseConstructL(TInt aAppUiFlags=EStandardApp);

   120 	

   121 	/**

   122     * Destructor.

   123     */

   124 	IMPORT_C virtual ~CAknViewAppUi();

   125     

   126     /**

   127     * Activates a specified application view, without passing any message.

   128     * The function leaves if activation of the view fails.

   129     * @param aViewId Identifier of the view to activate.

   130     */

   131 	IMPORT_C void ActivateLocalViewL(TUid aViewId);

   132 

   133     /**

   134     * Activates a specified application view, then passes the message text 

   135     * descriptor aCustomMessage for a message of type aCustomMessageId.

   136     * The function leaves if activation of the view fails.

   137     * @param aViewId Identifier of the view to activate.

   138     * @param aCustomMessageId Specifies the message type.

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

   140     */

   141 	IMPORT_C void ActivateLocalViewL(TUid aViewId, 

   142 	                                 TUid aCustomMessageId,

   143 	                                 const TDesC8& aCustomMessage);

   144 	

   145 	/**

   146     * Gets a pointer to specified application view.

   147     * @param aView ID of the application view.

   148     * @return Pointer to application view object, 

   149     * NULL if aView doesn't exists.

   150     */

   151 	IMPORT_C CAknView* View(TUid aView) const;

   152 	

   153 	/**

   154     * Registers and adds the view to the app UI. 

   155     * This function calls @c CCoeAppUi::RegisterViewL.

   156     * @param aView The view to be registered and added.

   157     */

   158 	IMPORT_C void AddViewL(CAknView* aView);	// takes ownership of aView

   159 

   160 	/**

   161     * Removes and deregisteres the view from the app UI. 

   162     * This function calls @c CCoeAppUi::DeregisterView.

   163     * @param aViewId The view to be deregistered and removed.

   164     */

   165 	IMPORT_C void RemoveView(TUid aViewId);

   166     

   167     /**

   168     * Processes user commands.

   169     * @param aCommand A command ID.

   170     */

   171 	IMPORT_C void ProcessCommandL(TInt aCommand);

   172 	

   173 	/**

   174     * Stops displaying the application’s menu bar.

   175     */

   176 	IMPORT_C void StopDisplayingMenuBar();

   177 

   178 	// Avkon view architecture system. Internal use only.

   179 	void ViewActivatedL(CAknView* aView, 

   180 	                    const TVwsViewId& aPrevViewId,

   181 	                    TUid aCustomMessageId,

   182 	                    const TDesC8& aCustomMessage);

   183 	

   184 	void ViewDeactivated(CAknView* aView);

   185 

   186     /**

   187     * Combines two views. If either of the views belongs to another view combination

   188     * then that combination is removed.

   189     * @since Series 60 5.0

   190     * @param aView1Id UID of the first (leftmost) view.

   191     * @param aView2Id UID of the second view.

   192     * @param aLeftViewSize Size of the first view (in percentages).

   193     */

   194     IMPORT_C void SetSplitViewL( const TUid aView1Id, const TUid aView2Id, const TInt aLeftViewSize );

   195 

   196     /**

   197     * Removes a view combination containing the given view UID. If the view

   198     * with the given UID is currently visible then the screen is switched to

   199     * single view and the the given view stays active.

   200     * @since Series 60 5.0

   201     * @param aViewId UID of a view combination.

   202     */

   203     IMPORT_C void RemoveSplitViewL( const TUid aViewId );

   204     	

   205     /**

   206     * Checks if split view is in use.

   207     * @since Series 60 5.0

   208     * @return ETrue if a split view is active.

   209     */

   210     IMPORT_C TBool SplitViewActive() const;

   211     	

   212     /**

   213     * Returns the currently focused view.

   214     * @since Series 60 5.0

   215     * @return UID of the currently focused view.

   216     */

   217     IMPORT_C TUid FocusedView() const;

   218     	

   219     /**

   220     * Checks if the given view is visible on the screen.

   221     * @since Series 60 5.0

   222     * @param aViewId View to be checked.

   223     * @return ETrue if the given view is visible.	

   224     */

   225     IMPORT_C TBool ViewShown( const TUid aViewId ) const;

   226     

   227     /**

   228     * Enables/disables local screen clearer.

   229     * Local screen clearer is used in the view based applications

   230     * to clear the application window if/when the view itself fails

   231     * to do this. By default, the clearer is used.

   232     * This function must be called before the BaseConstructL() to

   233     * prevent the screen clearer on application start up.

   234     *

   235     * @since 3.2 

   236     * @param aEnable ETrue enables local screen clearer.

   237     *                EFalse disables local screen clearer.

   238     */

   239     IMPORT_C void EnableLocalScreenClearer( TBool aEnable = ETrue );

   240     	

   241     /**

   242     * Returns view's rectangle.

   243     * @since Series 60 5.0

   244     * @param aViewId UID of the view whose rectangle should be returned.

   245     * @param Given view's drawing area.

   246     */

   247     TRect ViewRect( const TUid aViewId ) const;

   248     	

   249     /**

   250     * Handles keyboard initiated navigation between visible split views.

   251     * @since Series 60 5.0

   252     * @param aKeyEvent Keyboard event.

   253     * @param EKeyWasConsumed if view focus was changed.

   254     */

   255     TKeyResponse HandleViewNavigationL( const TKeyEvent& aKeyEvent );

   256     	

   257 protected:

   258 	

   259 	/**

   260     * From @c MEikStatusPaneObserver. Handles a change in the position or

   261     * size of the screen area occupied by the status pane.

   262     */

   263 	IMPORT_C void HandleStatusPaneSizeChange();

   264 

   265 	/**

   266     * From @c CCoeAppUi. Handles changes in keyboard focus when

   267     * an application switches to foreground.

   268     * @param aForeground @c ETrue if the application is in the foreground,

   269     * otherwise @c EFalse.

   270     */

   271 	IMPORT_C void HandleForegroundEventL(TBool aForeground);

   272 

   273     /**

   274     * From AknAppUi. Handles pointer-initiated view switch. Currently this

   275     * function does nothing but calls base class function.

   276     * @since Series 60 3.0

   277     * @param aEvent Window server event.

   278     * @param aDestination Pointer to the control which the event is targeted to.

   279     */

   280     IMPORT_C void HandleWsEventL( const TWsEvent& aEvent, CCoeControl* aDestination );

   281     	

   282 private:

   283 	static TInt ActivationCallBack(TAny* aThis);

   284 	void ActivationTick();

   285 	void QueueActivationTick();

   286 

   287     /**

   288     * Asserts that extension object has been created.

   289     * @return Extension object.

   290     */

   291     CAknViewAppUiExtension* Extension() const;

   292 

   293     /**

   294     * Activates views in split view.

   295     * @since Series 60 5.0

   296     * @param View under activation.

   297     */

   298     void ActivateSplitViewL( CViewActivationItem* aItem );

   299     	

   300     /**

   301     * If the given view is part of a split view then returns that split view,

   302     * @since Series 60 5.0

   303     * @param aViewId UID of a view that belongs to a split view.

   304     * @return Pointer to a correct split view or NULL if no corresponding split view was found.

   305     */

   306     TAknSplitViewContainer* SplitView( const TUid aViewId ) const;

   307     	

   308 protected:

   309 	

   310     // Application view.

   311     CAknView* iView;

   312 	

   313     // Application views.

   314     CAknViews* iViews;

   315 

   316 private:

   317     CAknViewShutter* iShutter;

   318     CAknLocalScreenClearer* iClearer;

   319     CAknViewActivationQueue* iActivationQueue;

   320     CIdle* iActivationTick;

   321     // extension class

   322     CAknViewAppUiExtension* iExtension;

   323     };

   324 

   325 #endif // __AKNVIEWAPPUI_H__