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

# QWSWindowSurface Class Reference
[QtGui module]

The QWSWindowSurface class provides the drawing area for top-level windows in Qtopia Core. More...

     #include <QWSWindowSurface>

This class is under development and is subject to change.

Inherits QWindowSurface.

This class was introduced in Qt 4.2.

- List of all members, including inherited members

### Public Types

- enum SurfaceFlag { Reserved, Buffered, Opaque }
- flags SurfaceFlags

### Public Functions

- QWSWindowSurface ()
- QWSWindowSurface ( QWidget * window )
- ~QWSWindowSurface ()
- virtual void beginPaint ( const QRegion & )
- const QRegion clipRegion () const
- const QRegion dirtyRegion () const
- virtual void endPaint ( const QRegion & )
- virtual void flush ( QWidget * widget, const QRegion & region, const QPoint & offset )
- virtual QImage image () const = 0
- bool isBuffered () const
- bool isOpaque () const
- bool isRegionReserved () const
- virtual bool isValid () const = 0
- virtual QString key () const = 0
- virtual bool lock ( int timeout = -1 )
- virtual QPaintDevice * paintDevice () = 0
- virtual QPoint painterOffset () const
- virtual QByteArray permanentState () const
- void setClipRegion ( const QRegion & clip )
- void setDirty ( const QRegion & region ) const
- virtual void setGeometry ( const QRect & rect )
- virtual void setPermanentState ( const QByteArray & data )
- virtual void setTransientState ( const QByteArray & state )
- SurfaceFlags surfaceFlags () const
- virtual QByteArray transientState () const
- virtual void unlock ()

- 11 public functions inherited from QWindowSurface

### Protected Functions

- void setSurfaceFlags ( SurfaceFlags flags )

## Detailed Description

The QWSWindowSurface class provides the drawing area for top-level windows in Qtopia Core.

Note that this class is only available in Qtopia Core.

In Qtopia Core, the default behavior is for each client to render its widgets into memory while the server is responsible for putting the contents of the memory onto the screen. QWSWindowSurface is used by the window system to implement the associated memory allocation.

When a screen update is required, the server runs through all the top-level windows that intersect with the region that is about to be updated, and ensures that the associated clients have updated their memory buffer. Then the server uses the screen driver to copy the content of the memory to the screen. To locate the relevant parts of memory, the driver is provided with the list of top-level windows that intersect with the given region. Associated with each of the top-level windows there is a window surface representing the drawing area of the window.

When deriving from the QWSWindowSurface class, e.g., when adding an accelerated graphics driver, there are several pure virtual functions that must be implemented. In addition, QWSWindowSurface provides several virtual functions that can be reimplemented to customize the drawing process.

- Pure Virtual Functions
- Virtual Functions
- Other Members

### Pure Virtual Functions

There are in fact two window surface instances for each top-level window; one used by the application when drawing a window, and another used by the server application to perform window compositioning. Implement the attach() to create the server-side representation of the surface. The data() function must be implemented to provide the required data. In addition, the related detach() function must be implemented to enable the window system to detach the server-side instance from the client.

Implement the key() function to uniquely identify the surface class, and the isValid() function to determine is a surface corresponds to a given widget.

The geometry() function must be implemented to let the window system determine the area required by the window surface (QWSWindowSurface also provides a corresponding virtual setGeometry() function that is called whenever the area necessary for the top-level window to be drawn, changes). The image() function is called by the window system during window compositioning, and must be implemented to return an image of the top-level window.

Finally, the paintDevice() function must be implemented to return the appropriate paint device, and the scroll() function must be implemented to scroll the given region of the surface the given number of pixels.

### Virtual Functions

When painting onto the surface, the window system will always call the beginPaint() function before any painting operations are performed. Likewise the endPaint() function is automatically called when the painting is done. Reimplement the painterOffset() function to alter the offset that is applied when drawing.

The window system uses the flush() function to put a given region of the widget onto the screen, and the release() function to deallocate the screen region corresponding to this window surface.

### Other Members

QWSWindowSurface provides the window() function returning a pointer to the top-level window the surface is representing. The currently visible region of the associated widget can be retrieved and set using the clipRegion() and setClipRegion() functions, respectively.

When the window system performs the window compositioning, it uses the SurfaceFlag enum describing the surface content. The currently set surface flags can be retrieved and altered using the surfaceFlags() and setSurfaceFlags() functions. In addition, QWSWindowSurface provides the isBuffered(), isOpaque() and isReserved() convenience functions. Use the dirtyRegion() function to retrieve the part of the widget that must be repainted, and the setDirty() function to ensure that a region is repainted.

