// Copyright (c) 2004-2009 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:

//

#include <coecontrolarray.h>	// class CCoeControlArray

#include <coecntrl.h>			// class CCoeControl

#include "coepanic.h"			// Cone panic codes

#include <e32std.h>				// class EUser

/**

Flags used internally.

*/

enum TFlags

	{

	/** Controls are owned externally. This means that the destructor

	shouldn't delete the individual controls. 

	*/

	EControlsOwnedExternally = 0x01,

	/** When the array is locked any attempt to add or remove elements will result in KErrLocked.

	*/

	EArrayLocked = 0x02

	};

LOCAL_C void CleanupComponentControl(TAny* aCleanupItem)	

	{

	CCoeControl* control = reinterpret_cast<CCoeControl*>(aCleanupItem);

	if (control)

		{

		control->RemoveFromParent();

		delete control;

		}

	}

LOCAL_C void CleanupExternallyOwnedComponentControl(TAny* aCleanupItem)	

	{

	CCoeControl* control = reinterpret_cast<CCoeControl*>(aCleanupItem);

	if (control)

		{

		control->RemoveFromParent();

		}

	}

//

// class CCoeControlArray::TCursor

//

/** Updates the cursor so that it points to the previous element in the array.

If the current element is the first one then this function does nothing and returns EFalse.

@return EFalse if the current element was the first one in the array, ETrue if it wasn't and the function

actually did something.

*/

EXPORT_C TBool CCoeControlArray::TCursor::Prev()

	{

	if(iIndex <= 0)

		return EFalse;

	iIndex--;

	UpdateMemento();

	return ETrue;

	}

/** Updates the cursor so that it points to the next element in the array.

If the current element is the last one then this function returns EFalse.

@return EFalse if the current element was the last one in the array, ETrue otherwise 

*/

EXPORT_C TBool CCoeControlArray::TCursor::Next()

	{

	const TInt count = iArray->Count();

	if(iIndex >= count-1) //If last element or beyond move to just off the end of the array

		{

		iIndex = count;

		iMemento = TCoeControlWithId(KCoeNoControlId);

		return EFalse;

		}	

	iIndex++;

	UpdateMemento();

	return ETrue;

	}

/** Checks if the cursor is valid. Use this to replace the comparison with NULL that you would

do with pointers. This function is typically used on the cursors returned by the find operations.

@return ETrue if the cursor points to a control, EFalse otherwise

*/

EXPORT_C TBool CCoeControlArray::TCursor::IsValid() const

	{

	UpdateIndex();

	return (iIndex != KErrNotFound);

	}

/** Checks if the cursors are equal. Cursors are equal if they point to the same control in the

same array else they are different.

@param aCursor The other cursor.

@return ETrue if the cursors point to the same position in the same array, EFalse 

otherwise.

*/

EXPORT_C TBool CCoeControlArray::TCursor::operator ==(const TCursor& aCursor) const

	{

	UpdateIndex();

	aCursor.UpdateIndex();

	ASSERT(IsValid());

	ASSERT(aCursor.IsValid());

	return (iIndex == aCursor.iIndex && iArray == aCursor.iArray);

	}

/** Checks if the cursors are different. Cursors are equal if they point to the same control in the

same array else they are different.

@param aCursor The other cursor.

@return EFalse if the cursors point to the same position in the same array, EFalse 

otherwise.

*/

EXPORT_C TBool CCoeControlArray::TCursor::operator !=(const TCursor& aCursor) const

	{

	UpdateIndex();	

	aCursor.UpdateIndex();

	ASSERT(IsValid());

	ASSERT(aCursor.IsValid());

	return !(iIndex == aCursor.iIndex && iArray == aCursor.iArray);

	}

/** Constructor.

@param aArray The array

@param aIndex The index into the array

*/

CCoeControlArray::TCursor::TCursor(const CCoeControlArray& aArray, TInt aIndex) : 

	iArray(&aArray), iIndex(aIndex), iMemento(KCoeNoControlId)

	{

	if(aIndex >= 0 && aIndex < aArray.Count())

		iMemento = TCoeControlWithId(aArray.At(aIndex));

	}

/** Gets the index of the cursor.

@return The index i.e. the position in the array

*/

