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 "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.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