doc/src/porting/qt4-styles.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2015 The Qt Company Ltd.
   4 ** Contact: http://www.qt.io/licensing/
   5 **
   6 ** This file is part of the documentation of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:FDL$
   9 ** Commercial License Usage
  10 ** Licensees holding valid commercial Qt licenses may use this file in
  11 ** accordance with the commercial license agreement provided with the
  12 ** Software or, alternatively, in accordance with the terms contained in
  13 ** a written agreement between you and The Qt Company. For licensing terms
  14 ** and conditions see http://www.qt.io/terms-conditions. For further
  15 ** information use the contact form at http://www.qt.io/contact-us.
  16 **
  17 ** GNU Free Documentation License Usage
  18 ** Alternatively, this file may be used under the terms of the GNU Free
  19 ** Documentation License version 1.3 as published by the Free Software
  20 ** Foundation and appearing in the file included in the packaging of
  21 ** this file.  Please review the following information to ensure
  22 ** the GNU Free Documentation License version 1.3 requirements
  23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
  24 ** $QT_END_LICENSE$
  25 **
  26 ****************************************************************************/
  27
  28 /*!
  29     \page qt4-styles.html
  30     \title The Qt 4 Style API
  31
  32     \contentspage {What's New in Qt 4}{Home}
  33     \previouspage The Network Module in Qt 4
  34     \nextpage Thread Support in Qt 4
  35
  36     Qt's style API is responsible for performing the widget drawing
  37     for built-in widgets. The Qt 4 style API has been revised to make
  38     it possible for a style to draw widgets without calling any
  39     functions on the widget.
  40
  41     Because Qt 4 is split across multiple libraries, Qt needed this
  42     update to be able to draw widgets from other libraries than
  43     QtGui. For application developers, this has other benefits, such
  44     as more managable parameter lists and the possibility of drawing
  45     any graphical element without having a widget of a specific
  46     type.
  47
  48     \section1 General Overview
  49
  50     The QStyle class is an abstract base class that encapsulates
  51     the look and feel of a GUI. Qt's built-in widgets use it to
  52     perform nearly all of their drawing, ensuring that they look
  53     exactly like the equivalent native widgets.
  54
  55     Most draw functions now take four arguments:
  56
  57     \list
  58     \o an enum value specifying which graphical element to draw
  59     \o a QStyleOption specifying how and where to render that element
  60     \o a QPainter that should be used to draw the element
  61     \o a QWidget on which the drawing is performed (optional)
  62     \endlist
  63
  64     The style gets all the information it needs to render the
  65     graphical element from QStyleOption. The widget is passed as the
  66     last argument in case the style needs it to perform special
  67     effects (such as animated default buttons on Mac OS X), but it
  68     isn't mandatory. In fact, QStyle can be used to draw on any
  69     paint device, not just widgets, by setting the QPainter properly.
  70
  71     Thanks to QStyleOption, it is now possible to make QStyle draw
  72     widgets without linking in any code for the widget. This is how
  73     Qt's built-in styles can draw Qt 3 widgets such as
  74     Q3ListView without necessarily linking against the Qt3Support
  75     library. Another significant benefit of the new approach is that
  76     it's now possible to use \l{QStyle}'s draw functions on other
  77     widgets than the built-in widgets; for example, you can draw a
  78     combobox on any widget, not just on a QComboBox.
  79
  80     QStyleOption has various subclasses for the various types of
  81     graphical elements that can be drawn, and it's possible to create
  82     custom subclasses. For example, the QStyle::PE_FrameFocusRect
  83     element expects a QStyleOptionFocusRect argument. This is
  84     documented for each enum value.
  85
  86     When reimplementing QStyle functions that take a
  87     QStyleOption parameter, you often need to cast the
  88     QStyleOption to a subclass (e.g., QStyleOptionFocusRect). For
  89     safety, you can use qstyleoption_cast() to ensure that the
  90     pointer type is correct. If the object isn't of the right type,
  91     qstyleoption_cast() returns 0. For example:
  92
  93     \snippet doc/src/snippets/code/doc_src_qt4-styles.cpp 0
  94
  95     For performance reasons, there are few member functions and the
  96     access to the variables is direct. This "low-level" feel makes
  97     the structures use straightforward and emphasizes that these are
  98     simply parameters used by the style functions. In addition, the
  99     caller of a QStyle function usually creates QStyleOption
 100     objects on the stack. This combined with Qt's extensive use of
 101     \l{implicit sharing} for types such as QString, QPalette, and
 102     QColor ensures that no memory allocation needlessly takes place.
 103     (Dynamic memory allocation can be an expensive operation,
 104     especially when drawing very often in a short time.)
 105
 106     \section1 Example Code
 107
 108     The following code snippet illustrates how to use QStyle to
 109     draw the focus rectangle from a custom widget's paintEvent():
 110
 111     \snippet doc/src/snippets/code/doc_src_qt4-styles.cpp 1
 112
 113     The next example shows how to derive from an existing style to
 114     customize the look of a graphical element:
 115
 116     \snippet doc/src/snippets/customstyle/customstyle.h 0
 117     \codeline
 118     \snippet doc/src/snippets/customstyle/customstyle.cpp 2
 119     \snippet doc/src/snippets/customstyle/customstyle.cpp 3
 120     \snippet doc/src/snippets/customstyle/customstyle.cpp 4
 121
 122     See also the \l{Styles Example} for a more detailed description of
 123     how custom styles can be created.
 124
 125     \section1 Comparison with Qt 3
 126
 127     The QStyle class has a similar API in Qt 4 as in Qt 3, with
 128     more or less the same functions. What has changed is the
 129     signature of the functions and the role played by QStyleOption.
 130     For example, here's the signature of the QStyle::drawControl()
 131     function in Qt 3:
 132
 133     \snippet doc/src/snippets/code/doc_src_qt4-styles.cpp 2
 134
 135     Here's the signature of the same function in Qt 4:
 136
 137     \snippet doc/src/snippets/code/doc_src_qt4-styles.cpp 3
 138
 139     In Qt 3, some of the information required to draw a graphical
 140     element was stored in a QStyleOption parameter, while the rest
 141     was deduced by querying the widget. In Qt 4, everything is stored
 142     in the QStyleOption parameter.
 143 */