TApaTaskList Class Reference

#include <mw/apgtask.h>

Link against: apgrfx.lib

class TApaTaskList
Public Member Enumerations
enumTCycleDirection { EForwards, EBackwards }
Public Member Functions
TApaTaskList(RWsSession &)
IMPORT_C TIntCycleTasks(TUid, TCycleDirection)
IMPORT_C TApaTaskFindApp(const TDesC &)
IMPORT_C TApaTaskFindApp(TUid)
IMPORT_C TApaTaskFindByPos(TInt)
IMPORT_C TApaTaskFindDoc(const TDesC &)
IMPORT_C TApaTaskFindNonEmbeddedApp(TUid)

Detailed Description

Accesses tasks running on a device.

Tasks can be identified by document, application specific UID or by caption name.

Users of this class can also cycle through a set of tasks running a specific application, bringing each one, in turn, into the foreground.

See also: TApaTask

Member Enumeration Documentation

Enum TCycleDirection

Defines the direction in which tasks are cycled to the foreground. This is used by the CycleTasks() function.

See also: TApaTaskList::CycleTasks()

EnumeratorValueDescription
EForwards

Cycles the task list forwards, i.e. the foreground task is moved to background, bringing the next foremost task to the foreground.

EBackwards

Cycles the list backwards, i.e. the task furthest from the foreground is brought to the foreground, pushing what was the foremost task to the next ordinal position.

Constructor & Destructor Documentation

TApaTaskList ( RWsSession & )

IMPORT_CTApaTaskList(RWsSession &aWsSession)

Constructs the task list object, taking a reference to a window server session.

Parameters
aWsSessionThe window server session.

Member Function Documentation

CycleTasks ( TUid, TCycleDirection )

IMPORT_C TIntCycleTasks(TUidaAppUid,
TCycleDirectionaDirection = EForwards
)

Brings the next task in the set of tasks running the specified application to the foreground.

If there is only one task, then no change occurs.

If the foremost task in the set is not the foreground task, then this is made the foreground task.

Thereafter, successive calls to this function bring the next task in the set to the foreground. The direction of the cycling can be specified and has the following effect:

for the forwards direction, the foreground task is sent to the background; the next foremost task is made the foreground task.

for the backwards direction, the task with the highest window group ordinal value, i.e. the task in the set which is furthest from the foreground, is brought to the foreground. The task that was the foremost task in the set is moved back by one position.

If the task brought to the foreground uses the View architecture, then the its top view is activated.

Parameters
aAppUidThe application specific UID.
aDirectionThe direction of cycling.
Return Value
KErrNone, if successful; KErrNotFound, if there are no tasks running the specified application.

FindApp ( const TDesC & )

IMPORT_C TApaTaskFindApp(const TDesC &aAppName)

Searches for a task that has the specified caption.

The result of the search depends on the number of tasks that have the specified caption.

If there is only one task, then that task is returned.

If there is more than one task, then the task returned depends on whether the first one found is in the foreground:

if the first task found is in the foreground, then the task returned by this function is the one with the highest window group ordinal value, i.e. the task which is furthest from the foreground.

if the first task found is not in the foreground, then that is the task that is returned.

If no matching task is found, then the object returned is an empty task, and calling TApaTask::Exists() on it returns false.

Parameters
aAppNameThe caption.
Return Value
A task having the specified caption, or an empty task.

FindApp ( TUid )

IMPORT_C TApaTaskFindApp(TUidaAppUid)

Searches for a task running the specified application.

The result of the search depends on the number of tasks that are running the specified application.

If there is only one task, then that task is returned.

If there is more than one task, then the task returned depends on whether the first one found is in the foreground:

if the first task found is in the foreground, then the task returned by this function is the one with the highest window group ordinal value, i.e. the task which is furthest from the foreground.

if the first task found is not in the foreground, then that is the task that is returned.

If no matching task is found, then the object returned is an empty task, and calling TApaTask::Exists() on it returns false.

Parameters
aAppUidThe application specific UID.
Return Value
A task having the specified caption, or an empty task.

FindByPos ( TInt )

IMPORT_C TApaTaskFindByPos(TIntaPos)

Searches for a task by the ordinal position of its window group.

Parameters
aPosThe ordinal position of a task's window group. A zero value refers to the foreground task.
Return Value
The task at the specified position. If there is no task at the specified position, or the specified position is invalid, then the object returned is an empty task, and calling TApaTask::Exists() on it returns false.

FindDoc ( const TDesC & )

IMPORT_C TApaTaskFindDoc(const TDesC &aDocName)

Searches for the task that is handling the specified document.

Parameters
aDocNameThe name of the document.
Return Value
The task that is handling the specified document. If no such task exists, then this is an empty task, i.e. a subsequent call to TApaTask::Exists() returns false.

FindNonEmbeddedApp ( TUid )

IMPORT_C TApaTaskFindNonEmbeddedApp(TUidaAppUid)

Searches for a non-embedded task running the specified application.

The result of the search depends on the number of tasks that are running the specified application. The search only considers non-embedded applications. It will ignore if any application running as embedded.

If there is only one non-embedded task, then that task is returned.

If there is more than one non-embedded task, then the task returned depends on whether the first one found is in the foreground:

if the first task found is in the foreground, then the task returned by this function is the one with the highest window group ordinal value, i.e. the task which is furthest from the foreground.

if the first task found is not in the foreground, then that is the task that is returned.

If no matching task is found, then the object returned is an empty task, and calling TApaTask::Exists() on it returns false.

Parameters
aAppUidThe application specific UID.
Return Value
A task having the specified caption, or an empty task.