1.1 --- a/epoc32/include/mw/aknpopupsettingpage.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/mw/aknpopupsettingpage.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,448 @@
1.4 -aknpopupsettingpage.h
1.5 +/*
1.6 +* Copyright (c) 2002 Nokia Corporation and/or its subsidiary(-ies).
1.7 +* All rights reserved.
1.8 +* This component and the accompanying materials are made available
1.9 +* 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
1.10 +* which accompanies this distribution, and is available
1.11 +* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.12 +*
1.13 +* Initial Contributors:
1.14 +* Nokia Corporation - initial contribution.
1.15 +*
1.16 +* Contributors:
1.17 +*
1.18 +* Description:
1.19 +*
1.20 +* Support for popup setting item lists. THe MAknQueryValue abstract type is
1.21 +* used to carry the state of the selection.
1.22 +*
1.23 +* This file also contains the definition for the contained editor of the setting page,
1.24 +* CAknPopupSettingList
1.25 +*
1.26 +*
1.27 +*/
1.28 +
1.29 +
1.30 +#ifndef __AKNPOPUPSETTINGPAGE_H__
1.31 +#define __AKNPOPUPSETTINGPAGE_H__
1.32 +
1.33 +
1.34 +#include <aknqueryvalue.h>
1.35 +#include <aknqueryvaluetext.h>
1.36 +#include <aknlistboxsettingpage.h>
1.37 +
1.38 +#include <AknDesCArrayDecorator.h>
1.39 +#include <AknListBoxLayoutDecorator.h>
1.40 +
1.41 +class CAknPopupSettingList;
1.42 +class CAknPopupSettingListExtension;
1.43 +
1.44 +/**
1.45 + * This interface should be implemented by classes that need to know
1.46 + * about events occurring in the popup field control
1.47 + */
1.48 +class MAknPopupSettingListObserver
1.49 + {
1.50 +public:
1.51 + /**
1.52 + * Event types
1.53 + */
1.54 + enum TAknPopupSettingListEvent
1.55 + {
1.56 + EAknPopupSettingSelectionAndRequestAccept,
1.57 + EAknPopupSettingSelectionAndStayOpen,
1.58 + EAknPopupSettingSelectionAndClose
1.59 + };
1.60 +public:
1.61 +/**
1.62 + * Handle events from the popup field control, such as when it changes between
1.63 + * selection list mode and label mode.
1.64 + *
1.65 + * Implementations of this observer routine should perform a base call to this specific
1.66 + * method, in order to pick up any default re-layout actions.
1.67 + *
1.68 + * @param aPopupSettingList pointer to the popup field control that generated the event
1.69 + * @param aEventType the type of event
1.70 + * @param aHint for possible future use
1.71 + *
1.72 + */
1.73 + virtual void HandlePopupSettingListEventL( CAknPopupSettingList* aPopupSettingList,
1.74 + TAknPopupSettingListEvent aEventType,
1.75 + TInt aHint)=0;
1.76 + };
1.77 +
1.78 +/**
1.79 + *
1.80 + * Represents menu list that appears in a popped up setting item
1.81 + */
1.82 +class CAknPopupSettingList :
1.83 + public CAknSetStyleListBox,
1.84 + public MEikListBoxObserver
1.85 + {
1.86 +
1.87 +protected:
1.88 +
1.89 +
1.90 +public:
1.91 + /**
1.92 + * Standard constructor.
1.93 + */
1.94 + IMPORT_C CAknPopupSettingList();
1.95 +
1.96 +/**
1.97 + * Destructor.
1.98 + *
1.99 + */
1.100 + IMPORT_C ~CAknPopupSettingList();
1.101 +
1.102 +/**
1.103 + * 2nd phase construction
1.104 + *
1.105 + */
1.106 + IMPORT_C void ConstructL();
1.107 +
1.108 +/**
1.109 + * Sets flag that enables user defined entry. Note that flag can also be set from resources,
1.110 + * but this method allows behaviour to be changed at runtime.
1.111 + *
1.112 + * @param aAllows if ETrue, set flag; if EFalse, clear flag.
1.113 + */
1.114 + IMPORT_C void SetAllowsUserDefinedEntry(TBool aAllows);
1.115 +
1.116 +
1.117 +/**
1.118 + * Used by the client to set the query value used to represent the user defined
1.119 + * value belonging to this popup field control.
1.120 + *
1.121 + * @param aValue pointer to value, ownership is not passed
1.122 + *
1.123 + */
1.124 + IMPORT_C void SetQueryValueL(MAknQueryValue* aValue);
1.125 +
1.126 +
1.127 +/**
1.128 + * Set the flag which determines whether the indicators are shown
1.129 + * In practice the indicators have the appearance of radio buttons
1.130 + *
1.131 + * @param aShowIndicators
1.132 + * If ETrue, indicators are displayed;
1.133 + * if EFalse, indicators are not displayed
1.134 + *
1.135 + */
1.136 + IMPORT_C void SetShowIndicators(TBool aShowIndicators);
1.137 +
1.138 +/**
1.139 + * number of lines used
1.140 + *
1.141 + * @return number of lines being currently displayed by control, which is determined
1.142 + * by the number of entries on the selection list, and whether the selection list is active.
1.143 + * NOTE that the number is limited by KAknMaxLinesOnOnePage
1.144 + *
1.145 + */
1.146 + IMPORT_C TInt NumLines() const;
1.147 +
1.148 +/**
1.149 + * set an observer of this class to receive events from popup setting list
1.150 + *
1.151 + * @param aObserver pointer to the class that implements the observer interface,
1.152 + *
1.153 + */
1.154 + IMPORT_C void SetPopupSettingListObserver(MAknPopupSettingListObserver* aObserver);
1.155 +
1.156 +public:
1.157 +/**
1.158 + * from CCoeControl
1.159 + * Construct from resources.
1.160 + * @param aReader constucted and positioned TResourceReader&
1.161 + */
1.162 + IMPORT_C void ConstructFromResourceL(TResourceReader& aReader);
1.163 +
1.164 +protected:
1.165 +
1.166 +/**
1.167 + * Create the popup list.
1.168 + *
1.169 + */
1.170 + IMPORT_C void CreateMenuListL();
1.171 +
1.172 +/**
1.173 + * Causes the list of pre-defined values to appear.
1.174 + * Use this method to activate the pop-up field from a menu option command.
1.175 + * Note that the desired control must have the focus before it can be activated.
1.176 + *
1.177 + */
1.178 + IMPORT_C void ActivateMenuListL();
1.179 +
1.180 +/**
1.181 + *
1.182 + * This routine sets up the text arrays for the menu list
1.183 + *
1.184 + */
1.185 + IMPORT_C void ConfigureMenuListL();
1.186 +
1.187 +/**
1.188 + * All this does now is remove this from the stack
1.189 + *
1.190 + */
1.191 + IMPORT_C void DestroyMenuList();
1.192 +
1.193 +public:
1.194 + /**
1.195 + * From CCoeControl. Handles pointer event
1.196 + * @param aPointerEvent Pointer event to be handled
1.197 + */
1.198 + IMPORT_C void HandlePointerEventL( const TPointerEvent& aPointerEvent );
1.199 +
1.200 + IMPORT_C void HandleResourceChange(TInt aType);
1.201 +
1.202 +private:
1.203 + /**
1.204 + * From CAknControl
1.205 + */
1.206 + IMPORT_C void* ExtensionInterface( TUid aInterface );
1.207 +
1.208 +protected:
1.209 +/**
1.210 + * From MEikListBoxObserver
1.211 + * Processes key events from the listbox. Responds to EEventEnterKeyPressed to accept
1.212 + * the pop-up.
1.213 + *
1.214 + * @param aListBox Listbox being observed
1.215 + * @param aEventType Event observed
1.216 + *
1.217 + *
1.218 + * This implementation is vestige of former implementation when the listbox was wrapped up,
1.219 + * not derived from. Currently observing itself..
1.220 + *
1.221 + */
1.222 + IMPORT_C void HandleListBoxEventL(CEikListBox* aListBox, TListBoxEvent aEventType);
1.223 +
1.224 +private: // from CCoeControl
1.225 + IMPORT_C void Reserved_1();
1.226 + IMPORT_C void Reserved_2();
1.227 +private:
1.228 + void CommonConstructL();
1.229 + void SetUpSelectionListL();
1.230 +/**
1.231 + * Set up the bitmap array for the "not pushed" and "pushed in" states
1.232 + *
1.233 + */
1.234 + void InitialiseRadioButtonBitmapsL();
1.235 +private:
1.236 +/**
1.237 + * Configures the decoration according to the currently set flags.
1.238 + * Should be called whenever the flags are changed.
1.239 + *
1.240 + */
1.241 + void ConfigureDecorator();
1.242 +/**
1.243 + * Configures the layout decoration according to the "has buttons" flag
1.244 + * Should be called whenever the flags are changed.
1.245 + *
1.246 + */
1.247 + void ConstructLayoutDecoratorL();
1.248 +
1.249 +private:
1.250 + // the following members are owned
1.251 +
1.252 + TAknDesCArrayDecorator iDecorator;
1.253 + CAknListBoxLayoutDecorator* iLayoutDecorator;
1.254 +
1.255 + // the following fields are reflected in the POPUP_SETTING_LIST resource structure
1.256 + TInt iFlags;
1.257 + HBufC* iOtherText;
1.258 +
1.259 + TInt iCurrentSelection;
1.260 + // elements to hold info regarding "new Item"- produced setting page
1.261 + TInt iNewItemSettingPageResourceId;
1.262 + TInt iNewItemEditorType;
1.263 + TInt iNewItemEditorControlResourceId;
1.264 +
1.265 + // the following members are not owned
1.266 + MAknQueryValue* iValue;
1.267 + MAknPopupSettingListObserver* iPopupSettingListObserver;
1.268 +
1.269 + //TInt iSpare_1;
1.270 + CAknPopupSettingListExtension* iExtension;
1.271 + };
1.272 +
1.273 +
1.274 +/**
1.275 +* Interface for the setting page containing a menu list with a Query value data model
1.276 +* This is the more generic of the list-style setting pages.
1.277 +*
1.278 +*/
1.279 +class CAknPopupSettingPage :
1.280 + public CAknListBoxSettingPage,
1.281 + public MAknPopupSettingListObserver
1.282 + {
1.283 +
1.284 +public:
1.285 + /**
1.286 + * C++ constructor. This constructor uses just the setting page resource Id to
1.287 + * construct the setting page, using listbox resource contained in the setting page
1.288 + * resource.
1.289 + * @param aResourceId a resource identifier for a AVKON_SETTING_PAGE resource
1.290 + * @param aQueryValue a reference to a query value object
1.291 + */
1.292 + IMPORT_C CAknPopupSettingPage(TInt aResourceID, MAknQueryValue& aQueryValue );
1.293 +
1.294 + /**
1.295 + * Constructor that allows separate setting page and editor resources
1.296 + *
1.297 + * This constructor allows the use of setting page using only the editor resource. Other combinations are also possible
1.298 + *
1.299 + * In all cases the number (if supplied i.e. <> 0 ) is used.
1.300 + *
1.301 + * Editor Resource Setting Page Resource
1.302 + * present present Both are used (but text & number overridden)
1.303 + * = 0 present Editor resource is used via SP resource (Effectively like the other constructor)
1.304 + * present = 0 Default Avkon SP resource if used + this editor resource
1.305 + * = 0 = 0 uses default resource for both SP and editor. This is OK if:
1.306 + * i) control type is present,
1.307 + * ii) a default resource exists ( OK for text, integer, date, time, duration )
1.308 + *
1.309 + * Note: THe first argument is a TDesC* (rather than TDesC&) because the other constructor
1.310 + * cannot initialize such a member without allocation or having an internal dummy buffer.
1.311 + *
1.312 + * Rules for text and numbers: The rules are the same for both: (non-zero length) text or number other
1.313 + * than EAknSettingPageNoOrdinalDisplayed if given in this constructor will not override resource
1.314 + * (unless that is zero length or EAknSettingPageNoOrdinalDisplayed). Note, however, that text or number given via the
1.315 + * specific API for setting them, WILL override resource.
1.316 + * It is assumed that number from resource is very rare. Special text is somewhat more likely.
1.317 + *
1.318 + * @param aSettingTitleText Text at top of setting pane
1.319 + * @param aSettingNumber Number at top left (if present)
1.320 + * @param aControlType Determines the type constructed and how its resource is read
1.321 + * @param aEditorResourceId Editor resource to use in the setting page (if present)
1.322 + * @param aSettingPageResourceId Setting Page to use (if present)
1.323 + * @param aQueryValue reference to a query value object
1.324 + */
1.325 + IMPORT_C CAknPopupSettingPage( const TDesC* aSettingTitleText,
1.326 + TInt aSettingNumber,
1.327 + TInt aControlType,
1.328 + TInt aEditorResourceId,
1.329 + TInt aSettingPageResourceId,
1.330 + MAknQueryValue& aQueryValue);
1.331 +
1.332 + /**
1.333 + * 2nd stage construction method. Type specific work is done here; most of the setting
1.334 + * page constuction is performed in a call the base contstruction of CAknSettingPage
1.335 + *
1.336 + */
1.337 + IMPORT_C virtual void ConstructL();
1.338 +
1.339 +/**
1.340 + * Access to the contained listbox (inside popup setting list)
1.341 + *
1.342 + * @return CAknSetStyleListBox* pointer to the listbox used in the setting page; Does not transfer ownership
1.343 + */
1.344 + IMPORT_C CAknSetStyleListBox* ListBoxControl() const;
1.345 +
1.346 +/**
1.347 + * Access to the editor control
1.348 + *
1.349 + * @return CAknPopupSettingList* a reference to the contained "editor" as a listbox; no ownership transferred
1.350 + */
1.351 + IMPORT_C CAknPopupSettingList* PopupSettingListBox() const;
1.352 +
1.353 +/**
1.354 + * From MAknPopupSettingListObserver
1.355 + * Handle events from the popup field control, such as when it changes between
1.356 + * selection list mode and label mode.
1.357 + *
1.358 + * @param aPopupSettingList pointer to the popup field control that generated the event
1.359 + * @param aEventType the type of event
1.360 + * @param aHint for possible future use
1.361 + *
1.362 + */
1.363 + IMPORT_C virtual void HandlePopupSettingListEventL(CAknPopupSettingList* aPopupSettingList,
1.364 + TAknPopupSettingListEvent aEventType, TInt aHint);
1.365 +
1.366 +/**
1.367 +* Can be used dynamically to set a new query value. This manages the setting up of the new
1.368 +* PopupSettingList and its listbox, and also the resizing and redrawing of the setting page
1.369 +* Note that all former query value objects and its associated arrays are owned by the client
1.370 +* and if no longer used, should be deleted.
1.371 +*
1.372 +* @param MAknQueryValue* aQueryValue - the new value; no transfer of ownership
1.373 +*/
1.374 + IMPORT_C void UpdateQueryValueL( MAknQueryValue* aQueryValue );
1.375 +
1.376 +/**
1.377 + * From CCoeControl
1.378 + */
1.379 + IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);
1.380 +
1.381 +protected:
1.382 +/**
1.383 +* C++ destructor
1.384 +*/
1.385 + IMPORT_C virtual ~CAknPopupSettingPage();
1.386 +
1.387 +/**
1.388 + * This is required to give access to the QueryValue data member from
1.389 + * re-implementations of the popup setting page
1.390 + *
1.391 + * @return MAknQueryValue* a pointer to the query value object
1.392 + *
1.393 + */
1.394 + IMPORT_C MAknQueryValue* QueryValue() const;
1.395 +
1.396 +/**
1.397 + * This method should be implemented in listbox classes to move the selection in
1.398 + * listbox editors prior to exiting from the setting page
1.399 + *
1.400 + */
1.401 + IMPORT_C virtual void SelectCurrentItemL();
1.402 +
1.403 +//
1.404 +// CoeControl Framework and reserved methods
1.405 +//
1.406 +protected:
1.407 +
1.408 +/**
1.409 + * Writes the internal state of the control and its components to aStream.
1.410 + * Does nothing in release mode.
1.411 + * Designed to be overidden and base called by subclasses.
1.412 + *
1.413 + * @param aWriteSteam A connected write stream
1.414 + */
1.415 + IMPORT_C virtual void WriteInternalStateL(RWriteStream& aWriteStream) const;
1.416 +
1.417 +/**
1.418 + * Reserved method derived from CCoeControl
1.419 + */
1.420 + IMPORT_C virtual void Reserved_2();
1.421 +
1.422 +private:
1.423 + /**
1.424 + * From CAknControl
1.425 + */
1.426 + IMPORT_C void* ExtensionInterface( TUid aInterface );
1.427 +
1.428 +/**
1.429 + * New reserved methods for CAknSettingPage hierarchy
1.430 + */
1.431 +private:
1.432 + IMPORT_C virtual void CAknSettingPage_Reserved_1();
1.433 + IMPORT_C virtual void CAknSettingPage_Reserved_2();
1.434 +
1.435 +private:
1.436 +/**
1.437 + * New reserved method from CAknListBoxSettingPage
1.438 + *
1.439 + */
1.440 + IMPORT_C virtual void CAknListBoxSettingPage_Reserved_1();
1.441 +
1.442 +private:
1.443 +
1.444 + // The objects pointed to or referenced by this is not owned
1.445 + MAknQueryValue& iQueryValue;
1.446 +
1.447 + TInt iSpare_1;
1.448 + TInt iSpare_2;
1.449 +
1.450 +};
1.451 +
1.452 +#endif