1.1 --- a/epoc32/include/mw/aknview.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/mw/aknview.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,409 @@
1.4 -aknview.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:
1.19 +*
1.20 +*/
1.21 +
1.22 +// AknView.h
1.23 +//
1.24 +// Copyright (c) 1997-2001 Symbian Ltd. All rights reserved.
1.25 +//
1.26 +
1.27 +#ifndef AKNVIEW_H
1.28 +#define AKNVIEW_H
1.29 +
1.30 +// INCLUDES
1.31 +#include <babitflags.h>
1.32 +#include <coecntrl.h>
1.33 +#include <eikmobs.h>
1.34 +#include <coeaui.h>
1.35 +#include <coeview.h>
1.36 +#include <eikdef.h>
1.37 +#include <coemop.h>
1.38 +
1.39 +// FORWARD DECLARATIONS
1.40 +class CAknViewAppUi;
1.41 +class CEikStatusPane;
1.42 +class CEikButtonGroupContainer;
1.43 +class CAknControlStack;
1.44 +class CAknViewExtension;
1.45 +class CAknToolbar;
1.46 +
1.47 +// CLASS DECLARATION
1.48 +
1.49 +/**
1.50 + * This is an abstract base class for a Series 60 application view.
1.51 + *
1.52 + * @since Series 60 0.9
1.53 + */
1.54 +class CAknView : public CBase, public MCoeView, public MEikMenuObserver,
1.55 + public MObjectProvider
1.56 + {
1.57 +public:
1.58 +
1.59 + /**
1.60 + * Standard constructor.
1.61 + */
1.62 + IMPORT_C CAknView();
1.63 +
1.64 + /**
1.65 + * Standard destructor.
1.66 + */
1.67 + IMPORT_C ~CAknView();
1.68 +
1.69 + /**
1.70 + * This is a second stage constructor initializing this view with standard
1.71 + * values. Should be called from derived classes second stage construction
1.72 + * functions.
1.73 + * @param aResId The numeric ID of the resource (@c iViewInfo) to be read.
1.74 + * If aResId=0, resource file is not accessed.
1.75 + */
1.76 + IMPORT_C void BaseConstructL(TInt aResId=0);
1.77 +
1.78 + /**
1.79 + * Constructs invisible button group container and menu if they don't exist
1.80 + * yet. They are placed on the view stack. To be used by views which need
1.81 + * to access the menu or cba before the view is activated for the first
1.82 + * time.
1.83 + */
1.84 + IMPORT_C void ConstructMenuAndCbaEarlyL();
1.85 +
1.86 + /**
1.87 + * Activate any view in the product. Calls @c CCoeAppUi::ActivateViewL(
1.88 + * aViewId)
1.89 + * @param aViewId Identifies the view to activate.
1.90 + */
1.91 + IMPORT_C void ActivateViewL(const TVwsViewId& aViewId);
1.92 +
1.93 + /**
1.94 + * Activate any view, then passes the message text @c aCustomMessage of
1.95 + * type @c aCustomMessageId. Calls @c CCoeAppUi::ActivateViewL(
1.96 + * aViewId,aCustomMessageId,aCustomMessage)
1.97 + * @param aViewId Identifies the view to activate.
1.98 + * @param aCustomMessageId Specifies the message type.
1.99 + * @param aCustomMessage The message passed to the activated view.
1.100 + */
1.101 + IMPORT_C void ActivateViewL(const TVwsViewId& aViewId,
1.102 + TUid aCustomMessageId,
1.103 + const TDesC8& aCustomMessage);
1.104 +
1.105 + /**
1.106 + * Returns views id, intended for overriding by sub classes.
1.107 + * @return id for this view.
1.108 + */
1.109 + IMPORT_C virtual TUid Id() const =0;
1.110 +
1.111 + /**
1.112 + * Event handler for status pane size changes.
1.113 + * @c CAknView provides an empty implementation for sub classes that do
1.114 + * not want to handle this event.
1.115 + */
1.116 + IMPORT_C virtual void HandleStatusPaneSizeChange();
1.117 +
1.118 + /**
1.119 + * From @c MCoeView. The full view Id for this view. Calls @c Id()
1.120 + * @return View identification number.
1.121 + */
1.122 + IMPORT_C TVwsViewId ViewId() const;
1.123 +
1.124 + /**
1.125 + * From @c MEikMenuObserver. This function processes user commands by
1.126 + * handling @c aCommand values @c EAknSoftkeyOptions, @c EAknCmdExit,
1.127 + * @c EEikCmdCanceled and passing the others to @c HandleCommandL()
1.128 + * for sub class to decide the actions.
1.129 + * @param aCommand ID of the command to respond to.
1.130 + */
1.131 + IMPORT_C virtual void ProcessCommandL(TInt aCommand);
1.132 +
1.133 + /**
1.134 + * Command handling function intended for overriding by sub classes.
1.135 + * Default implementation is empty.
1.136 + * @param aCommand ID of the command to respond to.
1.137 + */
1.138 + IMPORT_C virtual void HandleCommandL(TInt aCommand);
1.139 +
1.140 + /**
1.141 + * Menu bar accessor method. This returns the views menu if available,
1.142 + * otherwise it returns the applications menu bar.
1.143 + * @return @c CEikMenuBar pointer to views menu bar.
1.144 + */
1.145 + IMPORT_C virtual CEikMenuBar* MenuBar() const;
1.146 +
1.147 + /**
1.148 + * Calculates the client rectangle of the view, taking the applications
1.149 + * client rectangle and the views CBA into account.
1.150 + * Calls @c CEikAppUi::ClientRect()
1.151 + * @return @c TRect the area of the screen available to the application
1.152 + * for drawing.
1.153 + */
1.154 + IMPORT_C TRect ClientRect() const;
1.155 +
1.156 + /**
1.157 + * This function causes the menu bar to disappear from the screen until it
1.158 + * is invoked again by the user.
1.159 + * Calls @c CEikAppUi::StopDisplayingMenuBar().
1.160 + */
1.161 + IMPORT_C void StopDisplayingMenuBar();
1.162 +
1.163 + /**
1.164 + * Determines whether the application is foreground.
1.165 + * @return @c ETrue if view is foreground.
1.166 + */
1.167 + IMPORT_C TBool IsForeground() const;
1.168 +
1.169 + /**
1.170 + * Called by the framework when view's rectangle changes. The default
1.171 + * implementation is empty. This function is not used yet.
1.172 + * @since Series 60 3.0
1.173 + */
1.174 + IMPORT_C virtual void HandleViewRectChange();
1.175 +
1.176 + /**
1.177 + * Asks the view to redraw its area. Needs to be implemented only by
1.178 + * views used in split view architecture. The default implementation is
1.179 + * empty. This function is not used yet.
1.180 + * @since Series 60 3.0
1.181 + */
1.182 + IMPORT_C virtual void Redraw() const;
1.183 +
1.184 +
1.185 + /**
1.186 + * Avkon view architecture system. Internal use only.
1.187 + * Calls @c DoActivateL.
1.188 + */
1.189 + IMPORT_C virtual void AknViewActivatedL(const TVwsViewId& aPrevViewId,
1.190 + TUid aCustomMessageId,
1.191 + const TDesC8& aCustomMessage);
1.192 +
1.193 + /**
1.194 + * Avkon view architecture system. Internal use only. Function is called
1.195 + * by @c CAknViewAppUi::~CAknViewAppUi() for immediate view deactivation.
1.196 + * Calls @c DoDeactivate.
1.197 + */
1.198 + void AknViewDeactivated();
1.199 +
1.200 + /**
1.201 + * Avkon view architecture system. Internal use only.
1.202 + */
1.203 + void ProcessForegroundEventL(TBool aForeground);
1.204 +
1.205 +private: // formerly from @c MTopSetMember<CEikMenuBar>
1.206 + IMPORT_C virtual void Reserved_MtsmPosition();
1.207 + IMPORT_C virtual void Reserved_MtsmObject();
1.208 +
1.209 +protected:
1.210 +
1.211 + /**
1.212 + * Accessor for the applications user interface as a @c CAknViewAppUi.
1.213 + * @return Pointer to user interface instance.
1.214 + */
1.215 + IMPORT_C CAknViewAppUi* AppUi() const;
1.216 +
1.217 + /**
1.218 + * Status pane accessor method.
1.219 + * @return Pointer to status pane.
1.220 + */
1.221 + IMPORT_C CEikStatusPane* StatusPane() const;
1.222 +
1.223 + /**
1.224 + * Button group container (=CBA) accessor method.
1.225 + * This returns the views CBA if there is one, and the applications user
1.226 + * interfaces CBA otherwise.
1.227 + * @return Pointer to @c CEikButtonGroupContainer.
1.228 + */
1.229 + IMPORT_C CEikButtonGroupContainer* Cba() const;
1.230 +
1.231 + /**
1.232 + * Handles a view activation and passes the message of type
1.233 + * @c aCustomMessageId. This function is intended for overriding by
1.234 + * sub classes. This function is called by @c AknViewActivatedL().
1.235 + * Views should not launch waiting or modal notes or dialogs in
1.236 + * @c DoActivateL.
1.237 + * @param aPrevViewId Specifies the view previously active.
1.238 + * @param aCustomMessageId Specifies the message type.
1.239 + * @param aCustomMessage The activation message.
1.240 + */
1.241 + IMPORT_C virtual void DoActivateL(const TVwsViewId& aPrevViewId,
1.242 + TUid aCustomMessageId,
1.243 + const TDesC8& aCustomMessage) = 0;
1.244 +
1.245 + /**
1.246 + * View deactivation function intended for overriding by sub classes.
1.247 + * This function is called by @c AknViewDeactivated().
1.248 + */
1.249 + virtual void DoDeactivate() = 0;
1.250 +
1.251 +protected: // From MCoeView.
1.252 +
1.253 + /**
1.254 + * From @c MCoeView. Takes any action required when this view is activated.
1.255 + * Handles this view activation event from view server. Calls
1.256 + * @c CAknViewAppUi::ViewActivatedL()
1.257 + * @param aPrevViewId Specifies the view previously active.
1.258 + * @param aCustomMessageId Specifies the message type.
1.259 + * @param aCustomMessage Activation message.
1.260 + */
1.261 + IMPORT_C void ViewActivatedL(const TVwsViewId& aPrevViewId,
1.262 + TUid aCustomMessageId,
1.263 + const TDesC8& aCustomMessage);
1.264 +
1.265 + /**
1.266 + * From @c MCoeView. Takes any action that is required following
1.267 + * deactivation of this view. Handles this view deactivation event from
1.268 + * viewserver. Calls @c CAknViewAppUi::ViewDeactivated()
1.269 + */
1.270 + IMPORT_C void ViewDeactivated();
1.271 +
1.272 + /**
1.273 + * From @c MCoeView. Screen device changed function from viewserver.
1.274 + * @return TVwsViewIdAndMessage created with default values.
1.275 + */
1.276 + IMPORT_C TVwsViewIdAndMessage ViewScreenDeviceChangedL();
1.277 +
1.278 +protected: // from MObjectProvider
1.279 +
1.280 + /**
1.281 + * From @c MObjectProvider. Gets an (@c MAknsControlContext) object whose
1.282 + * type is encapsulated by the specified TTypeUid object. Calls
1.283 + * @c SupplyMopObject( @c TTypeUid aId,
1.284 + * @c CEikButtonGroupContainer* iCba, @c CEikMenuBar* iMenu ).
1.285 + * @param aId Encapsulates the @c Uid that identifies the type of object
1.286 + * required.
1.287 + * @return Pointer to the @c MAknsControlContext object provided. Note that
1.288 + * the pointer may be @c NULL.
1.289 + */
1.290 + IMPORT_C TTypeUid::Ptr MopSupplyObject(TTypeUid aId);
1.291 +
1.292 + /**
1.293 + * From @c MObjectProvider. Gets the parent object provider.
1.294 + * @return Pointer to the parent object provider (@c MObjectProvider) that
1.295 + * is @c CAknViewAppUi* iAppUi, or @c NULL.
1.296 + */
1.297 + IMPORT_C MObjectProvider* MopNext();
1.298 +
1.299 +protected: // From MEikMenuObserver.
1.300 +
1.301 + /**
1.302 + * From @c MEikMenuObserver. Menu emphasising or de-emphasising function.
1.303 + * @c CEikMenuBar objects call this on their observer. Updates the value of
1.304 + * the flags for the (@c aMenuControl) on the control stack.
1.305 + * @param aMenuControl The control to be emphasised or de-emphasisied.
1.306 + * @param aEmphasis @c ETrue to emphasize the menu, @c EFalse to refuse the
1.307 + * focus.
1.308 + */
1.309 + IMPORT_C virtual void SetEmphasis(CCoeControl* aMenuControl,
1.310 + TBool aEmphasis);
1.311 +
1.312 + /**
1.313 + * From @c MEikMenuObserver. Foreground event handling function intended
1.314 + * for overriding by sub classes.
1.315 + * @param aForeground Indicates the required focus state of the control.
1.316 + */
1.317 + IMPORT_C virtual void HandleForegroundEventL(TBool aForeground);
1.318 +
1.319 +private: // internal functions
1.320 + void ConstructMenuAndCbaL(TBool aVisible);
1.321 +
1.322 + /**
1.323 + * Asserts that extension class object exists.
1.324 + * @return Extension object.
1.325 + */
1.326 + CAknViewExtension* Extension() const;
1.327 +
1.328 +public: // new functions
1.329 +
1.330 + /**
1.331 + * @since Series 60 3.1
1.332 + * @return toolbar object.
1.333 + */
1.334 + IMPORT_C CAknToolbar* Toolbar() const;
1.335 +
1.336 + /**
1.337 + * This function causes toolbar to be hidden
1.338 + * @since Series 60 3.1
1.339 + */
1.340 + IMPORT_C void StopDisplayingToolbar();
1.341 +
1.342 + /**
1.343 + * Determines if the toolbar of this view is shown when the view is
1.344 + * activated.
1.345 + * @since S60 3.2
1.346 + * @return ETrue if toolbar is shown.
1.347 + */
1.348 + IMPORT_C TBool ToolbarShownOnViewActivation() const;
1.349 +
1.350 + /**
1.351 + * Sets toolbar visibility status of this view according to value given.
1.352 + * The value is used when view is activated.
1.353 + * @since S60 3.2
1.354 + * @param aVisible to determine if toolbar should be shown.
1.355 + */
1.356 + IMPORT_C void ShowToolbarOnViewActivation( TBool aVisible );
1.357 +
1.358 + /**
1.359 + * Saves toolbar status of this view according to values given.
1.360 + * The values are used when view is activated.
1.361 + * @since S60 3.2
1.362 + * @param aVisible to determine if toolbar should be shown.
1.363 + * @param aFocused ETrue if toolbar is focused, EFalse if not
1.364 + */
1.365 + void SaveToolbarStatus( TBool aVisible, TBool aFocused );
1.366 +
1.367 + /**
1.368 + * Sets new toolbar for the view. Deletes old toolbar. If the old toolbar
1.369 + * was shown before deleting, then the new toolbar will also be shown.
1.370 + * @since S60 5.0
1.371 + * @param aToolbar pointer to new toolbar
1.372 + */
1.373 + IMPORT_C void SetToolbar( CAknToolbar* aToolbar );
1.374 +
1.375 + /**
1.376 + * Creates a new toolbar object with the resource id given and sets it for
1.377 + * the view. Deletes old toolbar. If the old toolbar was shown before
1.378 + * deleting, then the new toolbar will also be shown.
1.379 + * @since S60 5.0
1.380 + * @param aResourceId Resource id of the new toolbar
1.381 + */
1.382 + IMPORT_C void CreateAndSetToolbarL( TInt aResourceId );
1.383 +
1.384 +
1.385 +protected: // Data
1.386 + // The follow object is not owned by this class. iCoeEnv is protected in
1.387 + // keeping with @c CCoeAppUi & @c CCoeControl
1.388 + CCoeEnv* iCoeEnv;
1.389 +
1.390 +private:
1.391 + CAknViewAppUi* iAppUi;
1.392 +
1.393 + // @c SAknViewInfo is the C++ image of resource structure AVKON_VIEW
1.394 + struct SAknViewInfo
1.395 + {
1.396 + public:
1.397 + TUint8 iVersion; // resource struct version
1.398 + TInt iHotKeys; // resource id
1.399 + TInt iMenu; // resource id
1.400 + TInt iCba; // resource id
1.401 + TInt iToolbar; // resource id
1.402 + TInt iExtension; // resource id
1.403 + };
1.404 +
1.405 + // The following member data are owned by this class
1.406 + SAknViewInfo iViewInfo;
1.407 + CEikMenuBar* iMenu;
1.408 + CEikButtonGroupContainer* iCba;
1.409 + TBitFlags iFlags;
1.410 + CAknViewExtension* iExtension;
1.411 + };
1.412 +
1.413 +#endif // AKNVIEW_H