TInt CCoeControlArray::TCursor::Index() const

	{

	UpdateIndex();

	return iIndex;

	}

/** Gets the control of the cursor.

@return The control.

*/

EXPORT_C CCoeControl* CCoeControlArray::TCursor::Ctrl() const

	{

	UpdateIndex();

	if(iIndex == KErrNotFound || iIndex >= iArray->Count())

		return NULL;

	else

		return iArray->At(iIndex).iControl;

	}

/** This function is used by any operation that requires an update of the memento.

*/

void CCoeControlArray::TCursor::UpdateMemento() const

	{

	if(iIndex >= 0 && iIndex < iArray->Count())

		iMemento = iArray->At(iIndex);

	else

		{

		iIndex = KErrNotFound;

		iMemento = TCoeControlWithId(KErrNotFound);

		}

	}

/** This function is used by any operation that requires an update of the index.

*/

void CCoeControlArray::TCursor::UpdateIndex() const

	{

	if(!iMemento.iControl)	// If we don't know what control this cursor should point to

		{

		// This is either an invalid cursor (if iIndex == -1) 

		// or one that points to the element just beyond the end of the array (iIndex == iArray->Count())

		// If the iIndex is pointing anywhere but at CCoeControlArray::End() it has gone bad

		if(iIndex != KErrNotFound && iIndex != iArray->Count())

			{

			iIndex = KErrNotFound;

			iMemento = TCoeControlWithId(KErrNotFound);

			}

		return;

		}

	if(iIndex >= 0 && iIndex < iArray->Count())	// If the index is within the valid range

		{

		// Check that the control at iIndex is the same as the memento

		const TCoeControlWithId controlWithId = iArray->At(iIndex);

		if(iMemento.iControl != controlWithId.iControl)	// If not, update the index to match the memento

			{

			const TInt newIndex = iArray->Find(iMemento.iControl).iIndex;

			if(newIndex != KErrNotFound)

				iIndex = newIndex;

			else

				{

				// If the memento control is no longer in the array, try update the memento instead

				UpdateMemento();

				}

			}

		}

	else

		{

		const TInt newIndex = iArray->Find(iMemento.iControl).iIndex;

		if(newIndex != KErrNotFound)

			iIndex = newIndex;

		else

			iMemento = TCoeControlWithId(KErrNotFound);	

		}

	}

//

// class CCoeControlArray

//

/** Creates a new CCoeControlArray.

@param aOwner The control that owns the new array

@return A new CCoeControlArray instance

*/

EXPORT_C CCoeControlArray* CCoeControlArray::NewL(CCoeControl& aOwner)

	{

	CCoeControlArray* self = new (ELeave) CCoeControlArray(aOwner);

	return self;

	}

/** Constructor.

*/

TCoeControlWithId::TCoeControlWithId(TInt aControlId, CCoeControl* aControl) : iControl(aControl), iId(aControlId)

	{

	}

/** The destructor will delete the controls in the array only if the EControlsOwnedExternally flag is not set.

*/

EXPORT_C CCoeControlArray::~CCoeControlArray()

	{

	if(!ControlsOwnedExternally())

		ResetAndDestroy();

	iControls.Close();

 	}

const TInt KControlArrayGranularity = 1;

/** Constructor 

@param aOwner The control that owns the new array

*/

EXPORT_C CCoeControlArray::CCoeControlArray(CCoeControl& aOwner)

 : iOwner(aOwner), iControls(KControlArrayGranularity, _FOFF(TCoeControlWithId, iId))

	{

	}

/** Gets the number of elements in the array.

@return The number of elements in the array

*/

EXPORT_C TInt CCoeControlArray::Count() const

	{

	return iControls.Count();

	}

/** Removes all the controls from the array but doesn't delete them.

*/

EXPORT_C void CCoeControlArray::Reset()

	{

	iControls.Reset();

	}

/** Removes all the controls from the array and deletes them.

*/

EXPORT_C void CCoeControlArray::ResetAndDestroy()

	{

	for(TInt i = iControls.Count()-1; i >= 0; i--)	// remove from the end, so we don't need to move any items

		{

		delete iControls[i].iControl;

		// The array must be shrunk immediately to avoid Kern-Exec 3 when calling CCoeControl::Components() 

		// or CCoeControl::ComponentControl(TInt aIndex) inside MCoeFocusObserver::HandleDestructionOfFocusedItem

 		iControls.Remove(i);

		}

	iControls.Reset();

	}

