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      * Closes the selection list 

   251      *

   252      *  @since v5.2 

   253      */

   254     IMPORT_C void CloseSelectionListL();

   255 

   256 public: // from CCoeControl

   257 

   258     /** 

   259      * From @c CCoeControl.

   260      *

   261      * Handles key events.

   262      *

   263      * @param aKeyEvent The key event. 

   264      * @param aType The type of key event.

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

   266      */

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

   268 

   269     /** 

   270      * From @c CCoeControl.

   271      * 

   272      * Constructs the control from a resource file.

   273      *

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

   275      */

   276 	IMPORT_C void ConstructFromResourceL(TResourceReader& aReader);

   277 

   278     /** 

   279      * From @c CCoeControl.

   280      *

   281      * Determines the minimum size of the control.

   282      * 

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

   284      */

   285 	IMPORT_C TSize MinimumSize();

   286 

   287     /**

   288      * From @c CCoeControl.

   289      *

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

   291      *

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

   293 	 */

   294 	IMPORT_C void HandleResourceChange(TInt aType);

   295 

   296     /**

   297      * From @c CCoeControl.

   298      *

   299      * Handles pointer events of popup field list.

   300      *

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

   302      */

   303     IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);

   304 public:

   305 	/**

   306     /**

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

   308      *

   309      * @param aMaxNoLines The maximum number of lines.

   310      */

   311 	IMPORT_C void SetMaxNumberOfLinesPermitted(TInt aMaxNoLines);

   312 public:

   313 

   314     /**

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

   316      * the label.

   317      *

   318      * @param aFormFieldRect The form field rectangle.

   319      */

   320 	IMPORT_C void SetFormFieldRect(TRect aFormFieldRect);

   321 

   322 protected: // from MCoeControlObserver

   323 	

   324     /** 

   325      * From @c MCoeControlObserver.

   326      *

   327      * Handles an event from an observed control.

   328      *

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

   330      * @param aEvent The event type. 

   331      */

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

   333 protected: // from MEikCommandObserver

   334 	

   335     /**

   336      * From @c MEikCommandObserver.

   337      *

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

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

   340      * 

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

   342      */

   343 	IMPORT_C void ProcessCommandL(TInt aCommandId);	

   344 protected: // From MEikListBoxObserver

   345 

   346     /**

   347      * From @c MEikListBoxObserver.

   348      *

   349      * Processes key events from the listbox. Responds to 

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

   351      * 

   352      * @param aListBox Listbox being observed.

   353      * @param aEventType Event observed.

   354      */

   355     IMPORT_C void HandleListBoxEventL(CEikListBox* aListBox, 

   356                                       TListBoxEvent aEventType);

   357 protected: // from CCoeControl

   358 

   359     /** 

   360      * From @c CCoeControl.

   361      *

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

   363      *

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

   365      */

   366 	IMPORT_C TInt CountComponentControls() const;

   367 

   368     /** 

   369      * From @c CCoeControl.

   370      *

   371      * Gets an indexed component of a compound control.

   372      * 

   373      * @param aIndex Control index.

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

   375      */

   376 	IMPORT_C CCoeControl* ComponentControl(TInt aIndex) const;

   377 

   378     /** 

   379      * From @c CCoeControl.

   380      *

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

   382      * control.

   383      */

   384 	IMPORT_C void SizeChanged();

   385 

   386     /**

   387      * From @c CCoeControl.

   388      *

   389      * Responds to a change in focus.

   390      *

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

   392      *        @c SetFocus(). 

   393      */

   394     IMPORT_C void FocusChanged( TDrawNow aDrawNow );

   395 

   396     /**

   397      * From @c CEikBorderedControl.

   398      *

   399      * Called by the framework to draw the control.

   400      *

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

   402      *        needed.

   403      */

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

   405 

   406 private: // from CCoeControl

   407 	IMPORT_C void Reserved_1();

   408 	IMPORT_C void Reserved_2();

   409 

   410 private:

   411     /**

   412     * From CAknControl

   413     */

   414     IMPORT_C void* ExtensionInterface( TUid aInterface );

   415 

   416 protected: // personal

   417 

   418     /**

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

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

   421      * @c ConstructFromResourceL().

   422      */

   423 	void CommonConstructL();

   424 protected: // from MObjectProvider

   425 

   426     /**

   427      * From @c CCoeControl.

   428      *

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

   430      *

   431      * @param aId An encapsulated object type ID.

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

   433      *         Note that the encapsulated pointer may be NULL.

   434      */

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

   436 private: // personal

   437 

   438     /** 

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

   440      *

   441      */

   442 	void ConstructLabelL();

   443 

   444 	/** 

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

   446 	 *

   447 	 */

   448 	void ConstructCommandButtonL();

   449 

   450 	/** 

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

   452 	 *

   453 	 */

   454 	void ConstructSelectionListL();

   455 

   456 	/** 

   457 	 * setup the scroll bar within the selection list box

   458 	 *

   459 	 */

   460 	void SetUpScrollBarL();

   461 

   462 	/** 

   463 	 * set the scroll bar selection

   464 	 *

   465 	 */

   466 	void SetScrollBarSelectionL();

   467 

   468 	/** 

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

   470 	 *

   471 	 */

   472 	void InitialiseRadioButtonBitmapsL();

   473 

   474 	/**

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

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

   477 	 * 

   478 	 * @return TBool ETrue always

   479 	 */

   480 	TBool HandleInteractionConfirmedL();

   481 

   482 	/**

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

   484 	 *

   485 	 */

   486 	void CreatePopoutL();

   487 

   488 	/**

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

   490 	 *

   491 	 */

   492 	void DestroyPopout();

   493 

   494 	/**

   495 	 * Checks to see if the popupfield is empty

   496 	 *

   497 	 */

   498 	TBool IsEmpty() const;

   499 	/**

   500 	 * Checks to see if the popupfield is invalid

   501 	 *

   502 	 */

   503 	TBool IsInvalid() const;

   504 	/**

   505 	 * Handles a horizontal key event

   506 	 *

   507 	 * @return TKeyResponse returns either EKeyWasConsumed

   508 	 *                       or EKeyWasNotConsumed

   509 	 */

   510 	TKeyResponse HandleHorizontalKeyEventL(TUint aKeyEventCode);

   511 private: // Avkon

   512 

   513     /**

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

   515      */

   516 	void CreateCbaL();

   517 

   518 	/**

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

   520 	 * Should be called whenever the flags are changed. 

   521 	 *

   522 	 */

   523 	void ConfigureDecorator();

   524 

   525 	/**

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

   527 	 * Should be called whenever the flags are changed. 

   528 	 *

   529 	 */

   530 	void ConstructLayoutDecoratorL();

   531 

   532 	/**

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

   534 	 *

   535 	 */

   536 	void ShowEmptyListNoteL();

   537 

   538 	/**

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

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

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

   542 	 * normal selection behaviour of popup list is activated.

   543 	 *

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

   545 	 *								if EFalse, popup list was cancelled

   546 	 *

   547 	 */

   548 	void AttemptExitL(TBool aAccept);

   549 

   550 	/**

   551 	 * Changes the mode of the popupfield to one of

   552 	 * the EAknPopupFieldSelectionMode's

   553 	 */

   554 	void ChangeMode(EAknPopupFieldSelectionMode aNewMode);

   555 

   556 private: // async 

   557 	static TInt AttemptExitCallbackL(TAny* aThis);

   558 	void DoAttemptExitL();

   559 	void DoSizeChangedL();

   560 protected:

   561 	// the following members are owned

   562     /**

   563      * Label of the popup field.

   564      * Own.

   565      */

   566 	CEikLabel* iLabel;

   567 

   568     /**

   569      * Bitmap button for the popup field.

   570      * Own.

   571      */

   572 	CAknPopupFieldBitmapButton* iButton;

   573 

   574     /**

   575      * List box for the popup field usage.

   576      * Own.

   577      */

   578 	CAknFormGraphicStyleListBox* iSelectionList;

   579 

   580     /**

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

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

   583      * Own.

   584      */

   585 	CAknListBoxLayoutDecorator* iLayoutDecorator;

   586 

   587     /**

   588      * Button group container for the popup field.

   589      * Own.

   590      */

   591 	CEikButtonGroupContainer* iCba;

   592 

   593     /**

   594      * Active object for calling @c AttemptExitCallbackL asynchronously.

   595      * Own.

   596      */

   597 	CAsyncCallBack* iAttemptExitAsync;

   598 

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

   600     /**

   601      * Flags for the popup field.

   602      */

   603     TInt iFlags;

   604 

   605     /**

   606      * Maximum line width.

   607      */

   608     TInt iWidth;

   609 

   610     /**

   611      * Text to the bottom of the selection array.

   612      * Own.

   613      */

   614     HBufC* iOtherText;

   615 

   616     /**

   617      * The empty list note text.

   618      * Own.

   619      */

   620     HBufC* iEmptyText;

   621 

   622     /**

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

   624      * list are available. 

   625      * Own.

   626      */

   627     HBufC* iInvalidText;

   628 

   629     /**

   630      * Resource id for the empty note.

   631      */

   632 	TInt iEmptyNoteResourceId;

   633 	

   634 	// the following members are not owned

   635     /**

   636      * Query value for the popup field.

   637      * Not own.

   638      */

   639 	MAknQueryValue* iValue;

   640 

   641     /**

   642      * Observer for receiving events from the popup field.

   643      * Not own.

   644      */

   645 	MAknPopupFieldObserver* iObserver;

   646 

   647 	// the following values are member variables

   648     /**

   649      * Enumeration representing form mode values.

   650      */

   651     EAknFormMode iFormMode;

   652 

   653     /**

   654      * Timeout for the empty tone.

   655      */

   656     CAknNoteDialog::TTimeout iEmptyNoteTimeout;

   657 

   658     /**

   659      * Tone for the empty note.

   660      */

   661     CAknNoteDialog::TTone iEmptyNoteTone;

   662 

   663     /**

   664      * Selection array for the popup field.

   665      */

   666     TAknDesCArrayDecorator iDecorator;

   667 

   668     /**

   669      * Enumeration representing selection mode values.

   670      */

   671     EAknPopupFieldSelectionMode iSelectionMode; 

   672 

   673     /**

   674      * Maximum number of items in selection array.

   675      */

   676 	TInt iMaxNoLines;

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

   678 private:

   679 	CAknPopupFieldExtension* iExtension;

   680     TInt iSpare[3];

   681 	};

   682 

   683 #endif // AKNPOPUPFIELD_H