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 * Support for popup setting item lists.  THe MAknQueryValue abstract type is 

    17 * used to carry the state of the selection. 

    18 *

    19 * This file also contains the definition for the contained editor of the setting page,

    20 * CAknPopupSettingList  

    21 *

    22 *

    23 */

    24 

    25 

    26 #ifndef __AKNPOPUPSETTINGPAGE_H__

    27 #define __AKNPOPUPSETTINGPAGE_H__ 

    28 

    29 

    30 #include <AknQueryValue.h>

    31 #include <AknQueryValueText.h>

    32 #include <AknListBoxSettingPage.h>

    33 

    34 #include <AknDesCArrayDecorator.h>

    35 #include <AknListBoxLayoutDecorator.h>

    36 

    37 class CAknPopupSettingList;

    38 class CAknPopupSettingListExtension;

    39 

    40 /** 

    41  * This interface should be implemented by classes that need to know

    42  * about events occurring in the popup field control

    43  */

    44 class MAknPopupSettingListObserver

    45 	{

    46 public:

    47 	/**

    48 	* Event types

    49 	*/

    50 	enum TAknPopupSettingListEvent

    51 		{

    52 		EAknPopupSettingSelectionAndRequestAccept,

    53 		EAknPopupSettingSelectionAndStayOpen,

    54 		EAknPopupSettingSelectionAndClose

    55 		};

    56 public:

    57 /**

    58  * Handle events from the popup field control, such as when it changes between

    59  * selection list mode and label mode.

    60  *

    61  * Implementations of this observer routine should perform a base call to this specific

    62  * method, in order to pick up any default re-layout actions.

    63  *

    64  * @param aPopupSettingList pointer to the popup field control that generated the event

    65  * @param aEventType the type of event

    66  * @param aHint for possible future use

    67  *

    68  */

    69 	virtual void HandlePopupSettingListEventL(	CAknPopupSettingList* aPopupSettingList, 

    70 												TAknPopupSettingListEvent aEventType, 

    71 												TInt aHint)=0;

    72 	};

    73 

    74 /**

    75  *

    76  * Represents menu list that appears in a popped up setting item

    77  */

    78 class CAknPopupSettingList :

    79 	public CAknSetStyleListBox,

    80 	public MEikListBoxObserver

    81 	{

    82 

    83 protected:

    84 

    85 

    86 public:

    87  /** 

    88  * Standard constructor.

    89  */

    90 	IMPORT_C CAknPopupSettingList();

    91 

    92 /** 

    93  * Destructor.

    94  *

    95  */

    96 	IMPORT_C ~CAknPopupSettingList();

    97 

    98 /** 

    99  * 2nd phase construction

   100  *

   101  */

   102 	IMPORT_C void ConstructL();

   103 

   104 /**

   105  * Sets flag that enables user defined entry. Note that flag can also be set from resources, 

   106  * but this method allows behaviour to be changed at runtime.

   107  *

   108  * @param aAllows	if ETrue, set flag; if EFalse, clear flag.

   109  */

   110 	IMPORT_C void SetAllowsUserDefinedEntry(TBool aAllows);

   111 

   112 

   113 /**

   114  * Used by the client to set the query value used to represent the user defined 

   115  * value belonging to this popup field control.

   116  *

   117  * @param aValue	pointer to value, ownership is not passed

   118  *

   119  */

   120 	IMPORT_C void SetQueryValueL(MAknQueryValue* aValue);

   121 

   122 

   123 /**

   124  * Set the flag which determines whether the indicators are shown

   125  * In practice the indicators have the appearance of radio buttons

   126  *

   127  * @param aShowIndicators	

   128  *		If ETrue, indicators are displayed; 

   129  *		if EFalse, indicators are not displayed

   130  *

   131  */

   132 	IMPORT_C void SetShowIndicators(TBool aShowIndicators);

   133 

   134 /**

   135  * number of lines used

   136  *

   137  * @return number of lines being currently displayed by control, which is determined 

   138  *		by the number of entries on the selection list, and whether the selection list is active.

   139  *		NOTE that the number is limited by KAknMaxLinesOnOnePage

   140  *

   141  */

   142 	IMPORT_C TInt NumLines() const;

   143 

   144 /**

   145  * set an observer of this class to receive events from popup setting list

   146  * 

   147  * @param aObserver pointer to the class that implements the observer interface,

   148  *

   149  */

   150 	IMPORT_C void SetPopupSettingListObserver(MAknPopupSettingListObserver* aObserver);

   151 

   152     /**

   153      * Selects current item.

   154      * 

   155      * @internal

   156      */

   157     void SelectCurrentItemL();

   158     

   159     /**

   160 	 * Returns index of currently selected list item.

   161 	 *

   162 	 * @return Currently selected item's index.

   163 	 */

   164     TInt CurrentSelection() const;

   165 

   166 public: 

   167 /** 

   168  * from CCoeControl

   169  * Construct from resources.

   170  * @param aReader	constucted and positioned TResourceReader&

   171  */

   172 	IMPORT_C void ConstructFromResourceL(TResourceReader& aReader);

   173 

   174 protected:

   175 

   176 /**

   177  * Create the popup list. 

   178  *

   179  */

   180 	IMPORT_C void CreateMenuListL();

   181 

   182 /**

   183  * Causes the list of pre-defined values to appear. 

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

   185  * Note that the desired control must have the focus before it can be activated.

   186  *

   187  */

   188 	IMPORT_C void ActivateMenuListL();

   189 

   190 /**

   191  *

   192  * This routine sets up the text arrays for the menu list

   193  *

   194  */

   195 	IMPORT_C void ConfigureMenuListL();

   196 

   197 /**

   198  * All this does now is remove this from the stack

   199  *

   200  */

   201 	IMPORT_C void DestroyMenuList();

   202 

   203 public:

   204     /**

   205     * From CCoeControl. Handles pointer event

   206     * @param aPointerEvent Pointer event to be handled

   207     */

   208     IMPORT_C void HandlePointerEventL( const TPointerEvent& aPointerEvent );

   209     

   210     IMPORT_C void HandleResourceChange(TInt aType);

   211 

   212 private:

   213     /**

   214     * From CAknControl

   215     */

   216     IMPORT_C void* ExtensionInterface( TUid aInterface );

   217 

   218 protected: 

   219 /**

   220  * From MEikListBoxObserver

   221  * Processes key events from the listbox. Responds to EEventEnterKeyPressed to accept

   222  * the pop-up.

   223  *

   224  * @param	aListBox	Listbox being observed

   225  * @param	aEventType	Event observed

   226  *

   227  *

   228  * This implementation is vestige of former implementation when the listbox was wrapped up,

   229  * not derived from. Currently observing itself..

   230  *

   231  */

   232 	IMPORT_C void HandleListBoxEventL(CEikListBox* aListBox, TListBoxEvent aEventType);

   233 

   234 private: // from CCoeControl

   235 	IMPORT_C void Reserved_1();

   236 	IMPORT_C void Reserved_2();

   237 private: 

   238 	void CommonConstructL();

   239 	void SetUpSelectionListL();

   240 /** 

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

   242  *

   243  */

   244 	void InitialiseRadioButtonBitmapsL();

   245 private: 

   246 /**

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

   248  * Should be called whenever the flags are changed. 

   249  *

   250  */

   251 	void ConfigureDecorator();

   252 /**

   253  * Configures the layout decoration according to the "has buttons" flag

   254  * Should be called whenever the flags are changed. 

   255  *

   256  */

   257 	void ConstructLayoutDecoratorL();

   258 

   259 private:

   260 	// the following members are owned

   261 

   262 	TAknDesCArrayDecorator iDecorator;

   263 	CAknListBoxLayoutDecorator* iLayoutDecorator;

   264 

   265 	// the following fields are reflected in the POPUP_SETTING_LIST resource structure

   266 	TInt iFlags;

   267 	HBufC* iOtherText;

   268 	

   269 	TInt iCurrentSelection;

   270 	// elements to hold info regarding "new Item"- produced setting page

   271 	TInt iNewItemSettingPageResourceId;

   272 	TInt iNewItemEditorType;

   273 	TInt iNewItemEditorControlResourceId;

   274 

   275 	// the following members are not owned

   276 	MAknQueryValue* iValue;

   277 	MAknPopupSettingListObserver* iPopupSettingListObserver;

   278 

   279 	//TInt iSpare_1;

   280 	CAknPopupSettingListExtension* iExtension;

   281 	};

   282 

   283 

   284 /**

   285 * Interface for the setting page containing a menu list with a Query value data model 

   286 * This is the more generic of the list-style setting pages. 

   287 *

   288 */

   289 class CAknPopupSettingPage : 

   290 	public CAknListBoxSettingPage, 

   291 	public MAknPopupSettingListObserver

   292 	{

   293 

   294 public:

   295 	/**

   296 	* C++ constructor.  This constructor uses just the setting page resource Id to 

   297 	* construct the setting page, using listbox resource contained in the setting page 

   298 	* resource.

   299 	* @param	aResourceId		a resource identifier for a AVKON_SETTING_PAGE resource

   300 	* @param	aQueryValue		a reference to a query value object

   301 	*/

   302 	IMPORT_C CAknPopupSettingPage(TInt aResourceID, MAknQueryValue& aQueryValue );

   303 

   304 	/**

   305 	 * Constructor that allows separate setting page and editor resources

   306 	 * 

   307 	 * This constructor allows the use of setting page using only the editor resource.  Other combinations are also possible

   308 	 *

   309 	 * In all cases the number (if supplied i.e. <> 0 ) is used.  

   310 	 *

   311 	 *		Editor Resource		Setting Page Resource

   312 	 *			present				present				Both are used (but text & number overridden)

   313 	 *			 = 0					present				Editor resource is used via SP resource (Effectively like the other constructor)

   314 	 *			present				= 0					Default Avkon SP resource if used + this editor resource

   315 	 *			 = 0					= 0					uses default resource for both SP and editor. This is OK if:

   316 	 *	 i) control type is present, 

   317 	 *  ii) a default resource exists ( OK for text, integer, date, time, duration )

   318 	 *

   319 	 * Note: THe first argument is a TDesC* (rather than TDesC&) because the other constructor

   320 	 * cannot initialize such a member without allocation or having an internal dummy buffer.

   321 	 *

   322 	 * Rules for text and numbers: The rules are the same for both:  (non-zero length) text or number other 

   323 	 * than EAknSettingPageNoOrdinalDisplayed if given in this constructor will not override resource 

   324 	 * (unless that is zero length or EAknSettingPageNoOrdinalDisplayed).  Note, however, that text or number given via the 

   325 	 * specific API for setting them, WILL override resource.

   326 	 * It is assumed that number from resource is very rare.  Special text is somewhat more likely.

   327 	 * 

   328 	 * @param aSettingTitleText	Text at top of setting pane

   329 	 * @param aSettingNumber		Number at top left (if present)

   330 	 * @param aControlType			Determines the type constructed and how its resource is read

   331 	 * @param aEditorResourceId	Editor resource to use in the setting page (if present)

   332 	 * @param aSettingPageResourceId		Setting Page to use (if present)

   333 	 * @param aQueryValue			reference to a query value object

   334 	 */

   335 	IMPORT_C CAknPopupSettingPage(	const TDesC* aSettingTitleText, 

   336 								TInt aSettingNumber, 

   337 								TInt aControlType,

   338 								TInt aEditorResourceId, 

   339 								TInt aSettingPageResourceId,

   340 								MAknQueryValue& aQueryValue);

   341 

   342 	/**

   343 	* 2nd stage construction method.  Type specific work is done here; most of the setting

   344 	* page constuction is performed in a call the base contstruction of CAknSettingPage

   345 	*

   346 	*/

   347 	IMPORT_C virtual void ConstructL();

   348 

   349 /**

   350  * Access to the contained listbox (inside popup setting list)

   351  *

   352  * @return	CAknSetStyleListBox* pointer to the listbox used in the setting page; Does not transfer ownership

   353  */

   354 	IMPORT_C CAknSetStyleListBox* ListBoxControl() const;

   355 

   356 /** 

   357  * Access to the editor control

   358  * 

   359  * @return	CAknPopupSettingList* a reference to the contained "editor" as a listbox; no ownership transferred

   360  */

   361 	IMPORT_C CAknPopupSettingList* PopupSettingListBox() const;

   362 

   363 /**

   364  *  From MAknPopupSettingListObserver

   365  * Handle events from the popup field control, such as when it changes between

   366  * selection list mode and label mode.

   367  *

   368  * @param aPopupSettingList pointer to the popup field control that generated the event

   369  * @param aEventType the type of event

   370  * @param aHint for possible future use

   371  *

   372  */

   373 	IMPORT_C virtual void HandlePopupSettingListEventL(CAknPopupSettingList* aPopupSettingList, 

   374 		TAknPopupSettingListEvent aEventType, TInt aHint);

   375 

   376 /**

   377 * Can be used dynamically to set a new query value.  This manages the setting up of the new

   378 * PopupSettingList and its listbox, and also the resizing and redrawing of the setting page

   379 * Note that all former query value objects and its associated arrays are owned by the client

   380 * and if no longer used, should be deleted.

   381 * 

   382 * @param MAknQueryValue* aQueryValue - the new value; no transfer of ownership

   383 */

   384 	IMPORT_C void UpdateQueryValueL( MAknQueryValue* aQueryValue );

   385 

   386 /**

   387  *	From CCoeControl

   388  */

   389     IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);

   390     

   391 protected:

   392 /**

   393 * C++ destructor

   394 */

   395 	IMPORT_C virtual ~CAknPopupSettingPage();

   396 

   397 /**

   398  * This is required to give access to the QueryValue data member from 

   399  * re-implementations of the popup setting page

   400  *

   401  * @return MAknQueryValue* a pointer to the query value object

   402  *

   403  */

   404 	IMPORT_C MAknQueryValue* QueryValue() const;

   405 

   406 /**

   407  * This method should be implemented in listbox classes to move the selection in 

   408  * listbox editors prior to exiting from the setting page

   409  *

   410  */

   411 	IMPORT_C virtual void SelectCurrentItemL();

   412 

   413 //

   414 // CoeControl Framework and reserved methods

   415 //

   416 protected:

   417 

   418 /**

   419  * Writes the internal state of the control and its components to aStream.

   420  * Does nothing in release mode.

   421  * Designed to be overidden and base called by subclasses.

   422  *

   423  * @param	aWriteSteam		A connected write stream

   424  */	

   425 	IMPORT_C virtual void WriteInternalStateL(RWriteStream& aWriteStream) const;

   426 

   427 /**

   428  *	Reserved method derived from CCoeControl

   429  */

   430 	IMPORT_C virtual void Reserved_2();

   431 

   432 private:

   433     /**

   434     * From CAknControl

   435     */

   436     IMPORT_C void* ExtensionInterface( TUid aInterface );

   437 

   438 /**

   439  * New reserved methods for CAknSettingPage hierarchy

   440  */ 

   441 private: 

   442 	IMPORT_C virtual void CAknSettingPage_Reserved_1();

   443 	IMPORT_C virtual void CAknSettingPage_Reserved_2();

   444 

   445 private:

   446 /**

   447  * New reserved method from CAknListBoxSettingPage 

   448  *

   449  */

   450 	IMPORT_C virtual void CAknListBoxSettingPage_Reserved_1();

   451  

   452 protected:	

   453     /**

   454      * From MEikCommandObserver

   455      * Processes events from the softkeys. (Or translated from key events)

   456      *

   457      * @param   aCommandId  Event Id from the soft-key

   458      * 

   459      * @since 5.2

   460      */

   461     IMPORT_C virtual void ProcessCommandL( TInt aCommandId );   

   462 	

   463 private:

   464 

   465 	// The objects pointed to or referenced by this is not owned

   466 	MAknQueryValue& iQueryValue;

   467 

   468 	TInt iSpare_1;

   469 	TInt iSpare_2;

   470 

   471 };

   472 

   473 #endif