1.1 --- a/epoc32/include/mw/aknviewappui.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/mw/aknviewappui.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,325 @@
1.4 -aknviewappui.h
1.5 +/*
1.6 +* Copyright (c) 2002 Nokia Corporation and/or its subsidiary(-ies).
1.7 +* All rights reserved.
1.8 +* This component and the accompanying materials are made available
1.9 +* 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
1.10 +* which accompanies this distribution, and is available
1.11 +* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.12 +*
1.13 +* Initial Contributors:
1.14 +* Nokia Corporation - initial contribution.
1.15 +*
1.16 +* Contributors:
1.17 +*
1.18 +* Description: Base class for view architecture-based applications.
1.19 +*
1.20 +*/
1.21 +
1.22 +#ifndef __AKNVIEWAPPUI_H__
1.23 +#define __AKNVIEWAPPUI_H__
1.24 +
1.25 +// INCLUDES
1.26 +#include <aknappui.h>
1.27 +
1.28 +// FORWARD DECLARATIONS
1.29 +class CAknView;
1.30 +class CAknViewShutter;
1.31 +class CAknLocalScreenClearer;
1.32 +class CAknViewAppUiExtension;
1.33 +class CAknViewNavigator;
1.34 +
1.35 +// MACROS
1.36 +#define iAvkonViewAppUi ((CAknViewAppUi*)CEikonEnv::Static()->EikAppUi())
1.37 +
1.38 +// CLASS DECLARATION
1.39 +
1.40 +/**
1.41 +* Base class for view architecture-based applications.
1.42 +*
1.43 +* @since Series 60 0.9
1.44 +*/
1.45 +class CAknViewAppUi : public CAknAppUi
1.46 + {
1.47 +public:
1.48 + NONSHARABLE_CLASS(CViewActivationItem) : public CBase
1.49 + {
1.50 + public:
1.51 +
1.52 + /**
1.53 + * Two-phased constructor.
1.54 + * @param aNewView Application view.
1.55 + * @param aCustomMessageId Message ID.
1.56 + * @param aCustomMessage Message contents.
1.57 + * @param aPrevViewId The UID of the previously active view.
1.58 + * @return Pointer to new @c CViewActivationItem object.
1.59 + */
1.60 + static CViewActivationItem* NewLC(CAknView* aNewView,
1.61 + TUid aCustomMessageId,
1.62 + const TDesC8& aCustomMessage,
1.63 + const TVwsViewId& aPrevViewId);
1.64 +
1.65 + /**
1.66 + * Destructor.
1.67 + */
1.68 + ~CViewActivationItem();
1.69 + private:
1.70 + CViewActivationItem(CAknView* aNewView,
1.71 + TUid aCustomMessageId,
1.72 + const TVwsViewId& aPrevViewId);
1.73 +
1.74 + void ConstructL(const TDesC8& aCustomMessage);
1.75 + public:
1.76 +
1.77 + // Application view.
1.78 + CAknView* iNewView;
1.79 +
1.80 + // Message ID.
1.81 + TUid iCustomMessageId;
1.82 +
1.83 + // Message contents.
1.84 + HBufC8* iCustomMessage;
1.85 +
1.86 + // The UID of the previously active view.
1.87 + TVwsViewId iPrevViewId;
1.88 + };
1.89 +
1.90 + /**
1.91 + * Container class used to hold information about one split view.
1.92 + */
1.93 + NONSHARABLE_CLASS(TAknSplitViewContainer)
1.94 + {
1.95 + public:
1.96 + /**
1.97 + * Checks is a view is part of the split view.
1.98 + * @param aViewId UID of the view to be checked.
1.99 + * @return ETrue if the given view belongs to the split view.
1.100 + */
1.101 + TBool IsPartOf( const TUid aViewId );
1.102 +
1.103 + public:
1.104 + // view uids
1.105 + TUid iViewIds[2];
1.106 + // ETrue if a view's activation failed
1.107 + TBool iFailed[2];
1.108 + // drawing areas
1.109 + TRect iViewRect[2];
1.110 + // the size of the leftmost view
1.111 + TInt iLeftViewSize;
1.112 + };
1.113 +
1.114 + typedef CArrayPtrFlat<CViewActivationItem> CAknViewActivationQueue;
1.115 + typedef CArrayPtrFlat<CAknView> CAknViews;
1.116 +
1.117 +public:
1.118 +
1.119 + /**
1.120 + * Initialises this app UI with standard values.
1.121 + * @param aAppUiFlags Application user interface flags.
1.122 + */
1.123 + IMPORT_C void BaseConstructL(TInt aAppUiFlags=EStandardApp);
1.124 +
1.125 + /**
1.126 + * Destructor.
1.127 + */
1.128 + IMPORT_C virtual ~CAknViewAppUi();
1.129 +
1.130 + /**
1.131 + * Activates a specified application view, without passing any message.
1.132 + * The function leaves if activation of the view fails.
1.133 + * @param aViewId Identifier of the view to activate.
1.134 + */
1.135 + IMPORT_C void ActivateLocalViewL(TUid aViewId);
1.136 +
1.137 + /**
1.138 + * Activates a specified application view, then passes the message text
1.139 + * descriptor aCustomMessage for a message of type aCustomMessageId.
1.140 + * The function leaves if activation of the view fails.
1.141 + * @param aViewId Identifier of the view to activate.
1.142 + * @param aCustomMessageId Specifies the message type.
1.143 + * @param aCustomMessage The message passed to the activated view.
1.144 + */
1.145 + IMPORT_C void ActivateLocalViewL(TUid aViewId,
1.146 + TUid aCustomMessageId,
1.147 + const TDesC8& aCustomMessage);
1.148 +
1.149 + /**
1.150 + * Gets a pointer to specified application view.
1.151 + * @param aView ID of the application view.
1.152 + * @return Pointer to application view object,
1.153 + * NULL if aView doesn't exists.
1.154 + */
1.155 + IMPORT_C CAknView* View(TUid aView) const;
1.156 +
1.157 + /**
1.158 + * Registers and adds the view to the app UI.
1.159 + * This function calls @c CCoeAppUi::RegisterViewL.
1.160 + * @param aView The view to be registered and added.
1.161 + */
1.162 + IMPORT_C void AddViewL(CAknView* aView); // takes ownership of aView
1.163 +
1.164 + /**
1.165 + * Removes and deregisteres the view from the app UI.
1.166 + * This function calls @c CCoeAppUi::DeregisterView.
1.167 + * @param aViewId The view to be deregistered and removed.
1.168 + */
1.169 + IMPORT_C void RemoveView(TUid aViewId);
1.170 +
1.171 + /**
1.172 + * Processes user commands.
1.173 + * @param aCommand A command ID.
1.174 + */
1.175 + IMPORT_C void ProcessCommandL(TInt aCommand);
1.176 +
1.177 + /**
1.178 + * Stops displaying the application’s menu bar.
1.179 + */
1.180 + IMPORT_C void StopDisplayingMenuBar();
1.181 +
1.182 + // Avkon view architecture system. Internal use only.
1.183 + void ViewActivatedL(CAknView* aView,
1.184 + const TVwsViewId& aPrevViewId,
1.185 + TUid aCustomMessageId,
1.186 + const TDesC8& aCustomMessage);
1.187 +
1.188 + void ViewDeactivated(CAknView* aView);
1.189 +
1.190 + /**
1.191 + * Combines two views. If either of the views belongs to another view combination
1.192 + * then that combination is removed.
1.193 + * @since Series 60 5.0
1.194 + * @param aView1Id UID of the first (leftmost) view.
1.195 + * @param aView2Id UID of the second view.
1.196 + * @param aLeftViewSize Size of the first view (in percentages).
1.197 + */
1.198 + IMPORT_C void SetSplitViewL( const TUid aView1Id, const TUid aView2Id, const TInt aLeftViewSize );
1.199 +
1.200 + /**
1.201 + * Removes a view combination containing the given view UID. If the view
1.202 + * with the given UID is currently visible then the screen is switched to
1.203 + * single view and the the given view stays active.
1.204 + * @since Series 60 5.0
1.205 + * @param aViewId UID of a view combination.
1.206 + */
1.207 + IMPORT_C void RemoveSplitViewL( const TUid aViewId );
1.208 +
1.209 + /**
1.210 + * Checks if split view is in use.
1.211 + * @since Series 60 5.0
1.212 + * @return ETrue if a split view is active.
1.213 + */
1.214 + IMPORT_C TBool SplitViewActive() const;
1.215 +
1.216 + /**
1.217 + * Returns the currently focused view.
1.218 + * @since Series 60 5.0
1.219 + * @return UID of the currently focused view.
1.220 + */
1.221 + IMPORT_C TUid FocusedView() const;
1.222 +
1.223 + /**
1.224 + * Checks if the given view is visible on the screen.
1.225 + * @since Series 60 5.0
1.226 + * @param aViewId View to be checked.
1.227 + * @return ETrue if the given view is visible.
1.228 + */
1.229 + IMPORT_C TBool ViewShown( const TUid aViewId ) const;
1.230 +
1.231 + /**
1.232 + * Enables/disables local screen clearer.
1.233 + * Local screen clearer is used in the view based applications
1.234 + * to clear the application window if/when the view itself fails
1.235 + * to do this. By default, the clearer is used.
1.236 + * This function must be called before the BaseConstructL() to
1.237 + * prevent the screen clearer on application start up.
1.238 + *
1.239 + * @since 3.2
1.240 + * @param aEnable ETrue enables local screen clearer.
1.241 + * EFalse disables local screen clearer.
1.242 + */
1.243 + IMPORT_C void EnableLocalScreenClearer( TBool aEnable = ETrue );
1.244 +
1.245 + /**
1.246 + * Returns view's rectangle.
1.247 + * @since Series 60 5.0
1.248 + * @param aViewId UID of the view whose rectangle should be returned.
1.249 + * @param Given view's drawing area.
1.250 + */
1.251 + TRect ViewRect( const TUid aViewId ) const;
1.252 +
1.253 + /**
1.254 + * Handles keyboard initiated navigation between visible split views.
1.255 + * @since Series 60 5.0
1.256 + * @param aKeyEvent Keyboard event.
1.257 + * @param EKeyWasConsumed if view focus was changed.
1.258 + */
1.259 + TKeyResponse HandleViewNavigationL( const TKeyEvent& aKeyEvent );
1.260 +
1.261 +protected:
1.262 +
1.263 + /**
1.264 + * From @c MEikStatusPaneObserver. Handles a change in the position or
1.265 + * size of the screen area occupied by the status pane.
1.266 + */
1.267 + IMPORT_C void HandleStatusPaneSizeChange();
1.268 +
1.269 + /**
1.270 + * From @c CCoeAppUi. Handles changes in keyboard focus when
1.271 + * an application switches to foreground.
1.272 + * @param aForeground @c ETrue if the application is in the foreground,
1.273 + * otherwise @c EFalse.
1.274 + */
1.275 + IMPORT_C void HandleForegroundEventL(TBool aForeground);
1.276 +
1.277 + /**
1.278 + * From AknAppUi. Handles pointer-initiated view switch. Currently this
1.279 + * function does nothing but calls base class function.
1.280 + * @since Series 60 3.0
1.281 + * @param aEvent Window server event.
1.282 + * @param aDestination Pointer to the control which the event is targeted to.
1.283 + */
1.284 + IMPORT_C void HandleWsEventL( const TWsEvent& aEvent, CCoeControl* aDestination );
1.285 +
1.286 +private:
1.287 + static TInt ActivationCallBack(TAny* aThis);
1.288 + void ActivationTick();
1.289 + void QueueActivationTick();
1.290 +
1.291 + /**
1.292 + * Asserts that extension object has been created.
1.293 + * @return Extension object.
1.294 + */
1.295 + CAknViewAppUiExtension* Extension() const;
1.296 +
1.297 + /**
1.298 + * Activates views in split view.
1.299 + * @since Series 60 5.0
1.300 + * @param View under activation.
1.301 + */
1.302 + void ActivateSplitViewL( CViewActivationItem* aItem );
1.303 +
1.304 + /**
1.305 + * If the given view is part of a split view then returns that split view,
1.306 + * @since Series 60 5.0
1.307 + * @param aViewId UID of a view that belongs to a split view.
1.308 + * @return Pointer to a correct split view or NULL if no corresponding split view was found.
1.309 + */
1.310 + TAknSplitViewContainer* SplitView( const TUid aViewId ) const;
1.311 +
1.312 +protected:
1.313 +
1.314 + // Application view.
1.315 + CAknView* iView;
1.316 +
1.317 + // Application views.
1.318 + CAknViews* iViews;
1.319 +
1.320 +private:
1.321 + CAknViewShutter* iShutter;
1.322 + CAknLocalScreenClearer* iClearer;
1.323 + CAknViewActivationQueue* iActivationQueue;
1.324 + CIdle* iActivationTick;
1.325 + // extension class
1.326 + CAknViewAppUiExtension* iExtension;
1.327 + };
1.328 +
1.329 +#endif // __AKNVIEWAPPUI_H__