Class CApaWindowGroupName

CApaWindowGroupName

Support

Supported from 5.0

Description

Gives access to the name of a window group and the information encoded by that name.

A window group is associated with a task, i.e. a running application. The window group's name encodes four pieces of information for that task:

• The name of the document that the task is handling

• The task's caption

• The application specific UID, as eight hexadecimal characters

• Status information for the task, as two hexadecimal characters

Derivation

CApaWindowGroupName Gives access to the name of a window group and the information encoded by that name CBase Base class for all classes to be instantiated on the heap

Defined in CApaWindowGroupName:
AppUid(), Caption(), ConstructFromWgIdL(), DocName(), DocNameIsAFile(), FindByAppUid(), FindByCaption(), FindByDocName(), Hidden(), IsBusy(), IsSystem(), New(), NewL(), NewLC(), RespondsToShutdownEvent(), RespondsToSwitchFilesEvent(), SetAppUid(), SetBusy(), SetCaptionL(), SetDocNameIsAFile(), SetDocNameL(), SetHidden(), SetRespondsToShutdownEvent(), SetRespondsToSwitchFilesEvent(), SetSystem(), SetWindowGroupName(), SetWindowGroupNameL(), WindowGroupName(), ~CApaWindowGroupName()

Inherited from CBase:
operator new()

static CApaWindowGroupName* NewL(const RWsSession& aWsSession);

Description

Creates a window group name object and assigns a default name to it.

Parameters

const RWsSession& aWsSession A window server session.

Return value

CApaWindowGroupName* A pointer to the new window group name object.

static CApaWindowGroupName* NewLC(const RWsSession& aWsSession);

Description

Creates a window group name object, assigns a default name to it, and puts a pointer to the new object onto the cleanup stack.

Parameters

const RWsSession& aWsSession A window server session.

Return value

CApaWindowGroupName* A pointer to the new window group name object.

static CApaWindowGroupName* NewL(const RWsSession& aWsSession, TInt aWgId);

Description

Creates a window group name object and assigns to it the name taken from the specified window group.

Parameters

const RWsSession& aWsSession A window server session. TInt aWgId The ID of a window group.

Return value

CApaWindowGroupName* A pointer to the new window group name object.

static CApaWindowGroupName* NewLC(const RWsSession& aWsSession, TInt aWgId);

Description

Creates a window group name object, assigns to it the name taken from the specified window group, and puts a pointer to the new object onto the cleanup stack.

Parameters

const RWsSession& aWsSession A window server session. TInt aWgId The ID of a window group.

Return value

CApaWindowGroupName* A pointer to the new window group name object.

static CApaWindowGroupName* NewL(const RWsSession& aWsSession, const TDesC& aWgName);

Description

Creates a window group name object and assigns to it the specified name.

The name must have valid format. Typically, this is an existing window group name.

Parameters

const RWsSession& aWsSession A window server session. const TDesC& aWgName A valid window group name.

Return value

CApaWindowGroupName* A pointer to the new window group name object.

static CApaWindowGroupName* NewLC(const RWsSession& aWsSession, const TDesC& aWgName);

Description

Creates a window group name object, assigns to it the specified name, and puts a pointer to the new object onto the cleanup stack.

The name must have valid format. Typically, this is an existing window group name.

Parameters

const RWsSession& aWsSession A window server session. const TDesC& aWgName A valid window group name.

Return value

CApaWindowGroupName* A pointer to the new window group name object.

static CApaWindowGroupName* New(const RWsSession& aWsSession, HBufC* aWgName);

Description

Creates a window group name object and takes ownership of the heap descriptor containing a name.

The name must have valid format. Typically, this is an existing window group name.

Note that the function cannot leave.

Parameters

const RWsSession& aWsSession A window server session. HBufC* aWgName A heap descriptor containing a valid window group name. This pointer must not be null, otherwise the function raises an APGRFX 3 panic.

Return value

CApaWindowGroupName* A pointer to the new window group name object.

void ConstructFromWgIdL(TInt aWgId);

Description

Assigns to this object the name taken from the specified window group.

Any previously existing name contained by this window group name object is lost.

If the specified window group does not exist or it has no name, then a default name is assigned.

Parameters

TInt aWgId The ID of a window group.

~CApaWindowGroupName();

Description

Destructor.

Frees resources owned by the object prior to its destruction.

TUid AppUid() const;

Description

Gets the UID of the task's application.

Return value

TUid The application specific UID. If the format of the window group name is not recognized, then this is zero.

TPtrC Caption() const;

Description

Gets the task's caption.

Return value

TPtrC A non-modifiable pointer descriptor representing the caption. If the format of the window group name is not recognized, then this is a zero length descriptor.

TPtrC DocName() const;

Description

Gets the name of the document that the task is handling.

Return value

TPtrC A non-modifiable pointer descriptor representing the document name. If the format of the window group name is not recognized, then this is a zero length descriptor.

TBool IsBusy() const;

Description

Tests whether the task is marked as busy.

Return value

TBool True, if the task is marked as busy; false, otherwise.

See also:

• CEikonEnv::IsBusy()

TBool IsSystem() const;

Description

Tests whether the task is marked as a system task.

Return value

TBool True, if the task is marked as a system task; false, otherwise.

See also:

• CEikonEnv::IsSystem()

TBool DocNameIsAFile() const;

Description

Tests whether the document name is a file.

Return value

TBool True, if the document name is a file; false, otherwise.

See also:

• CEikonEnv::DocNameIsAFile()

TPtrC WindowGroupName() const;

