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 *     Represents a combo box type control, used to implement the Series 60 

    16 *     pop-up field.

    17 *     

    18 *

    19 */

    20 

    21 

    22 #ifndef AKNPOPUPFIELD_H

    23 #define AKNPOPUPFIELD_H

    24 

    25 #include <eikcmobs.h>

    26 #include <eiklbx.h>

    27 #include <eikbctrl.h>

    28 #include <eikcmbut.h>

    29 #include <bamdesca.h>

    30 

    31 #include <AknDesCArrayDecorator.h>

    32 #include <AknListBoxLayoutDecorator.h>

    33 #include <aknnotedialog.h>

    34 

    35 class TResourceReader;

    36 class CEikLabel;

    37 class CEikCommandButton;

    38 class CAknFormGraphicStyleListBox;

    39 class MAknQueryValue;

    40 

    41 class CAknPopupField;

    42 class CAknPopupFieldExtension;

    43 

    44 /** 

    45  * this interface should be implemented by classes that need to know

    46  * about events occurring in the popup field control

    47  */

    48 class MAknPopupFieldObserver

    49 	{

    50 public:

    51 	enum TAknPopupFieldEvent

    52 		{

    53 		EAknPopupFieldEventModeChange,

    54 		EAknPopupFieldEventValueChange

    55 		};

    56 public:

    57     /**

    58      * Handles events from the popup field control, such as changes between

    59      * selection list mode and label mode.

    60      *

    61      * @param aPopupField pointer to the popup field control that generated

    62      *        the event.

    63      * @param aEventType the type of event.

    64      * @param aHint for possible future use.

    65      */

    66     virtual void HandlePopupFieldEventL(CAknPopupField* aPopupField,

    67                                         TAknPopupFieldEvent aEventType,

    68                                         TInt aHint)=0;

    69 	};

    70 

    71 /**

    72  * Represents a combo box type control, used to implement the Series 60 

    73  * pop-up field.

    74  */

    75 class CAknPopupField :

    76 	public CEikBorderedControl, 

    77 	public MCoeControlObserver, 

    78 	public MEikCommandObserver, 

    79 	public MEikListBoxObserver

    80 	{

    81 protected:

    82 	/**

    83 	 * Specialises bitmap button to make the layout correct for popup field

    84 	 */

    85 	class CAknPopupFieldBitmapButton : public CEikBitmapButton

    86 		{

    87 	public:

    88 		/**

    89 		 * Constructor

    90 		 */

    91 		CAknPopupFieldBitmapButton();

    92 		};

    93 public:

    94     /**

    95      * Selection mode of the popup field.

    96      */

    97     enum EAknPopupFieldSelectionMode

    98         {

    99         /** 

   100          * Label mode. In Label mode popup field is minimized and popup field

   101          * looks identical to a list item. When it receives the selection key 

   102          * press it is changed to @c EAknPopupFieldSelectionListMode and the 

   103          * pre-defined list is displayed. 

   104          */

   105         EAknPopupFieldLabelMode,

   106 		

   107         /** 

   108          * Selection list mode. In this selection mode pre-defined popup 

   109          * selection list is displayed.

   110          */    

   111 		EAknPopupFieldSelectionListMode

   112 		};

   113 

   114     /**

   115      * Form mode for the popup field.

   116      */

   117 	enum EAknFormMode

   118         {

   119         /** View mode. */

   120         EAknFormModeView,

   121 

   122         /** Editable mode. */    

   123         EAknFormModeEdit,

   124 

   125         /** View mode with graphic. */

   126         EAknFormModeViewWideWithGraphic,

   127 

   128         /** View mode without graphic. */

   129         EAknFormModeViewWideWithoutGraphic,

   130 

   131         /** Edit mode with graphic. */

   132         EAknFormModeEditWideWithGraphic,

   133 

   134         /** Edit mode without graphic. */

   135 		EAknFormModeEditWideWithoutGraphic

   136 		};

   137 public: 

   138 	EAknPopupFieldSelectionMode SelectionMode() const { return iSelectionMode; }

   139 	EAknFormMode FormMode() const { return iFormMode; }

   140     /**

   141      * C++ default constructor.

   142      */

   143 	IMPORT_C CAknPopupField();

   144 

   145 	/**

   146 	 * Destructor

   147 	 */

   148 	IMPORT_C ~CAknPopupField();

   149 

   150     /** 

   151      * Handles 2nd phase construction.

   152      */

   153 	IMPORT_C void ConstructL();

   154 

   155     /**

   156      * Sets a flag that enables user defined entry. Note that flag can also be 

   157      * set from resources, but this method allows behaviour to be changed at 

   158      * runtime.

   159      *

   160      * @param aAllows if @c ETrue sets a flag.

   161      */

   162 	IMPORT_C void SetAllowsUserDefinedEntry(TBool aAllows);

   163 

   164     /**

   165      * Causes a list of pre-defined values to appear. 

   166      * Use this method to activate the pop-up field from a menu option command.

   167      * Note that the desired control must be focused on before it can be 

   168      * activated.

   169      */

   170 	IMPORT_C void ActivateSelectionListL();

   171 

   172     /**

   173      * Used by the client to set the query value. It is used to represent the 

   174      * user defined query value in this popup field control.

   175      *

   176      * @param aValue Pointer to query value, ownership is not passed.

   177      */

   178 	IMPORT_C void SetQueryValueL(MAknQueryValue* aValue);

   179 

   180     /**

   181      * Sets the font of the contained label.

   182      *

   183      * @param aFont Font definition used to set the font of the contained 

   184      *        label.

   185      */

   186 	IMPORT_C void SetFont(const CFont* aFont);

   187 

   188     /**

   189      * Sets a flag that determines whether the indicators are shown.

   190      * In practice the indicators have the appearance of radio buttons.

   191      *

   192      * @param aShowIndicators If @c ETrue, indicators are displayed.

   193      */

   194 	IMPORT_C void SetShowIndicatorsL(TBool aShowIndicators);

   195 

   196     /**

   197      * Number of lines used.

   198      *

   199      * @return Number of entries on the selection list. If selection list 

   200      *         is not active, 1 is returned.

   201      *	       NOTE that the number is limited by @c KAknMaxEditorLines.

   202      */

   203 	IMPORT_C TInt NumLines() const;

   204 

   205     /**

   206      * Sets an observer of this class to receive events from popup field.

   207      * 

   208      * @param aObserver Pointer to the class that implements the observer 

   209      *        interface.

   210      */

   211 	IMPORT_C void SetPopupFieldObserver(MAknPopupFieldObserver* aObserver);

   212 

   213     /**

   214      * Sets the note to be displayed when the selection list has no items 

   215      * available.

   216      * 

   217      * @param aResourceId Resource id for the note.

   218      * @param aTimeout = CAknNoteDialog::EShortTimeout Timeout for the note. 

   219      * @param aTone = CAknNoteDialog::ENoTone Tone for the note.

   220      */

   221 	IMPORT_C void SetEmptyListNoteL(TInt aResourceId,

   222 									CAknNoteDialog::TTimeout aTimeout = CAknNoteDialog::EShortTimeout,

   223 									CAknNoteDialog::TTone aTone = CAknNoteDialog::ENoTone);

   224 

   225     /**

   226      * Sets the empty list note text. This note is displayed when the 

   227      * selection list has no items available.

   228      * 

   229      * @param aEmptyText The empty list note text.

   230      */

   231     IMPORT_C void SetEmptyTextL(const TDesC& aEmptyText);

   232 

   233     /**

   234      * Sets the text to be added to the bottom of the array to enter user 

   235      * defined data.

   236      * 

   237      * @param aOtherText Text to the bottom of the selection array.

   238      */

   239 	IMPORT_C void SetOtherTextL(const TDesC& aOtherText);

   240 

   241     /**

   242      * Sets the text for view state when none of the elements in the

   243      * list are available. 

   244      *

   245      * @param aInvalidText The invalid text.

   246      */

   247 	IMPORT_C void SetInvalidTextL(const TDesC &aInvalidText);

   248 

   249 

   250 public: // from CCoeControl

   251 

   252     /** 

   253      * From @c CCoeControl.

   254      *

   255      * Handles key events.

   256      *

   257      * @param aKeyEvent The key event. 

   258      * @param aType The type of key event.

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

   260      */

   261 	IMPORT_C TKeyResponse OfferKeyEventL(const TKeyEvent& aKeyEvent,TEventCode aType);

   262 

   263     /** 

   264      * From @c CCoeControl.

   265      * 

   266      * Constructs the control from a resource file.

   267      *

   268      * @param aReader The resource reader pointing to the popup field resource.

   269      */

   270 	IMPORT_C void ConstructFromResourceL(TResourceReader& aReader);

   271 

   272     /** 

   273      * From @c CCoeControl.

   274      *

   275      * Determines the minimum size of the control.

   276      * 

   277      * @return The minimum size required by the control.

   278      */

   279 	IMPORT_C TSize MinimumSize();

   280 

   281     /**

   282      * From @c CCoeControl.

   283      *

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

   285      *

   286      * @param aType The type of the resource change. 

   287 	 */

   288 	IMPORT_C void HandleResourceChange(TInt aType);

   289 

   290     /**

   291      * From @c CCoeControl.

   292      *

   293      * Handles pointer events of popup field list.

   294      *

   295      * @param aPointerEvent The pointer event to be handled.

   296      */

   297     IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);

   298 public:

   299 	/**

   300     /**

   301      * Sets the maximium number of lines that can be displayed.

   302      *

   303      * @param aMaxNoLines The maximum number of lines.

   304      */

   305 	IMPORT_C void SetMaxNumberOfLinesPermitted(TInt aMaxNoLines);

   306 public:

   307 

   308     /**

   309      * Sets a form field rectangle so that a popup field can correctly position

   310      * the label.

   311      *

   312      * @param aFormFieldRect The form field rectangle.

   313      */

   314 	IMPORT_C void SetFormFieldRect(TRect aFormFieldRect);

   315 

   316 protected: // from MCoeControlObserver

   317 	

   318     /** 

   319      * From @c MCoeControlObserver.

   320      *

   321      * Handles an event from an observed control.

   322      *

   323      * @param aControl The control that sent the event.

   324      * @param aEvent The event type. 

   325      */

   326 	IMPORT_C void HandleControlEventL(CCoeControl* aControl,TCoeEvent aEvent);

   327 protected: // from MEikCommandObserver

   328 	

   329     /**

   330      * From @c MEikCommandObserver.

   331      *

   332      * Processes events from the softkeys. Responds to @c EAknSoftkeyOk and 

   333      * @c EAknSoftkeyCancel to accept or cancel the pop-up.

   334      * 

   335      * @param aCommandId Event Id from the soft-key.

   336      */

   337 	IMPORT_C void ProcessCommandL(TInt aCommandId);	

   338 protected: // From MEikListBoxObserver

   339 

   340     /**

   341      * From @c MEikListBoxObserver.

   342      *

   343      * Processes key events from the listbox. Responds to 

   344      * @c EEventEnterKeyPressed to accept the pop-up.

   345      * 

   346      * @param aListBox Listbox being observed.

   347      * @param aEventType Event observed.

   348      */

   349     IMPORT_C void HandleListBoxEventL(CEikListBox* aListBox, 

   350                                       TListBoxEvent aEventType);

   351 protected: // from CCoeControl

   352 

   353     /** 

   354      * From @c CCoeControl.

   355      *

   356      * Gets the number of controls contained in a compound control.

   357      *

   358      * @return The number of component controls contained by this control.

   359      */

   360 	IMPORT_C TInt CountComponentControls() const;

   361 

   362     /** 

   363      * From @c CCoeControl.

   364      *

   365      * Gets an indexed component of a compound control.

   366      * 

   367      * @param aIndex Control index.

   368      * @return The component control with an index of @c aIndex. 

   369      */

   370 	IMPORT_C CCoeControl* ComponentControl(TInt aIndex) const;

   371 

   372     /** 

   373      * From @c CCoeControl.

   374      *

   375      * Responds to changes to the size and position of the contents of this 

   376      * control.

   377      */

   378 	IMPORT_C void SizeChanged();

   379 

   380     /**

   381      * From @c CCoeControl.

   382      *

   383      * Responds to a change in focus.

   384      *

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

   386      *        @c SetFocus(). 

   387      */

   388     IMPORT_C void FocusChanged( TDrawNow aDrawNow );

   389 

   390     /**

   391      * From @c CEikBorderedControl.

   392      *

   393      * Called by the framework to draw the control.

   394      *

   395      * @param aRect Rectangle in which the Cone framework believes drawing is 

   396      *        needed.

   397      */

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

   399 

   400 private: // from CCoeControl

   401 	IMPORT_C void Reserved_1();

   402 	IMPORT_C void Reserved_2();

   403 

   404 private:

   405     /**

   406     * From CAknControl

   407     */

   408     IMPORT_C void* ExtensionInterface( TUid aInterface );

   409 

   410 protected: // personal

   411 

   412     /**

   413      * Construction tasks common to both a normal construction and a construction 

   414      * from a resource. Used from @c ConstructL() and 

   415      * @c ConstructFromResourceL().

   416      */

   417 	void CommonConstructL();

   418 protected: // from MObjectProvider

   419 

   420     /**

   421      * From @c CCoeControl.

   422      *

   423      * Retrieves an object of the same type as that encapsulated in @c aId.

   424      *

   425      * @param aId An encapsulated object type ID.

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

   427      *         Note that the encapsulated pointer may be NULL.

   428      */

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

   430 private: // personal

   431 

   432     /** 

   433      * Create the label that will show the currently selected value.

   434      *

   435      */

   436 	void ConstructLabelL();

   437 

   438 	/** 

   439 	 * Create the command button that will be used to show the other choices indicator.

   440 	 *

   441 	 */

   442 	void ConstructCommandButtonL();

   443 

   444 	/** 

   445 	 * Create the selection list box that will fill the expanded popup field

   446 	 *

   447 	 */

   448 	void ConstructSelectionListL();

   449 

   450 	/** 

   451 	 * setup the scroll bar within the selection list box

   452 	 *

   453 	 */

   454 	void SetUpScrollBarL();

   455 

   456 	/** 

   457 	 * set the scroll bar selection

   458 	 *

   459 	 */

   460 	void SetScrollBarSelectionL();

   461 

   462 	/** 

   463 	 * Set up the bitmap array for the "not pushed" and "pushed in" states

   464 	 *

   465 	 */

   466 	void InitialiseRadioButtonBitmapsL();

   467 

   468 	/**

   469 	 * Handles the case where the selection list is closed. If necessary, 

   470 	 * update the value of the text label that is displayed.

   471 	 * 

   472 	 * @return TBool ETrue always

   473 	 */

   474 	TBool HandleInteractionConfirmedL();

   475 

   476 	/**

   477 	 * Create the popup list. Warn the user if there are no entries in the list.

   478 	 *

   479 	 */

   480 	void CreatePopoutL();

   481 

   482 	/**

   483 	 * Destroy the popup list and remove it from the stack

   484 	 *

   485 	 */

   486 	void DestroyPopout();

   487 

   488 	/**

   489 	 * Checks to see if the popupfield is empty

   490 	 *

   491 	 */

   492 	TBool IsEmpty() const;

   493 	/**

   494 	 * Checks to see if the popupfield is invalid

   495 	 *

   496 	 */

   497 	TBool IsInvalid() const;

   498 	/**

   499 	 * Handles a horizontal key event

   500 	 *

   501 	 * @return TKeyResponse returns either EKeyWasConsumed

   502 	 *                       or EKeyWasNotConsumed

   503 	 */

   504 	TKeyResponse HandleHorizontalKeyEventL(TUint aKeyEventCode);

   505 private: // Avkon

   506 

   507     /**

   508      * Creates the CBA for use when the selection list is active

   509      */

   510 	void CreateCbaL();

   511 

   512 	/**

   513 	 * Configures the decoration according to the currently set flags.

   514 	 * Should be called whenever the flags are changed. 

   515 	 *

   516 	 */

   517 	void ConfigureDecorator();

   518 

   519 	/**

   520 	 * Configures the layout decoration according to the radio button flag

   521 	 * Should be called whenever the flags are changed. 

   522 	 *

   523 	 */

   524 	void ConstructLayoutDecoratorL();

   525 

   526 	/**

   527 	 * display a note when the selection list has no items available

   528 	 *

   529 	 */

   530 	void ShowEmptyListNoteL();

   531 

   532 	/**

   533 	 * Re-defined method of the base class. Gets called when the 

   534 	 * user tries to select a value. If required, an editor is created to 

   535 	 * allow the user to input the user defined value. Otherwise, the

   536 	 * normal selection behaviour of popup list is activated.

   537 	 *

   538 	 * @param aAccept	If ETrue, popup list was accepted; 

   539 	 *								if EFalse, popup list was cancelled

   540 	 *

   541 	 */

   542 	void AttemptExitL(TBool aAccept);

   543 

   544 	/**

   545 	 * Changes the mode of the popupfield to one of

   546 	 * the EAknPopupFieldSelectionMode's

   547 	 */

   548 	void ChangeMode(EAknPopupFieldSelectionMode aNewMode);

   549 

   550 private: // async 

   551 	static TInt AttemptExitCallbackL(TAny* aThis);

   552 	void DoAttemptExitL();

   553 	void DoSizeChangedL();

   554 protected:

   555 	// the following members are owned

   556     /**

   557      * Label of the popup field.

   558      * Own.

   559      */

   560 	CEikLabel* iLabel;

   561 

   562     /**

   563      * Bitmap button for the popup field.

   564      * Own.

   565      */

   566 	CAknPopupFieldBitmapButton* iButton;

   567 

   568     /**

   569      * List box for the popup field usage.

   570      * Own.

   571      */

   572 	CAknFormGraphicStyleListBox* iSelectionList;

   573 

   574     /**

   575      * Contains a popup field selection array and a leading text that will be 

   576      * inserted before the text from the descriptor array entry.

   577      * Own.

   578      */

   579 	CAknListBoxLayoutDecorator* iLayoutDecorator;

   580 

   581     /**

   582      * Button group container for the popup field.

   583      * Own.

   584      */

   585 	CEikButtonGroupContainer* iCba;

   586 

   587     /**

   588      * Active object for calling @c AttemptExitCallbackL asynchronously.

   589      * Own.

   590      */

   591 	CAsyncCallBack* iAttemptExitAsync;

   592 

   593 	// the following fields are reflected in the POPUP_FIELD resource structure

   594     /**

   595      * Flags for the popup field.

   596      */

   597     TInt iFlags;

   598 

   599     /**

   600      * Maximum line width.

   601      */

   602     TInt iWidth;

   603 

   604     /**

   605      * Text to the bottom of the selection array.

   606      * Own.

   607      */

   608     HBufC* iOtherText;

   609 

   610     /**

   611      * The empty list note text.

   612      * Own.

   613      */

   614     HBufC* iEmptyText;

   615 

   616     /**

   617      * The invalid text. Used in the view state when none of the elements in the

   618      * list are available. 

   619      * Own.

   620      */

   621     HBufC* iInvalidText;

   622 

   623     /**

   624      * Resource id for the empty note.

   625      */

   626 	TInt iEmptyNoteResourceId;

   627 	

   628 	// the following members are not owned

   629     /**

   630      * Query value for the popup field.

   631      * Not own.

   632      */

   633 	MAknQueryValue* iValue;

   634 

   635     /**

   636      * Observer for receiving events from the popup field.

   637      * Not own.

   638      */

   639 	MAknPopupFieldObserver* iObserver;

   640 

   641 	// the following values are member variables

   642     /**

   643      * Enumeration representing form mode values.

   644      */

   645     EAknFormMode iFormMode;

   646 

   647     /**

   648      * Timeout for the empty tone.

   649      */

   650     CAknNoteDialog::TTimeout iEmptyNoteTimeout;

   651 

   652     /**

   653      * Tone for the empty note.

   654      */

   655     CAknNoteDialog::TTone iEmptyNoteTone;

   656 

   657     /**

   658      * Selection array for the popup field.

   659      */

   660     TAknDesCArrayDecorator iDecorator;

   661 

   662     /**

   663      * Enumeration representing selection mode values.

   664      */

   665     EAknPopupFieldSelectionMode iSelectionMode; 

   666 

   667     /**

   668      * Maximum number of items in selection array.

   669      */

   670 	TInt iMaxNoLines;

   671 	// NOTE: use Extension() to extend this class.

   672 private:

   673 	CAknPopupFieldExtension* iExtension;

   674     TInt iSpare[3];

   675 	};

   676 

   677 #endif // AKNPOPUPFIELD_H