Symbian^3 Application Developer Library >

CCoeControlArray Class Reference

class CCoeControlArray : public CBase

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.

Inherits from

Nested Classes and Structures

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 ()
Private Member Functions
CCoeControlArray ( CCoeControl &)
IMPORT_C CCoeControl * CtrlById ( TInt )
TInt IndexById ( TInt )
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()
Public Member Enumerations
enum TEvent { EControlAdded , EControlRemoved }
Private Attributes
RArray < TCoeControlWithId > iControls
TInt iFlags
CCoeControl & iOwner

Constructor & Destructor Documentation

CCoeControlArray(CCoeControl &)

IMPORT_C CCoeControlArray ( CCoeControl & aOwner ) [private]

Constructor

Parameters

CCoeControl & aOwner The control that owns the new array

~CCoeControlArray()

IMPORT_C ~CCoeControlArray ( )

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

Member Functions Documentation

AppendLC(CCoeControl *, TInt)

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

Appends a control at the end of the array.

Parameters

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

At(TInt)

IMPORT_C TCoeControlWithId At ( TInt aIndex )

Gets the element at the given index.

Parameters

TInt aIndex The index of the control

At(TInt)

IMPORT_C const TCoeControlWithId At ( TInt aIndex ) const

Gets the element at the given index.

Parameters

TInt aIndex The index of the control

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

ControlById(TInt)

T * ControlById ( TInt aControlId )

Gets the control with the given id.

Parameters

TInt aControlId The id of the desired control.

ControlById(TInt)

const T * ControlById ( TInt aControlId ) const

Gets the control with the given id.

Parameters

TInt aControlId The id of the desired control.

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.

Count()

IMPORT_C TInt Count ( ) const

Gets the number of elements in the array.

CtrlById(TInt)

IMPORT_C CCoeControl * CtrlById ( TInt aControlId ) const [private]

Gets the control with the given id or NULL if there is no control with the given id.

Parameters

TInt aControlId The id of the control

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.

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.

Parameters

const CCoeControl * aControl The control to find.

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.

Parameters

TInt aControlId The id of the control to find.

Id(const CCoeControl &)

IMPORT_C TInt Id ( const CCoeControl & aControl ) const

Gets the id of the control.

Parameters

const CCoeControl & aControl The control

IndexById(TInt)

TInt IndexById ( TInt aControlId ) const [private]

Gets the index of the control with the given id or KErrNotFound if there is no control that has that id.

Parameters

TInt aControlId The id of the control

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.

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 =  KCoeNoControlId The id of the new control.

InsertLC(TCursor &, CCoeControl *, TInt)

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

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.

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

Parameters

TCursor & aInsertAt The position at which we want to insert the new control.
CCoeControl * aControl The new control we want to add.
TInt aControlId =  KCoeNoControlId The id of the new 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.

NewL(CCoeControl &)

IMPORT_C CCoeControlArray * NewL ( CCoeControl & aOwner ) [static]

Creates a new CCoeControlArray .

Parameters

CCoeControl & aOwner The control that owns the new array

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.

Parameters

const CCoeControl * aControl The control to remove

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.

Parameters

TCursor aRemoveAt The position of the control to remove

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.

Parameters

TInt aControlId The id of the control to remove

Replace(CCoeControl *, CCoeControl *)

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

Replaces a control in the array with another control.

Parameters

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

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.

Parameters

TBool 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.

Parameters

TLinearOrder < TCoeControlWithId > 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.

Member Enumerations Documentation

Enum TEvent

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

Enumerators

EControlAdded

A control has been added to the array

EControlRemoved

A control has been removed from the array

Member Data Documentation

RArray< TCoeControlWithId > iControls

RArray < TCoeControlWithId > iControls [private]

TInt iFlags

TInt iFlags [private]

CCoeControl & iOwner

CCoeControl & iOwner [private]

Copyright ©2010 Nokia Corporation and/or its subsidiary(-ies).
All rights reserved. Unless otherwise stated, these materials are provided under the terms of the Eclipse Public License v1.0.