|  | Home · All Classes · Main Classes · Grouped Classes · Modules · Functions |

# QScreen Class Reference
[QtGui module]

The QScreen class is a base class for implementing screen drivers in Qtopia Core. More...

     #include <QScreen>

Inherited by QLinuxFbScreen, QTransformedScreen, QVFbScreen, and QVNCScreen.

- List of all members, including inherited members

### Public Types

- enum PixelType { NormalPixel, BGRPixel }

### Public Functions

- QScreen ( int displayId )
- virtual ~QScreen ()
- virtual int alloc ( unsigned int red, unsigned int green, unsigned int blue )
- uchar * base () const
- virtual void blank ( bool on )
- virtual void blit ( const QImage & image, const QPoint & topLeft, const QRegion & region )
- QRgb * clut ()
- virtual bool connect ( const QString & displaySpec ) = 0
- virtual QWSWindowSurface * createSurface ( QWidget * widget ) const
- virtual QWSWindowSurface * createSurface ( const QString & key ) const
- int depth () const
- int deviceHeight () const
- int deviceWidth () const
- virtual void disconnect () = 0
- virtual void exposeRegion ( QRegion region, int windowIndex )
- int height () const
- virtual bool initDevice () = 0
- virtual bool isInterlaced () const
- virtual bool isTransformed () const
- int linestep () const
- virtual QSize mapFromDevice ( const QSize & size ) const
- virtual QPoint mapFromDevice ( const QPoint & point, const QSize & screenSize ) const
- virtual QRect mapFromDevice ( const QRect & rectangle, const QSize & screenSize ) const
- virtual QImage mapFromDevice ( const QImage & image ) const
- virtual QRegion mapFromDevice ( const QRegion & region, const QSize & screenSize ) const
- virtual QSize mapToDevice ( const QSize & size ) const
- virtual QPoint mapToDevice ( const QPoint & point, const QSize & screenSize ) const
- virtual QRect mapToDevice ( const QRect & rectangle, const QSize & screenSize ) const
- virtual QImage mapToDevice ( const QImage & image ) const
- virtual QRegion mapToDevice ( const QRegion & region, const QSize & screenSize ) const
- int numCols ()
- QPoint offset () const
- virtual bool onCard ( const unsigned char * buffer ) const
- virtual bool onCard ( const unsigned char * buffer, ulong & offset ) const
- int physicalHeight () const
- int physicalWidth () const
- PixelType pixelType () const
- virtual int pixmapDepth () const
- virtual int pixmapLinestepAlignment ()
- virtual int pixmapOffsetAlignment ()
- virtual QRegion region () const
- virtual void restore ()
- virtual void save ()
- int screenSize () const
- virtual void setDirty ( const QRect & rectangle )
- virtual void setMode ( int width, int height, int depth ) = 0
- virtual void shutdownDevice ()
- virtual void solidFill ( const QColor & color, const QRegion & region )
- int subScreenIndexAt ( const QPoint & position ) const
- virtual QList<QScreen *> subScreens () const
- virtual bool supportsDepth ( int depth ) const
- int totalSize () const
- virtual int transformOrientation () const
- int width () const

### Static Public Members

- QScreen * instance ()

## Detailed Description

The QScreen class is a base class for implementing screen drivers in Qtopia Core.

Note that this class is only available in Qtopia Core. Custom screen drivers derived from QScreen can be added by subclassing the QScreenDriverPlugin class, using the QScreenDriverFactory class to dynamically load the driver into the application, but there should only be one screen object per application.

The QScreen class provides functions enabling framebuffer and palette management and drawing on screen. The class also provides information about several screen properties, e.g its metrics. Finally, the QScreen class and its descendants act as factories for the screen cursor, creating the cursor whenever required.

- Framebuffer Management
- Palette Management
- Drawing on Screen
- Screen Properties

### Framebuffer Management

When a Qtopia Core application starts, the connect() function will be called to map in the framebuffer and the accelerated drivers that the graphics card control registers, and when initializing the framebuffer, the initDevice() function will be called. The latter function can be reimplemented to set up the graphics card (note that the default implementation does nothing).

Likewise, just before a Qtopia Core application exits, the disconnect() function will be called. This function should be reimplemented to unmap the framebuffer. The shutdownDevice() function is also called on shutdown, and can be reimplemented to support graphics card specific cleanup.

