CCoeControlArray Class Reference

#include <mw/coecontrolarray.h>

Link against: cone.lib

class CCoeControlArray : public CBase

Inherits from

CCoeControlArray

Nested Classes and Structures

CCoeControlArray::TCursor

Public Member Enumerations
enum	TEvent { EControlAdded, EControlRemoved }

Public Member Functions
	~CCoeControlArray()
IMPORT_C TCursor	AppendLC(CCoeControl *, TInt)
IMPORT_C TCoeControlWithId	At(TInt)
IMPORT_C const TCoeControlWithId	At(TInt)
IMPORT_C TCursor	Begin()
T *	ControlById(TInt)
const T *	ControlById(TInt)
IMPORT_C TBool	ControlsOwnedExternally()
IMPORT_C TInt	Count()
IMPORT_C TCursor	End()
IMPORT_C TCursor	Find(const CCoeControl *)
IMPORT_C TCursor	Find(TInt)
IMPORT_C TInt	Id(const CCoeControl &)
IMPORT_C TCursor	InsertAfterLC(TInt, CCoeControl *, TInt)
IMPORT_C TCursor	InsertLC(TCursor &, CCoeControl *, TInt)
IMPORT_C TBool	IsArrayLocked()
IMPORT_C CCoeControlArray *	NewL(CCoeControl &)
IMPORT_C TInt	Remove(const CCoeControl *)
IMPORT_C CCoeControl *	Remove(TCursor)
IMPORT_C CCoeControl *	RemoveById(TInt)
IMPORT_C TInt	Replace(CCoeControl , CCoeControl )
IMPORT_C void	Reset()
IMPORT_C void	ResetAndDestroy()
IMPORT_C void	SetArrayLocked()
IMPORT_C void	SetControlsOwnedExternally(TBool)
IMPORT_C void	Sort(TLinearOrder< TCoeControlWithId >)
IMPORT_C void	SortById()

Inherited Functions
	CBase::CBase()
	CBase::Delete(CBase *)
	CBase::Extension_(TUint,TAny &,TAny )
	CBase::operator new(TUint)
	CBase::operator new(TUint,TAny *)
	CBase::operator new(TUint,TLeave)
	CBase::operator new(TUint,TLeave,TUint)
	CBase::operator new(TUint,TUint)
	CBase::~CBase()

Detailed Description

Class that represents an array of controls.

The CCoeControlArray class is used to store the child controls of a container control. The method CCoeControl::InitComponentArrayL() must be used to create the array and the method CCoeControlArray& CCoeControl::Components() can be used to get this array.

Member Enumeration Documentation

Enum TEvent

Defines the possible events related to a change to the contents of the array.

Enumerator	Value	Description
EControlAdded		A control has been added to the array
EControlRemoved		A control has been removed from the array

Constructor & Destructor Documentation

~CCoeControlArray ( )

IMPORT_C

~CCoeControlArray

(

)

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

Member Function Documentation

AppendLC ( CCoeControl *, TInt )

IMPORT_C TCursor	AppendLC	(	CCoeControl *	aControl,
			TInt	aControlId = KCoeNoControlId
		)

Appends a control at the end of the array.

Parameter	Description
aControl	The control to add
aControlId	The id for the new control

Returns: A cursor to the added control

At ( TInt )

IMPORT_C TCoeControlWithId

(

TInt

aIndex

)

Gets the element at the given index.

Parameter	Description
aIndex	The index of the control

Returns: The control and its id

At ( TInt )

IMPORT_C const TCoeControlWithId

(

TInt

aIndex

)

const

Gets the element at the given index.

Parameter	Description
aIndex	The index of the control

Returns: The control and its id

Begin ( )

IMPORT_C TCursor

Begin

(

)

const

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().

Returns: A cursor that points to the first control in the array.

ControlById ( TInt )

T *

ControlById

(

TInt

aControlId

)

Gets the control with the given id.

Parameter	Description
aControlId	The id of the desired control.

Returns: The control with the given id.

ControlById ( TInt )

const T *

ControlById

(

TInt

aControlId

)

const

Gets the control with the given id.

Parameter	Description
aControlId	The id of the desired control.

Returns: The control with the given id.

ControlsOwnedExternally ( )

IMPORT_C TBool

ControlsOwnedExternally

(

)

const

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.

Returns: ETrue if the array does NOT own the controls, EFalse if the array owns the controls.

Count ( )

IMPORT_C TInt

Count

(

)

const

Gets the number of elements in the array.

Returns: The number of elements in the array

End ( )

IMPORT_C TCursor

End

(

)

const

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.

Returns: A cursor that points right after the last element

Find ( const CCoeControl * )

IMPORT_C TCursor

Find

(

const CCoeControl *

aControl

)

const

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.

Parameter	Description
aControl	The control to find.

Returns: 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.

Find ( TInt )

IMPORT_C TCursor

Find

(

TInt

aControlId

)

const

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.

Parameter	Description
aControlId	The id of the control to find.

Returns: 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.

Id ( const CCoeControl & )

IMPORT_C TInt

(

const CCoeControl &

aControl

)

const

Gets the id of the control.

Parameter	Description
aControl	The control

Returns: The id of the control or KErrNotFound if the control can't be found.

InsertAfterLC ( TInt, CCoeControl *, TInt )

