Classes - Annotated - Tree - Functions - Home - Structure

QStyle Class Reference

The API for this class is under development and is subject to change.
We do not recommend the use of this class for production work at this time.

The QStyle class specifies the look and feel of a GUI. More...

#include <qstyle.h>

Inherits QObject.

Inherited by QCommonStyle.

List of all member functions.

Public Members

Static Public Members


Detailed Description

The QStyle class specifies the look and feel of a GUI.

A large number of GUI elements are common to many widgets. The QStyle class allows the look of these elements to be modified across all widgets that use the QStyle functions. It also provides two feel options: Motif and Windows.

Although it is not possible to fully enumerate the look of graphic elements and the feel of widgets in a GUI, QStyle provides a considerable amount of control and customisability.

In Qt 1.x the look and feel option for widgets was specified by a single value - the GUIStyle. Starting with Qt 2.0, this notion has been expanded to allow the look to be specified by virtual drawing functions.

Derived classes may reimplement some or all of the drawing functions to modify the look of all widgets that use those functions.

Languages written from right to left (such as hebrew and arabic) usually also mirror the whole layout of widgets. If you design a style, you should take special care when drawing asymmetric elements to make sure that they also look correct in a mirrored layout. You can start your application with -reverse to check the mirrored layout. Also notice, that for a reversed layout, the light usually comes from top right instead of top left.

The actual reverse layout is performed automatically when possible. However, for the sake of flexibility, the translation cannot be performed everywhere. The documentation for each function in the QStyle API states whether the function expects/returns logical or screen coordinates. Using logical coordinates (in ComplexControls, for example) provides great flexibility in controlling the look of a widget. Use visualRect() when necessary to translate logical coordinates into screen coordinates for drawing.


Member Type Documentation

QStyle::ComplexControl

This enum represents a ComplexControl. A ComplexControl is different from a ControlElement. ComplexControls have different behavior depending upon where the user clicks or which keys are pressed.

See also SubControl and drawComplexControl().

QStyle::ContentsType

This enum represents a ContentsType. It is used to calculate sizes for the contents of various widgets.

See also sizeFromContents().

QStyle::ControlElement

This enum represents a ControlElement. A ControlElement is part of a widget that does some action or display information to the user.

See also drawControl().

QStyle::ControlElementFlags

This enum represents flags for drawing ControlElements. Not all controls use all of these flags. Note that these flags can have different meaning for different controls. For an explanation of the relationship of various controls and flags, as well as the different meanings of the flags, see the Style overview.

QStyle::PixelMetric

This enum represents a PixelMetric. A PixelMetric is a style dependent size represented as a single pixel value.

See also pixelMetric().

QStyle::PrimitiveElement

This enum represents a style PrimitiveElement. A PrimitiveElement is a common GUI element, such as a checkbox indicator or pushbutton bevel.

For more explanation of a spin widget, see the QSpinBox documentation.

For more information on dock windows, see the QDockWindow documentation.

See also drawPrimitive().

QStyle::PrimitiveElementFlags

This enum represents flags for drawing PrimitiveElements. Not all primitives use all of these flags. Note that these flags can have different meaning for different primitives. For an explanation of the relationship of various primitives and flags, as well as the different meanings of the flags, see the Style overview.

See also drawPrimitive().

QStyle::StyleHint

This enum represents a StyleHint. A StyleHint is a general Look and/or Feel hint.

See also styleHint().

QStyle::StylePixmap

This enum represents a StylePixmap. A StylePixmap is a pixmap that can follow some existing GUI style or guideline.

See also stylePixmap().

QStyle::SubControl

This enum represents a SubControl within a ComplexControl.

See also ComplexControl.

QStyle::SubRect

This enum represents a sub-area of a widget. Style implementations would use these areas to draw the different parts of a widget.

See also subRect().


Member Function Documentation

QStyle::~QStyle () [virtual]

Destroys the style and frees all allocated resources.

void QStyle::drawComplexControl ( ComplexControl control, QPainter * p, const QWidget * widget, const QRect & r, const QColorGroup & cg, CFlags flags = CStyle_Default, SCFlags sub = SC_All, SCFlags subActive = SC_None, void ** data = 0 ) const [virtual]

