epoc32/include/mw/aknpopupsettingpage.h
author William Roberts <williamr@symbian.org>
Wed, 31 Mar 2010 12:33:34 +0100 (2010-03-31)
branchSymbian3
changeset 4 837f303aceeb
parent 2 2fe1408b6811
permissions -rw-r--r--
Current Symbian^3 public API header files (from PDK 3.0.h)
This is the epoc32/include tree with the "platform" subtrees removed, and
all but a selected few mbg and rsg files removed.
     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 private:
   453 
   454 	// The objects pointed to or referenced by this is not owned
   455 	MAknQueryValue& iQueryValue;
   456 
   457 	TInt iSpare_1;
   458 	TInt iSpare_2;
   459 
   460 };
   461 
   462 #endif