Update copyright headers
[qt:qt.git] / 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 */