/*

* Copyright (c) 2002 Nokia Corporation and/or its subsidiary(-ies).

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of "Eclipse Public License v1.0"

* which accompanies this distribution, and is available

* at the URL "http://www.eclipse.org/legal/epl-v10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description: 

*

*/

// AknQueryValue.h

//

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

//

#if !defined(__AKNQUERYVALUE_H__)

#define __AKNQUERYVALUE_H__

#include <eikenv.h>

#include <babitflags.h>

class MDesCArray;

/**

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

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

 * which may be either a query or a setting page

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

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

 * can be accessed as a descriptor.

 */

class MAknQueryValue

	{

public:

	/**

	 * Possible modes are query & setting page 

	 * 

	 */

	enum TMode

		{

		EQueryMode,

		ESettingPageMode

		};

protected:

	/**

	 * If EAutoAppendBitIndex is set, 

	 * the query value auto appends new values

	 */

	enum TFlagBits

		{

		ESettingPageModeBitIndex = 0,

		EAutoAppendBitIndex

		};

public:

	virtual ~MAknQueryValue() {}

	/**

	 * Returns the array as a descriptor array, 

	 * ownership will be not passed 

	 */	

	virtual const MDesCArray* MdcArray() const = 0;

    /**

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

     * 

     * @return	descriptor representing current value, new 

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

    */	

	virtual HBufC* CurrentValueTextLC() = 0;

	/**

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

     * If no matches, returns zero

     *

    */

	virtual TInt CurrentValueIndex() const = 0;

	/**

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

     *

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

    */

	virtual void SetCurrentValueIndex(const TInt aIndex) = 0;

    /**

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

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

     * remains unchanged.

     *

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

     */	

	virtual TBool CreateEditorL() = 0;

	/**

	 * Set QueryMode to be whether query or settingpage -mode

	 *

     * @param aMode	value from <p>TMode	 

	 */

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

	/**

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

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

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

	 *

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

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

	 *

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

	 * that take both these resources

	 *		Editor Resource		Setting Page Resource

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

	 *			 = 0					present				Editor resource is used via SP resource 

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

	 *

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

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

	 * CAknQueryValueXXXX class.

	 * 

	 * @param aSettingPageResourceId		AVKON_SETTING_PAGE resource ID to use

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

	 *

	 */

	virtual void SetSettingPageResourceIds( 

		TInt aSettingPageResourceId, 

		TInt aSettingPageEditorResourceId ) = 0;

	/**

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

	 *

     * @param aAppend	set/unset flag EAutoAppendBitIndex	 

	 */

	virtual void SetAutoAppend( TBool aAppend ) = 0;

protected:

	/**

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

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

	 *

	 */

	virtual void AppendValueIfNewL() = 0;

private:

	IMPORT_C virtual void Reserved_MAknQueryValue();

   };

/** 

 * Pure virtual class that adds some standard functionality for queries

 *

 */

class CAknQueryValue : public CBase, public MAknQueryValue

	{

public:

	/**

	 * Set QueryMode to be whether query or settingpage -mode

	 *

     * @param aMode	value from <p>TMode	 

	 */

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

	/**

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

	 * 

	 * @param aSettingPageResourceId		AVKON_SETTING_PAGE resource ID to use

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

	 *

	 */	

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

	/**

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

	 *

     * @param aAppend	set/unset flag EAutoAppendBitIndex	 

	 */	

	IMPORT_C virtual void SetAutoAppend( TBool aAppend );

	/**

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

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

	 *

	 */	

	IMPORT_C virtual void AppendValueIfNewL();

protected:

	/**

	 * Check if given index is valid within descriptor array

	 *

     * @param aIndex   index to be checked	 	 

	 */

	TBool IsValidIndex(TInt aIndex) 

	{

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

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

	    return EFalse;

	return ETrue;

	}

protected:

    /** 

     * Flags that determine behavior

     *

     */

	TBitFlags16	iFlags;

    /** 

     * Resource id for setting page

     *

     */

	TInt iSettingPageResourceId;

    /** 

     * Resource id for editor in setting page

     *

     */	

	TInt iSettingPageEditorResourceId;

private:

	TInt iSpare;

// from MAknQueryValue

	IMPORT_C void Reserved_MAknQueryValue();

	};

#endif // __AKNQUERYVALUE_H__