Collapse all Symbian^3 Application Developer Library

CApaWindowGroupName Class Reference

class CApaWindowGroupName : public CBase

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.

Inherits from

CApaWindowGroupName
- CBase

Public Member Functions
	~CApaWindowGroupName ()
IMPORT_C TUid	AppUid ()
IMPORT_C TPtrC	Caption ()
IMPORT_C void	ConstructFromWgIdL ( TInt )
IMPORT_C TPtrC	DocName ()
IMPORT_C TBool	DocNameIsAFile ()
IMPORT_C void	FindByAppUid ( TUid , RWsSession &, TInt &)
IMPORT_C void	FindByCaption (const TDesC &, RWsSession &, TInt &)
IMPORT_C void	FindByDocName (const TDesC &, RWsSession &, TInt &)
IMPORT_C TBool	Hidden ()
IMPORT_C TBool	IsAppReady ()
IMPORT_C TBool	IsBusy ()
IMPORT_C TBool	IsSystem ()
IMPORT_C CApaWindowGroupName *	New (const RWsSession &, HBufC *)
IMPORT_C CApaWindowGroupName *	NewL (const RWsSession &)
IMPORT_C CApaWindowGroupName *	NewL (const RWsSession &, TInt )
IMPORT_C CApaWindowGroupName *	NewL (const RWsSession &, const TDesC &)
IMPORT_C CApaWindowGroupName *	NewLC (const RWsSession &)
IMPORT_C CApaWindowGroupName *	NewLC (const RWsSession &, TInt )
IMPORT_C CApaWindowGroupName *	NewLC (const RWsSession &, const TDesC &)
IMPORT_C TBool	RespondsToShutdownEvent ()
IMPORT_C TBool	RespondsToSwitchFilesEvent ()
IMPORT_C void	SetAppReady ( TBool )
IMPORT_C void	SetAppUid ( TUid )
IMPORT_C void	SetBusy ( TBool )
IMPORT_C void	SetCaptionL (const TDesC &)
IMPORT_C void	SetDocNameIsAFile ( TBool )
IMPORT_C void	SetDocNameL (const TDesC &)
IMPORT_C void	SetHidden ( TBool )
IMPORT_C void	SetRespondsToShutdownEvent ( TBool )
IMPORT_C void	SetRespondsToSwitchFilesEvent ( TBool )
IMPORT_C void	SetSystem ( TBool )
IMPORT_C void	SetWindowGroupName ( HBufC *)
IMPORT_C TInt	SetWindowGroupName ( RWindowGroup &)
IMPORT_C void	SetWindowGroupNameL (const TDesC &)
IMPORT_C TPtrC	WindowGroupName ()

Private Member Functions
	CApaWindowGroupName (const RWsSession &)
void	DefaultConstructL ()
TInt	FindDelimiter ( TApaDelimiter )
void	GetStatusFromName ()
void	ReAllocIfNecessaryL ( TInt )
void	WriteStatusToName ()

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

Private Member Enumerations
enum	TApaDelimiter { EEndStatus = 1, EEndUid , EEndCaption , ELast = EEndCaption }
enum	TApaStatus { ESystem = 0x01, EBusy = 0x02, EDocNameNotAFile = 0x04, EDoesNotRespondToShutdownEvent = 0x08, EDoesNotRespondToSwitchFilesEvent = 0x10, EIsHidden = 0x20, EAppReady = 0x40 }

Private Attributes
HBufC *	iBuf
TUint	iStatus
const RWsSession &	iWsSession

Constructor & Destructor Documentation

CApaWindowGroupName(const RWsSession &)

CApaWindowGroupName

(

const RWsSession &

aWsSession

)

[private]

Parameters

const RWsSession & aWsSession

~CApaWindowGroupName()

IMPORT_C

~CApaWindowGroupName

(

)

Destructor.

Frees resources owned by the object prior to its destruction.

Member Functions Documentation

AppUid()

IMPORT_C TUid

AppUid

(

)

const

Gets the UID of the task's application.

Caption()

IMPORT_C TPtrC

Caption

(

)

const

Gets the task's caption.

ConstructFromWgIdL(TInt)

IMPORT_C void

ConstructFromWgIdL

(

TInt

aWgId

)

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.

DefaultConstructL()

void

DefaultConstructL

(

)

[private]

DocName()

IMPORT_C TPtrC

DocName

(

)

const

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

DocNameIsAFile()

IMPORT_C TBool

DocNameIsAFile

(

)

const

Tests whether the document name is a file.

CEikonEnv::DocNameIsAFile()

FindByAppUid(TUid, RWsSession &, TInt &)

IMPORT_C void	FindByAppUid	(	TUid	aAppUid,
			RWsSession &	aWsSession,
			TInt &	aPrevWgId
		)	[static]

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(const TDesC &, RWsSession &, TInt &)

IMPORT_C void	FindByCaption	(	const TDesC &	aCaption,
			RWsSession &	aWsSession,
			TInt &	aPrevWgId
		)	[static]

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(const TDesC &, RWsSession &, TInt &)

IMPORT_C void	FindByDocName	(	const TDesC &	aDocName,
			RWsSession &	aWsSession,
			TInt &	aPrevWgId
		)	[static]

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.

FindDelimiter(TApaDelimiter)

TInt

FindDelimiter

(

TApaDelimiter

aDelim

)

const [private]

Parameters

TApaDelimiter aDelim

GetStatusFromName()

void

GetStatusFromName

(

)

[private]

Hidden()

IMPORT_C TBool

Hidden

(

)

const

Tests whether the task is marked as hidden.

IsAppReady()

IMPORT_C TBool

IsAppReady

(

)

const

Tests whether the task is marked as ready.

IsBusy()

IMPORT_C TBool

