epoc32/include/mw/akndialog.h
author William Roberts <williamr@symbian.org>
Tue, 16 Mar 2010 16:12:26 +0000 (2010-03-16)
branchSymbian2
changeset 2 2fe1408b6811
parent 1 666f914201fb
child 4 837f303aceeb
permissions -rw-r--r--
Final list of Symbian^2 public API header files
     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 
    19 #ifndef __AKNDIALOG_H__
    20 #define __AKNDIALOG_H__
    21 
    22 
    23 #include <eikdialg.h>
    24 #include <eikmobs.h>
    25 
    26 
    27 class CAknDialogAttributes;
    28 
    29 /**
    30  * Base class for different types of @c AknDialogs
    31  *
    32  * Instances of the @c CAikDialog class may be created, and it is possible to
    33  * add controls directly to them. However it is more normal to create a 
    34  * subclass, and to handle the controls appearing on the dialog dynamically.
    35  */
    36 class CAknDialog : public CEikDialog, public MEikMenuObserver
    37     {
    38     public :
    39 
    40         /** 
    41          * C++ default constructor. 
    42          */ 
    43         IMPORT_C CAknDialog() ;
    44 
    45         /** 
    46          * Handles Symbian 2nd phase construction.
    47          *
    48          * A menu resource MUST be specified - this function will Panic 
    49          * otherwise. If a menu is not required use @c CEikDialog!
    50          * 
    51          * @param aMenuTitleResourceId Title of the menu.
    52          */
    53         IMPORT_C void ConstructL( TInt aMenuTitleResourceId ) ;
    54 		
    55         /**
    56          * Destructor. 
    57          */ 
    58         IMPORT_C ~CAknDialog() ;
    59 
    60         /**
    61          * From @c CEikDialog.
    62          *
    63          * Loads, displays, and destroys the dialog.
    64          * 
    65          * This function loads the specified dialog from a resource and 
    66          * displays it. The method then destroys the dialog when it exits,
    67          * therefore there is no need for the application program to 
    68          * destroy the dialog.
    69          *
    70          * @param aResourceId The resource ID of the dialog to load.
    71          * @return Zero, unless it is a waiting dialog. For a waiting dialog,
    72          *         the return value is the ID of the button that closed the
    73          *         dialog, or zero if it was the cancel button 
    74          *         (@c EEikBidCancel).
    75          */
    76 		IMPORT_C TInt ExecuteLD( TInt aResourceId ) ;
    77 
    78         /**
    79          * From @c CEikDialog.
    80          *
    81          * Prepares the dialog, by constructing it from the specified resource.
    82          *
    83          * @param aResourceId The resource ID of the dialog.
    84          */
    85         IMPORT_C  void PrepareLC(TInt aResourceId);
    86 
    87         /**
    88          * From @c CEikDialog.
    89          *
    90          * Runs the dialog and returns the ID of the button used to dismiss it.
    91          *
    92          * The dialog is destroyed on exit.
    93          * 
    94          * This function is called by the dialog framework (@c ExecuteLD()) to
    95          * perform dynamic construction (layout) and to display/destroy the 
    96          * dialog. Static construction of the dialog must already be complete 
    97          * before this function is called, e.g. using @c PrepareLC().
    98          *
    99          * The function returns immediately unless @c EEikDialogFlagWait has 
   100          * been specified in the @c DIALOG resource. If @c EEikDialogFlagWait 
   101          * is specified, it returns when the dialog exits.
   102          *
   103          * @return The ID of the button used to dismiss the dialog.
   104          */
   105         IMPORT_C TInt RunLD();
   106 
   107 		// From MEikMenuObserver
   108         /**
   109          * From @c MEikMenuObserver.
   110          *
   111          * Called by the Uikon framework to handle the emphasising or 
   112          * de-emphasising of a menu window.
   113          *
   114          * @c CEikMenuBar objects call this on their observer to emphasise
   115          * themselves when they are displayed, and de-emphasise themselves when
   116          * they stop displaying.
   117          *
   118          * @param aMenuControl The menu control. 
   119          * @param aEmphasis @c ETrue to emphasize the menu, 
   120          *        @c EFalse otherwise. 
   121          */ 
   122         IMPORT_C virtual void SetEmphasis( CCoeControl* aMenuControl,
   123                                            TBool aEmphasis ) ;
   124         /**
   125          * Not implemented.
   126          *
   127          * @param aResourceId Not used.
   128          * @param aMenuPane Not used.
   129          */ 
   130         IMPORT_C virtual void DynInitMenuPaneL( TInt aResourceId, 
   131                                                 CEikMenuPane* aMenuPane ) ;
   132 
   133         /**
   134          * From @c MEikMenuObserver.
   135          *
   136          * Hides the menu.
   137          *
   138          * @param aCommandId Not used.
   139          */ 
   140 		IMPORT_C virtual void ProcessCommandL( TInt aCommandId ) ;
   141 
   142 		// From CCoeControl
   143 
   144         /** 
   145          * From @c CCoeControl.
   146          *
   147          * Handles key events.
   148          *
   149          * If a control wishes to process key events, it should implement this
   150          * function. The implementation must ensure that the function returns
   151          * @c EKeyWasNotConsumed if it does not do anything in response to a
   152          * key event, otherwise, other controls or dialogs may be prevented 
   153          * from receiving the key event. If it is able to process the event
   154          * it should return @c EKeyWasConsumed.
   155          *
   156          * When a key event occurs, the control framework calls this function 
   157          * for each control on the control stack, until one of them can process 
   158          * the key event (and returns @c EKeyWasConsumed).
   159          *
   160          * Each keyboard key press results in three separate events: 
   161          * @c EEventKeyDown, @c EEventKey, and @c EEventKeyUp, in that order.
   162          *
   163          * To receive key events, which can be processed by this function, 
   164          * the application should call @c CCoeAppUi::AddToStackL() to add the 
   165          * control to the stack. This only applies, however, to controls which 
   166          * are not components of a compound control. Compound controls should 
   167          * pass key events to their components as necessary: the components 
   168          * themselves do not go on the stack.
   169          *
   170          * @param aKeyEvent The key event. 
   171          * @param aType The type of key event: @c EEventKey, @c EEventKeyUp or 
   172          *        @c EEventKeyDown. 
   173          * @return Indicates whether or not the key event was used by 
   174          *         this control. 
   175          */ 
   176 		IMPORT_C TKeyResponse OfferKeyEventL(const TKeyEvent& aKeyEvent,
   177                                              TEventCode aType) ;
   178 
   179         /** 
   180          * From @c CCoeControl.
   181          *
   182          * Responds to a change in focus.
   183          *
   184          * This is called whenever the control gains or loses focus, as a 
   185          * result of a call to @c SetFocus(). A typical use of 
   186          * @c FocusChanged() is to change the appearance of the control, 
   187          * for example by drawing a focus rectangle around it.
   188          *
   189          * @param aDrawNow Contains the value that was passed to it by 
   190          *        @c SetFocus(). 
   191          */ 
   192         IMPORT_C void FocusChanged(TDrawNow aDrawNow); 
   193 
   194         /** 
   195          * From @c CCoeControl.
   196          *
   197          * Handles pointer events.
   198          *
   199          * This function gets called whenever a pointer event occurs in the
   200          * control, i.e. when the pointer is within the control's extent, 
   201          * or when the control has grabbed the pointer. The control should 
   202          * implement this function to handle pointer events.
   203          *
   204          * Note: events of type @c EButton1Down are processed before 
   205          * @c HandlePointerEventL() is called, in order to transfer keyboard
   206          * focus to the control in which the @c EButton1Down event occurred.
   207          *
   208          * @param aPointerEvent The pointer event
   209          */ 
   210         IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);
   211 
   212 	private: // formerly from MTopSetMember<CEikMenuBar>, now reserved
   213 		
   214         IMPORT_C virtual void Reserved_MtsmPosition();
   215 
   216         IMPORT_C virtual void Reserved_MtsmObject();
   217 
   218     private:
   219     
   220         /**
   221         * From CAknControl
   222         */
   223         IMPORT_C void* ExtensionInterface( TUid aInterface );
   224 
   225     protected:
   226 
   227         /**
   228          * From @c CEikDialog.
   229          *
   230          * Handles a dialog button press for the specified button. 
   231          *
   232          * This function is invoked when the user presses a button in the
   233          * button panel. It is not called if the Cancel button is activated 
   234          * unless the @c EEikDialogFlagNotifyEsc flag has been set.
   235          *
   236          * If there is an Options key then pops up menu, otherwise exits.
   237          *
   238          * The function should be overridden by the derived class, and is 
   239          * usually used to validate the values of the dialog's controls. 
   240          * The function should return @c ETrue if it is OK to exit, and 
   241          * @c EFalse to keep the dialog active. It should always return
   242          * @c ETrue if the button with ID @c EEikBidOK was activated.
   243          *
   244          * @param aButtonId The ID of the button that was activated.
   245          * @return @c ETrue to validate and exit the dialog, 
   246          *         @c EFalse to keep the dialog active. If @c ETrue, the 
   247          *         dialog will be destroyed automatically by @c ExecuteLD(). 
   248          *         The default implementation returns @c ETrue no matter which
   249          *         button is pressed.
   250          */
   251 		IMPORT_C virtual TBool OkToExitL( TInt aButtonId ) ;
   252 
   253         /**
   254          * From @c CEikDialog.
   255          *
   256          * Displays menu bar.
   257          */
   258 		IMPORT_C void DisplayMenuL() ;
   259 
   260         /**
   261          * From @c CEikDialog.
   262          *
   263          * Hides menu bar.
   264          */
   265         IMPORT_C void HideMenu() ;
   266 		
   267         /**
   268          * From @c CEikDialog.
   269          *
   270          * Checks if menu is displayed.
   271          * 
   272          * @return @c ETrue if menu is displayed,
   273          *         @c EFalse otherwise.
   274          */
   275         IMPORT_C TBool MenuShowing() const ;
   276 		
   277         /**
   278          * From @c CEikDialog.
   279          *
   280          * Lays out the dialog's components when the size of the dialog 
   281          * is changed.
   282          */
   283 		IMPORT_C virtual void SizeChanged();
   284 	
   285         /**
   286          * From @c CEikDialog.
   287          *
   288          * Draws the control.
   289          * 
   290          * @param aRect Area to be drawn.
   291          */
   292         IMPORT_C virtual void Draw(const TRect &aRect) const;
   293 
   294 	protected: // from MObjectProvider
   295 		
   296         /** 
   297          * From @c MObjectProvider. 
   298          *
   299          * Gets Mop supply object of the given type.  
   300          *
   301          * @param aId Identifier for the supply object.
   302          * @return Pointer to the supply object type ID.
   303          */
   304         IMPORT_C TTypeUid::Ptr MopSupplyObject(TTypeUid aId);
   305 
   306     private: 
   307 
   308 		IMPORT_C virtual void CEikDialog_Reserved_1();
   309 		
   310         IMPORT_C virtual void CEikDialog_Reserved_2();	
   311 
   312     private: // new function 
   313 
   314 		IMPORT_C virtual void CAknDialog_Reserved();
   315 	
   316     protected: // new function 
   317 
   318         /** 
   319          * Creates or replaces dialog's menu bar.
   320          *
   321          * @param aMenuTitleResourceId Title of the menu bar. 
   322          */ 
   323         void CreateMenuBarL(TInt aMenuTitleResourceId);
   324 
   325     protected:
   326 		        
   327         /**
   328          * Dialog's menu bar. 
   329          * Not owned.
   330          */
   331 		CEikMenuBar* iMenuBar;
   332 
   333 private:
   334 
   335 	enum TAknDialogFlag
   336 	    {
   337 	    EAknDialogFlagDialogDeleted = 1,
   338         EAknDialogFlagDefaultSounds = 2,
   339 		EAknDialogFlagNotConstructed = 4
   340 	    };
   341 
   342     CAknDialogAttributes* iAttributes;  // Was TInt iSpare;
   343 
   344 	CAknDialogAttributes* AttributesL();
   345 
   346 	} ;
   347 
   348 #endif // __AKNDIALOG_H__
   349 
   350  
   351 // End of file