The save() function allows subclasses of QScreen to save the state of the graphics card. Hardware QScreen descendants should save the state of the registers here to enable switching between virtual consoles. The corresponding restore() function enables restoration of a previously saved state of the graphics card. Note that the default implementations of these two functions do nothing.

QScreen also provides the base() function returning a pointer to the beginning of the framebuffer. Use the onCard() function to determine whether the framebuffer is within the graphics card's memory. The totalSize() function returns the size of the available graphics card memory, including the screen.

### Palette Management

For palette management, the QScreen class provides the clut() function to retrieve the screen's color lookup table (i.e. its color palette), and the numCols() function to determine the number of entries in this table. The alloc() function can be used to retrieve the index in the screen's palette which is the closest match to a given RGB value, and the supportsDepth() function to determine if the screen supports a given color depth.

### Drawing on Screen

When deriving from QScreen, either the blit() or the exposeRegion() function must be reimplemented to enable drawing on screen.

The blit() function copies a given region in a given image to a specified point using device coordinates, and should be reimplemented to make use of accelerated hardware. Note that reimplementing blit() requires that the solidFill() function is reimplemented as well. The solidFill() function allows subclasses of QScreen to fill the given region of the screen with the specified color. The exposeRegion() function paints a given region on screen. Note that normally there is no need to call either of these functions explicitly.

Reimplement the blank() function to control the display of contents on the screen. The setDirty() function can be reimplemented to indicate that a given rectangle of the screen has been altered. Note that the default implementations of these two latter functions do nothing.

QScreen also provides the mapFromDevice() and mapToDevice() function to map an object from the framebuffer coordinate system to the coordinate space used by the application, and vice versa.

See the QDirectPainter and QDecoration class documentation for more information about drawing on screen.

### Screen Properties

QScreen provides information about several screen properties: The size of the screen can be retrieved using the screenSize() function. Alternatively, its width and height can be retrieved using the width() and height() functions respectively. QScreen also provides the deviceWidth() and deviceHeight() functions which returns the full size of the device. Note that these metrics can differ from the ones used if the display is centered within the framebuffer.

The setMode() function allows subclasses of QScreen to set the framebuffer to a new resolution (width and height) and bit depth. The current depth of the framebuffer can be retrieved using the depth() function.

Use the pixmapDepth() function to obtain the preferred depth for pixmaps. In addition, QScreen provides the pixmapOffsetAlignment() function returning the value to which the start address of pixmaps held in the graphics card's memory, should be aligned. The pixmapLinestepAlignment() returns the value to which the individual scanlines of pixmaps should be aligned.

The isInterlaced() function tells whether the screen is displaying images progressively, and the isTransformed() function whether it is rotated. The transformOrientation() function can be reimplemented to return the current rotation.

The linestep() function returns the length of each scanline of the framebuffer.

The pixelType() returns the screen's pixel storage format as described by the PixelType enum, the opType() function returns the screen's operation type, and the lastOp() function returns the screens last operation.

See also Running Applications and Qtopia Core.

## Member Type Documentation

### enum QScreen::PixelType

This enum describes the pixel storage format of the screen, i.e. the order of the red (R), green (G) and blue (B) components of a pixel.

Constant | Value | Description
--- | --- | ---
`QScreen::NormalPixel` | `0` | Red-green-blue (RGB)
`QScreen::BGRPixel` | `1` | Blue-green-red (BGR)

See also pixelType().

## Member Function Documentation

### QScreen::QScreen ( int displayId )

Constructs a QScreen object. The displayId identifies the the Qtopia Core server to connect to.

### QScreen::~QScreen () `[virtual]`

Destroys this QScreen object.

### int QScreen::alloc ( unsigned int red, unsigned int green, unsigned int blue ) `[virtual]`

Returns the index in the screen's palette which is the closest match to the given RGB value (red, green, blue).

Note that this function only apply in paletted modes, i.e. in modes where only palette indexes (and not actual color values) are stored in memory (e.g. 8-bit mode).

See also clut().

### uchar * QScreen::base () const

Returns a pointer to the beginning of the framebuffer.

See also onCard().

### void QScreen::blank ( bool on ) `[virtual]`