/** Sorts the controls using their index as the key.

*/

EXPORT_C void CCoeControlArray::SortById()

	{

	iControls.SortSigned();

	}

/**This function provides a pluggable implementation to sort the array of controls.

@param aOrder The user defined static method which implements the algorithm for sorting.

*/

EXPORT_C void CCoeControlArray::Sort(TLinearOrder< TCoeControlWithId > aOrder)

	{

	iControls.Sort(aOrder);

	}

/** This function checks if the controls are owned by the array or not. If the controls are owned by the array they

will be deleted when the array is destroyed else they will not.

@return ETrue if the array does NOT own the controls, EFalse if the array owns the controls.

*/

EXPORT_C TBool CCoeControlArray::ControlsOwnedExternally() const

	{

	return (iFlags&EControlsOwnedExternally);

	}

/** Is used to set whether the array owns the controls or not. If the controls are owned by the array they

will be deleted when the array is destroyed else they will not.

@param aOwnedExternally ETrue if the controls are owned externally, EFalse if

they are owned by the array.

*/

EXPORT_C void CCoeControlArray::SetControlsOwnedExternally(TBool aOwnedExternally)

	{

	if(aOwnedExternally)

		{

		iFlags |= EControlsOwnedExternally;

		}

	else 

		{

		iFlags &= ~EControlsOwnedExternally;

		}

	}

/** Checks whether the array is locked or not. If an array is locked any attempt to add or remove controls

will fail with KErrLocked.

@return ETrue if the array is locked, EFalse otherwise

*/

EXPORT_C TBool CCoeControlArray::IsArrayLocked() const

	{

	return (iFlags&EArrayLocked);

	}

/** Locks the array. If an array is locked any attempt to add or remove controls

will fail with KErrLocked.

*/

EXPORT_C void CCoeControlArray::SetArrayLocked()

	{

	iFlags |= EArrayLocked;

	}

/** Gets a cursor that points to the first element of the array. Note that if the array is empty

this is actually equivalent to a call to End().

@return A cursor that points to the first control in the array.

*/

EXPORT_C CCoeControlArray::TCursor CCoeControlArray::Begin() const

	{

	return TCursor(*this, 0);

	}

/** Gets a cursor to the position right after the last element in the array. To get the last element

use Prev(). This cursor is useful as argument to the insertion function to add the new control at the end of the array.

@return A cursor that points right after the last element

*/

EXPORT_C CCoeControlArray::TCursor CCoeControlArray::End() const

	{

	return TCursor(*this, Count());

	}

/** Gets a cursor to the control, if the control is found in the array. Use

the TCursor::IsValid function to check that the search found something or not.

@param aControl The control to find.

@return A cursor to the control. This may be an invalid cursor if we didn't 

find the requested control. Use TCursor::IsValid() to check if the cursor is valid.

*/

EXPORT_C CCoeControlArray::TCursor CCoeControlArray::Find(const CCoeControl* aControl) const

	{

	const TInt numControls = iControls.Count();

	for(TInt index = 0; index < numControls; index++)

		{

		if(iControls[index].iControl == aControl)

			return TCursor(*this, index);

		}

	return TCursor(*this, KCoeNoControlId);

	}

/** Gets a cursor to the control, if the control with the given id is found in the array.

Use the TCusror::IsValid function to check that the search found something or not.

@param aControlId The id of the control to find.

@return A cursor to the control. This may be an invalid cursor if we didn't 

find the requested control. Use TCursor::IsValid() to check if the cursor is valid.

*/

EXPORT_C CCoeControlArray::TCursor CCoeControlArray::Find(TInt aControlId) const

	{

	const TInt index = iControls.Find(TCoeControlWithId(aControlId));

	return TCursor(*this, index);

	}

/** Appends a control at the end of the array.

@param aControl The control to add

@param aControlId The id for the new control

@return A cursor to the added control

*/

EXPORT_C CCoeControlArray::TCursor CCoeControlArray::AppendLC(CCoeControl* aControl, TInt aControlId)

	{

	TCursor cursor = End();

	InsertLC(cursor, aControl, aControlId);

	return cursor;

	}

