Qt 4.2: QWSWindowSurface Class Reference

|  | 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.

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 bool attach ( const QByteArray & data ) = 0
- virtual void beginPaint ( const QRegion & region )
- const QRegion clipRegion () const
- virtual const QByteArray data () const = 0
- virtual void detach () = 0
- const QRegion dirtyRegion () const
- virtual void endPaint ( const QRegion & region )
- virtual void flush ( QWidget * widget, const QRegion & region, const QPoint & offset )
- virtual QRect geometry () const = 0
- virtual const QImage image () const = 0
- bool isBuffered () const
- bool isOpaque () const
- bool isReserved () const
- virtual bool isValidFor ( const QWidget * window ) const = 0
- virtual const QString key () const = 0
- virtual QPaintDevice * paintDevice () = 0
- virtual QPoint painterOffset () const
- virtual void release ()
- virtual void scroll ( const QRegion & region, int dx, int dy ) = 0
- void setClipRegion ( const QRegion & clip )
- void setDirty ( const QRegion & region ) const
- virtual void setGeometry ( const QRect & rectangle )
- SurfaceFlags surfaceFlags () const
- QWidget * window () const

### 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 isValidFor() 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` | `0x1` | 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 ()

Destroys this surface.

### bool QWSWindowSurface::attach ( const QByteArray & data ) `[pure 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 detach() and data().

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

This function is called before painting onto the surface begins, with the region in which the painting will occur.

See also endPaint() and paintDevice().

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

Returns the region currently visible on the screen.

See also setClipRegion().

### const QByteArray QWSWindowSurface::data () const `[pure virtual]`

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

See also attach().

### void QWSWindowSurface::detach () `[pure virtual]`

Implement this function to detach a server-side instance from the client.

See also attach() and release().

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

Returns the region that must be repainted.

See also setDirty().

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

This function is called after painting onto the surface has ended, with the region in which the painting was performed.

See also beginPaint() and paintDevice().

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

Flushes the given region from the specified widget onto the screen.

Note that the offset parameter is currently unused.

See also painterOffset().

### QRect QWSWindowSurface::geometry () const `[pure virtual]`

Implement this function to return the currently allocated area.

See also setGeometry(), scroll(), and image().

### const 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::isReserved () const

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

See also surfaceFlags().

### bool QWSWindowSurface::isValidFor ( const QWidget * window ) 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().

### const 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 isValidFor().

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

Implement this function to return the appropriate paint device.

See also painterOffset().

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

Returns the offset to be used when painting.

See also paintDevice().

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

Releases the current allocated screen region associated with this window surface.

See also detach().

### void QWSWindowSurface::scroll ( const QRegion & region, int dx, int dy ) `[pure virtual]`

Scrolls the given region dx pixels to the right and dy downward; both dx and dy may be negative.

See also geometry().

### 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 & rectangle ) `[virtual]`

Sets the currently allocated area to be the given rectangle.

This function is called whenever area covered by the top-level window changes.

See also geometry().

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

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

See also surfaceFlags().

### SurfaceFlags QWSWindowSurface::surfaceFlags () const

Returns the surface flags describing the contents of this surface.

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

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

Returns a pointer to the top-level window associated with this surface.

See also isValidFor() and key().