Avoids displaying any contents on the screen if on is true; otherwise the contents is shown.

The default implementation does nothing.

### void QScreen::blit ( const QImage & image, const QPoint & topLeft, const QRegion & region ) `[virtual]`

Copies the given region in the given image to the point specified by topLeft using device coordinates.

Reimplement this function to use accelerated hardware. Note that reimplementing this function requires that the solidFill() function is reimplemented as well.

See also exposeRegion() and Adding an Accelerated Graphics Driver.

### QRgb * QScreen::clut ()

Returns the screen's color lookup table (i.e. its color palette).

Note that this function only apply in paletted modes, i.e. in modes where only palette indexes (and not actual color values) are stored in memory (e.g. 8-bit mode).

See also alloc(), depth(), and numCols().

### bool QScreen::connect ( const QString & displaySpec ) `[pure virtual]`

This function is called by every Qtopia Core application on startup, and must be reimplemented to map in the framebuffer and the accelerated drivers that the graphics card control registers.

The displaySpec argument is passed by the QWS_DISPLAY environment variable or the -display command line parameter, and has the following syntax:

     [screen driver][:driver specific options][:display number]

For example, to use the mach64 driver on fb1 as display 2:

     Mach64:/dev/fb1:2

See also disconnect() and Running Applications.

### QWSWindowSurface * QScreen::createSurface ( QWidget * widget ) const `[virtual]`

Creates a new QWSWindowSurface for widget.

### QWSWindowSurface * QScreen::createSurface ( const QString & key ) const `[virtual]`

This is an overloaded member function, provided for convenience.

Creates a new QWSWindowSurface matching the name given by key.

This function is used by the application that runs as a GuiServer when when it needs to create a server side representation of a surface.

This function was introduced in Qt 4.2.

See also QApplication::Type.

### int QScreen::depth () const

Returns the depth of the framebuffer, in bits per pixel.

Note that the returned depth is the number of bits each pixel takes up rather than the number of significant bits, so 24bpp and 32bpp express the same range of colors (8 bits of red, green and blue).

See also clut() and pixmapDepth().

### int QScreen::deviceHeight () const

Returns the full height of the framebuffer device.

Note that the returned height can differ from the height which Qtopia Core will actually use, that is if the display is centered within the framebuffer.

See also deviceWidth() and height().

### int QScreen::deviceWidth () const

Returns the full width of the framebuffer device.

Note that the returned width can differ from the width which Qtopia Core will actually use, that is if the display is centered within the framebuffer.

See also deviceHeight() and width().

### void QScreen::disconnect () `[pure virtual]`

This function is called by every Qtopia Core application just before exiting, and should be reimplemented to unmap the framebuffer.

See also connect().

### void QScreen::exposeRegion ( QRegion region, int windowIndex ) `[virtual]`

Paints the given region on screen. The windowIndex parameter refer to the affected windows.

Note that there is no need to call this function explicitly, but it must be reimplemented in derived classes. It can also be reimplemented to make use of accelerated hardware, but this is typically done by reimplementing the blit() function instead.

See also blit().

### int QScreen::height () const

Returns the height of the framebuffer, in pixels.

See also deviceHeight() and width().

### bool QScreen::initDevice () `[pure virtual]`

This function is called by the Qtopia Core server when initializing the framebuffer.

Reimplement this function to make accelerated drivers set up the graphics card. The default implementation does nothing.

See also Adding an Accelerated Graphics Driver.

### QScreen * QScreen::instance () `[static]`

Returns a pointer to the application's QScreen instance.

If this screen consists of several subscreens, operations to this instance will affect all subscreens. Use the subscreens() function to retrieve access to a particular subscreen.

See also subScreens() and subScreenIndexAt().

### bool QScreen::isInterlaced () const `[virtual]`

Returns true if the display is interlaced (for instance a television screen); otherwise returns false.

If true, drawing is altered to look better on such displays.

### bool QScreen::isTransformed () const `[virtual]`

Returns true if the screen is transformed (for instance, rotated 90 degrees); otherwise returns false.

See also QTransformedScreen::transformation().

### int QScreen::linestep () const

Returns the length of each scanline of the framebuffer, in bytes.

See also QDirectPainter::linestep().

### QSize QScreen::mapFromDevice ( const QSize & size ) const `[virtual]`

