Symbian
Symbian OS Library

SYMBIAN OS V9.3

[Index] [Spacer] [Previous] [Next]



Location: APGWGNAM.H
Link against: apgrfx.lib

Class CApaWindowGroupName

class CApaWindowGroupName : public CBase;

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

Members

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

Inherited from CBase:
Delete(), Extension_(), operator new()


Construction and destruction


~CApaWindowGroupName()

IMPORT_C ~CApaWindowGroupName();

Description

Destructor.

Frees resources owned by the object prior to its destruction.


NewL()

static IMPORT_C 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.


NewLC()

static IMPORT_C 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.


NewL()

static IMPORT_C 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.


NewLC()

static IMPORT_C 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.


NewL()

static IMPORT_C 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 a 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.


NewLC()

static IMPORT_C 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.

[Top]


Member functions


New()

static IMPORT_C 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.


ConstructFromWgIdL()

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


SetWindowGroupNameL()

IMPORT_C void SetWindowGroupNameL(const TDesC &aWgName);

Description

Sets the full window group name in this object.

Parameters

const TDesC &aWgName

The full window group name.


SetWindowGroupName()

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


FindByAppUid()

static IMPORT_C 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.


FindByCaption()

static IMPORT_C 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.


FindByDocName()

static IMPORT_C 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.


SetBusy()

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


IsBusy()

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


SetSystem()

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


IsSystem()

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


SetDocNameIsAFile()

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


DocNameIsAFile()

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


SetRespondsToShutdownEvent()

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


RespondsToShutdownEvent()

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


SetRespondsToSwitchFilesEvent()

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


RespondsToSwitchFilesEvent()

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


SetHidden()

IMPORT_C void SetHidden(TBool aIsHidden);

Description

Marks the task as hidden.

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

Parameters

TBool aIsHidden

ETrue if the task is to be marked as hidden; EFalse if not.


Hidden()

IMPORT_C TBool Hidden() const;

Description

Tests whether the task is marked as hidden.

Return value

TBool

True if the task is hidden; false otherwise.


SetAppReady()

IMPORT_C void SetAppReady(TBool aIsReady);

Description

Sets the task as ready.

Parameters

TBool aIsReady

ETrue if the task is to be marked as ready; EFalse if not.


IsAppReady()

IMPORT_C TBool IsAppReady() const;

Description

Tests whether the task is marked as ready.

Return value

TBool

True if the task is ready; false otherwise.


SetAppUid()

IMPORT_C void SetAppUid(TUid aAppUid);

Description

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

Parameters

TUid aAppUid

The application specific UID.


AppUid()

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


SetCaptionL()

IMPORT_C void SetCaptionL(const TDesC &aCaption);

Description

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

Parameters

const TDesC &aCaption

The caption.


Caption()

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


SetDocNameL()

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


DocName()

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


SetWindowGroupName()

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


WindowGroupName()

IMPORT_C TPtrC WindowGroupName() const;

Description

Gets the full window group name.

Return value

TPtrC

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

[Top]


Member enumerations


Enum anonymous

n/a

Description

EMaxLength