CCoeControlArray in Application Framework Control

class CCoeControlArray : public CBase;

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.

Derivation

CBase - Base class for all classes to be instantiated on the heap.

CCoeControlArray - Class that represents an array of controls.

Members

Defined in CCoeControlArray:

AppendLC(CCoeControl *,TInt)Appends a control at the end of the array.
At(TInt)Gets the element at the given index.
At(TInt)constGets the element at the given index.
Begin()constGets a cursor that points to the first element of the array. Note that if the ar...
ControlById(TInt)Gets the control with the given id.
ControlById(TInt)constGets the control with the given id.
ControlsOwnedExternally()constThis function checks if the controls are owned by the array or not. If the contr...
Count()constGets the number of elements in the array.
EControlAddedA control has been added to the array
EControlRemovedA control has been removed from the array
End()constGets a cursor to the position right after the last element in the array. To get ...
Find(TInt)constGets a cursor to the control, if the control with the given id is found in the a...
Find(const CCoeControl *)constGets a cursor to the control, if the control is found in the array. Use the CCoe...
Id(const CCoeControl &)constGets the id of the control.
InsertAfterLC(TInt,CCoeControl *,TInt)Inserts a control after the control with the given id.
InsertLC(TCursor &,CCoeControl *,TInt)Inserts a control at the given position.
IsArrayLocked()constChecks whether the array is locked or not. If an array is locked any attempt to ...
NewL(CCoeControl &)Creates a new CCoeControlArray.
Remove(TCursor)Removes a control but does NOT delete the control itself. The ownership of the c...
Remove(const CCoeControl *)Removes a control but does NOT delete the control itself. The ownership of the c...
RemoveById(TInt)Removes a control but does NOT delete the control itself. The ownership of the c...
Replace(CCoeControl *,CCoeControl *)Replaces a control in the array with another control.
Reset()Removes all the controls from the array but doesn't delete them.
ResetAndDestroy()Removes all the controls from the array and deletes them.
SetArrayLocked()Locks the array. If an array is locked any attempt to add or remove controls wil...
SetControlsOwnedExternally(TBool)Is used to set whether the array owns the controls or not. If the controls are o...
Sort(TLinearOrder< TCoeControlWithId >)This function provides a pluggable implementation to sort the array of controls....
SortById()Sorts the controls using their index as the key.
TCursorThis class is an iterator for the CCoeControlArray class.
TEventDefines the possible events related to a change to the contents of the array.
~CCoeControlArray()The destructor will delete the controls in the array only if the EControlsOwnedE...

Inherited from CBase:

Delete(CBase *)Deletes the specified object.
Extension_(TUint,TAny *&,TAny *)Extension function
operator new(TUint)Allocates the object from the heap and then initialises its contents to binary z...
operator new(TUint,TAny *)Initialises the object to binary zeroes.
operator new(TUint,TLeave)Allocates the object from the heap and then initialises its contents to binary z...
operator new(TUint,TLeave,TUint)Allocates the object from the heap and then initialises its contents to binary z...
operator new(TUint,TUint)Allocates the object from the heap and then initialises its contents to binary z...

IMPORT_C static CCoeControlArray* NewL(CCoeControl &aOwner);

Description

Creates a new CCoeControlArray.

Parameters


                                 						CCoeControl &aOwner

The control that owns the new array

Return value

CCoeControlArray *

A new CCoeControlArray instance

IMPORT_C ~CCoeControlArray();

Description

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

IMPORT_C TInt Count() const;

Description

Gets the number of elements in the array.

Return value

TInt

The number of elements in the array

IMPORT_C void Reset();

Description

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

IMPORT_C void ResetAndDestroy();

Description

Removes all the controls from the array and deletes them.

IMPORT_C void SortById();

Description

Sorts the controls using their index as the key.

IMPORT_C TBool ControlsOwnedExternally() const;

Description

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 value

TBool

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

IMPORT_C void SetControlsOwnedExternally(TBool aOwnedExternally);

Description

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.

Parameters


                                 						TBool aOwnedExternally

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

IMPORT_C TBool IsArrayLocked() const;

Description

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 value

TBool

ETrue if the array is locked, EFalse otherwise

IMPORT_C void SetArrayLocked();

Description

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

T* ControlById(TInt aControlId);

Description

Gets the control with the given id.

Parameters


                                 						TInt aControlId

The id of the desired control.

Return value

T *

The control with the given id.

const T* ControlById(TInt aControlId) const;

Description

Gets the control with the given id.

Parameters


                                 						TInt aControlId

The id of the desired control.

Return value

const T *

The control with the given id.

IMPORT_C TCursor Begin() const;

Description

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 CCoeControlArray::End()const.

Return value

CCoeControlArray::TCursor

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

IMPORT_C TCursor End() const;

Description

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 value

CCoeControlArray::TCursor

A cursor that points right after the last element

IMPORT_C TCursor Find(const CCoeControl *aControl) const;

Description

Gets a cursor to the control, if the control is found in the array. Use the CCoeControlArray::TCursor::IsValid()const function to check that the search found something or not.

Parameters

const CCoeControl *aControl

The control to find.

Return value

CCoeControlArray::TCursor

A cursor to the control. This may be an invalid cursor if we didn't find the requested control. Use CCoeControlArray::TCursor::IsValid()const to check if the cursor is valid.

IMPORT_C TCursor Find(TInt aControlId) const;

Description

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.

Parameters


                                 						TInt aControlId

The id of the control to find.

Return value

CCoeControlArray::TCursor

A cursor to the control. This may be an invalid cursor if we didn't find the requested control. Use CCoeControlArray::TCursor::IsValid()const to check if the cursor is valid.

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