This virtual function allows subclasses of QScreen to map the given object from the framebuffer coordinate system to the coordinate space used by the application.

In the case of a size object, this means switching its height and width. Note that the default implementation simply returns the given size as it is.

See also mapToDevice().

### QPoint QScreen::mapFromDevice ( const QPoint & point, const QSize & screenSize ) const `[virtual]`

This is an overloaded member function, provided for convenience.

This virtual function allows subclasses of QScreen to map the given object from the framebuffer coordinate system to the coordinate space used by the application, passing the device's screenSize as argument.

Note that the default implementation returns the given point as it is.

### QRect QScreen::mapFromDevice ( const QRect & rectangle, const QSize & screenSize ) const `[virtual]`

This is an overloaded member function, provided for convenience.

This virtual function allows subclasses of QScreen to map the given object from the framebuffer coordinate system to the coordinate space used by the application, passing the device's screenSize as argument.

The default implementation returns the given rectangle as it is.

### QImage QScreen::mapFromDevice ( const QImage & image ) const `[virtual]`

This is an overloaded member function, provided for convenience.

This virtual function allows subclasses of QScreen to map the given object from the framebuffer coordinate system to the coordinate space used by the application.

The default implementation returns the given image as it is.

### QRegion QScreen::mapFromDevice ( const QRegion & region, const QSize & screenSize ) const `[virtual]`

This is an overloaded member function, provided for convenience.

This virtual function allows subclasses of QScreen to map the given object from the framebuffer coordinate system to the coordinate space used by the application, passing the device's screenSize as argument .

The default implementation returns the given region as it is.

### QSize QScreen::mapToDevice ( const QSize & size ) const `[virtual]`

This virtual function allows subclasses of QScreen to map the given object from the coordinate space used by the application to the framebuffer coordinate system.

In the case of a size object, this means switching its height and width. Note that the default implementation simply returns the given size as it is.

See also mapFromDevice().

### QPoint QScreen::mapToDevice ( const QPoint & point, const QSize & screenSize ) const `[virtual]`

This is an overloaded member function, provided for convenience.

This virtual function allows subclasses of QScreen to map the given object from the coordinate space used by the application to the framebuffer coordinate system, passing the device's screenSize as argument.

Note that the default implementation returns the given point as it is.

### QRect QScreen::mapToDevice ( const QRect & rectangle, const QSize & screenSize ) const `[virtual]`

This is an overloaded member function, provided for convenience.

This virtual function allows subclasses of QScreen to map the given object from the coordinate space used by the application to the framebuffer coordinate system, passing the device's screenSize as argument.

Note that the default implementation returns the given rectangle as it is.

### QImage QScreen::mapToDevice ( const QImage & image ) const `[virtual]`

This is an overloaded member function, provided for convenience.

This virtual function allows subclasses of QScreen to map the given object from the coordinate space used by the application to the framebuffer coordinate system.

The default implementation returns the given image as it is.

### QRegion QScreen::mapToDevice ( const QRegion & region, const QSize & screenSize ) const `[virtual]`

This is an overloaded member function, provided for convenience.

This virtual function allows subclasses of QScreen to map the given object from the coordinate space used by the application to the framebuffer coordinate system, passing the device's screenSize as argument.

The default implementation returns the given region as it is.

### int QScreen::numCols ()

Returns the number of entries in the screen's color lookup table (i.e. its color palette). The color table can be retrieved using the clut() function.

See also clut().

### QPoint QScreen::offset () const

Returns the logical offset of the screen.

This function was introduced in Qt 4.2.

### bool QScreen::onCard ( const unsigned char * buffer ) const `[virtual]`

Returns true if the specified buffer is within the graphics card's memory; otherwise returns false (i.e. if it's in main RAM).

See also base() and totalSize().

### bool QScreen::onCard ( const unsigned char * buffer, ulong & offset ) const `[virtual]`

This is an overloaded member function, provided for convenience.

If the specified buffer is within the graphics card's memory, this function stores the offset (in bytes) from the start of graphics card memory, in the location specified by the offset parameter.

### int QScreen::physicalHeight () const

Returns the physical height of the screen (in millimeters).

This function was introduced in Qt 4.2.

See also physicalWidth().