IMPORT_C TCursor	InsertAfterLC	(	TInt	aInsertAfterId,
			CCoeControl *	aControl,
			TInt	aControlId = KCoeNoControlId
		)

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.

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.

Parameter	Description
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.
aControl	The new control we want to add.
aControlId	The id of the new control.

Returns: A cursor to the added control

InsertLC ( TCursor &, CCoeControl *, TInt )

IMPORT_C TCursor	InsertLC	(	TCursor &	aInsertAt,
			CCoeControl *	aControl,
			TInt	aControlId = KCoeNoControlId
		)

Inserts a control at the given position.

The function will also result in the CCoeControl::HandleControlArrayEventL method being called on the owner of the array. The event being generated is EControlAdded.

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

Parameter	Description
aInsertAt	The position at which we want to insert the new control.
aControl	The new control we want to add.
aControlId	The id of the new control.

Returns: A cursor to the added control

IsArrayLocked ( )

IMPORT_C TBool

IsArrayLocked

(

)

const

Checks whether the array is locked or not. If an array is locked any attempt to add or remove controls will fail with KErrLocked.

Returns: ETrue if the array is locked, EFalse otherwise

NewL ( CCoeControl & )

IMPORT_C CCoeControlArray *

NewL

(

CCoeControl &

aOwner

)

[static]

Creates a new CCoeControlArray.

Parameter	Description
aOwner	The control that owns the new array

Returns: A new CCoeControlArray instance

Remove ( const CCoeControl * )

IMPORT_C TInt

Remove

(

const CCoeControl *

aControl

)

Removes a control but does NOT delete the control itself. The ownership of the control is transferred to the caller.

The function will also result in the CCoeControl::HandleControlArrayEventL method being called on the owner of the array. The event being generated is EControlRemoved.

Parameter	Description
aControl	The control to remove

Returns: KErrNone if the control was removed successfully, KErrNotFound if the control could not be found.

Remove ( TCursor )

IMPORT_C CCoeControl *

Remove

(

TCursor

aRemoveAt

)

Removes a control but does NOT delete the control itself. The ownership of the control is transferred to the caller.

The function will also result in the CCoeControl::HandleControlArrayEventL method being called on the owner of the array. The event being generated is EControlRemoved.

Parameter	Description
aRemoveAt	The position of the control to remove

Returns: A pointer to the control that has been removed. This can be used by the caller to delete the control.

RemoveById ( TInt )

IMPORT_C CCoeControl *

RemoveById

(

TInt

aControlId

)

Removes a control but does NOT delete the control itself. The ownership of the control is transferred to the caller.

The function will also result in the CCoeControl::HandleControlArrayEventL method being called on the owner of the array. The event being generated is EControlRemoved.

Parameter	Description
aControlId	The id of the control to remove

Returns: A pointer to the control that has been removed. This can be used by the caller to delete the control. The function returns NULL if no control with the given aControlId has been found.

Replace ( CCoeControl , CCoeControl )

IMPORT_C TInt	Replace	(	CCoeControl *	aOriginalControl,
			CCoeControl *	aNewControl
		)

Replaces a control in the array with another control.

Parameter	Description
aOriginalControl	The control that must be replaced
aNewControl	The new control

Returns: A standard error code

Reset ( )

IMPORT_C void

Reset

(

)

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

ResetAndDestroy ( )

IMPORT_C void

ResetAndDestroy

(

)

Removes all the controls from the array and deletes them.

SetArrayLocked ( )

IMPORT_C void

SetArrayLocked

(

)

Locks the array. If an array is locked any attempt to add or remove controls will fail with KErrLocked.

SetControlsOwnedExternally ( TBool )

IMPORT_C void

SetControlsOwnedExternally

(

TBool

aOwnedExternally

)

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.

Parameter	Description
aOwnedExternally	ETrue if the controls are owned externally, EFalse if they are owned by the array.

Sort ( TLinearOrder< TCoeControlWithId > )

IMPORT_C void

Sort

(

TLinearOrder< TCoeControlWithId >

aOrder

)

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

Parameter	Description
aOrder	The user defined static method which implements the algorithm for sorting.

SortById ( )

IMPORT_C void

SortById

(

)

Sorts the controls using their index as the key.

CCoeControlArray Class Reference

Inherits from

Nested Classes and Structures

Detailed Description

Member Enumeration Documentation

Enum TEvent

Constructor & Destructor Documentation

~CCoeControlArray ( )

Member Function Documentation

AppendLC ( CCoeControl *, TInt )

At ( TInt )

At ( TInt )

Begin ( )

ControlById ( TInt )

ControlById ( TInt )

ControlsOwnedExternally ( )

Count ( )

End ( )

Find ( const CCoeControl * )

Find ( TInt )

Id ( const CCoeControl & )

InsertAfterLC ( TInt, CCoeControl *, TInt )

InsertLC ( TCursor &, CCoeControl *, TInt )

IsArrayLocked ( )

NewL ( CCoeControl & )

Remove ( const CCoeControl * )

Remove ( TCursor )

RemoveById ( TInt )

Replace ( CCoeControl *, CCoeControl * )

Reset ( )

ResetAndDestroy ( )

SetArrayLocked ( )

SetControlsOwnedExternally ( TBool )

Sort ( TLinearOrder< TCoeControlWithId > )

SortById ( )

Replace ( CCoeControl , CCoeControl )