Class CWsScreenDevice

CWsScreenDevice

Support

Supported from 5.0

Description

Software device screen.

An object of this class can be used to inquire or set parameters of the software screen, and determine the physical limits of the device.

Derivation

CBase Base class for all classes to be instantiated on the heap CBitmapDevice Defines an interface for the capabilities and attributes of a bitmapped graphics device CGraphicsDevice Specifies the interface for concrete device classes CWsScreenDevice Software device screen MGraphicsDeviceMap Interface class for mapping between twips and device-specific units (pixels) MWsClientClass Base class for all classes whose objects are clients of the window server engine

Defined in CWsScreenDevice:
AddFile(), CWsScreenDevice(), Construct(), CopyScreenToBitmap(), CreateContext(), DisplayMode(), FontHeightInPixels(), FontHeightInTwips(), GetDefaultScreenSizeAndRotation(), GetFontById(), GetNearestFontInPixels(), GetNearestFontInTwips(), GetPalette(), GetPixel(), GetRotationsList(), GetScanLine(), GetScreenModeSizeAndRotation(), HorizontalPixelsToTwips(), HorizontalTwipsToPixels(), NumScreenModes(), NumTypefaces(), PaletteAttributes(), PointerRect(), RectCompare(), ReleaseFont(), RemoveFile(), ScreenModeEnforcement(), SetCurrentRotations(), SetCustomPalette(), SetPalette(), SetScreenMode(), SetScreenModeEnforcement(), SetScreenSizeAndRotation(), SizeInPixels(), SizeInTwips(), TypefaceSupport(), VerticalPixelsToTwips(), VerticalTwipsToPixels(), ~CWsScreenDevice()

Inherited from CBase:
operator new()

Inherited from CBitmapDevice:
CreateBitmapContext()

Inherited from MGraphicsDeviceMap:
PixelsToTwips(), TwipsToPixels()

Inherited from MWsClientClass:
WsHandle()

See also:

• CFbsScreenDevice

CWsScreenDevice();

Description

Default constructor. Developers should use the other constructor overload.

CWsScreenDevice(RWsSession &aWs);

Description

Constructs a new screen device attached to a particular window server session.

Parameters

RWsSession &aWs The window server session this screen should be attached to.

TInt Construct();

Description

Completes construction of the object.

Return value

TInt KErrorNone if successful, otherwise another of the system-wide error codes.

~CWsScreenDevice();

Description

Destructor.

TInt AddFile(const TDesC& aName,TInt& aId);

Description

Adds a font file to the device's font store.

Parameters

const TDesC& aName Name of the font file. TInt& aId ID for the font file.

Return value

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

See also:

• CBitmapDevice::AddFile()

TInt CopyScreenToBitmap(const CFbsBitmap *aBitmap) const;

Description

Saves the entire screen to a bitmap.

Parameters

const CFbsBitmap* aBitmap Bitmap to be filled with the screen image.

Return value

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

TInt CopyScreenToBitmap(const CFbsBitmap *aBitmap, const TRect &aRect) const;

Description

Saves a region of the screen to a bitmap.

Parameters

const CFbsBitmap* aBitmap Bitmap will be filled with the screen region image. const TRect &aRect Screen region to be saved.

Return value

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

TInt CreateContext(CGraphicsContext*& aGc);

Description

Creates a graphics context for this device.

Parameters

CGraphicsContext*& aGc On successful return, contains a new graphics context referring to this screen device.

Return value

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

See also:

• CGraphicsDevice::CreateContext()

TInt CreateContext(CWindowGc*& aGc);

Description

Creates a window graphics context for this device.

Parameters

CWindowGc*& aGc On successful return, contains a new graphics context referring to this screen device.

Return value

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

See also:

• CGraphicsDevice::CreateContext()

TDisplayMode DisplayMode() const;

Description

Gets the device display mode.

Return value

TDisplayMode The device's display mode.

See also:

• CGraphicsDevice::DisplayMode()

TInt FontHeightInPixels(TInt aTypefaceIndex,TInt aHeightIndex) const;

Description

Gets the height of the specified font in pixels.

The value returned is rounded up or down to the nearest font height in pixels.

The specified font is the one with height index number aHeightIndex of the typeface with index number aTypefaceIndex.

Parameters

