1 /*

     2 * Copyright (c) 1997-1999 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 __EIKDIALG_H__

    20 #define __EIKDIALG_H__

    21 

    22 #ifndef __COECOBS_H__

    23 #include <coecobs.h>

    24 #endif

    25 

    26 #ifndef __COECCNTX_H__

    27 #include <coeccntx.h>

    28 #endif

    29 

    30 #ifndef __EIKBCTRL_H__

    31 #include <eikbctrl.h>

    32 #endif

    33 

    34 #ifndef __EIKDPOBS_H__

    35 #include <eikdpobs.h>

    36 #endif

    37 

    38 #ifndef __BADESCA_H__

    39 #include <badesca.h>

    40 #endif 

    41 

    42 #ifndef __GULFTFLG_HRH__

    43 #include <gulftflg.hrh>

    44 #endif

    45 

    46 

    47 

    48 //

    49 // Header files needed by deprecated interfaces.

    50 //

    51 

    52 #ifndef __EIKBUTB_H__

    53 #include <eikbutb.h>

    54 #endif

    55 

    56 #ifndef __EIKBTGPC_H__

    57 #include <eikbtgpc.h>

    58 #endif

    59 

    60 #include <AknPopupFader.h>

    61 

    62 // constant definitions

    63 const TInt KAknMediatorFacade(0x10275076);

    64 

    65 

    66 class CEikMover;

    67 class CEikCaptionedControl;

    68 class CEikCapCArray;

    69 class CEikDialogPageSelector;

    70 class CEikButtonGroupContainer;

    71 class CEikDialogButtonCommandObserver;

    72 class MEikCommandObserver;

    73 class CAknDialog;

    74 class CAknNoteDialog;

    75 

    76 struct SEikControlInfo;

    77 

    78 class  CEikDialogExtension ;

    79 // <SKIN>

    80 class CAknsListBoxBackgroundControlContext ;

    81 //

    82 // Forward declarations needed by deprecated interfaces.

    83 //

    84 

    85 class CEikLabel;

    86 class CGlobalText;

    87 class MAknDialogMediatorObserver;

    88 struct SEikRange;

    89 struct SEikDegreesMinutesDirection;

    90 

    91 

    92 /**

    93  * The @c CEikDialog class provides an instantiable base class for dialogs. 

    94  * Controls can be added directly to this class but it is normal to create

    95  * a subclass to handle the controls appearing on the dialog dynamically.

    96  */

    97 class CEikDialog : public CEikBorderedControl,

    98                    public MCoeControlObserver,

    99                    public MEikDialogPageObserver,

   100                    public MCoeControlContext, 

   101                    public MAknFadedComponent

   102     { 

   103 

   104 public:

   105 

   106     DECLARE_TYPE_ID(0x10282EA8)

   107     

   108 	/**

   109      * C++ default constructor.

   110      */

   111     IMPORT_C CEikDialog(); 

   112 

   113     /**

   114      * Destructor.

   115      */

   116 	IMPORT_C ~CEikDialog(); 

   117 

   118     /**

   119      * Loads, displays, and destroys the dialog.

   120      *

   121      * This function loads the specified dialog from a resource and displays

   122      * it. The method then destroys the dialog when it exits, therefore there

   123      * is no need for the application program to destroy the dialog.

   124      *

   125      * In the resource file, use the @c EEikBidOk dialog button ID for an 

   126      * OK/Done/Continue button and @c EEikBidCancel for a Cancel button.

   127      *

   128      * The function returns immediately unless @c EEikDialogFlagWait has been 

   129      * specified in the @c DIALOG resource. If @c EEikDialogFlagWait is 

   130      * specified, it returns when the dialog exits.

   131      * 

   132      * @param aResourceId The resource ID of the dialog to load.

   133      * @return Zero, unless it is a waiting dialog. For a waiting dialog, 

   134      *         the return value is the ID of the button that closed the dialog, 

   135      *         or zero if it was the cancel button (@c EEikBidCancel).

   136      */

   137 	IMPORT_C virtual TInt ExecuteLD(TInt aResourceId);

   138 	

   139     /**

   140      * Prepares the dialog, constructing it from the specified resource.

   141      * 

   142      * @param aResourceId The resource ID of the dialog.

   143      */

   144     IMPORT_C virtual void PrepareLC(TInt aResourceId);

   145 

   146     /**

   147      * Reads the dialog resources into the dialog, constructing it from the specified resource.

   148      * The function is only to help loading dialog resources and 

   149      * extracting dialog data, in other cases use (@c PrepareLC()).

   150      * Unlike PrepareLC(), it does not add the dialog to control stack.

   151      * @since 3.2

   152      * 

   153      * @param aResourceId The resource ID of the dialog.

   154      */

   155     IMPORT_C void ReadResourceLC(TInt aResourceId);

   156 

   157     /**

   158      * Runs the dialog and returns the ID of the button used to dismiss it.

   159      *

   160      * The dialog is destroyed on exit.

   161      *

   162      * This function is called by the dialog framework (@c ExecuteLD()) to 

   163      * perform dynamic construction (layout) and to display/destroy the 

   164      * dialog. Static construction of the dialog must already be complete 

   165      * before this function is called, e.g. using @c PrepareLC().

   166      *

   167      * The function returns immediately unless @c EEikDialogFlagWait has 

   168      * been specified in the @c DIALOG resource. If @c EEikDialogFlagWait is    

   169      * specified it returns when the dialog exits.

   170      *

   171      * @return The ID of the button used to dismiss the dialog.

   172      */

   173     IMPORT_C virtual TInt RunLD();

   174 

   175     /**

   176      * Sets the dialog title text from a descriptor.

   177      *

   178      * @deprecated

   179      * @param aText The descriptor containing the new title text.

   180      */

   181     IMPORT_C void SetTitleL(const TDesC& aText);

   182 	

   183     /**

   184      * Sets the dialog title text from a resource.

   185      *

   186      * @deprecated

   187      * @param aResourceId The ID of the resource containing the title text.

   188      */

   189     IMPORT_C void SetTitleL(TInt aResourceId);

   190 	

   191     /**

   192      * Sets the specified page to be dimmed or undimmed. The page is redrawn

   193      * immediately.

   194      *

   195      * @param aPageId The ID of the page to be dimmed.

   196      * @param aDimmed @c ETrue to dim the page, @c EFalse to un-dim it.

   197      */

   198     IMPORT_C void SetPageDimmedNow(TInt aPageId,TBool aDimmed);

   199 	

   200     /**

   201      * Sets the specified dialog line to a non-focusing state. After this

   202      * function is called, the line will never be given keyboard focus.

   203      * 

   204      * @param aControlId The ID of the control in the line which is to be 

   205      *        set as non-focusing.

   206      */

   207     IMPORT_C void SetLineNonFocusing(TInt aControlId);

   208 	

   209     /**

   210      * Dims and deactivates, or un-dims and re-activates, the specified line.

   211      *

   212      * @param aControlId The ID of the line to dim or un-dim.

   213      * @param aDimmed @c ETrue to dim the line, @c EFalse to un-dim it.

   214      */

   215     IMPORT_C void SetLineDimmedNow(TInt aControlId,TBool aDimmed);

   216 	

   217     /**

   218      * Makes the specified control visible or invisible. This function affects

   219      * the specified control, the visibility of the caption is not affected.

   220      *

   221      * @param aControlId The ID of the control to make visible or invisible.

   222      * @param aVisible @c ETrue to make the control visible. 

   223      *        @c EFalse to make the control invisible.

   224      */

   225     IMPORT_C void MakeLineVisible(TInt aControlId,TBool aVisible);

   226 	

   227     /**

   228      * Makes the whole specified line visible and active or invisible and 

   229      * inactive. This function affects both the specified control and

   230      * the caption.

   231      *

   232      * @param aControlId The ID of the control on the line to make visible 

   233      *        or invisible.

   234      * @param aVisible @c ETrue to make the line visible. @c EFalse to make the 

   235      *        line invisible.

   236      */

   237     IMPORT_C void MakeWholeLineVisible(TInt aControlId,TBool aVisible);

   238 	

   239     /**

   240      * Deletes the specified dialog line.

   241      *

   242      * @param aControlId The dialog line to delete.

   243      * @param aRedraw Whether to redraw the page. Default value is @c ETrue.

   244      */

   245     IMPORT_C void DeleteLine(TInt aControlId, TBool aRedraw=ETrue);

   246 	

   247     /**

   248      * Inserts a line in the dialog. The function takes as arguments the page

   249      * and line index at which the line is to be inserted, and the resource used

   250      * to construct it.

   251      * 

   252      * @param aIndex The index at which the line is to be inserted.

   253      * @param aResourceId The ID of the resource which defines the line.

   254      * @param aPageId The page on which the line is to be added.

   255      */

   256     IMPORT_C void InsertLineL(TInt aIndex,TInt aResourceId,TInt aPageId=0);

   257 	

   258     /**

   259      * Makes the specified panel button visible or invisible.

   260      *

   261      * @param aButtonId The ID of the panel button to make visible or invisible.

   262      * @param aVisible @c ETrue to make the panel visible. 

   263      *        @c EFalse to make it invisible.

   264      */

   265     IMPORT_C void MakePanelButtonVisible(TInt aButtonId,TBool aVisible);

   266 

   267     /**

   268      * Tries to change focus to the specified line. Fails if the line ID is not

   269      * valid. Calls @c PrepareForFocusTransitionL() before focus is given to

   270      * the line.

   271      *

   272      * @param aControlId The ID of the line to focus.

   273      */

   274     IMPORT_C void TryChangeFocusToL(TInt aControlId);

   275 	

   276     /**

   277      * Switches the latent line. The latent line is switched from

   278      * @c aNoLongerLatent to @c aBecomesLatent. If dialog lines are latent they

   279      * are not visible and are not taken into account when laying out the

   280      * dialog. Latent lines can then be swapped around on the dialog later.

   281      *

   282      * @param aBecomesLatent The line ID of the line to become latent.

   283      * @param aNoLongerLatent The line ID of the line to that is no longer 

   284      *        latent.

   285      */

   286     IMPORT_C void SwitchLineLatency(TInt aBecomesLatent,TInt aNoLongerLatent);

   287 	

   288     /**

   289      * Sets the specified page to be densely packed, or normally packed. This

   290      * reduces the spacing between the dialog's lines.

   291      *

   292      * @param aPageId The ID of the page to be densely packed.

   293      * @param aDensePacking @c ETrue for dense packing. @c EFalse for normal 

   294      *        packing.

   295      */

   296     IMPORT_C void SetPageDensePacking(TInt aPageId,TBool aDensePacking);

   297 	

   298     /**

   299      * Dynamically constructs a dialog with the specified flags and buttons 

   300      * and with a single activated empty page with ID 0. The dialog is therefore

   301      * ready to dynamically add lines to.

   302      *

   303      * @param aFlags Dialog flags.

   304      * @param aButtonsId Dialog buttons.

   305      */

   306     IMPORT_C void ConstructAutoDialogLC(TInt aFlags,TInt aButtonsId);

   307 	

   308     /**

   309      * Sets controllers return value.

   310      *

   311      * @param[in] aControlId Control identifier for wanted caption controller.

   312      * @param[in] aControlType Type of control.

   313      * @param[out] aReturnValue Controllers return value.

   314      * @deprecated

   315      */

   316     IMPORT_C void DeclareItemAuto(TInt aControlId,

   317                                   TInt aControlType,

   318                                   TAny* aReturnValue);

   319 	

   320     /**

   321      * Lays out the dialog, setting it to take its preferred size and 

   322      * position for the screen.

   323      *

   324      * @since 5.1 

   325      */

   326     IMPORT_C void Layout();

   327 	

   328     /**

   329      * Gets the preferred size of a dialog. The maximum size that the dialog

   330      * must fit within must be specified, e.g. the size of the physical screen.

   331      *

   332      * @param aMaxSize The maximum size of the area in which the dialog must

   333      *        fit.

   334      * @return The preferred size of the dialog.

   335      */

   336     IMPORT_C TSize PreferredSize(const TSize& aMaxSize) const;

   337 	

   338     /**

   339      * Creates a control line on the page ID specified active page in 

   340      * the dialog. 

   341      * The line can thereafter be accessed through the identifier @c aControlId.

   342      * A control of type @c aControlType is created by the control factory and

   343      * the return value of the line set to @c aReturnValue. If the value of 

   344      * @c aControlType is not known to the control factory then the construction

   345      * of the control must be handled by @c CreateCustomControlL().

   346      *

   347      * @param aCaption The caption to appear in the dialog line.

   348      * @param aControlId The ID of the active page on which the control 

   349      *        line is to be created.

   350      * @param aControlType The type of control to create.

   351      * @param aReturnValue Deprecated. A random pointer.

   352      * @return A pointer to the newly created control.

   353      */

   354     IMPORT_C CCoeControl* CreateLineByTypeL(const TDesC& aCaption,

   355                                             TInt aControlId,

   356                                             TInt aControlType,

   357                                             TAny* aReturnValue);

   358 	

   359     /**

   360      * Creates a control line on the caption specified active page 

   361      * in the dialog. 

   362      * The line can thereafter be accessed through the identifier 

   363      * @c aControlId.

   364      * A control of type @c aControlType is created by the control 

   365      * factory and the return value of the line set to @c aReturnValue.

   366      * If the value of @c aControlType is not known to the control factory

   367      * then the construction of the control must be handled by 

   368      * @c CreateCustomControlL().

   369      * 

   370      * @param aCaption The active page on which the control line is 

   371      *        to be created.

   372      * @param aPageId The ID of the active page on which the control line is

   373      *        to be created.

   374      * @param aControlId The ID of the control. After the line is created this

   375      *        can be used to access it.

   376      * @param aControlType The type of control to create.

   377      * @param aReturnValue Deprecated. A random pointer.

   378      * @return A pointer to the newly created control.

   379      */

   380     IMPORT_C CCoeControl* CreateLineByTypeL(const TDesC& aCaption,

   381                                             TInt aPageId,

   382                                             TInt aControlId,

   383                                             TInt aControlType,

   384                                             TAny* aReturnValue);

   385 	

   386     /**

   387      * Sets the specified control's caption text from a descriptor.

   388      * 

   389      * @param aControlId The ID of the control for which the caption 

   390      *        text is being set.

   391      * @param aText The text for the caption.

   392      */

   393     IMPORT_C void SetControlCaptionL(TInt aControlId,const TDesC& aText);

   394 	

   395     /**

   396      * Sets the specified control's caption text from a resource.

   397      *

   398      * @param aControlId The ID of the control for which the caption 

   399      *        text is being set.

   400      * @param aResourceId The ID of the resource containing the text for

   401      *        the caption.

   402      */

   403     IMPORT_C void SetControlCaptionL(TInt aControlId,TInt aResourceId);

   404 	

   405     /**

   406      * Gets a pointer to the specified control's caption.

   407      *

   408      * @param aControlId The ID of the control for which the label is required.

   409      * @return A pointer to the caption.

   410      */

   411     IMPORT_C CEikLabel* ControlCaption(TInt aControlId) const;

   412 

   413     /**

   414      * Returns a pointer to the specified control. 

   415      * 

   416      * Panics if the control ID is invalid. Does not imply transfer 

   417      * of ownership. 

   418      *

   419      * @param aControlId The ID of the control for which a pointer is required.

   420      * @return A pointer to the control with ID aControlId.

   421      */ 

   422     IMPORT_C CCoeControl* Control(TInt aControlId) const;

   423 

   424     /**

   425      * Gets a pointer to the specified control. 

   426      * 

   427      * @param aControlId The ID of the control for which a pointer is required.

   428      * @return A pointer to the control with ID aControlId, or 

   429      *         NULL if it doesn't exist.

   430      */

   431     IMPORT_C CCoeControl* ControlOrNull(TInt aControlId) const;

   432 	

   433     /**

   434      * Gets a reference to the dialog's command button container.

   435      *

   436      * @return The dialog's button group container.

   437      */

   438     IMPORT_C CEikButtonGroupContainer& ButtonGroupContainer() const;

   439 	

   440     /**

   441      * Gets a reference to the dialog title bar.

   442      *

   443      * @return A reference to the dialog title bar.

   444      */ 

   445     IMPORT_C CEikMover& Title() const;

   446 	

   447     /**

   448      * Gets a page id for the current page.

   449      * 

   450      * @return Page id.

   451      */

   452     IMPORT_C TInt ActivePageId() const;

   453     

   454     /**

   455      * Activates the first page on the dialog. At least one page must be active

   456      * before this method can be used.

   457      */

   458     IMPORT_C void ActivateFirstPageL() const;

   459 

   460 

   461 

   462 // To Support Edit/View state switch for forms (Sapphire DFRD)

   463 // This breaks Binary Compatibility

   464 

   465     /**

   466      * Sets the dialog to either editable or uneditable

   467      *

   468      * @param aEditable @c ETrue if dialog is editable.

   469      *        @c EFalse if dialog is uneditable.

   470      */

   471 	IMPORT_C void SetEditableL( TBool aEditable ) ;

   472 	

   473     /**

   474      * Checks if the dialog is editable.

   475      * 

   476      * @return @c ETrue if editable.

   477      */

   478     IMPORT_C TBool IsEditable() const ;

   479 

   480 

   481 public: // from CCoeControl

   482 

   483     /**

   484      * From @c CCoeControl.

   485      *

   486      * Handles a key event. Overrides @c CCoeControl::OfferKeyEventL().

   487      *

   488      * @param aKeyEvent The key event.

   489      * @param aType The type of key event: @c EEventKey, @c EEventKeyUp 

   490      *        or @c EEventKeyDown.

   491      * @return Indicates whether or not the key event was used by this control.

   492      *         @c EKeyWasConsumed if the control takes action on the key event

   493      *         or @c EKeyWasNotConsumed otherwise.

   494      */

   495     IMPORT_C TKeyResponse OfferKeyEventL(const TKeyEvent& aKeyEvent,

   496                                          TEventCode aType);

   497 	

   498     /**

   499      * From @c CCoeControl.

   500      *

   501      * Responds to a change in focus.

   502      *

   503      * This is called whenever the control gains or loses focus, as a result 

   504      * of a call to @c SetFocus(). A typical use of @c FocusChanged() is to 

   505      * change the appearance of the control, for example by drawing a focus 

   506      * rectangle around it.

   507      *

   508      * The default implementation is empty, and should be overridden by the 

   509      * @c CCoeControl-derived class.

   510      *

   511      * @param aDrawNow Contains the value that was passed to it by 

   512      *        @c SetFocus().

   513      */

   514     IMPORT_C void FocusChanged(TDrawNow aDrawNow);

   515 	

   516     /**

   517      * From @c CCoeControl.

   518      *

   519      * Gets the list of logical colours used to draw the control.

   520      *

   521      * The list includes an explanation of how each colour is used. 

   522      * The default implementation is empty.

   523      *

   524      * If overriding @c GetColorUseListL(), the implementation must include 

   525      * a base call to @c CCoeControl's @c GetColorUseListL().

   526      * 

   527      * @since ER5U

   528      * @param &aColorUseList The colour list.

   529      */

   530     IMPORT_C virtual void GetColorUseListL(

   531         CArrayFix<TCoeColorUse>& aColorUseList) const; 

   532         // not available before Release 005u

   533 	

   534     /**

   535      * From @c CCoeControl.

   536      *

   537      * Handles a change to the control's resources.

   538      * 

   539      * The types of resources handled are those which are shared across the 

   540      * environment, e.g. colours or fonts. For colour scheme changes, 

   541      * @c DrawDeferred() is called in order to redraw the control.

   542      * 

   543      * If overriding @c HandleResourceChange(), the implementation must include

   544      * a base call to @c CCoeControl's @c HandleResourceChange().

   545      * 

   546      * @since ER5U

   547      * @param aType A message UID value.

   548      */ 

   549     IMPORT_C virtual void HandleResourceChange(TInt aType);			

   550             // not available before Release 005u

   551 

   552     /**

   553      * From @c CCoeControl.

   554      *

   555      * Gets the control's input capabilities.

   556      * 

   557      * Classes that override @c CCoeControl::OfferKeyEventL() should also 

   558      * override this function, returning a @c TCoeInputCapabilities object 

   559      * whose attributes correspond to the behaviour of the @c OfferKeyEventL() 

   560      * function. The default implementation returns 

   561      * @c TCoeInputCapabilities::ENone.

   562      * 

   563      * It is not necessary to call @c InputCapabilities() on any component 

   564      * controls from inside a class's @c InputCapabilities() function. This 

   565      * is done automatically by the UI Control Framework.

   566      * 

   567      * @since ER5U

   568      * @return The control's input capabilities. 

   569      */

   570     IMPORT_C TCoeInputCapabilities InputCapabilities() const;

   571 	

   572     /**

   573      * From @c CCoeControl.

   574      *

   575      * Sets the dialog visibility

   576      * 

   577      * @param aVisible @c ETrue control is visible.

   578      *        @c EFalse control is invisible.

   579      */

   580     IMPORT_C void MakeVisible(TBool aVisible);

   581     

   582     /**

   583      * From @c CCoeControl.

   584      *

   585      * Handles pointer events.

   586      *

   587      * This function gets called whenever a pointer event occurs in the 

   588      * control, i.e. when the pointer is within the control's extent, 

   589      * or when the control has grabbed the pointer. The control should 

   590      * implement this function to handle pointer events.

   591      *

   592      * Note: events of type @c EButton1Down are processed before 

   593      * @c HandlePointerEventL() is called, in order to transfer keyboard 

   594      * focus to the control in which the @c EButton1Down event occurred.

   595      *

   596      * If overriding @c HandlePointerEventL(), the implementation must include

   597      * a base call to @c CCoeControl's @c HandlePointerEventL().

   598      *

   599      * @param aPointerEvent The pointer event.

   600      */

   601     IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);

   602 

   603 protected: // from MEikDialogPageObserver

   604 

   605     /**

   606      * From @c MEikDialogPageObserver.

   607      *

   608      * Should be implemented to prepare for focus transition from the 

   609      * current line. 

   610      *

   611      * For example to validate the contents of the current control.

   612      */

   613     IMPORT_C virtual void PrepareForFocusTransitionL();

   614 	

   615     /**

   616      * From @c MEikDialogPageObserver.

   617      * 

   618      * Should be implemented to take any action required when the active 

   619      * dialog page is changed.

   620      *

   621      * Not implemented.

   622      * 

   623      * @param aPageId The ID of the page being switched to.

   624      */

   625     IMPORT_C virtual void PageChangedL(TInt aPageId);

   626 	

   627     /** 

   628      * From @c MEikDialogPageObserver

   629      * 

   630      * Should be implemented to take any action required when the current 

   631      * line is changed to @c aControlId. 

   632      *

   633      * Not implemented.

   634      *

   635      * @param aControlId The ID of the control being switched to.

   636      */

   637     IMPORT_C virtual void LineChangedL(TInt aControlId);

   638 

   639 public: // from MEikDialogPageObserver

   640 	

   641     /** 

   642      * From @c MEikDialogPageObserver.

   643      *

   644      * Creates a control line in the dialog.on the active page with caption

   645      * text @c aCaption.

   646      * The line can thereafter be accessed through the identifier 

   647      * @c aControlId.

   648      * A control of type @c aControlType is created by the @c Eikon 

   649      * control factory and the return value of the line set to @c aReturnValue.

   650      * If the value of @c aControlType is not known to the Eikon control 

   651      * factory then the construction of the control must be handled by 

   652      * @c CreateCustomControlL.

   653      * 

   654      * @param aControlType The type of the custom control.

   655      * @return Information for the custom control.

   656      */

   657     IMPORT_C virtual SEikControlInfo CreateCustomControlL(TInt aControlType);

   658 	

   659     /**

   660      * From @c MEikDialogPageObserver.

   661      * 

   662      * For forms only:

   663      * Ths should be overriden with mappings between the base control types 

   664      * that form knows how to layout.

   665      * 

   666      * Always returns @c MEikDialogPageObserver::EUnknownType. 

   667      *

   668      * @param aControlType Not used.

   669      * @return Current implementation always 

   670      *         returns @c MEikDialogPageObserver::EUnknownType.

   671      */

   672     IMPORT_C MEikDialogPageObserver::TFormControlTypes 

   673         ConvertCustomControlTypeToBaseControlType(TInt aControlType) const;

   674 	

   675     /**

   676      * From @c MEikDialogPageObserver. 

   677      * 

   678      * Should be implemented to get the custom auto value for the custom control

   679      * @c aControl of type @c aControlType with return value @c aReturnValue. 

   680      *

   681      * This method is included in the interface to support deprecated legacy

   682      * code only.

   683      *

   684      * Not implemented. 

   685      * 

   686      * @param aReturnValue The custom controls return value.

   687      * @param aControlType The type of the custom control.

   688      * @param aControl The control whose auto value is being retrieved.

   689      * @deprecated

   690      */

   691     IMPORT_C virtual void GetCustomAutoValue(TAny* aReturnValue,

   692                                              TInt aControlType,

   693                                              const CCoeControl* aControl);

   694 

   695 protected: // from MCoeControlContext

   696 

   697     /**

   698      * From @c MCoeControlContext.

   699      * 

   700      * Initialises graphics context settings.

   701      *

   702      * This function should be implemented by derived classes to initialise

   703      * the graphics context, given by @c aGc, with the required settings. 

   704      *

   705      * @param aGc The graphics context to be initialised.

   706      */

   707 	IMPORT_C void PrepareContext(CWindowGc& aGc) const;

   708 

   709 protected: //from CCoeControl

   710 

   711     /**

   712      * From @c CCoeControl.

   713      *

   714      * Writes the internal state to the given stream.

   715      * 

   716      * @param[out] aWriteStream Target stream.

   717      */ 

   718 	IMPORT_C void WriteInternalStateL(RWriteStream& aWriteStream) const;

   719 

   720 private: // from CCoeControl

   721 

   722 	IMPORT_C void Draw(const TRect& aRect) const;

   723 

   724 protected:

   725 

   726     /**

   727      * Returns the number of the control components.

   728      * 

   729      * In Avkon returns 2 as the button group container is not internal.

   730      *

   731      * @return Number of control components. 

   732      */

   733 	IMPORT_C TInt CountComponentControls() const;

   734 

   735     /**

   736      * Returns a pointer to the component control at the specified index 

   737      * in the component control list.

   738      *

   739      * Does not imply transfer of ownership.

   740      *

   741      * @param aIndex The index of the required component control.

   742      * @return The required component control.

   743      */

   744 	IMPORT_C CCoeControl* ComponentControl(TInt aIndex) const;

   745 

   746 protected:

   747 

   748     /**

   749      * Gets number of lines in the specified page. 

   750      * 

   751      * @param aPageIndex Index of the page container. 

   752      * @return The number of lines in the page.

   753      */

   754 	IMPORT_C TInt GetNumberOfLinesOnPage(TInt aPageIndex) const;

   755 

   756     /** 

   757      * Gets number of pages in the page selector.

   758      * 

   759      * @return The number of pages. 

   760      */ 

   761 	IMPORT_C TInt GetNumberOfPages() const;

   762 

   763     /**

   764      * Gets specified line from specified page.

   765      *

   766      * @param aLineIndex Index of the requested line. 

   767      * @param aPageIndex Index of the requested page. 

   768      * @return The wanted line.

   769      */ 

   770 	IMPORT_C CEikCaptionedControl* GetLineByLineAndPageIndex(TInt aLineIndex, 

   771                                                       TInt aPageIndex) const;

   772 

   773 private:

   774 	

   775     IMPORT_C void SizeChanged();

   776 	

   777     IMPORT_C TSize MinimumSize();

   778 	

   779     IMPORT_C void ConstructFromResourceL(TResourceReader& aReader);

   780 	

   781     IMPORT_C void Reserved_2();

   782 

   783 private:

   784 

   785     /**

   786     * From CAknControl

   787     */

   788     IMPORT_C void* ExtensionInterface( TUid aInterface );

   789 

   790 protected: // from MCoeControlObserver

   791 

   792     /**

   793      * From @c MCoeControlObserver. 

   794      *

   795      * Handles control events. 

   796      * 

   797      * The default implementation handles events of type @c EEventStateChanged,

   798      * @c EEventInteractionRefused, and @c EEventPrepareFocusTransition by 

   799      * calling @c HandleControlStateChangeL(), @c HandleInteractionRefused(),

   800      * and @c PrepareForFocusTransitionL() respectively.

   801      *

   802      * Overrides @c MCoeControlObserver::HandleControlEventL().

   803      * 

   804      * @param aControl The control reporting the event.

   805      * @param aEventType The event type.

   806      */ 

   807 	IMPORT_C void HandleControlEventL(CCoeControl* aControl,

   808                                       TCoeEvent aEventType);

   809 

   810 protected: // new functions

   811 

   812     /**

   813      * Tries to exit the dialog when the specified button is pressed, if this 

   814      * button should exit the dialog.

   815      *

   816      * See @c OkToExitL() to determine which buttons can exit the dialog.

   817      * 

   818      * This will fail if user exit is prevented by the 

   819      * @c EEikDialogFlagNoUserExit flag. If the @c EEikDialogFlagNotifyEsc flag

   820      * is not set and the dialog has been cancelled it immediately deletes 

   821      * itself.

   822      * 

   823      * @param aButtonId The id of the pressed button.

   824      */

   825     IMPORT_C void TryExitL(TInt aButtonId);

   826 	

   827     /**

   828      * Adjusts the IDs of all controls on a specified page. 

   829      *

   830      * The adjustment consists of incrementing all the control IDs by 

   831      * @c aControlIdDelta.

   832      * 

   833      * @param aPageId The page on which the control IDs are to be adjusted.

   834      * @param aControlIdDelta The amount to increment the IDs.

   835      */

   836     IMPORT_C void AdjustAllIdsOnPage(TInt aPageId,TInt aControlIdDelta);

   837 	

   838     /** 

   839      * Protected constructor creates a sleeping dialog from a resource. 

   840      *

   841      * A sleeping dialog is one which can be displayed at any time since 

   842      * its memory resources are pre-allocated.

   843      * 

   844      * @param aResourceId The resource ID of the dialog to be constructed.

   845      */ 

   846     IMPORT_C void ConstructSleepingDialogL(TInt aResourceId);

   847 	

   848     /**

   849      * Protected construction of a high priority sleeping dialog from 

   850      * a resource. 

   851      *

   852      * A sleeping dialog is one which can be displayed at any time since 

   853      * its memory resources are pre-allocated. 

   854      * 

   855      * @param aResourceId The resource ID of the dialog to be constructed.

   856      */ 

   857     IMPORT_C void ConstructSleepingAlertDialogL(TInt aResourceId);

   858 	

   859     /** 

   860      * Rouses a sleeping dialog by dynamically constructing the dialog and

   861      * then bringing it to the front.

   862      *

   863      * Derived dialogs should pre-allocate any memory they need for 

   864      * initialisation during construction via @c ConstructFromResourceL() 

   865      * for each individual control. Derived versions of @c PreLayoutDynInitL()

   866      * cannot rely on allocating any further memory.

   867      *

   868      * @return Zero.

   869      */ 

   870     IMPORT_C TInt RouseSleepingDialog();

   871 

   872     /**

   873      * Exits sleeping dialog without deleting it.

   874      */ 

   875     IMPORT_C void ExitSleepingDialog();

   876 	

   877     /** 

   878      * Gets the ID of the control in the focused line.

   879      * 

   880      * @return Current control ID.

   881      */ 

   882     IMPORT_C TInt IdOfFocusControl() const;

   883 	

   884     /**

   885      * Gets the line index of the specified control.

   886      *

   887      * The control must be on the active page.

   888      *

   889      * @param aControl The control for which the line index is required.

   890      * @return The line index, or @c KErrNotFound if the control is not on the

   891      *         active page.

   892      */ 

   893     IMPORT_C TInt FindLineIndex(const CCoeControl& aControl) const;

   894 

   895     /**

   896      * Gets a pointer to the line containing the specified control. 

   897      *

   898      * This does not imply transfer of ownership from the dialog.

   899      *

   900      * @param aControlId The ID of the control.

   901      * @return A pointer to the line containing the control identified by

   902      *         @c aControlId.

   903      */ 

   904     IMPORT_C CEikCaptionedControl* Line(TInt aControlId) const;

   905 

   906     /**

   907      * Gets a pointer to the current line.

   908      *

   909      * This does not imply transfer of ownership from the dialog.

   910      *

   911      * @return A pointer to the current line.

   912      */

   913     IMPORT_C CEikCaptionedControl* CurrentLine() const;

   914 	

   915     /**

   916      * Rotates the focus by a specified number of steps.

   917      *

   918      * Each line is a step, as are dialog tabs.

   919      *

   920      * @param aDelta The number of steps.

   921      * @return @c ETrue if rotation of focus is successful, 

   922      *         @c EFalse if there are no lines in the dialog or the rotation is

   923      *         otherwise unsuccessful.

   924      */ 

   925     IMPORT_C TBool RotateFocusByL(TInt aDelta);

   926 	

   927     /**

   928      * Gets the index of the dialog's active page.

   929      *

   930      * Pages are indexed from 0 in the order they are added.

   931      *

   932      * @return The index of the active page.

   933      */ 

   934     IMPORT_C TInt ActivePageIndex() const;

   935 	

   936     /**

   937      * Recalculates the minimum sizes of the lines on the active page.

   938      *

   939      * Overrides @c CCoeControl::ResetLineMinimumSizes().

   940      */

   941     IMPORT_C void ResetLineMinimumSizes();

   942 	

   943     /**

   944      * Swaps the dialog's button group container with a new container.

   945      *

   946      * The dialog takes ownership of the new container. A pointer to the old

   947      * button group container is returned and ownership of this object is 

   948      * transferred to the calling object.

   949      *

   950      * @param aContainer The new button group container.

   951      * @return A pointer to the old button group container. This is no longer

   952      *         owned by the dialog.

   953      */

   954     IMPORT_C CEikButtonGroupContainer* SwapButtonGroupContainer(

   955                                         CEikButtonGroupContainer* aContainer);

   956 	

   957     /**

   958      * Gets a pointer to the dialog's internal button command observer. 

   959      *

   960      * This is required when creating a new button group container for 

   961      * the dialog.

   962      * 

   963      * A dialog uses a proxy to observe button commands. This means dialog

   964      * subclasses can directly observe commands, either issued by controls 

   965      * added to the dialog pages, or by menus launched by the dialog.

   966      *

   967      * @since 5.1

   968      * @return A pointer to the dialog's internal button

   969      *         command observer.

   970      */ 

   971     IMPORT_C MEikCommandObserver* ButtonCommandObserver() const;

   972 

   973 protected: // new functions

   974 

   975     /**

   976      * Not implemented.

   977      *

   978      * @param aButtonId Not used.

   979      * @return Always return @c ETrue.

   980      */

   981     IMPORT_C virtual TBool OkToExitL(TInt aButtonId);

   982 	

   983     /**

   984      * Initializes the dialog's controls before the dialog is sized and 

   985      * layed out. Empty by default.

   986      */

   987     IMPORT_C virtual void PreLayoutDynInitL();

   988 	

   989     /**

   990      * Initializes the dialog's controls after the dialog has been sized 

   991      * but before it has been activated. Empty by default.

   992      */

   993     IMPORT_C virtual void PostLayoutDynInitL();

   994 	

   995     /**

   996      * Sets the line which initally receives focus.

   997      * This is the first focusable line on the first page in the

   998      * dialog by default. Reimplementations of this method must

   999      * activate a page before doing anything else.

  1000      */

  1001     IMPORT_C virtual void SetInitialCurrentLine();

  1002 	

  1003     /**

  1004      * Handles a state change in the control with id aControlId. 

  1005      * Empty by default.

  1006      *

  1007      * @param aControlId Not used.

  1008      */

  1009     IMPORT_C virtual void HandleControlStateChangeL(TInt aControlId);

  1010 	

  1011     /**

  1012      * Should handle an attempt by the user to activate a dimmed button with

  1013      * id aControlId. Prints an info message by default.

  1014      *

  1015      * Not implemented / Does nothing in Avkon.

  1016      *

  1017      * @param aControlId Not used.

  1018      */

  1019     IMPORT_C virtual void HandleInteractionRefused(TInt aControlId);

  1020 	

  1021     /**

  1022      * Sets the size and position of the dialog given the specified size hint.

  1023      *

  1024      * The parameter is ignored if the @c FlagFillAppClientRect is set.

  1025      * Otherwise it it centered and given the size that was asked for.

  1026      *

  1027      * @param aSize The new size.

  1028      */

  1029     IMPORT_C virtual void SetSizeAndPosition(const TSize& aSize);

  1030 	

  1031     /**

  1032      * Returns the border style for this dialog.

  1033      *

  1034      * @return Border style. Always returns @c AknBorderId::EAknBorderNotePopup.

  1035      */

  1036     IMPORT_C virtual TInt BorderStyle();

  1037 	

  1038     // Added for Avkon

  1039 

  1040     /**

  1041      * Routine to map the button id ( Avkon softkey command id) to 

  1042      * @c CEikBidCancel if it is a "cancel" type command type. 

  1043      *

  1044      * The following cases are mapped to a give an @c ExecuteLD return value 

  1045      * of 0:

  1046      *

  1047      *		@c EAknSoftkeyCancel:

  1048      *		@c EAknSoftkeyBack:

  1049      *		@c EAknSoftkeyNo:

  1050      *

  1051      * Other cases are left unchanged.

  1052      * 

  1053      * This operation is performed at the last minute and does not affect other

  1054      * processing in @c CEik/AknDialog. 

  1055      *

  1056      * It is a framework method; It can be overridded to obtain customized 

  1057      * behaviour.

  1058      *

  1059      * @param aButtonId input id to map. 

  1060      * @return 0 for re-mapped negative command ids other values 

  1061      *         are returned as their original command id values.

  1062      */

  1063     IMPORT_C virtual TInt MappedCommandId( TInt aButtonId );

  1064 	

  1065     /**

  1066      * Get form flags of the active page

  1067      *

  1068      * @return Active page's form flags 

  1069      */ 

  1070     IMPORT_C TInt FormFlagsFromActivePage();

  1071 

  1072 /* The following two methods are deprecated

  1073 	GetFirstLineOnFirstPageOrNull

  1074 	ControlsOnPage

  1075 

  1076 instead the functionality can be achieved by

  1077 	TInt GetNumberOfLinesOnPage(TInt aPageIndex) const;

  1078 	TInt GetNumberOfPages() const;

  1079 	CEikCaptionedControl* GetLineByLineAndPageIndex(TInt aLineIndex, 

  1080 	                                                TInt aPageIndex) const;

  1081 */

  1082 

  1083     /**

  1084      * Gets first line of the first page. 

  1085      * 

  1086      * @deprecated

  1087      * @return Pointer to the first line of the first page. If NULL there is no

  1088      *         such line.

  1089      */

  1090 	IMPORT_C virtual CEikCaptionedControl* GetFirstLineOnFirstPageOrNull();

  1091 

  1092     /**

  1093      * Gets all lines in the given page.

  1094      *

  1095      * @param aControls After execution holds all captions in the page.

  1096      * @param aPageId ID of the target page.

  1097      * @deprecated

  1098      */

  1099     IMPORT_C void ControlsOnPage(RArray<CEikCaptionedControl*>& aControls, 

  1100                                  TInt aPageId) const;

  1101 

  1102     

  1103 

  1104 

  1105 protected: // from MObjectProvider

  1106 

  1107     /**

  1108      * From @c MObjectProvider.

  1109      *

  1110      * Retrieves an object of the same type as that encapsulated in aId.

  1111      *

  1112      * This function is used to allow controls to ask their owners for 

  1113      * access to other objects that they own.

  1114      *

  1115      * Other than in the case where NULL is returned, the object returned 

  1116      * must be of the same object type - that is, the @c ETypeId member of 

  1117      * the object pointed to by the pointer returned by this function must 

  1118      * be equal to the iUid member of aId.

  1119      *

  1120      * @param aId An encapsulated object type ID. 

  1121      * @return Encapsulates the pointer to the object provided. 

  1122      *         Note that the encapsulated pointer may be NULL. 

  1123      */ 

  1124     IMPORT_C TTypeUid::Ptr MopSupplyObject(TTypeUid aId);

  1125 

  1126 private: // new functions

  1127 

  1128     IMPORT_C virtual void CEikDialog_Reserved_1();

  1129 	

  1130     IMPORT_C virtual void CEikDialog_Reserved_2();

  1131 

  1132 private: // internal functions

  1133 	

  1134     void BaseConstructL();

  1135