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 */

    17 

    18 // AknQueryValue.h

    19 //

    20 // Copyright (c) 2001 Symbian Ltd.  All rights reserved.

    21 //

    22 

    23 #if !defined(__AKNQUERYVALUE_H__)

    24 #define __AKNQUERYVALUE_H__

    25 

    26 

    27 #include <eikenv.h>

    28 #include <babitflags.h>

    29 

    30 class MDesCArray;

    31 

    32 /**

    33  * Mixin class representing a value that is accessed as text.

    34  * <p> The Value can be changed by creating an editor dialog, 

    35  * which may be either a query or a setting page

    36  * or optionally by choosing an entry from an array of values. 

    37  * The array can be accessed as a descriptor array, and the value 

    38  * can be accessed as a descriptor.

    39  */

    40 class MAknQueryValue

    41 	{

    42 public:

    43 	/**

    44 	 * Possible modes are query & setting page 

    45 	 * 

    46 	 */

    47 	enum TMode

    48 		{

    49 		EQueryMode,

    50 		ESettingPageMode

    51 		};

    52 protected:

    53 	/**

    54 	 * If EAutoAppendBitIndex is set, 

    55 	 * the query value auto appends new values

    56 	 */

    57 	enum TFlagBits

    58 		{

    59 		ESettingPageModeBitIndex = 0,

    60 		EAutoAppendBitIndex

    61 		};

    62 public:

    63 	virtual ~MAknQueryValue() {}

    64 	

    65 	/**

    66 	 * Returns the array as a descriptor array, 

    67 	 * ownership will be not passed 

    68 	 */	

    69 	virtual const MDesCArray* MdcArray() const = 0;

    70 	

    71     /**

    72      * This should be implemented so that it returns the current value as text

    73      * 

    74      * @return	descriptor representing current value, new 

    75      * descriptor is created and left on cleanup stack, ownership passed back to client

    76     */	

    77 	virtual HBufC* CurrentValueTextLC() = 0;

    78 	

    79 	/**

    80      * Returns the index in the array of the current value. 

    81      * If no matches, returns zero

    82      *

    83     */

    84 	virtual TInt CurrentValueIndex() const = 0;

    85 	

    86 	/**

    87      * Changes the current value to correspond to a value in the array.

    88      *

    89      * @param aIndex	index in array of value to set as current

    90     */

    91 	virtual void SetCurrentValueIndex(const TInt aIndex) = 0;

    92 	

    93     /**

    94      * Creates an editor within context. If the value is edited and OK'd,

    95      * the new value will be set as the current value. Otherwise the current value 

    96      * remains unchanged.

    97      *

    98      * @return	ETrue if current value was altered; EFalse otherwise

    99      */	

   100 	virtual TBool CreateEditorL() = 0;

   101 	

   102 	/**

   103 	 * Set QueryMode to be whether query or settingpage -mode

   104 	 *

   105      * @param aMode	value from <p>TMode	 

   106 	 */

   107 	virtual void SetQueryMode( MAknQueryValue::TMode aMode ) = 0;

   108 

   109 	/**

   110 	 * Override the default resource IDs used if a Setting Page mode query is put up.

   111 	 * All Queryvalue implementations should have default resource set up. Hence this

   112 	 * need not be called unless non-default resource is required.

   113 	 *

   114 	 * THE IMPLEMENTATION OF THESE RESOURCE OVERRIDES IS RESERVED FOR FUTURE VERSIONS

   115 	 * OF SERIES 60. NOT CURRENTLY FUNCTIONAL. DO NOT USE.

   116 	 *

   117 	 * The rules for usage of these ids is the same as that for the CAknSettingPage constructors

   118 	 * that take both these resources

   119 	 *		Editor Resource		Setting Page Resource

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

   121 	 *			 = 0					present				Editor resource is used via SP resource 

   122 	 *			present					= 0					default SP resource for the query type is used + this editor resource

   123 	 *

   124 	 * The type of the editor resource is fixed. If editor resource override is being

   125 	 * used, then the resource must be for that control type of editor used in the

   126 	 * CAknQueryValueXXXX class.

   127 	 * 

   128 	 * @param aSettingPageResourceId		AVKON_SETTING_PAGE resource ID to use

   129 	 * @param aSettingPageEditorResourceId	Editor resource ID to use (takes precedence)

   130 	 *

   131 	 */

   132 	virtual void SetSettingPageResourceIds( 

   133 		TInt aSettingPageResourceId, 

   134 		TInt aSettingPageEditorResourceId ) = 0;

   135 	

   136 	/**

   137 	 * Set the QueryValue to append a new user value, if distinct from former value 

   138 	 *

   139      * @param aAppend	set/unset flag EAutoAppendBitIndex	 

   140 	 */

   141 	virtual void SetAutoAppend( TBool aAppend ) = 0;

   142 

   143 protected:

   144 	/**

   145 	 * Method to add the current value to the QueryValueArray if it is new.

   146 	 * The new value is not owned by QueryValue object, but is "given away"

   147 	 *

   148 	 */

   149 	virtual void AppendValueIfNewL() = 0;

   150 private:

   151 	IMPORT_C virtual void Reserved_MAknQueryValue();

   152    };

   153 

   154 /** 

   155  * Pure virtual class that adds some standard functionality for queries

   156  *

   157  */

   158 class CAknQueryValue : public CBase, public MAknQueryValue

   159 	{

   160 public:

   161 	/**

   162 	 * Set QueryMode to be whether query or settingpage -mode

   163 	 *

   164      * @param aMode	value from <p>TMode	 

   165 	 */

   166 	IMPORT_C virtual void SetQueryMode( MAknQueryValue::TMode aMode );

   167 	

   168 	/**

   169 	 * Override the default resource IDs used if a Setting Page mode query is put up.

   170 	 * 

   171 	 * @param aSettingPageResourceId		AVKON_SETTING_PAGE resource ID to use

   172 	 * @param aSettingPageEditorResourceId	Editor resource ID to use (takes precedence)

   173 	 *

   174 	 */	

   175 	IMPORT_C virtual void SetSettingPageResourceIds( TInt aSettingPageResourceId, TInt aSettingPageEditorResourceId );

   176 	

   177 	/**

   178 	 * Set the QueryValue to append a new user value, if distinct from former value 

   179 	 *

   180      * @param aAppend	set/unset flag EAutoAppendBitIndex	 

   181 	 */	

   182 	IMPORT_C virtual void SetAutoAppend( TBool aAppend );

   183 	

   184 	/**

   185 	 * Method to add the current value to the QueryValueArray if it is new.

   186 	 * The new value is not owned by QueryValue object, but is "given away"

   187 	 *

   188 	 */	

   189 	IMPORT_C virtual void AppendValueIfNewL();

   190 protected:

   191 	/**

   192 	 * Check if given index is valid within descriptor array

   193 	 *

   194      * @param aIndex   index to be checked	 	 

   195 	 */

   196 	TBool IsValidIndex(TInt aIndex) 

   197 	{

   198 	if (MdcArray()->MdcaCount() < 1) return ETrue;

   199 	if (aIndex < 0 || aIndex >= MdcArray()->MdcaCount())

   200 	    return EFalse;

   201 	return ETrue;

   202 	}

   203 

   204 protected:

   205     /** 

   206      * Flags that determine behavior

   207      *

   208      */

   209 	TBitFlags16	iFlags;

   210     /** 

   211      * Resource id for setting page

   212      *

   213      */

   214 	TInt iSettingPageResourceId;

   215     /** 

   216      * Resource id for editor in setting page

   217      *

   218      */	

   219 	TInt iSettingPageEditorResourceId;

   220 private:

   221 	TInt iSpare;

   222 // from MAknQueryValue

   223 	IMPORT_C void Reserved_MAknQueryValue();

   224 	};

   225 

   226 #endif // __AKNQUERYVALUE_H__

   227