Draws the ComplexControl control using the painter p in the area r. Colors are used from the color group cg. The sub argument specifies which SubControls to draw. Multiple SubControls can be OR'ed together. The subActive argument specifies which SubControl to draw as active.

The rect r should be in logical coordinates. Reimplementations of this function should use visualRect() to change the logical corrdinates into screen coordinates when using drawPrimitive() and drawControl().

The flags argument is used to control how the ComplexControl is drawn. Multiple flags can OR'ed together.

The widget argument is a pointe rto a QWidget or one of its subclasses. The widget can be cast to the appropriate type based on the value of control. The data argument can be used to pass extra information required when drawing the ComplexControl. Note that data can be zero even for ComplexControls that make use of the extra data. See the table below for the appropriate widget and data casts:

ComplexControl Widget Cast Data Data Cast Notes
CC_SpinWidget const QSpinWidget * unused
CC_ComboBox const QComboBox * unused
CC_ScrollBar const QScrollBar * data[0] int * position in pixels for the start of the slider handle.
CC_Slider const QSlider * data[0] int * position in pixel for the start of the slider handle.
CC_ToolButton const QToolButton * data[0] bool * when the tool button has auto-raise enabled, this bool is TRUE when the mouse is over the tool button, FALSE otherwise.
data[1] bool * this bool TRUE when the tool button only contains an arrow, FALSE otherwise.
data[2] ArrowType * when the tool button only contains an arrow, this is the arrow type.
CC_TitleBar const QWidget * unused
CC_ListView const QListView * data[0] QListViewItem * pointer to the item that needs branches drawn

See also ComplexControl and SubControl.

void QStyle::drawComplexControlMask ( ComplexControl control, QPainter * p, const QWidget * widget, const QRect & r, void ** data = 0 ) const [virtual]

Draw a bitmask for the ComplexControl control using the painter p in the area r. See the documentation for drawComplexControl() for an explanation on the use of the widget and data arguments.

The rect r should be in logical coordinates. Reimplementations of this function should use visualRect() to change the logical corrdinates into screen coordinates when using drawPrimitive() and drawControl().

See also drawComplexControl and ComplexControl.

void QStyle::drawControl ( ControlElement element, QPainter * p, const QWidget * widget, const QRect & r, const QColorGroup & cg, CFlags how = CStyle_Default, void ** data = 0 ) const [virtual]

Draws the ControlElement element using the painter p in the area r. Colors are used from the color group cg.

The rect r should be in screen coordinates.

The how argument is used to control how the ControlElement is drawn. Multiple flags can be OR'ed together.

The widget argument is a pointer to a QWidget or one of its subclasses. The widget can be cast to the appropriate type based on the value of element. The data argument can be used to pass extra information required when drawing the ControlElement. Note that data can be zero even for ControlElements that make use of the extra data. See the table below for the appropriate widget and data casts:

ControlElement Widget Cast Data Data Cast Notes
CE_PushButton const QPushButton * unused
CE_PushButtonLabel const QPushButton * unused
CE_CheckBox const QCheckBox * unused
CE_CheckboxLabel const QCheckBox * unused
CE_RadioButton const QRadioButton * unused
CE_RadioButtonLabel const QRadioButton * unused
CE_TabBarTab const QTabBar * unused
CE_TabBarLabel const QTabBar * data[0] QTab * pointer to the QTab being drawn.
CE_ProgressBarGroove const QProgressBar * unused
CE_ProgressBarContents const QProgressBar * unused
CE_ProgressBarLabel const QProgressBar * unused
CE_PopupMenuItem const QPopupMenu * data[0] QMenuItem * pointer to the menu item being drawn.
data[1] int * width of the tab column where key accelerators are drawn.
data[2] int * maximum width of the check column where checkmarks and iconsets are drawn.
CE_MenuBarItem const QMenuBar * data[0] QMenuItem * pointer to the menu item being drawn.

See also ControlElement and ControlElementFlags.

