/*

* 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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

* which accompanies this distribution, and is available

* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description: 

*     Support for Setting Item Lists (See Selection Service specification)

*		Contains setting item classes (whole hierarchy) and the 

*		array classes used to set up the setting item listbox

*

*/

#if !defined(__AKNSETTINGITEMLIST_H__)

#define __AKNSETTINGITEMLIST_H__

#include <in_sock.h>

#include <AknControl.h>

// For graphics API

#include <gulicon.h>

// For CEikFormattedListBox

#include <eikfrlb.h>

// For setting page

#include <aknsettingpage.h>

// For query stuff

#include <aknqueryvaluetext.h>

// Maximum length of the blanking text

const TInt KMaxPasswordBlankingTextLength = 10;

class CAknSettingItemExtension;

/**

* CAknSettingItem is the base class for all setting items. The abstracted functionality

* is implemented in this class if possible.  

*

* All array of setting items is held in CAknSettingItemArray, which in turn is owned by

* CAknSettingItemList, a listbox type.

* 

*/

class CAknSettingItem : public CBase, public MAknSettingPageObserver

	{

friend class CAknSettingItemArray;

public:

	enum TFlags

		{

		EIsHidden = 0x1,

		EHasIcon = 0x2,

		EIsNumberedStyle = 0x4,

        ENoProtection = 0x8,

        EViewOnly = 0x10,

        EProtected = 0x20

        };

        // Setting item protection states

   enum TSettingItemProtection

        {

        ENoSettingItemProtection,

        ESettingItemViewOnly,

        ESettingItemProtected

        };

public:

	/**

	* Constructor

	*

	* @param the unique identifier fo the setting item (not its number)

	*/

	IMPORT_C CAknSettingItem( TInt identifier );

	/**

	* Destructor

	*/

	IMPORT_C ~CAknSettingItem();

	/**

	* 

	* 2nd-stage constuctor.  Resource for setting item is read externally in setting item list

	* and the values are passed here.

	*/

	IMPORT_C void ConstructL( 

		const TBool aIsNumberedStyle,

		const TInt aOrdinal, 

		const TDesC& aSettingTitle, 

		CArrayPtr<CGulIcon>* aIconArray,

		const TInt aSettingPageResource, 

		const TInt aEditorControlType,

		const TInt aSettingEditorResource = 0, 

		const TInt aAssociatedResource = 0 );

	/**

	* This command externalizes the current setting.  The displayed (internal) copy

	* is transferred to the external copy (the one referenced in the constructor).

	*

	* This must be called by the client if he wants this to happen.  Note that StoreAllL() 

	* on the setting item list will call this for each setting item.

	*/

	IMPORT_C virtual void StoreL();

	/*

	* The external value is transferred to the internal value

	* This occurs at construction, but may be called by client code when required.

	*/

	IMPORT_C virtual void LoadL(); 

	/**

	*

	* This launches the setting page 

	*

	* @param		aCalledFromMenu - ignored in this class

	*

	*/

	IMPORT_C virtual void EditItemL( TBool aCalledFromMenu );

	/**

	*

	* This method is called by framework in order to update the text in the setting

	* item. It may be called by the client.

	*

	*/

	IMPORT_C virtual void UpdateListBoxTextL();

	/**

	* Access to the setting Name 

	*.@return	the setting name

	*/

	IMPORT_C TPtrC SettingName();

	/**

	* Access to the setting number

	* @return the setting number

	*/

	IMPORT_C TInt SettingNumber() const;

	/**

	* Access to the setting visibility

	* @return ETrue if the setting item is hidden

	*/

	IMPORT_C TBool IsHidden() const;

	/**

	* Access to the numbering style of the setting item

	* @return	ETrue if it is numbered

	*/

	IMPORT_C TBool IsNumberedStyle() const;

	/**

	* Set the visibility 

	* @param		Set to ETrue to hide the item; EFalse to make it visible

	*

	*				Note that the setting item array must have be notified of this

	*				by calling CAknSettingItemList::HandleChangeInItemArrayOrVisibility

	*/

	IMPORT_C void SetHidden(TBool aHidden );

	/*

	* This method obtains the current value's setting text

	*

	* @return	Reference to descriptor with the text 

	*/

	IMPORT_C virtual const TDesC& SettingTextL();

	/**

	* This gives access to the listbox text content at this item (fully decorated)

	*

	* @return	pointer to listboxtext. No allocation is performed and no change of ownership

	*/

	IMPORT_C HBufC* ListBoxText();

	/**

	* Access to the setting item's identifier. This is set in the setting item's constructor

	* but usually comes via resource in the setting item list read of its resource structure

	*

	* @return The identifier of this setting item

	*/

	IMPORT_C TInt Identifier() const;

	/**

	* Checks if the setting item has a bitmap in its setting contents 

	* @return	ETrue if it has a bitmap

	*/

	IMPORT_C TBool HasIcon() const;

	/**

	* This sets the text to display if the current setting is empty. 

	*

	* @param		text to make display when there is empty setting. A copy is made in the setting item

	*/

	IMPORT_C void SetEmptyItemTextL( const TDesC& aEmptyItemText );

	IMPORT_C void SetCompulsoryIndTextL( const TDesC& aCompulsoryInd );

	// From MAknSettingPageObserver

	IMPORT_C virtual void HandleSettingPageEventL(CAknSettingPage* aSettingPage,TAknSettingPageEvent aEventType );

	/**

	* Get the index at which this item appears in the listbox

	*

	* @return index in listbox

	*/

	IMPORT_C TInt VisibleIndex();

	/**

	* Set the flags that are required for some of the setting page constructors

	*

	* @param aFlagPattern	Flag pattern to set

	*/

	IMPORT_C void SetSettingPageFlags( TInt aFlagPattern);

	/**

	* Access method for the setting page specific flags

	* @return the flag pattern

	*/

	IMPORT_C TInt SettingPageFlags( ) const;

    /**

    * Set the parent lisbox into the setting item

    *

    * @since 2.0

    * @param aListBox   listbox with which the setting item is associated.

    */

    void SetParentListBox( const CEikFormattedCellListBox* aListBox );

    /**

    * Set the protection state of the setting item

    *

    * The protection state is for protecting selected settings from editing. 

    * The protection can be set to:

    *   - prohibit opening of the setting page

    *   - allow access to the setting page, but prohibit editing of it

    *

    * The protected item is indicated in the setting item list with a lock icon. 

    * If a user tries to open a protected setting item, a notification is shown 

    * to the user.

    *

    * The "view only" -mode is only possible for pop-up setting page.

    *

    * @since 3.1

    * @param aProtected Sets the protection state of the setting item

    */

    IMPORT_C void SetProtectionState( CAknSettingItem::TSettingItemProtection aProtected );

    /**

    * Get the protection state

    *

    * See SetProtected for details for the different states.

    *

    * @since 3.1

    * @return Protection state of the setting item

    */

    IMPORT_C CAknSettingItem::TSettingItemProtection ProtectionState();

protected:

	/**

	* Method called by framework to complete the construction.  Extra allocations of

	* memory or extra resource reading can happen here.

	*

	*/

	IMPORT_C virtual void CompleteConstructionL();

	/**

	*

	* Method to obtain a new bitmap for the setting content

	*

	* This method is usually empty in setting items classes except for volume and slider.

    * Any derived implementations of this method should call SetIconMask().

	*

	*/

	IMPORT_C virtual CFbsBitmap* CreateBitmapL();

// Utilities

	/**

	*

	* A setting page should know when it is "Editing". This is set in EditItemL

	* and cleared to 0 when the dialog is finished.

	*

	* @param		pointer to the currently executing settting page dialog

	*

	*/

	IMPORT_C void SetSettingPage( CAknSettingPage* aSettingPage );

	/*

	* Access to the current setting page

	*

	* @return	pointer to the currently executing setting page. 0 if there is none

	*/

	IMPORT_C CAknSettingPage* SettingPage() const;

	/**

	* Performs standard setup on a setting page

	*

	*/

	IMPORT_C void SetUpStandardSettingPageL();

	/**

	* Access to the empty text that has been set, or is default

	*

	* @return	ref to empty text descriptor

	*/

	IMPORT_C TDesC& EmptyItemText() const; // Assumed only needs to be used by SettingTextL

	/**

	* Access to the setting page resource id that might have been read by

	* the setting item resource.

	* 

	* @return	0 or the setting page resource id

	*/

	IMPORT_C TInt SettingPageResourceId() const;

	/**

	* Access to the setting page editor's resource id that might have been read by

	* the setting item resource.

	* 

	* @return	0 or the setting page editor's id

	*/

	IMPORT_C TInt SettingEditorResourceId() const;

	/**

	* Returns the associate editor resource.  This is an LLINK in the seting item 

	* resource that subclasses can use in CompleteContstructionL

	*

	* @return	0 or the extra resource id

	*/

	IMPORT_C TInt AssociatedResourceId() const;

	/**

	* 

	* @return the control type of the settin page editor

	*

	*/

	TInt EditorControlType() const;

    /**

    * This sets the mask of this setting item's icon array, if it exists.

    * The normal usage of this routine is inside a re-implementation of CAknSettingItem::CreateBitmapL.

    * It is used to set the mask of the setting item's setting icon as a side effect of a 

    * framework call to CreateBitmapL

    *

    * The return value may need to be looked at to decide how to dispose of, for example, an

    * a CGulIcon that may be holding the mask.

    * 

    * @since 2.0

    * @param aMask  bitmap to set as a mask for the CGulIcon in the setting listbox's icon array

    * @return TBool ETrue if the ownership of aMask has been passed

    */

    IMPORT_C TBool SetIconMask( CFbsBitmap* aMask );

    /**

    * This sets the mask of this setting item's icon array, if it exists, using the mask from the

    * passed icon.

    * It returns the bitmap from the aIcon. 

    * The method also takes ownership of aIcon and may delete it (but not its bitmap).

    * 

    * @since 2.0

    * @param aIcon  icon of which the mask is passed through to SetIconMask() and bitmap is returned

    * @return CFbsBitmap* bitmap from aIcon. Ownership of the bitmap is transfered to the caller

    */

    CFbsBitmap* SetIconMaskAndReturnBitmap( CGulIcon* aIcon );

private:

	/**

	* This routine causes any bitmaps that are extracted from setting pages to be updated

	* according to the current (internal) setting value

	*/

	void UpdateBitmapL();

	/**

	* Set the index at which the item is to appear in the setting item list 

	* Only needed by CAknSettingItemArray

	*/

	void SetVisibleIndex( TInt aVisibleIndex );

	/**

	* Set the ordinal value. This is used for dynamic changing of the ordinal by 

	* CAknSettingItemArray

	*

	*/

	void SetOrdinal( TInt aOrdinal );

	/**

	*

	* Clean up a setting text for display by replacing all non printing characters 

	* by spaces

	*

	*/

	TPtrC ReplaceNonPrintingCharacters( TDes& aTextToClean );

private:

	IMPORT_C void CAknSettingItem_Reserved();

private:

	TUint iFlags;

	TInt iIdentifier;

	TInt iOrdinal;

	TInt iSettingIdentifier;

	TInt iSettingPageResourceId;

	TInt iEditorControlType;

	TInt iSettingEditorResourceId;

	TInt iAssociatedResourceId;

	TInt iIconIndex; // Only valid if relevant bit is set in iFlags

	HBufC* iEmptyItemText; // Owned 

	HBufC* iSettingName;  // Owned

	HBufC* iListBoxText;  // Owned

	HBufC* iCompulsoryText; // Owned

	// Following are not owned

	CAknSettingPage* iSettingPage; // This is a ref that is valid when non-0 - when the SP is "up"

	CArrayPtr<CGulIcon>* iIconArray;	// Reference to the array only !

	TInt iVisibleIndex;

	// Set flags that are in the Setting pages' constructors 

	TInt iSettingPageFlags;

    // Pointer to the listbox that the setting item is providing data to

    const CEikFormattedCellListBox* iParentListBox; // Not owned

	CAknSettingItemExtension* iExtension;

	};

