1 aknpopupsettingpage.h

     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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.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 public: 

   153 /** 

   154  * from CCoeControl

   155  * Construct from resources.

   156  * @param aReader	constucted and positioned TResourceReader&

   157  */

   158 	IMPORT_C void ConstructFromResourceL(TResourceReader& aReader);

   159 

   160 protected:

   161 

   162 /**

   163  * Create the popup list. 

   164  *

   165  */

   166 	IMPORT_C void CreateMenuListL();

   167 

   168 /**

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

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

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

   172  *

   173  */

   174 	IMPORT_C void ActivateMenuListL();

   175 

   176 /**

   177  *

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

   179  *

   180  */

   181 	IMPORT_C void ConfigureMenuListL();

   182 

   183 /**

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

   185  *

   186  */

   187 	IMPORT_C void DestroyMenuList();

   188 

   189 public:

   190     /**

   191     * From CCoeControl. Handles pointer event

   192     * @param aPointerEvent Pointer event to be handled

   193     */

   194     IMPORT_C void HandlePointerEventL( const TPointerEvent& aPointerEvent );

   195     

   196     IMPORT_C void HandleResourceChange(TInt aType);

   197 

   198 private:

   199     /**

   200     * From CAknControl

   201     */

   202     IMPORT_C void* ExtensionInterface( TUid aInterface );

   203 

   204 protected: 

   205 /**

   206  * From MEikListBoxObserver

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

   208  * the pop-up.

   209  *

   210  * @param	aListBox	Listbox being observed

   211  * @param	aEventType	Event observed

   212  *

   213  *

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

   215  * not derived from. Currently observing itself..

   216  *

   217  */

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

   219 

   220 private: // from CCoeControl

   221 	IMPORT_C void Reserved_1();

   222 	IMPORT_C void Reserved_2();

   223 private: 

   224 	void CommonConstructL();

   225 	void SetUpSelectionListL();

   226 /** 

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

   228  *

   229  */

   230 	void InitialiseRadioButtonBitmapsL();

   231 private: 

   232 /**

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

   234  * Should be called whenever the flags are changed. 

   235  *

   236  */

   237 	void ConfigureDecorator();

   238 /**

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

   240  * Should be called whenever the flags are changed. 

   241  *

   242  */

   243 	void ConstructLayoutDecoratorL();

   244 

   245 private:

   246 	// the following members are owned

   247 

   248 	TAknDesCArrayDecorator iDecorator;

   249 	CAknListBoxLayoutDecorator* iLayoutDecorator;

   250 

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

   252 	TInt iFlags;

   253 	HBufC* iOtherText;

   254 	

   255 	TInt iCurrentSelection;

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

   257 	TInt iNewItemSettingPageResourceId;

   258 	TInt iNewItemEditorType;

   259 	TInt iNewItemEditorControlResourceId;

   260 

   261 	// the following members are not owned

   262 	MAknQueryValue* iValue;

   263 	MAknPopupSettingListObserver* iPopupSettingListObserver;

   264 

   265 	//TInt iSpare_1;

   266 	CAknPopupSettingListExtension* iExtension;

   267 	};

   268 

   269 

   270 /**

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

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

   273 *

   274 */

   275 class CAknPopupSettingPage : 

   276 	public CAknListBoxSettingPage, 

   277 	public MAknPopupSettingListObserver

   278 	{

   279 

   280 public:

   281 	/**

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

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

   284 	* resource.

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

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

   287 	*/

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

   289 

   290 	/**

   291 	 * Constructor that allows separate setting page and editor resources

   292 	 * 

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

   294 	 *

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

   296 	 *

   297 	 *		Editor Resource		Setting Page Resource

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

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

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

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

   302 	 *	 i) control type is present, 

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

   304 	 *

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

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

   307 	 *

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

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

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

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

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

   313 	 * 

   314 	 * @param aSettingTitleText	Text at top of setting pane

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

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

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

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

   319 	 * @param aQueryValue			reference to a query value object

   320 	 */

   321 	IMPORT_C CAknPopupSettingPage(	const TDesC* aSettingTitleText, 

   322 								TInt aSettingNumber, 

   323 								TInt aControlType,

   324 								TInt aEditorResourceId, 

   325 								TInt aSettingPageResourceId,

   326 								MAknQueryValue& aQueryValue);

   327 

   328 	/**

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

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

   331 	*

   332 	*/

   333 	IMPORT_C virtual void ConstructL();

   334 

   335 /**

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

   337  *

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

   339  */

   340 	IMPORT_C CAknSetStyleListBox* ListBoxControl() const;

   341 

   342 /** 

   343  * Access to the editor control

   344  * 

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

   346  */

   347 	IMPORT_C CAknPopupSettingList* PopupSettingListBox() const;

   348 

   349 /**

   350  *  From MAknPopupSettingListObserver

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

   352  * selection list mode and label mode.

   353  *

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

   355  * @param aEventType the type of event

   356  * @param aHint for possible future use

   357  *

   358  */

   359 	IMPORT_C virtual void HandlePopupSettingListEventL(CAknPopupSettingList* aPopupSettingList, 

   360 		TAknPopupSettingListEvent aEventType, TInt aHint);

   361 

   362 /**

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

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

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

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

   367 * 

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

   369 */

   370 	IMPORT_C void UpdateQueryValueL( MAknQueryValue* aQueryValue );

   371 

   372 /**

   373  *	From CCoeControl

   374  */

   375     IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);

   376     

   377 protected:

   378 /**

   379 * C++ destructor

   380 */

   381 	IMPORT_C virtual ~CAknPopupSettingPage();

   382 

   383 /**

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

   385  * re-implementations of the popup setting page

   386  *

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

   388  *

   389  */

   390 	IMPORT_C MAknQueryValue* QueryValue() const;

   391 

   392 /**

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

   394  * listbox editors prior to exiting from the setting page

   395  *

   396  */

   397 	IMPORT_C virtual void SelectCurrentItemL();

   398 

   399 //

   400 // CoeControl Framework and reserved methods

   401 //

   402 protected:

   403 

   404 /**

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

   406  * Does nothing in release mode.

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

   408  *

   409  * @param	aWriteSteam		A connected write stream

   410  */	

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

   412 

   413 /**

   414  *	Reserved method derived from CCoeControl

   415  */

   416 	IMPORT_C virtual void Reserved_2();

   417 

   418 private:

   419     /**

   420     * From CAknControl

   421     */

   422     IMPORT_C void* ExtensionInterface( TUid aInterface );

   423 

   424 /**

   425  * New reserved methods for CAknSettingPage hierarchy

   426  */ 

   427 private: 

   428 	IMPORT_C virtual void CAknSettingPage_Reserved_1();

   429 	IMPORT_C virtual void CAknSettingPage_Reserved_2();

   430 

   431 private:

   432 /**

   433  * New reserved method from CAknListBoxSettingPage 

   434  *

   435  */

   436 	IMPORT_C virtual void CAknListBoxSettingPage_Reserved_1();

   437 

   438 private:

   439 

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

   441 	MAknQueryValue& iQueryValue;

   442 

   443 	TInt iSpare_1;

   444 	TInt iSpare_2;

   445 

   446 };

   447 

   448 #endif