Class CDirectScreenAccess

class CDirectScreenAccess : public CActive;

Description

An active object used to start direct screen access.

Direct screen access is a way of drawing to the screen without using the window server. As this avoids client-server communication, it is much faster, and may be useful for games and video. Note that some interaction with the window server is needed in order to prevent the application from drawing over other application's data.

The object's (private) CDirectScreenAccess::RunL() function is called by the window server in order to abort direct screen access. This might occur when another window needs to be displayed in front or when the window with direct screen access is moved. The active object's priority is RDirectScreenAccess::EPriorityVeryHigh so that direct screen access will be aborted as quickly as possible.

Derivation

• CBase - Base class for all classes to be instantiated on the heap.

• CActive - The core class of the active object abstraction.

• CDirectScreenAccess - An active object used to start direct screen access.

Members

Defined in CDirectScreenAccess:

• DoCancel()Implements cancellation of an outstanding request.
• DrawingRegion()Gets the clipping region to draw to.
• Gc()Gets the graphics context for drawing to the screen.
• NewL(RWsSession &,CWsScreenDevice &,RWindowBase &,MDirectScreenAccess &)Allocates and constructs the object and adds it to the current active scheduler.
• RunL()Handles an active object's request completion event.
• ScreenDevice()Gets the screen device to draw to.
• StartL()Informs the window server that you are going to start direct screen access and s...

Inherited from CActive:

• CActive(TInt)Constructs the active object with the specified priority.
• Cancel()Cancels the wait for completion of an outstanding request.
• Deque()Removes the active object from the active scheduler's list of active objects.
• EPriorityHighA priority higher than EPriorityUserInput.
• EPriorityIdleA low priority, useful for active objects representing background processing.
• EPriorityLowA priority higher than EPriorityIdle but lower than EPriorityStandard.
• EPriorityStandardMost active objects will have this priority.
• EPriorityUserInputA priority higher than EPriorityStandard; useful for active objects handling use...
• Extension_(TUint,TAny *&,TAny *)Extension function
• IsActive()constDetermines whether the active object has a request outstanding.
• IsAdded()constDetermines whether the active object has been added to the active scheduler's li...
• Priority()constGets the priority of the active object.
• RunError(TInt)Handles a leave occurring in the request completion event handler CActive::RunL(...
• SetActive()Indicates that the active object has issued a request and that it is now outstan...
• SetPriority(TInt)Sets the priority of the active object.
• TPriorityDefines standard priorities for active objects.
• iStatusThe request status associated with an asynchronous request.

Inherited from CBase:

• Delete(CBase *)Deletes the specified object.
• operator new(TUint)Allocates the object from the heap and then initialises its contents to binary z...
• operator new(TUint,TAny *)Initialises the object to binary zeroes.
• operator new(TUint,TLeave)Allocates the object from the heap and then initialises its contents to binary z...
• operator new(TUint,TLeave,TUint)Allocates the object from the heap and then initialises its contents to binary z...
• operator new(TUint,TUint)Allocates the object from the heap and then initialises its contents to binary z...

IMPORT_C static CDirectScreenAccess* NewL(RWsSession &aWs, CWsScreenDevice &aScreenDevice, RWindowBase &aWin, MDirectScreenAccess &aAbort);

Description

Allocates and constructs the object and adds it to the current active scheduler.

This function always causes a flush of the window server buffer.

Parameters

RWsSession &aWs A session with the window server. CWsScreenDevice &aScreenDevice Specifies the characteristics of the screen device to draw to. RWindowBase &aWin The window to draw to directly. MDirectScreenAccess &aAbort Defines an AbortNow() and a CDirectScreenAccess::Restart() function which are both called on aborting, as part of the CDirectScreenAccess::RunL(). CDirectScreenAccess::Restart() is called from an idle time active object (CIdle).

Return value

CDirectScreenAccess * The newly constructed object.

IMPORT_C void StartL();

Description

Informs the window server that you are going to start direct screen access and sets up a graphics context with which you can draw to the screen.

It should also be called to restart direct screen access after CActive::Cancel() has been called to stop it.

While the DSA is in operation, it is strongly advised that the client should not make any call to WSERV that will affect the visible area of the window in which the DSA is taking place.

When WSERV tells the client that it needs to abort its DSA, it waits to receive the acknowledgment from the client that it has done so. However, it doesn't wait for ever, since the client may have entered some long running calculation or even an infinite loop. So WSERV also waits on a timer: if the timer expires before the client acknowledges, then WSERV continues; if, later on, WSERV gets notification from the client that it has aborted the DSA, then WSERV will invalidate the region in which the DSA was taking place, just in case there had been a conflict between the DSA and another client.

This function always causes a flush of the window server buffer.

inline CFbsBitGc* Gc();

Description

Gets the graphics context for drawing to the screen.

This is set up by calling CDirectScreenAccess::StartL(). Its origin is set so that you should use window coordinates to specify which part of the screen to draw to and its clipping region is set to the visible part of the window.

Code built to run on the Emulator must call CFbsScreenDevice::Update() in order to see the results of drawing to this graphics context, but this may not be required on all target hardware.

Return value

CFbsBitGc * The graphics context for drawing to the screen.

inline CFbsScreenDevice *& ScreenDevice();

Description

Gets the screen device to draw to.

You should not use this screen device to create fonts because the object is deleted and recreated when direct screen access is aborted and restarted. Instead, create and use your own CFbsScreenDevice object to create fonts.

Return value

CFbsScreenDevice *& The target screen device.

inline RRegion* DrawingRegion();

Description

Gets the clipping region to draw to.

You must not draw outside of this region.

The clipping region is calculated when CDirectScreenAccess::StartL() is called, and is only updated if CDirectScreenAccess::StartL() is called again.

The region is specified in screen coordinates. This can be useful if you need to reapply the clipping region to the graphics context (CFbsBitGc::SetClippingRegion(const TRegion *)).

Return value

RRegion * The clipping region to draw to.

private: virtual void DoCancel();

Description

Implements cancellation of an outstanding request.

This function is called as part of the active object's CActive::Cancel().

It must call the appropriate cancel function offered by the active object's asynchronous service provider. The asynchronous service provider's cancel is expected to act immediately.

CDirectScreenAccess::DoCancel() must not wait for event completion; this is handled by CActive::Cancel().

See also:

• CActive::Cancel()Cancels the wait for completion of an outstanding request.

private: virtual void RunL();

Description

Handles an active object's request completion event.

A derived class must provide an implementation to handle the completed request. If appropriate, it may issue another request.

The function is called by the active scheduler when a request completion event occurs, i.e. after the active scheduler's WaitForAnyRequest() function completes.

Before calling this active object's CDirectScreenAccess::RunL() function, the active scheduler has:

1. decided that this is the highest priority active object with a completed request

2. marked this active object's request as complete (i.e. the request is no longer outstanding)

CDirectScreenAccess::RunL() runs under a trap harness in the active scheduler. If it leaves, then the active scheduler calls CActive::RunError(TInt) to handle the leave.

Note that once the active scheduler's Start() function has been called, all user code is run under one of the program's active object's CDirectScreenAccess::RunL() or CActive::RunError(TInt) functions.

See also:

• CActiveScheduler::Start()Starts a new wait loop under the control of the current active scheduler.
• CActiveScheduler::Error(TInt)constHandles the result of a leave occurring in an active object’s RunL() function.
• CActiveScheduler::WaitForAnyRequest()Wait for an asynchronous request to complete.