See also Qtopia Core Architecture.

## Member Type Documentation

### enum QWSWindowSurface::SurfaceFlag
flags QWSWindowSurface::SurfaceFlags

This enum is used to describe the window surface's contents. It is used by the screen driver to handle region allocation and composition.

Constant | Value | Description
--- | --- | ---
`QWSWindowSurface::Reserved` |  | The surface contains a reserved area. Once allocated, a reserved area can not not be changed by the window system, i.e., no other widgets can be drawn on top of this.
`QWSWindowSurface::Buffered` | `0x2` | The surface is in a memory area which is not part of a framebuffer. (A top-level window with QWidget::windowOpacity() other than 1.0 must use a buffered surface in order to making blending with the background work.)
`QWSWindowSurface::Opaque` | `0x4` | The surface contains only opaque pixels.

The SurfaceFlags type is a typedef for QFlags<SurfaceFlag>. It stores an OR combination of SurfaceFlag values.

See also surfaceFlags() and setSurfaceFlags().

## Member Function Documentation

### QWSWindowSurface::QWSWindowSurface ()

Constructs an empty surface.

### QWSWindowSurface::QWSWindowSurface ( QWidget * window )

Constructs an empty surface for the given top-level window.

### QWSWindowSurface::~QWSWindowSurface ()

### void QWSWindowSurface::beginPaint ( const QRegion & ) `[virtual]`

### const QRegion QWSWindowSurface::clipRegion () const

Returns the region currently visible on the screen.

See also setClipRegion().

### const QRegion QWSWindowSurface::dirtyRegion () const

Returns the region that must be repainted.

See also setDirty().

### void QWSWindowSurface::endPaint ( const QRegion & ) `[virtual]`

### void QWSWindowSurface::flush ( QWidget * widget, const QRegion & region, const QPoint & offset ) `[virtual]`

### QImage QWSWindowSurface::image () const `[pure virtual]`

Implement this function to return an image of the top-level window.

See also geometry().

### bool QWSWindowSurface::isBuffered () const

Returns true if the QWSWindowSurface::Buffered is set; otherwise returns false.

See also surfaceFlags().

### bool QWSWindowSurface::isOpaque () const

Returns true if the QWSWindowSurface::Opaque is set; otherwise returns false.

See also surfaceFlags().

### bool QWSWindowSurface::isRegionReserved () const

### bool QWSWindowSurface::isValid () const `[pure virtual]`

Implement this function to return true if the surface is a valid surface for the given top-level window; otherwise return false.

See also window() and key().

### QString QWSWindowSurface::key () const `[pure virtual]`

Implement this function to return a string that uniquely identifies the class of this surface.

See also window() and isValid().

### bool QWSWindowSurface::lock ( int timeout = -1 ) `[virtual]`

### QPaintDevice * QWSWindowSurface::paintDevice () `[pure virtual]`

### QPoint QWSWindowSurface::painterOffset () const `[virtual]`

Returns the offset to be used when painting.

See also paintDevice().

### QByteArray QWSWindowSurface::permanentState () const `[virtual]`

Implement this function to return the data required for creating a server-side representation of the surface.

See also setPermanentState() and attach().

### void QWSWindowSurface::setClipRegion ( const QRegion & clip )

Sets the region currently visible on the screen to be the given clip region.

See also clipRegion().

### void QWSWindowSurface::setDirty ( const QRegion & region ) const

Marks the given region as dirty, i.e., altered.

See also dirtyRegion().

### void QWSWindowSurface::setGeometry ( const QRect & rect ) `[virtual]`

### void QWSWindowSurface::setPermanentState ( const QByteArray & data ) `[virtual]`

Implement this function to attach a server-side surface instance to the corresponding client side instance using the given data. Return true if successful; otherwise return false.

See also permanentState(), detach(), and data().

### void QWSWindowSurface::setSurfaceFlags ( SurfaceFlags flags ) `[protected]`

Sets the surface flags describing the contents of this surface, to be the given flags.

See also surfaceFlags().

### void QWSWindowSurface::setTransientState ( const QByteArray & state ) `[virtual]`

See also transientState().

### SurfaceFlags QWSWindowSurface::surfaceFlags () const

Returns the surface flags describing the contents of this surface.

See also setSurfaceFlags(), isBuffered(), isOpaque(), and isReserved().

### QByteArray QWSWindowSurface::transientState () const `[virtual]`

See also setTransientState().

### void QWSWindowSurface::unlock () `[virtual]`