IsBusy

(

)

const

Tests whether the task is marked as busy.

CEikonEnv::IsBusy()

IsSystem()

IMPORT_C TBool

IsSystem

(

)

const

Tests whether the task is marked as a system task.

CEikonEnv::IsSystem()

New(const RWsSession &, HBufC *)

IMPORT_C CApaWindowGroupName *	New	(	const RWsSession &	aWsSession,
			HBufC *	aWgName
		)	[static]

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.

NewL(const RWsSession &)

IMPORT_C CApaWindowGroupName *

NewL

(

const RWsSession &

aWsSession

)

[static]

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

Parameters

const RWsSession & aWsSession

A window server session.

NewL(const RWsSession &, TInt)

IMPORT_C CApaWindowGroupName *	NewL	(	const RWsSession &	aWsSession,
			TInt	aWgId
		)	[static]

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.

NewL(const RWsSession &, const TDesC &)

IMPORT_C CApaWindowGroupName *	NewL	(	const RWsSession &	aWsSession,
			const TDesC &	aWgName
		)	[static]

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.

NewLC(const RWsSession &)

IMPORT_C CApaWindowGroupName *

NewLC

(

const RWsSession &

aWsSession

)

[static]

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.

NewLC(const RWsSession &, TInt)

IMPORT_C CApaWindowGroupName *	NewLC	(	const RWsSession &	aWsSession,
			TInt	aWgId
		)	[static]

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.

NewLC(const RWsSession &, const TDesC &)

IMPORT_C CApaWindowGroupName *	NewLC	(	const RWsSession &	aWsSession,
			const TDesC &	aWgName
		)	[static]

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.

ReAllocIfNecessaryL(TInt)

void

ReAllocIfNecessaryL

(

TInt

aExtraLengthReqd

)

[private]

Parameters

TInt aExtraLengthReqd

RespondsToShutdownEvent()

IMPORT_C TBool

RespondsToShutdownEvent

(

)

const

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

CEikonEnv::RespondsToShutdownEvent()

RespondsToSwitchFilesEvent()

IMPORT_C TBool

RespondsToSwitchFilesEvent

(

)

const

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

CEikonEnv::RespondsToSwitchFilesEvent()

SetAppReady(TBool)

IMPORT_C void

SetAppReady

(

TBool

aIsReady

)

Sets the task as ready.

Parameters

TBool aIsReady

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

SetAppUid(TUid)

IMPORT_C void

SetAppUid

(

TUid

aAppUid

)

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

Parameters

TUid aAppUid

The application specific UID.

SetBusy(TBool)

IMPORT_C void

SetBusy

(

TBool

aBusy

)

Sets the task's busy status in this object.

CEikonEnv::SetBusy()

Parameters

TBool aBusy

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

SetCaptionL(const TDesC &)

IMPORT_C void

SetCaptionL

(

const TDesC &

aCaption

)

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

Parameters

const TDesC & aCaption

The caption.

SetDocNameIsAFile(TBool)

IMPORT_C void

SetDocNameIsAFile

(

TBool

aDocNameIsAFile

)

Sets the document name status in this object.

CEikonEnv::SetDocNameIsAFile()

Parameters

TBool aDocNameIsAFile

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

SetDocNameL(const TDesC &)

IMPORT_C void

SetDocNameL

(

const TDesC &

aDocName

)

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

Parameters

const TDesC & aDocName

The document name.

SetHidden(TBool)

IMPORT_C void

SetHidden

(

TBool

aIsHidden

)

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.

SetRespondsToShutdownEvent(TBool)

IMPORT_C void

SetRespondsToShutdownEvent

(

TBool

aRespondsToShutdownEvent

)

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

CEikonEnv::SetRespondsToShutdownEvent()

Parameters

TBool aRespondsToShutdownEvent

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

SetRespondsToSwitchFilesEvent(TBool)

IMPORT_C void

SetRespondsToSwitchFilesEvent

(

TBool

aRespondsToSwitchFilesEvent

)

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

CEikonEnv::SetRespondsToSwitchFilesEvent()

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.

SetSystem(TBool)

IMPORT_C void

SetSystem

(

TBool

aSystem

)

Sets the task's system status in this object.

CEikonEnv::SetSystem()

Parameters

TBool aSystem

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

SetWindowGroupName(HBufC *)

IMPORT_C void

SetWindowGroupName

(

HBufC *

aWgName

)

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.

SetWindowGroupName(RWindowGroup &)

IMPORT_C TInt

SetWindowGroupName

(

RWindowGroup &

aGroupWin

)

const

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

Parameters

RWindowGroup & aGroupWin

The window group.

SetWindowGroupNameL(const TDesC &)

IMPORT_C void

SetWindowGroupNameL

(

const TDesC &

aWgName

)

Sets the full window group name in this object.

Parameters

const TDesC & aWgName

The full window group name.

WindowGroupName()

IMPORT_C TPtrC

WindowGroupName

(

)

const

Gets the full window group name.

WriteStatusToName()

void

WriteStatusToName

(

)

[private]

Member Enumerations Documentation

Enum TApaDelimiter

Enumerators

EEndStatus = 1
EEndUid
EEndCaption
ELast = EEndCaption

Enum TApaStatus

Enumerators

ESystem = 0x01
EBusy = 0x02
EDocNameNotAFile = 0x04
EDoesNotRespondToShutdownEvent = 0x08
EDoesNotRespondToSwitchFilesEvent = 0x10
EIsHidden = 0x20
EAppReady = 0x40

Member Data Documentation

HBufC * iBuf

HBufC *

iBuf

[private]

TUint iStatus

TUint

iStatus

[private]

const RWsSession & iWsSession

const RWsSession &

iWsSession

[private]