← Back to branch summary

~oif-team/ubuntu/natty/qt4-x11/xi2.1

« back to all changes in this revision

Viewing changes to doc/src/porting/qt4-styles.qdoc

  • Committer: Bazaar Package Importer
  • Author(s): Alessandro Ghersi
  • Date: 2009-11-02 18:30:08 UTC
  • mfrom: (1.2.2 upstream)
  • mto: (15.2.5 experimental)
  • mto: This revision was merged to the branch mainline in revision 88.
  • Revision ID: james.westby@ubuntu.com-20091102183008-b6a4gcs128mvfb3m
Tags: upstream-4.6.0~beta1
Import upstream version 4.6.0~beta1

Show diffs side-by-side

added added

removed removed

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