2 * Copyright (c) 2002 Nokia Corporation and/or its subsidiary(-ies).
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".
9 * Initial Contributors:
10 * Nokia Corporation - initial contribution.
16 * Support for popup setting item lists. THe MAknQueryValue abstract type is
17 * used to carry the state of the selection.
19 * This file also contains the definition for the contained editor of the setting page,
20 * CAknPopupSettingList
26 #ifndef __AKNPOPUPSETTINGPAGE_H__
27 #define __AKNPOPUPSETTINGPAGE_H__
30 #include <AknQueryValue.h>
31 #include <AknQueryValueText.h>
32 #include <AknListBoxSettingPage.h>
34 #include <AknDesCArrayDecorator.h>
35 #include <AknListBoxLayoutDecorator.h>
37 class CAknPopupSettingList;
38 class CAknPopupSettingListExtension;
41 * This interface should be implemented by classes that need to know
42 * about events occurring in the popup field control
44 class MAknPopupSettingListObserver
50 enum TAknPopupSettingListEvent
52 EAknPopupSettingSelectionAndRequestAccept,
53 EAknPopupSettingSelectionAndStayOpen,
54 EAknPopupSettingSelectionAndClose
58 * Handle events from the popup field control, such as when it changes between
59 * selection list mode and label mode.
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.
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
69 virtual void HandlePopupSettingListEventL( CAknPopupSettingList* aPopupSettingList,
70 TAknPopupSettingListEvent aEventType,
76 * Represents menu list that appears in a popped up setting item
78 class CAknPopupSettingList :
79 public CAknSetStyleListBox,
80 public MEikListBoxObserver
88 * Standard constructor.
90 IMPORT_C CAknPopupSettingList();
96 IMPORT_C ~CAknPopupSettingList();
99 * 2nd phase construction
102 IMPORT_C void ConstructL();
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.
108 * @param aAllows if ETrue, set flag; if EFalse, clear flag.
110 IMPORT_C void SetAllowsUserDefinedEntry(TBool aAllows);
114 * Used by the client to set the query value used to represent the user defined
115 * value belonging to this popup field control.
117 * @param aValue pointer to value, ownership is not passed
120 IMPORT_C void SetQueryValueL(MAknQueryValue* aValue);
124 * Set the flag which determines whether the indicators are shown
125 * In practice the indicators have the appearance of radio buttons
127 * @param aShowIndicators
128 * If ETrue, indicators are displayed;
129 * if EFalse, indicators are not displayed
132 IMPORT_C void SetShowIndicators(TBool aShowIndicators);
135 * number of lines used
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
142 IMPORT_C TInt NumLines() const;
145 * set an observer of this class to receive events from popup setting list
147 * @param aObserver pointer to the class that implements the observer interface,
150 IMPORT_C void SetPopupSettingListObserver(MAknPopupSettingListObserver* aObserver);
153 * Selects current item.
157 void SelectCurrentItemL();
160 * Returns index of currently selected list item.
162 * @return Currently selected item's index.
164 TInt CurrentSelection() const;
169 * Construct from resources.
170 * @param aReader constucted and positioned TResourceReader&
172 IMPORT_C void ConstructFromResourceL(TResourceReader& aReader);
177 * Create the popup list.
180 IMPORT_C void CreateMenuListL();
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.
188 IMPORT_C void ActivateMenuListL();
192 * This routine sets up the text arrays for the menu list
195 IMPORT_C void ConfigureMenuListL();
198 * All this does now is remove this from the stack
201 IMPORT_C void DestroyMenuList();
205 * From CCoeControl. Handles pointer event
206 * @param aPointerEvent Pointer event to be handled
208 IMPORT_C void HandlePointerEventL( const TPointerEvent& aPointerEvent );
210 IMPORT_C void HandleResourceChange(TInt aType);
216 IMPORT_C void* ExtensionInterface( TUid aInterface );
220 * From MEikListBoxObserver
221 * Processes key events from the listbox. Responds to EEventEnterKeyPressed to accept
224 * @param aListBox Listbox being observed
225 * @param aEventType Event observed
228 * This implementation is vestige of former implementation when the listbox was wrapped up,
229 * not derived from. Currently observing itself..
232 IMPORT_C void HandleListBoxEventL(CEikListBox* aListBox, TListBoxEvent aEventType);
234 private: // from CCoeControl
235 IMPORT_C void Reserved_1();
236 IMPORT_C void Reserved_2();
238 void CommonConstructL();
239 void SetUpSelectionListL();
241 * Set up the bitmap array for the "not pushed" and "pushed in" states
244 void InitialiseRadioButtonBitmapsL();
247 * Configures the decoration according to the currently set flags.
248 * Should be called whenever the flags are changed.
251 void ConfigureDecorator();
253 * Configures the layout decoration according to the "has buttons" flag
254 * Should be called whenever the flags are changed.
257 void ConstructLayoutDecoratorL();
260 // the following members are owned
262 TAknDesCArrayDecorator iDecorator;
263 CAknListBoxLayoutDecorator* iLayoutDecorator;
265 // the following fields are reflected in the POPUP_SETTING_LIST resource structure
269 TInt iCurrentSelection;
270 // elements to hold info regarding "new Item"- produced setting page
271 TInt iNewItemSettingPageResourceId;
272 TInt iNewItemEditorType;
273 TInt iNewItemEditorControlResourceId;
275 // the following members are not owned
276 MAknQueryValue* iValue;
277 MAknPopupSettingListObserver* iPopupSettingListObserver;
280 CAknPopupSettingListExtension* iExtension;
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.
289 class CAknPopupSettingPage :
290 public CAknListBoxSettingPage,
291 public MAknPopupSettingListObserver
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
299 * @param aResourceId a resource identifier for a AVKON_SETTING_PAGE resource
300 * @param aQueryValue a reference to a query value object
302 IMPORT_C CAknPopupSettingPage(TInt aResourceID, MAknQueryValue& aQueryValue );
305 * Constructor that allows separate setting page and editor resources
307 * This constructor allows the use of setting page using only the editor resource. Other combinations are also possible
309 * In all cases the number (if supplied i.e. <> 0 ) is used.
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 )
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.
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.
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
335 IMPORT_C CAknPopupSettingPage( const TDesC* aSettingTitleText,
338 TInt aEditorResourceId,
339 TInt aSettingPageResourceId,
340 MAknQueryValue& aQueryValue);
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
347 IMPORT_C virtual void ConstructL();
350 * Access to the contained listbox (inside popup setting list)
352 * @return CAknSetStyleListBox* pointer to the listbox used in the setting page; Does not transfer ownership
354 IMPORT_C CAknSetStyleListBox* ListBoxControl() const;
357 * Access to the editor control
359 * @return CAknPopupSettingList* a reference to the contained "editor" as a listbox; no ownership transferred
361 IMPORT_C CAknPopupSettingList* PopupSettingListBox() const;
364 * From MAknPopupSettingListObserver
365 * Handle events from the popup field control, such as when it changes between
366 * selection list mode and label mode.
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
373 IMPORT_C virtual void HandlePopupSettingListEventL(CAknPopupSettingList* aPopupSettingList,
374 TAknPopupSettingListEvent aEventType, TInt aHint);
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.
382 * @param MAknQueryValue* aQueryValue - the new value; no transfer of ownership
384 IMPORT_C void UpdateQueryValueL( MAknQueryValue* aQueryValue );
389 IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);
395 IMPORT_C virtual ~CAknPopupSettingPage();
398 * This is required to give access to the QueryValue data member from
399 * re-implementations of the popup setting page
401 * @return MAknQueryValue* a pointer to the query value object
404 IMPORT_C MAknQueryValue* QueryValue() const;
407 * This method should be implemented in listbox classes to move the selection in
408 * listbox editors prior to exiting from the setting page
411 IMPORT_C virtual void SelectCurrentItemL();
414 // CoeControl Framework and reserved methods
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.
423 * @param aWriteSteam A connected write stream
425 IMPORT_C virtual void WriteInternalStateL(RWriteStream& aWriteStream) const;
428 * Reserved method derived from CCoeControl
430 IMPORT_C virtual void Reserved_2();
436 IMPORT_C void* ExtensionInterface( TUid aInterface );
439 * New reserved methods for CAknSettingPage hierarchy
442 IMPORT_C virtual void CAknSettingPage_Reserved_1();
443 IMPORT_C virtual void CAknSettingPage_Reserved_2();
447 * New reserved method from CAknListBoxSettingPage
450 IMPORT_C virtual void CAknListBoxSettingPage_Reserved_1();
454 // The objects pointed to or referenced by this is not owned
455 MAknQueryValue& iQueryValue;