/** Inserts a control after the control with the given id.

Each array has an owner (an instance of the CCoeControl class) which is the container of all the child controls. 

Each control has a parent and for the child controls this parent must be the container. This function will automatically 

update the parent of aControl.

The function will also result in the CCoeControl::HandleControlArrayEventL method being called

on the owner of the array. The event being generated is EControlAdded.

@param aInsertAfterId The id of the control after which we want to insert the new control. If a control with this 

id can't be found in the array the function will leave with KErrNotFound.

@param aControl The new control we want to add.

@param aControlId The id of the new control.

@return A cursor to the added control

@leave KErrLocked if the array has been locked using the CCoeControlArray::SetArrayLocked() function.

@leave KErrNotFound if the array doesn't contain a control identified by aInsertAfterId. 

*/

EXPORT_C CCoeControlArray::TCursor CCoeControlArray::InsertAfterLC(TInt aInsertAfterId, CCoeControl* aControl, TInt aControlId)

	{

	const TInt index = IndexById(aInsertAfterId);

	if(index == KErrNotFound)

		{

		if(!(iFlags & EControlsOwnedExternally))

			delete aControl;

		User::Leave(KErrNotFound);

		}

	TCursor cursor(*this, index);

	cursor.Next();	// insert before the next item

	return(InsertLC(cursor, aControl, aControlId));

	}

/** Inserts a control at the given position. 

Each array has an owner (an instance of the CCoeControl class) which is the container of all the child controls. 

Each control has a parent and for the child controls this parent must be the container. This function will automatically 

update the parent of aControl.

The function will also result in the CCoeControl::HandleControlArrayEventL method being called

on the owner of the array. The event being generated is EControlAdded.

@param aInsertAt The position at which we want to insert the new control.

@param aControl The new control we want to add.

@param aControlId The id of the new control.

@return A cursor to the added control

@leave KErrLocked if the array has been locked using the CCoeControlArray::SetArrayLocked() function.

*/

EXPORT_C CCoeControlArray::TCursor CCoeControlArray::InsertLC(TCursor& aInsertAt, CCoeControl* aControl, TInt aControlId)

	{

 	__ASSERT_DEBUG(this, Panic(ECoePanicNonExistentArray));	

	const TBool externallyOwned = iFlags & EControlsOwnedExternally;

	// Set parent before pushing the CleanupComponenetControl, so that we can 

	// look for external ownership on parent if something leaves

	const TInt err = aControl->SetParent(&iOwner);

	if(err != KErrNone)

		{

		if(!externallyOwned)

			delete aControl;

		User::Leave(err);

		}

	CleanupStack::PushL(TCleanupItem((externallyOwned ? 

										CleanupExternallyOwnedComponentControl : 

										CleanupComponentControl),

									 aControl));

	if(IsArrayLocked())

		User::Leave(KErrLocked);

#ifdef _DEBUG	

	__ASSERT_DEBUG(aControlId == KCoeNoControlId || 

			iControls.Find(TCoeControlWithId(aControlId)) == KErrNotFound, Panic(ECoePanicDuplicateControlId));

#endif	

	// To preserve the insertion order of controls without assigned ID

	if(aControlId == KCoeNoControlId)	// If the control has not been given an ID...

		{

		// ...loop through all controls and find the largest negative ID (i.e. the one closest to zero)

		TInt autoId = KMinTInt32;

		const TInt count = iControls.Count();

		for(TInt i = 0; i < count; i++)

			{

			const TInt controlId = iControls[i].iId;

			if(controlId < 0 && autoId <= controlId)

				{

				autoId = controlId+1;

				}

			}

		aControlId = autoId;	// Give the new control the next larger negative ID

		}

	iControls.InsertL(TCoeControlWithId(aControlId, aControl), aInsertAt.Index());

	iOwner.HandleControlArrayEventL(EControlAdded, this, aControl, aControlId);	

	const TCursor newItemCursor = aInsertAt; 

	aInsertAt.Next();	// Move the cursor forward to presserve its position in the array

	return newItemCursor;

	}

/** Removes a control but does NOT delete the control itself. The ownership of the control is 

transferred to the caller.