### int QScreen::physicalWidth () const

Returns the physical width of the screen (in millimeters).

This function was introduced in Qt 4.2.

See also physicalHeight().

### PixelType QScreen::pixelType () const

Returns the pixel storage format of the screen.

See also PixelType.

### int QScreen::pixmapDepth () const `[virtual]`

Returns the preferred depth for pixmaps, in bits per pixel.

See also depth().

### int QScreen::pixmapLinestepAlignment () `[virtual]`

Returns the value (in bits) to which individual scanlines of pixmaps held in the graphics card's memory, should be aligned.

The default implementation returns 64. Reimplement this function to override the return value when implementing an accelerated driver.

See also pixmapOffsetAlignment() and Adding an Accelerated Graphics Driver.

### int QScreen::pixmapOffsetAlignment () `[virtual]`

Returns the value (in bits) to which the start address of pixmaps held in the graphics card's memory, should be aligned.

The default implementation returns 64. Reimplement this function to override the return value when implementing an accelerated driver.

See also pixmapLinestepAlignment() and Adding an Accelerated Graphics Driver.

### QRegion QScreen::region () const `[virtual]`

Returns the region covered by this screen.

This function was introduced in Qt 4.2.

### void QScreen::restore () `[virtual]`

This virtual function allows subclasses of QScreen to restore a previously saved state of the graphics card.

Note that the default implementation does nothing.

See also save().

### void QScreen::save () `[virtual]`

This virtual function allows subclasses of QScreen to save the state of the graphics card, and be able to restored it later.

Hardware QScreen descendants should save the state of the registers here, if necessary, to enable switching between virtual consoles (for example to and from X).

Note that the default implementation does nothing.

See also restore().

### int QScreen::screenSize () const

Returns the size of the screen, in bytes.

The screen size is always located at the beginning of framebuffer memory, i.e. it can also be retrieved using the base() function.

See also base().

### void QScreen::setDirty ( const QRect & rectangle ) `[virtual]`

This virtual function allows subclasses of QScreen to indicate that the given rectangle of the screen has been altered.

Note that the default implementation does nothing.

### void QScreen::setMode ( int width, int height, int depth ) `[pure virtual]`

This virtual function allows subclasses of QScreen to set the framebuffer to a new resolution (width and height) and bit depth.

After doing this any currently-existing paint engines will be invalid and the screen should be completely redrawn. In a multiple-process situation, all other applications must be notified to set the same mode and redraw.

Note that the default implementation does nothing.

### void QScreen::shutdownDevice () `[virtual]`

This virtual function is called by the Qtopia Core server on shutdown, and allows subclasses of QScreen to support graphics card specific cleanup.

The default implementation simply hides the mouse cursor.

### void QScreen::solidFill ( const QColor & color, const QRegion & region ) `[virtual]`

This virtual function allows subclasses of QScreen to fill the given region of the screen with the specified color. Note that this function is not intended to be called explicitly.

See also blit().

### int QScreen::subScreenIndexAt ( const QPoint & position ) const

Returns the index of the subscreen at the given position; returns -1 if no screen is found.

The index identifies the subscreen in the list of pointers returned by the subScreens() function.

This function was introduced in Qt 4.2.

See also instance() and subScreens().

### QList<QScreen *> QScreen::subScreens () const `[virtual]`

Returns a list of this screen's subscreens. Use this function to retrieve access to a particular subscreen. Use the subScreenIndexAt() function to retrieve the index of a screen at a given position.

Note that if this screen consists of several subscreens, operations to this instance will affect all subscreens by default.

This function was introduced in Qt 4.2.

See also instance() and subScreenIndexAt().

### bool QScreen::supportsDepth ( int depth ) const `[virtual]`

Returns true if the screen supports the specified color depth; otherwise returns false.

See also clut().

### int QScreen::totalSize () const

Returns the size of the available graphics card memory, including the screen, in bytes.

Offscreen memory is only used by the accelerated drivers.

See also onCard().

### int QScreen::transformOrientation () const `[virtual]`

This virtual function allows subclasses of QScreen to return the current rotation of the screeen as an integer value.

The default implementation returns 0.

See also isTransformed().

### int QScreen::width () const

Returns the width of the framebuffer, in pixels.

See also deviceWidth() and height().