Description

Appends a control at the end of the array.

Parameters

`CCoeControl *aControl`	The control to add
`TInt aControlId`	The id for the new control

Return value

CCoeControlArray::TCursor

A cursor to the added control

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

Description

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(CCoeControlArray::TEvent,const CCoeControlArray *,CCoeControl *,TInt) method being called on the owner of the array. The event being generated is EControlAdded.

Parameters

`TInt 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.
`CCoeControl *aControl`	The new control we want to add.
`TInt aControlId`	The id of the new control.

Return value

CCoeControlArray::TCursor

A cursor to the added control

Leave codes

`KErrLocked`	if the array has been locked using the CCoeControlArray::SetArrayLocked() function.
`KErrNotFound`	if the array doesn't contain a control identified by aInsertAfterId.

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

Description

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(CCoeControlArray::TEvent,const CCoeControlArray *,CCoeControl *,TInt) method being called on the owner of the array. The event being generated is EControlAdded.

Parameters

`CCoeControlArray::TCursor &aInsertAt`	The position at which we want to insert the new control.
`CCoeControl *aControl`	The new control we want to add.
`TInt aControlId`	The id of the new control.

Return value

CCoeControlArray::TCursor

A cursor to the added control

Leave codes

KErrLocked

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

IMPORT_C TInt Remove(const CCoeControl *aControl);

Description

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(CCoeControlArray::TEvent,const CCoeControlArray *,CCoeControl *,TInt) method being called on the owner of the array. The event being generated is EControlRemoved.

Parameters

const CCoeControl *aControl

The control to remove

Return value

TInt

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

IMPORT_C CCoeControl* Remove(TCursor aRemoveAt);

Description

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(CCoeControlArray::TEvent,const CCoeControlArray *,CCoeControl *,TInt) method being called on the owner of the array. The event being generated is EControlRemoved.

Parameters


                                 						CCoeControlArray::TCursor aRemoveAt

The position of the control to remove

Return value

CCoeControl *

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

IMPORT_C CCoeControl* RemoveById(TInt aControlId);

Description

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(CCoeControlArray::TEvent,const CCoeControlArray *,CCoeControl *,TInt) method being called on the owner of the array. The event being generated is EControlRemoved.

Parameters


                                 						TInt aControlId

The id of the control to remove

Return value

CCoeControl *

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.

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

Description

Replaces a control in the array with another control.

Parameters

`CCoeControl *aOriginalControl`	The control that must be replaced
`CCoeControl *aNewControl`	The new control

Return value

TInt

A standard error code

IMPORT_C TCoeControlWithId At(TInt aIndex);

Description

Gets the element at the given index.

Parameters


                                 						TInt aIndex

The index of the control

Return value

TCoeControlWithId

The control and its id

IMPORT_C const TCoeControlWithId At(TInt aIndex) const;

Description

Gets the element at the given index.

Parameters


                                 						TInt aIndex

The index of the control

Return value

const TCoeControlWithId

The control and its id

IMPORT_C TInt Id(const CCoeControl &aControl) const;

Description

Gets the id of the control.

Parameters

const CCoeControl &aControl

The control

Return value

TInt

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

IMPORT_C void Sort(TLinearOrder< TCoeControlWithId > aOrder);

Description

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

Parameters


                                 						TLinearOrder< TCoeControlWithId > aOrder

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

class TCursor;

Description

This class is an iterator for the CCoeControlArray class.

Members

Defined in CCoeControlArray::TCursor:

Control()Gets the control.
Control()constGets the control.
IsValid()constChecks if the cursor is valid. Use this to replace the comparison with NULL that...
Next()Updates the cursor so that it points to the next element in the array. If the cu...
Prev()Updates the cursor so that it points to the previous element in the array. If th...
operator!=(const TCursor &)constChecks if the cursors are different. Cursors are equal if they point to the same...
operator==(const TCursor &)constChecks if the cursors are equal. Cursors are equal if they point to the same con...

Member functions

`Control()`

T* Control();

Description

Gets the control.

Return value

T *

The control at the current cursor position.

`Control()const`

const T* Control() const;

Description

Gets the control.

Return value

const T *

The control at the current cursor position.

`Prev()`

IMPORT_C TBool Prev();

Description

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 value

TBool

EFalse if the current element was the first one in the array, ETrue if it wasn't and the function actually did something.

`Next()`

IMPORT_C TBool Next();

Description

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 value

TBool

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

`IsValid()const`

IMPORT_C TBool IsValid() const;

Description

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 value

TBool

ETrue if the cursor points to a control, EFalse otherwise

`operator==(const TCursor &)const`

IMPORT_C TBool operator==(const TCursor &aCursor) const;

Description

Checks if the cursors are equal. Cursors are equal if they point to the same control in the same array else they are different.

Parameters

const CCoeControlArray::TCursor &aCursor

The other cursor.

Return value

TBool

ETrue if the cursors point to the same position in the same array, EFalse otherwise.

`operator!=(const TCursor &)const`

IMPORT_C TBool operator!=(const TCursor &aCursor) const;

Description

Checks if the cursors are different. Cursors are equal if they point to the same control in the same array else they are different.

Parameters

const CCoeControlArray::TCursor &aCursor

The other cursor.

Return value

TBool

EFalse if the cursors point to the same position in the same array, EFalse otherwise.

TEvent

Description

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

`EControlAdded`	A control has been added to the array
`EControlRemoved`	A control has been removed from the array

Class CCoeControlArray

Description

Derivation

Members

Construction and destruction

NewL(CCoeControl &)

Description

Parameters

Return value