TInt aTypefaceIndex A typeface index number, in the range: 0 to (NumTypefaces() - 1). TInt aHeightIndex A font height index number, in the range: 0 to (iNumHeights - 1).

Return value

TInt The height of the font, in pixels.

See also:

• CBitmapDevice::FontHeightInPixels()

TInt FontHeightInTwips(TInt aTypefaceIndex,TInt aHeightIndex) const;

Description

Gets the height in twips of the specified font.

The value returned is rounded up or down to the nearest font height in twips.

The specified font is the one with height index number aHeightIndex of the typeface with index number aTypefaceIndex.

Parameters

TInt aTypefaceIndex A typeface index number, in the range: 0 to (NumTypefaces() - 1). TInt aHeightIndex A font height index number, in the range: 0 to (iNumHeights - 1).

Return value

TInt The height of the font, in twips.

See also:

• CGraphicsDevice::FontHeightInTwips()

void GetDefaultScreenSizeAndRotation(TPixelsTwipsAndRotation& aSizeAndRotation) const;

Description

Gets the current screen size and rotation — screen size is specified in both pixels and twips.

Parameters

TPixelsTwipsAndRotation& aSizeAndRotation The default screen size and rotation, defining screen size in both pixels and twips.

void GetDefaultScreenSizeAndRotation(TPixelsAndRotation &aSizeAndRotation) const;

Description

Gets the current screen size and rotation — screen size is specified in pixels.

Parameters

TPixelsAndRotation &aSizeAndRotation The default screen size and rotation, defining screen size in pixels.

TInt GetFontById(CFont*& aFont, TUid aUid, const TAlgStyle& aAlgStyle);

Description

Gets a font by its UID.

Within a font file each font has its own UID. An algorithmic style is not part of the actual font description, but is applied to it. For example algorithmic bolding applies an algorithm to increase the apparent weight of each character in the font. Note that the algorithm is applied blindly, and that a typeface may already have a style e.g. it may already be bold or italic. Thus a bold face will appear extra-bold if algorithmic bolding is applied to it. Algorithmic effects are not necessarily a substitute for typeface design and should be used with care.

Parameters

CFont*& aFont On a successful return, contains a pointer to the new CFont. TUid aUid UID of the font. const TAlgStyle& aAlgStyle The algorithmic style to apply.

Return value

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

TInt GetNearestFontInPixels(CFont*& aFont,const TFontSpec& aFontSpec);

Description

Gets the nearest font to that specified for use by a bitmapped graphics device.

The font and bitmap server returns a pointer to the nearest matching font from those available, in aFont.

Parameters

CFont*& aFont On return, the pointer is set to point to the device font which most closely approximates to the font specification passed in the second argument const TFontSpec& aFontSpec An absolute font specification

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

See also:

• CBitmapDevice::GetNearestFontInPixels()

TInt GetNearestFontInTwips(CFont*& aFont,const TFontSpec& aFontSpec);

Description

Gets the nearest font, in twips, to that in the specified font specification.

The font and bitmap server returns a pointer to the nearest matching font from those available, in aFont.

Parameters

CFont*& aFont On return, the pointer is set to point to the device font which most closely approximates to the font specification passed in the second argument. const TFontSpec& aFontSpec An absolute font specification.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

See also:

• MGraphicsDeviceMap::GetNearestFontInTwips()

TInt GetPalette(CPalette*& aPalette) const;

Support

Supported from 6.1

Description

Gets the screen device's palette.

Parameters

CPalette*& aPalette On return, contains the screen device's palette otherwise NULL. The caller takes on the responsibility for discarding the palette.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

See also:

• CFbsScreenDevice::GetPalette()

void SetPalette(CPalette* aPalette);

Support

Supported from 6.1

Description

Sets the screen device's palette. Use of this class is deprecated.

Parameters

CPalette* aPalette The new screen device's palette.

void PaletteAttributes(TBool& aModifiable,TInt& aNumEntries) const;

Support

Supported from 6.1

Description

Gets the palette attributes of the device.

Parameters

TBool& aModifiable On return, holds information on whether or not the device’s palette is modifiable (true) or fixed (false). TInt& aNumEntries On return, holds the number of entries in the device’s palette.

See also:

• CFbsScreenDevice::PaletteAttributes()

