QDecoration Class Reference
^{[QtGui module]}

Detailed Description

The QDecoration class allows the appearance of top level windows to be customized.

Note that this class is non-portable, and that it is only available in Qtopia Core.

Qtopia Core provides window management of top level windows. The appearance of the borders and buttons (the decoration) around these windows can be customized by deriving from the QDecoration class. Custom decorations can be added by subclassing the QDecorationPlugin class, using the QDecorationFactory class to dynamically load the decoration into the application. To actually apply a decoration to an application, use the QApplication::qwsSetDecoration() function.

The QDecoration class provides the virtual paint() function that can be reimplemented to paint the border and title decoration around a specified widget using a given painter and decoration state.

The DecorationRegion enum is used to specify which region to paint. This enum describes the various regions of the window decoration. The region() function is used to retrieve the actual regions the decoration occupy. It is also possible to determine the type of region containing a given point, using the regionAt() function. The DecorationState enum is used to specify a region's state, e.g. whether it is active or not.

QDecoration also provides the possibility of building the system menu for a given top level widget with its virtual buildSysMenu() function. The menuTriggered() function is called whenever an action in such a widget's menu is triggered.

The virtual regionClicked() and regionDoubleClicked() functions are provided to enable response to mouse clicks. The default implementations responds to (single) clicks on items in a widget's system menu and double clicks on a widget's title.

Finally, the QDecoration class provides a couple of static functions, startMove() and startResize(), which start the move or resize action by making the appropiate decoration region active and grabbing the mouse input.

See also QDecorationFactory, QDecorationPlugin, and QDirectPainter.

Member Type Documentation

enum QDecoration::DecorationRegion

This enum describes the various regions of the window decoration.

See also region(), regionAt(), and DecorationState.

enum QDecoration::DecorationState

This enum describes the various states of a decoration region.

See also paint() and DecorationRegion.

Member Function Documentation

QDecoration::QDecoration ()

Constructs a decoration object.

QDecoration::~QDecoration ()   [virtual]

Destroys this decoration object.

void QDecoration::buildSysMenu ( QWidget * widget, QMenu * menu )   [virtual]

Builds the system menu for the given top level widget.

See also menuTriggered().

void QDecoration::menuTriggered ( QWidget * widget, QAction * action )

This function is called whenever an action in a top level widget's menu is triggered. Pointers to the widget and action are passed as arguments.

See also buildSysMenu().

bool QDecoration::paint ( QPainter * painter, const QWidget * widget, int decorationRegion = All, DecorationState state = Normal )   [pure virtual]

This virtual function allows subclasses of QDecoration to paint the border and title decoration for the specified top level widget using the given painter and state.

The specified decorationRegion is a bitmask of the values described by the DecorationRegion enum.

QRegion QDecoration::region ( const QWidget * widget, const QRect & rectangle, int decorationRegion = All )   [pure virtual]

Returns the region specified by decorationRegion, for the given top level widget.

The rectangle parameter specifies the rectangle the decoration is wrapped around. The decorationRegion is a bitmask of the values described by the DecorationRegion enum.

See also regionAt().

QRegion QDecoration::region ( const QWidget * widget, int decorationRegion = All )

This is an overloaded member function, provided for convenience.

Returns the region specified by decorationRegion containing the given widget. The decorationRegion is a bitmask of the values described by the DecorationRegion enum.

int QDecoration::regionAt ( const QWidget * widget, const QPoint & point )   [virtual]

Returns the type of the first region of the specified top level widget containing the given point.

The return value is one of the DecorationRegion enum's values. Use the region() function to retrieve the actual region. If none of the widget's regions contain the point, this function returns None.

See also region().

void QDecoration::regionClicked ( QWidget * widget, int region )   [virtual]

This function is called whenever a region in a top level widget is clicked. The parameters specifies the widget as well as the region. Note that the region parameter is one of the DecorationRegion values.

The default implementation responds to clicks on items in the system menu, performing the requested actions.

See also regionDoubleClicked().

void QDecoration::regionDoubleClicked ( QWidget * widget, int region )   [virtual]

This function is called whenever a region in a top level widget is double clicked. The parameters specifies the widget as well as the region. Note that the region parameter is one of the DecorationRegion values.

The default implementation responds to a double click on the widget's title, toggling its size between the maximum and its normal size.

See also regionClicked().

void QDecoration::startMove ( QWidget * widget )   [static]

Starts to move the given widget by making its Title region active and grabbing the mouse input. The widget must be a top level widget.

See also DecorationRegion.

void QDecoration::startResize ( QWidget * widget )   [static]

Starts to resize the given widget by making its BottomRight region active and grabbing the mouse input. The widget must be a top level widget.

See also DecorationRegion.