Description

Gets the full window group name.

Return value

TPtrC A non-modifiable pointer descriptor representing the full window group name.

TBool RespondsToShutdownEvent() const;

Description

Tests whether the task can deal with a request to shutdown.

Return value

TBool True, if the task can deal with a request to shutdown; false, otherwise.

See also:

• CEikonEnv::RespondsToShutdownEvent()

TBool RespondsToSwitchFilesEvent() const;

Description

Tests whether the task can deal with a request to switch files.

Return value

TBool True, if the task can deal with a request to switch files; false otherwise.

See also:

• CEikonEnv::RespondsToSwitchFilesEvent()

TBool Hidden();

Support

Supported from 6.0

Description

Tests whether the task is marked as hidden.

Return value

TBool True, if the task is hidden; false, otherwise.

static void FindByDocName(const TDesC& aDocName, RWsSession& aWsSession, TInt& aPrevWgId);

Description

Searches for the next window group by document name.

A running application, also known as a task, is associated with a window group. The function searches for the next task handling the specified document, and returns its associated window group ID.

Parameters

const TDesC& aDocName The name of the document. RWsSession& aWsSession A window server session. TInt& aPrevWgId On entry, the previous window group ID. On return, the next window group ID. On first call to this function pass a zero value. When there are no more matching window groups, contains KErrNotFound.

static void FindByCaption(const TDesC& aCaption, RWsSession& aWsSession, TInt& aPrevWgId);

Description

Searches for the next window group by caption.

A running application, also known as a task, is associated with a window group. The function searches for the next task having the specified caption, and returns its associated window group ID.

Parameters

const TDesC& aCaption The caption. RWsSession& aWsSession A window server session. TInt& aPrevWgId On entry, the previous window group ID. On return, the next window group ID. On first call to this function pass a zero value. When there are no more matching window groups, contains KErrNotFound.

static void FindByAppUid(TUid aAppUid, RWsSession& aWsSession, TInt& aPrevWgId);

Description

Searches for the next window group by application UID.

A running application, also known as a task, is associated with a window group. The function searches for the next task running the specified application, and returns its associated window group ID.

Parameters

TUid aAppUid The application specific UID. RWsSession& aWsSession A window server session. TInt& aPrevWgId On entry, the previous window group ID. On return, the next window group ID. On first call to this function pass a zero value. When there are no more matching window groups, contains KErrNotFound.

void SetAppUid(TUid aAppUid);

Description

Sets the specified UID into the window group name in this object.

Parameters

TUid aAppUid The application specific UID.

void SetCaptionL(const TDesC& aCaption);

Description

Sets the specified caption into the window group name in this object.

Parameters

const TDesC& aCaption The caption.

void SetDocNameL(const TDesC& aDocName);

Description

Sets the specified document name into the window group name in this object.

Parameters

const TDesC& aDocName The document name.

void SetBusy(TBool aBusy);

Description

Sets the task's busy status in this object.

Parameters

TBool aBusy ETrue, marks the task as busy; EFalse, marks the task as not busy.

See also:

• CEikonEnv::SetBusy()

void SetSystem(TBool aSystem);

Description

Sets the task's system status in this object.

Parameters

TBool aSystem ETrue, marks the task as a system task; EFalse, marks the task as not a system task.

See also:

• CEikonEnv::SetSystem()

void SetDocNameIsAFile(TBool aDocNameIsAFile);

Description

Sets the document name status in this object.

Parameters

TBool aDocNameIsAFile ETrue, the document name is a filename; EFalse, the document name is not a filename.

See also:

• CEikonEnv::SetDocNameIsAFile()

void SetWindowGroupNameL(const TDesC& aWgName);

Description

Sets the full window group name in this object.

Parameters

const TDesC& aWgName The full window group name.

void SetWindowGroupName(HBufC* aWgName);

Description

Sets the full window group name in this object, taking ownership of the specified heap descriptor.

The function cannot leave.

Parameters

HBufC* aWgName A heap descriptor containing the full window group name. The pointer must not be null, otherwise the function raises a APGRFX 3 panic.

TInt SetWindowGroupName(RWindowGroup& aGroupWin) const;

Description

Sets the window group name contained by this object into the specified window group.

Parameters

RWindowGroup& aGroupWin The window group.

Return value

TInt KErrNone, if successful; otherwise, one of the other system-wide error codes.

void SetRespondsToShutdownEvent(TBool aRespondsToShutdownEvent);

Description

Sets the task's shutdown handling status in this object.

Parameters

TBool aRespondsToShutdownEvent ETrue, if the task can deal with a shutdown request; EFalse, if the task cannot deal with a shutdown request.

See also:

• CEikonEnv::SetRespondsToShutdownEvent()

void SetRespondsToSwitchFilesEvent(TBool aRespondsToSwitchFilesEvent);

Description

Sets the task's switch file handling status in this object.

Parameters

TBool aRespondsToSwitchFilesEvent ETrue, if the task can deal with a request to switch file; EFalse, if the task cannot deal with with a request to switch files.

See also:

• CEikonEnv::SetRespondsToSwitchFilesEvent()

void SetHidden(TBool aIsHidden);

Support

Supported from 6.0

Description

Marks the task as hidden.

Parameters

TBool ETrue, if the task is to be marked as hidden; EFalse, otherwise.

Notes:

• In general, tasks marked as hidden do not appear in tasklists. Specifically, TApaTask::FindByPos() will ignore any tasks marked as hidden.

See also:

• TApaTaskList::FindByPos()