TInt SetCustomPalette(const CPalette* aPalette);

Support

Supported from 6.1

Description

Sets the custom palette.

Parameters

const CPalette* aPalette The custom palette.

Return value

TInt The custom palette. Provides an error code if it fails.

void GetPixel(TRgb& aColor,const TPoint& aPixel) const;

Description

Gets the RGB colour of an individual pixel on a screen device.

Parameters

TRgb& aColor On return, contains the RGB colour of the pixel. const TPoint& aPixel The (x,y) co-ordinates of the pixel. NB. The top left pixel is (0,0).

See also:

• CBitmapDevice::GetPixel()

TInt GetRotationsList(TInt aMode, CArrayFixFlat<TInt> *aRotationList) const;

Support

Supported from 5.1

Description

Gets the list of valid rotations for a particular screen size.

The list of valid rotations for the screen size is set in WSINI.INI.

Parameters

TInt aMode The index of the screen size for which the valid rotation list is required. CArrayFixFlat<TInt> *aRotationList The list of valid screen orientations.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

See also:

• SetCurrentRotations()

void GetScanLine(TDes8 &aBuf,const TPoint &aPixel,TInt aLength, TDisplayMode aDispMode) const;

Description

Get a scanline into a buffer.

The pixels are converted from the bitmapped graphics device display mode format to the format of the specified device display mode.

By specifying the start pixel and number of pixels either the whole or a portion of a bitmapped graphics device pixel row may be copied.

Parameters

TDes8 &aBuf A buffer into which pixels are copied, it must be sufficiently large to store all the scanline pixels. const TPoint& aPixel The (x,y) co-ordinates of the first pixel of the bitmap scanline to be put into the buffer. TInt aLength The number of pixels to put into the buffer. TDisplayMode aDispMode The display mode into which to convert the pixels.

See also:

• CBitmapDevice::GetScanLine()

void GetScreenModeSizeAndRotation(TInt aMode, TPixelsTwipsAndRotation &aSizeAndRotation) const;

Description

Get the screen rotation and size, in both pixels and twips, for the specified screen mode.

Parameters

TInt aMode The index of screen mode for which the screen size the rotation are required. TPixelsTwipsAndRotation &aSizeAndRotation The orientation of the specified screen mode, and its size in both pixels and twips.

void GetScreenModeSizeAndRotation(TInt aMode, TPixelsAndRotation &aSizeAndRotation) const;

Description

Get the screen rotation and size, in pixels, for the specified screen mode.

Parameters

TInt aMode The index of screen mode for which the screen size the rotation are required. TPixelsAndRotation &aSizeAndRotation The orientation of the specified screen mode, and its size in pixels.

TInt HorizontalPixelsToTwips(TInt aPixels) const;

Description

Translates a specified pixel value to a twips value.

Parameters

TInt aPixels The value in pixels to be translated.

Return value

TInt The equivalent number of twips.

TInt HorizontalTwipsToPixels(TInt aTwips) const;

Description

Translates a specified twips value to a pixel value.

Parameters

TInt aTwips The value in twips to be translated.

Return value

TInt The equivalent number of pixels.

See also:

• MGraphicsDeviceMap::HorizontalTwipsToPixels()

TInt NumScreenModes() const;

Description

Gets the number of available screen size modes.

Each mode has a different size, and one or more possible rotations/orientations.

Return value

TInt The number of screen modes.

TInt NumTypefaces() const;

Description

Gets the number of typefaces supported by the screen device.

Return value

TInt The number of typefaces supported.

See also:

• CGraphicsDevice::NumTypefaces()

TRect PointerRect() const;

Description

Gets the active area for the pointing device.

This is a device-dependent parameter, and will typically depend on the screen size and other possible factors.

Return value

TRect The active area, measured in pixels.

TBool RectCompare(const TRect& aRect1, const TRect& aRect2);

Description

Compares two areas of the screen to see if they have the same content.

Parameters

const TRect &aRect1 A rectangle. const TRect &aRect2 Another rectangle.

Return value

TBool ETrue if the two screen areas are identical.

void ReleaseFont(CFont* aFont);

Description

Releases a specified font.

This function is used to indicate that the specified font is no longer needed for use by the screen device map. As fonts can be shared between applications, this function does not delete the copy of the font from RAM unless the font was only being used by this particular device map.