void QStyle::drawControlMask ( ControlElement element, QPainter * p, const QWidget * widget, const QRect & r, void ** data = 0 ) const [virtual]

Draw a bitmask for the ControlElement element using the painter p in the area \r. See the documentation for drawControl() for an explanation on use of the widget and data arguments.

The rect r should be in screen coordinates.

See also drawControl() and ControlElement.

void QStyle::drawItem ( QPainter * p, const QRect & r, int flags, const QColorGroup & g, bool enabled, const QPixmap * pixmap, const QString & text, int len = -1, const QColor * penColor = 0 ) const [virtual]

Draws the text or pixmap in rectangle r using painter p and color group g. The pen color is specified with penColor. The enabled bool indicates whether or not the item is enabled; when reimplementing this bool should influence how the item is drawn. If len is -1 (the default) all the text is drawn; otherwise only the first len characters of text are drawn. The text is aligned according to the alignment flags (see Qt::AlignmentFlags).

void QStyle::drawPrimitive ( PrimitiveElement op, QPainter * p, const QRect & r, const QColorGroup & cg, PFlags flags = PStyle_Default, void ** data = 0 ) const [virtual]

Draws the style PrimitiveElement op using the painter p in the area r. Colors are used from the color group cg.

The rect r should be in screen coordinates.

The flags argument is used to control how the PrimitiveElement is drawn. Multiple flags can be OR'ed together.

For example, a pressed button would be drawn with the flags PStyle_Enabled and PStyle_Down.

The data argument can be used to control how various PrimitiveElements are drawn. Note that data can be zero even for PrimitiveElementss that make use of extra data. When data is non-zero, the data is used as follows:

PrimitiveElement Data Data Cast Notes
PE_FocusRect data[0] const QColor * pointer to the background color the on which focus rect is being drawn.
PE_Panel data[0] int * line width for drawing the panel.
PE_PanelPopup data[0] int * line width for drawing the panel.
PE_PanelMenuBar data[0] int * line width for drawing the panel.
PE_PanelDockWindow data[0] int * line width for drawing the panel.
PE_GroupBoxFrame data[0] int * frame shape for the group box. See the documentation for QFrame for more details.
data[1] int * frame shadow for the group box.
data[2] int * line width for the group box.
data[3] int * mid-line width for the group box.

For all other PrimitiveElements, data is unused.

See also PrimitiveElement and PrimitiveElementFlags.

GUIStyle QStyle::guiStyle () const

This function is obsolete. It is provided to keep old source working. We strongly advise against using it in new code.

Returns an indicator to the additional "feel" component of a style. Current supported values are Qt::WindowsStyle and Qt::MotifStyle.

QRect QStyle::itemRect ( QPainter * p, const QRect & r, int flags, bool enabled, const QPixmap * pixmap, const QString & text, int len = -1 ) const [virtual]

Returns the appropriate area (see below) within rectangle r in which to draw the text or pixmap using painter p. If len is -1 (the default) all the text is drawn; otherwise only the first len characters of text are drawn. The text is aligned according to the alignment flags (see Qt::AlignmentFlags).

If r is larger than the area needed to render the text the rectangle that is returned will be offset within r in accordance with the alignment flags. For example if flags is AlignVCenter | AlignHCenter the returned rectangle will be centered within r. If r is smaller than the area needed the rectangle that is returned will be larger than r (the smallest rectangle large enough to render the text or pixmap).

QStyle::operator GUIStyle () const

This function is obsolete. It is provided to keep old source working. We strongly advise against using it in new code.

bool QStyle::operator!= ( GUIStyle s ) const

This function is obsolete. It is provided to keep old source working. We strongly advise against using it in new code.

bool QStyle::operator== ( GUIStyle s ) const

This function is obsolete. It is provided to keep old source working. We strongly advise against using it in new code.

int QStyle::pixelMetric ( PixelMetric metric, const QWidget * widget = 0 ) const [virtual]

Returns the pixel metric for metric. The widget argument is a pointer to a QWidget of one of its subclasses. The widget can be cast to the appropriate type based on the value of metric. Note that widget can be zero even for PixelMetrics that make use of widget. See the table below for the appropriate widget casts:

PixelMetric Widget Cast
PM_SliderControlThickness const QSlider *
PM_SliderLength const QSlider *
PM_SliderTickmarkOffset const QSlider *
PM_SliderSpaceAvailable const QSlider *
PM_TabBarTabOverlap const QTabBar *
PM_TabBarTabHSpace const QTabBar *
PM_TabBarTabVSpace const QTabBar *
PM_TabBarBaseHeight const QTabBar *
PM_TabBarBaseOverlap const QTabBar *

See also PixelMetric.

void QStyle::polish ( QWidget * ) [virtual]

Initializes the appearance of a widget.

This function is called for every widget at some point after it has been fully created but just before it is shown the very first time.

Reasonable actions in this function might be to call QWidget::setBackgroundMode for the widget. An example of highly unreasonable use would be setting the geometry!

The QWidget::inherits() function may provide enough information to allow class-specific customizations. But be careful not to hard-code things too much because new QStyle subclasses will be expected to work reasonably with all current and future widgets.

See also unPolish(QWidget*).

Examples: themes/metal.cpp and themes/wood.cpp.

void QStyle::polish ( QApplication * ) [virtual]

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Late initialization of the QApplication object.

See also unPolish(QApplication*).

void QStyle::polish ( QPalette & ) [virtual]

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

The style may have certain requirements for color palettes. In this function it has the chance to change the palette according to these requirements.

See also QPalette and QApplication::setPalette().

void QStyle::polishPopupMenu ( QPopupMenu * ) [virtual]

Polishes the popup menu according to the GUI style. This usually means setting the mouse tracking (QPopupMenu::setMouseTracking()) and whether the menu is checkable by default (QPopupMenu::setCheckable()).

SubControl QStyle::querySubControl ( ComplexControl control, const QWidget * widget, const QPoint & pos, void ** data = 0 ) const [virtual]

Returns the SubControl for widget at the point pos. The widget argument is a pointer to a QWidget or one of its subclasses,. The widget can be case to the appropriate type based on the value of control. The data argument can be used to pass extra information required when drawing the ComplexControl. Note that data can be zero even for ComplexControls that make use of the extra data. See the documentation for drawComplexControl() for an explanation of the widget and data arguments.

Note that pos is passed in screen coordinates. When using querySubControlMetrics() to check for hits and misses, use visualRect() to change the logical coordinates into screen coordinates.

See also drawComplexControl(), ComplexControl, SubControl and querySubControlMetrics().

QRect QStyle::querySubControlMetrics ( ComplexControl control, const QWidget * widget, SubControl subcontrol, void ** data = 0 ) const [virtual]

Returns the rect for the SubControl subcontrol for widget in logical coordinates.

The widget argument is a pointer to a QWidget or one of its subclasses. The widget can be cast to the appropriate type based on the value of control. The data argument can be used to pass extra information required when drawing the ComplexControl. Note that data can be zero even for ComplexControls that make use of the extra data. See the documentation for drawComplexControl() for an explanation of the widget and data arguments.

See also drawComplexControl(), ComplexControl and SubControl.

QSize QStyle::sizeFromContents ( ContentsType contents, const QWidget * widget, const QSize & contentsSize, void ** data = 0 ) const [virtual]

Returns the size of widget based on the contents size contentsSize.

The widget argument is a pointer to a QWidget or one of its subclasses. The widget can be cast to the appropriate type based on the value of contents. The data argument can be used to pass extra information required when calculating the size. Note that data can be zero even for ContentsTypes that make use of the extra data. See the table below for the appropriate widget and data casts:

ContentsType Widget Cast Data Data Cast Notes
CT_PushButton const QPushButton * unused
CT_CheckBox const QCheckBox * unused
CT_RadioButton const QRadioButton * unused
CT_ToolButton const QToolButton * unused
CT_ComboBox const QComboBox * unused
CT_Splitter const QSplitter * unused
CT_DockWindow const QDockWindow * unused
CT_ProgressBar const QProgressBar * unused
CT_PopupMenuItem const QPopupMenu * data[0] QMenuItem * pointer to the menu item to use when calculating the size

