williamr@2: /*
williamr@2: * Copyright (c) 2002 Nokia Corporation and/or its subsidiary(-ies).
williamr@2: * All rights reserved.
williamr@2: * This component and the accompanying materials are made available
williamr@4: * under the terms of "Eclipse Public License v1.0"
williamr@2: * which accompanies this distribution, and is available
williamr@4: * at the URL "http://www.eclipse.org/legal/epl-v10.html".
williamr@2: *
williamr@2: * Initial Contributors:
williamr@2: * Nokia Corporation - initial contribution.
williamr@2: *
williamr@2: * Contributors:
williamr@2: *
williamr@2: * Description: 
williamr@2: *
williamr@2: */
williamr@2: 
williamr@2: // AknQueryValue.h
williamr@2: //
williamr@2: // Copyright (c) 2001 Symbian Ltd.  All rights reserved.
williamr@2: //
williamr@2: 
williamr@2: #if !defined(__AKNQUERYVALUE_H__)
williamr@2: #define __AKNQUERYVALUE_H__
williamr@2: 
williamr@2: 
williamr@2: #include <eikenv.h>
williamr@2: #include <babitflags.h>
williamr@2: 
williamr@2: class MDesCArray;
williamr@2: 
williamr@2: /**
williamr@2:  * Mixin class representing a value that is accessed as text.
williamr@2:  * <p> The Value can be changed by creating an editor dialog, 
williamr@2:  * which may be either a query or a setting page
williamr@2:  * or optionally by choosing an entry from an array of values. 
williamr@2:  * The array can be accessed as a descriptor array, and the value 
williamr@2:  * can be accessed as a descriptor.
williamr@2:  */
williamr@2: class MAknQueryValue
williamr@2: 	{
williamr@2: public:
williamr@2: 	/**
williamr@2: 	 * Possible modes are query & setting page 
williamr@2: 	 * 
williamr@2: 	 */
williamr@2: 	enum TMode
williamr@2: 		{
williamr@2: 		EQueryMode,
williamr@2: 		ESettingPageMode
williamr@2: 		};
williamr@2: protected:
williamr@2: 	/**
williamr@2: 	 * If EAutoAppendBitIndex is set, 
williamr@2: 	 * the query value auto appends new values
williamr@2: 	 */
williamr@2: 	enum TFlagBits
williamr@2: 		{
williamr@2: 		ESettingPageModeBitIndex = 0,
williamr@2: 		EAutoAppendBitIndex
williamr@2: 		};
williamr@2: public:
williamr@2: 	virtual ~MAknQueryValue() {}
williamr@2: 	
williamr@2: 	/**
williamr@2: 	 * Returns the array as a descriptor array, 
williamr@2: 	 * ownership will be not passed 
williamr@2: 	 */	
williamr@2: 	virtual const MDesCArray* MdcArray() const = 0;
williamr@2: 	
williamr@2:     /**
williamr@2:      * This should be implemented so that it returns the current value as text
williamr@2:      * 
williamr@2:      * @return	descriptor representing current value, new 
williamr@2:      * descriptor is created and left on cleanup stack, ownership passed back to client
williamr@2:     */	
williamr@2: 	virtual HBufC* CurrentValueTextLC() = 0;
williamr@2: 	
williamr@2: 	/**
williamr@2:      * Returns the index in the array of the current value. 
williamr@2:      * If no matches, returns zero
williamr@2:      *
williamr@2:     */
williamr@2: 	virtual TInt CurrentValueIndex() const = 0;
williamr@2: 	
williamr@2: 	/**
williamr@2:      * Changes the current value to correspond to a value in the array.
williamr@2:      *
williamr@2:      * @param aIndex	index in array of value to set as current
williamr@2:     */
williamr@2: 	virtual void SetCurrentValueIndex(const TInt aIndex) = 0;
williamr@2: 	
williamr@2:     /**
williamr@2:      * Creates an editor within context. If the value is edited and OK'd,
williamr@2:      * the new value will be set as the current value. Otherwise the current value 
williamr@2:      * remains unchanged.
williamr@2:      *
williamr@2:      * @return	ETrue if current value was altered; EFalse otherwise
williamr@2:      */	
williamr@2: 	virtual TBool CreateEditorL() = 0;
williamr@2: 	
williamr@2: 	/**
williamr@2: 	 * Set QueryMode to be whether query or settingpage -mode
williamr@2: 	 *
williamr@2:      * @param aMode	value from <p>TMode	 
williamr@2: 	 */
williamr@2: 	virtual void SetQueryMode( MAknQueryValue::TMode aMode ) = 0;
williamr@2: 
williamr@2: 	/**
williamr@2: 	 * Override the default resource IDs used if a Setting Page mode query is put up.
williamr@2: 	 * All Queryvalue implementations should have default resource set up. Hence this
williamr@2: 	 * need not be called unless non-default resource is required.
williamr@2: 	 *
williamr@2: 	 * THE IMPLEMENTATION OF THESE RESOURCE OVERRIDES IS RESERVED FOR FUTURE VERSIONS
williamr@2: 	 * OF SERIES 60. NOT CURRENTLY FUNCTIONAL. DO NOT USE.
williamr@2: 	 *
williamr@2: 	 * The rules for usage of these ids is the same as that for the CAknSettingPage constructors
williamr@2: 	 * that take both these resources
williamr@2: 	 *		Editor Resource		Setting Page Resource
williamr@2: 	 *			present				present				Both are used (but text & number overridden)
williamr@2: 	 *			 = 0					present				Editor resource is used via SP resource 
williamr@2: 	 *			present					= 0					default SP resource for the query type is used + this editor resource
williamr@2: 	 *
williamr@2: 	 * The type of the editor resource is fixed. If editor resource override is being
williamr@2: 	 * used, then the resource must be for that control type of editor used in the
williamr@2: 	 * CAknQueryValueXXXX class.
williamr@2: 	 * 
williamr@2: 	 * @param aSettingPageResourceId		AVKON_SETTING_PAGE resource ID to use
williamr@2: 	 * @param aSettingPageEditorResourceId	Editor resource ID to use (takes precedence)
williamr@2: 	 *
williamr@2: 	 */
williamr@2: 	virtual void SetSettingPageResourceIds( 
williamr@2: 		TInt aSettingPageResourceId, 
williamr@2: 		TInt aSettingPageEditorResourceId ) = 0;
williamr@2: 	
williamr@2: 	/**
williamr@2: 	 * Set the QueryValue to append a new user value, if distinct from former value 
williamr@2: 	 *
williamr@2:      * @param aAppend	set/unset flag EAutoAppendBitIndex	 
williamr@2: 	 */
williamr@2: 	virtual void SetAutoAppend( TBool aAppend ) = 0;
williamr@2: 
williamr@2: protected:
williamr@2: 	/**
williamr@2: 	 * Method to add the current value to the QueryValueArray if it is new.
williamr@2: 	 * The new value is not owned by QueryValue object, but is "given away"
williamr@2: 	 *
williamr@2: 	 */
williamr@2: 	virtual void AppendValueIfNewL() = 0;
williamr@2: private:
williamr@2: 	IMPORT_C virtual void Reserved_MAknQueryValue();
williamr@2:    };
williamr@2: 
williamr@2: /** 
williamr@2:  * Pure virtual class that adds some standard functionality for queries
williamr@2:  *
williamr@2:  */
williamr@2: class CAknQueryValue : public CBase, public MAknQueryValue
williamr@2: 	{
williamr@2: public:
williamr@2: 	/**
williamr@2: 	 * Set QueryMode to be whether query or settingpage -mode
williamr@2: 	 *
williamr@2:      * @param aMode	value from <p>TMode	 
williamr@2: 	 */
williamr@2: 	IMPORT_C virtual void SetQueryMode( MAknQueryValue::TMode aMode );
williamr@2: 	
williamr@2: 	/**
williamr@2: 	 * Override the default resource IDs used if a Setting Page mode query is put up.
williamr@2: 	 * 
williamr@2: 	 * @param aSettingPageResourceId		AVKON_SETTING_PAGE resource ID to use
williamr@2: 	 * @param aSettingPageEditorResourceId	Editor resource ID to use (takes precedence)
williamr@2: 	 *
williamr@2: 	 */	
williamr@2: 	IMPORT_C virtual void SetSettingPageResourceIds( TInt aSettingPageResourceId, TInt aSettingPageEditorResourceId );
williamr@2: 	
williamr@2: 	/**
williamr@2: 	 * Set the QueryValue to append a new user value, if distinct from former value 
williamr@2: 	 *
williamr@2:      * @param aAppend	set/unset flag EAutoAppendBitIndex	 
williamr@2: 	 */	
williamr@2: 	IMPORT_C virtual void SetAutoAppend( TBool aAppend );
williamr@2: 	
williamr@2: 	/**
williamr@2: 	 * Method to add the current value to the QueryValueArray if it is new.
williamr@2: 	 * The new value is not owned by QueryValue object, but is "given away"
williamr@2: 	 *
williamr@2: 	 */	
williamr@2: 	IMPORT_C virtual void AppendValueIfNewL();
williamr@2: protected:
williamr@2: 	/**
williamr@2: 	 * Check if given index is valid within descriptor array
williamr@2: 	 *
williamr@2:      * @param aIndex   index to be checked	 	 
williamr@2: 	 */
williamr@2: 	TBool IsValidIndex(TInt aIndex) 
williamr@2: 	{
williamr@2: 	if (MdcArray()->MdcaCount() < 1) return ETrue;
williamr@2: 	if (aIndex < 0 || aIndex >= MdcArray()->MdcaCount())
williamr@2: 	    return EFalse;
williamr@2: 	return ETrue;
williamr@2: 	}
williamr@2: 
williamr@2: protected:
williamr@2:     /** 
williamr@2:      * Flags that determine behavior
williamr@2:      *
williamr@2:      */
williamr@2: 	TBitFlags16	iFlags;
williamr@2:     /** 
williamr@2:      * Resource id for setting page
williamr@2:      *
williamr@2:      */
williamr@2: 	TInt iSettingPageResourceId;
williamr@2:     /** 
williamr@2:      * Resource id for editor in setting page
williamr@2:      *
williamr@2:      */	
williamr@2: 	TInt iSettingPageEditorResourceId;
williamr@2: private:
williamr@2: 	TInt iSpare;
williamr@2: // from MAknQueryValue
williamr@2: 	IMPORT_C void Reserved_MAknQueryValue();
williamr@2: 	};
williamr@2: 
williamr@2: #endif // __AKNQUERYVALUE_H__
williamr@2: