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