See also ContentsType.

int QStyle::styleHint ( StyleHint stylehint, const QWidget * widget = 0, void *** returnData = 0 ) const [virtual]

Returns the style hint stylehint for widget. Currently, widget and returnData are unused, and are provided only for future development considerations.

For explanation on the return values of this function, see the StyleHint documentation.

See also StyleHint.

QPixmap QStyle::stylePixmap ( StylePixmap stylepixmap, const QWidget * widget = 0, void ** data = 0 ) const [virtual]

Returns a pixmap for stylepixmap.

The data argument can be used to pass extra information required when drawing the ControlElement. Note that data can be zero even for StylePixmaps that make use of the extra data. Currently, the data argument is unused.

The widget argument is a pointer to a QWidget or one of its subclasses. The widget can be cast to the appropriate type based on the value of stylepixmap. See the table below for the appropriate widget casts:

StylePixmap Widget Cast
SP_TitleBarMinButton const QWidget *
SP_TitleBarMaxButton const QWidget *
SP_TitleBarCloseButton const QWidget *
SP_TitleBarNormalButton const QWidget *
SP_TitleBarShadeButton const QWidget *
SP_TitleBarUnshadeButton const QWidget *
SP_DockWindowCloseButton const QDockWindow *

See also StylePixmap.

QRect QStyle::subRect ( SubRect subrect, const QWidget * widget ) const [virtual]

Returns the sub-area subrect for widget in logical coordinates.

The widget argument is a pointer to a QWidget or one of its subclasses. The widget can be cast to the appropriate type based on the value of subrect. See the table below for the appropriate widget casts:

SubRect Widget Cast
SR_PushButtonContents const QPushButton *
SR_PushButtonFocusRect const QPushButton *
SR_CheckBoxIndicator const QCheckBox *
SR_CheckBoxContents const QCheckBox *
SR_CheckBoxFocusRect const QCheckBox *
SR_RadioButtonIndicator const QRadioButton *
SR_RadioButtonContents const QRadioButton *
SR_RadioButtonFocusRect const QRadioButton *
SR_ComboBoxFocusRect const QComboBox *
SR_DockWindowHandleRect const QWidget *
SR_ProgressBarGroove const QProgressBar *
SR_ProgressBarContents const QProgressBar *
SR_ProgressBarLabel const QProgressBar *

NOTE: The tear-off handle (SR_DockWindowHandleRect) for QDockWindow is a private class. You can gain access to the QDockWindow by using the QWidget::parentWidget() function. For example:

  if (! widget->parentWidget())
      return;
  const QDockWindow *dw = (const QDockWindow *) widget->parentWidget();
  

See also SubRect.

void QStyle::unPolish ( QWidget * ) [virtual]

Undoes the initialization of a widget's appearance.

This function is the counterpart to polish. It is called for every polished widget when the style is dynamically changed. The former style has to unpolish its settings before the new style can polish them again.

See also polish(QWidget*).

Examples: themes/metal.cpp and themes/wood.cpp.

void QStyle::unPolish ( QApplication * ) [virtual]

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Undoes the application polish.

See also polish(QApplication*).

QRect QStyle::visualRect ( const QRect & logical, const QWidget * w ) [static]

Returns the rect logical in screen coordinates. The bounding rect for widget w is used to perform the translation. This function is provided to aid style implementors in supporting right-to-left mode.

See also QApplication::reverseLayout().

QRect QStyle::visualRect ( const QRect & logical, const QRect & bounding ) [static]

This is an overloaded member function, provided for convenience. It behaves essentially like the above function.

Returns the rect logical in screen coordinates. The rect bounding is used to perform the translation. This function is provided to aid style implementors in supporting right-to-left mode.

See also QApplication::reverseLayout().


Search the documentation, FAQ, qt-interest archive and more (uses www.trolltech.com):


This file is part of the Qt toolkit, copyright © 1995-2001 Trolltech, all rights reserved.


Copyright © 2001 TrolltechTrademarks
Qt version 3.0.0-beta2