Parameters

CFont* aFont A pointer to the font to be released.

See also:

• MGraphicsDeviceMap::ReleaseFont()

void RemoveFile(TInt aId=0);

Description

Removes a font file from the font store.

Parameters

TInt aId=0 The ID of the font file to be removed, default 0.

See also:

• CBitmapDevice::RemoveFile()

TScreenModeEnforcement ScreenModeEnforcement() const;

Description

Gets the current screen size mode enforcement settings.

The global screen mode enforcement setting defines the requirements that a group window must meet to be displayed. The requirements may have been set in wsini.ini, or using SetScreenModeEnforcement().

Return value

TScreenModeEnforcement The screen mode enforcement requirements.

void SetCurrentRotations(TInt aMode, CFbsBitGc::TGraphicsOrientation aRotation) const;

Support

Supported from 5.1

Description

Sets the screen rotation that should be used with a particular screen size.

After calling this function, whenever you change into the screen size specified by aMode you will have the rotation aRotation. The setting remains in force until it is explicitly changed using this function.

Parameters

TInt aMode The index of the screen size the rotation applies to. CFbsBitGc::TGraphicsOrientation aRotation The new orientation of the screen.

Panic codes

Panics if the specified rotation is not allowed in the given screen size mode.

See also:

• GetRotationsList()

void SetScreenMode(TInt aMode);

Description

Sets the screen mode.

Note:

• This function is only useful for testing. This is because normally the screen size mode reflects the state of real hardware, e.g. the flip in the Ericsson R380 smartphone.

Parameters

TInt aMode The screen mode index, starting from zero.

void SetScreenModeEnforcement(TScreenModeEnforcement aMode) const;

Description

Sets the screen mode enforcement requirements.

This global setting defines the requirements that a group window must meet to be displayed. The value may be set using this function, but is more likely to be defined in wsini.ini.

Parameters

TScreenModeEnforcement aMode The screen mode enforcement requirements.

void SetScreenSizeAndRotation(const TPixelsTwipsAndRotation& aSizeAndRotation);

Description

Sets the current screen size, in twips and pixels, and the rotation for the screen device.

Parameters

const TPixelsTwipsAndRotation& aSizeAndRotation The new rotation and the screen size in both pixels and twips.

void SetScreenSizeAndRotation(const TPixelsAndRotation& aSizeAndRotation);

Description

Sets the current screen size in pixels, and the rotation for the screen device.

Parameters

const TPixelsAndRotation& aSizeAndRotation The new rotation and the screen size in pixels.

TSize SizeInPixels() const;

Description

Get the size of the screen device area in pixels.

Return value

TSize The x and y dimensions of the screen device area, in pixels.

See also:

• CGraphicsDevice::SizeInPixels()

TSize SizeInTwips() const;

Description

Get the size of the screen device area in twips.

Return value

TSize The x and y dimensions of the screen device area, in twips.

See also:

• CGraphicsDevice::SizeInTwips()

void TypefaceSupport(TTypefaceSupport& aTypefaceSupport,TInt aTypefaceIndex) const;

Description

Gets typeface information for a particular typeface index number.

This information is returned in aTypefaceSupport, and includes:

• the typeface name and typeface attributes (in a TTypeface object),

• the number of font heights,

• the maximum and minimum font heights,

• whether it is a scalable typeface.

Parameters

TTypefaceSupport& aTypefaceSupport On return, if the function executed successfully, this object contains the typeface information. TInt aTypefaceIndex A typeface index number, in the range: zero to (NumTypefaces() - 1).

See also:

• CGraphicsDevice::TypefaceSupport()

TInt VerticalPixelsToTwips(TInt aPixels) const;

Description

Translates a vertical dimension of a screen device in pixels to a vertical dimension in twips.

Parameters

TInt aPixels A vertical dimension of a device in pixels.

Return value

TInt The vertical dimension in twips.

See also:

• MGraphicsDeviceMap::VerticalPixelsToTwips()

TInt VerticalTwipsToPixels(TInt aTwips) const;

Description

Translates a vertical dimension of a screen device in twips to a vertical dimension in pixels.

Parameters

TInt aTwips A vertical dimension of a device in twips.

Return value

TInt The vertical dimension in pixels.