/**

* Support for abstact text setting type. Corresponds to CAknTextSettingPage

*

*/

class CAknTextSettingItem : public CAknSettingItem

{

public:

	/*

	* Constructor 

	*

	* @param		resource identifier for this setting item

	* @param		Setting text

	*

	*/

	IMPORT_C CAknTextSettingItem( TInt aIdentifier, TDes& aText );

	/**

	* Destructor

	*/ 

	IMPORT_C ~CAknTextSettingItem();

	/**

	* This command externalizes the current setting. The displayed (internal) copy

	* is transferred to the external copy (the one referenced in the constructor).

	*

	* This must be called by the client if he wants this to happen. Note that StoreAllL() 

	* on the setting item list will call this for each setting item.

	*/

	IMPORT_C virtual void StoreL();

	/*

	* The external value is transferred to the internal value

	* This occurs at construction, but may be called by client code when required.

	*/

	IMPORT_C virtual void LoadL(); // Called from 2nd stage constructors

	/*

	* This method obtains the current value's setting text.

	* 

	* The reference is returned and is not a copy of the text, but refers to the current

	* internal text value. This is the value that would be externalized if StoreL were called. 

	* An exception to this is if the current text is zero length. In that case a reference to the 

	* empty text is returned (which would not be externalized if StoreL is called).

	*

	* @return	Reference to descriptor with the current internal text 

	*/

	IMPORT_C virtual const TDesC& SettingTextL();

	/**

	*

	* This launches the setting page for text editing

	*

	* @param		aCalledFromMenu - ignored in this class

	*

	*/

	IMPORT_C virtual void EditItemL( TBool aCalledFromMenu );

protected:

	/**

	*  Access for re-implementors to the internal text 

	*

	* @return	reference to a TPtr holding the internal text

	*/

	IMPORT_C TPtr& InternalTextPtr();

	/**

	*  Access for re-implementors to the external text

	*

	* @return	TPtrC pointing to the external text

	*/

	IMPORT_C TPtrC ExternalText();

	/**

	* Allows re-implementors to set the external text

	* No change of ownership is implied.

	*

	* @param	 a reference to the external text

	*