diff options
Diffstat (limited to 'doc/src/porting/qt4-styles.qdoc')
| -rw-r--r-- | doc/src/porting/qt4-styles.qdoc | 157 |
1 files changed, 157 insertions, 0 deletions
diff --git a/doc/src/porting/qt4-styles.qdoc b/doc/src/porting/qt4-styles.qdoc new file mode 100644 index 0000000..4134962 --- /dev/null +++ b/doc/src/porting/qt4-styles.qdoc @@ -0,0 +1,157 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at http://qt.nokia.com/contact. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page qt4-styles.html + \title The Qt 4 Style API + + \contentspage {What's New in Qt 4}{Home} + \previouspage The Network Module in Qt 4 + \nextpage Thread Support in Qt 4 + + Qt's style API is responsible for performing the widget drawing + for built-in widgets. The Qt 4 style API has been revised to make + it possible for a style to draw widgets without calling any + functions on the widget. + + Because Qt 4 is split across multiple libraries, Qt needed this + update to be able to draw widgets from other libraries than + QtGui. For application developers, this has other benefits, such + as more managable parameter lists and the possibility of drawing + any graphical element without having a widget of a specific + type. + + \section1 General Overview + + The QStyle class is an abstract base class that encapsulates + the look and feel of a GUI. Qt's built-in widgets use it to + perform nearly all of their drawing, ensuring that they look + exactly like the equivalent native widgets. + + Most draw functions now take four arguments: + + \list + \o an enum value specifying which graphical element to draw + \o a QStyleOption specifying how and where to render that element + \o a QPainter that should be used to draw the element + \o a QWidget on which the drawing is performed (optional) + \endlist + + The style gets all the information it needs to render the + graphical element from QStyleOption. The widget is passed as the + last argument in case the style needs it to perform special + effects (such as animated default buttons on Mac OS X), but it + isn't mandatory. In fact, QStyle can be used to draw on any + paint device, not just widgets, by setting the QPainter properly. + + Thanks to QStyleOption, it is now possible to make QStyle draw + widgets without linking in any code for the widget. This is how + Qt's built-in styles can draw Qt 3 widgets such as + Q3ListView without necessarily linking against the Qt3Support + library. Another significant benefit of the new approach is that + it's now possible to use \l{QStyle}'s draw functions on other + widgets than the built-in widgets; for example, you can draw a + combobox on any widget, not just on a QComboBox. + + QStyleOption has various subclasses for the various types of + graphical elements that can be drawn, and it's possible to create + custom subclasses. For example, the QStyle::PE_FrameFocusRect + element expects a QStyleOptionFocusRect argument. This is + documented for each enum value. + + When reimplementing QStyle functions that take a + QStyleOption parameter, you often need to cast the + QStyleOption to a subclass (e.g., QStyleOptionFocusRect). For + safety, you can use qstyleoption_cast() to ensure that the + pointer type is correct. If the object isn't of the right type, + qstyleoption_cast() returns 0. For example: + + \snippet doc/src/snippets/code/doc_src_qt4-styles.qdoc 0 + + For performance reasons, there are few member functions and the + access to the variables is direct. This "low-level" feel makes + the structures use straightforward and emphasizes that these are + simply parameters used by the style functions. In addition, the + caller of a QStyle function usually creates QStyleOption + objects on the stack. This combined with Qt's extensive use of + \l{implicit sharing} for types such as QString, QPalette, and + QColor ensures that no memory allocation needlessly takes place. + (Dynamic memory allocation can be an expensive operation, + especially when drawing very often in a short time.) + + \section1 Example Code + + The following code snippet illustrates how to use QStyle to + draw the focus rectangle from a custom widget's paintEvent(): + + \snippet doc/src/snippets/code/doc_src_qt4-styles.qdoc 1 + + The next example shows how to derive from an existing style to + customize the look of a graphical element: + + \snippet doc/src/snippets/customstyle/customstyle.h 0 + \codeline + \snippet doc/src/snippets/customstyle/customstyle.cpp 2 + \snippet doc/src/snippets/customstyle/customstyle.cpp 3 + \snippet doc/src/snippets/customstyle/customstyle.cpp 4 + + See also the \l{Styles Example} for a more detailed description of + how custom styles can be created. + + \section1 Comparison with Qt 3 + + The QStyle class has a similar API in Qt 4 as in Qt 3, with + more or less the same functions. What has changed is the + signature of the functions and the role played by QStyleOption. + For example, here's the signature of the QStyle::drawControl() + function in Qt 3: + + \snippet doc/src/snippets/code/doc_src_qt4-styles.qdoc 2 + + Here's the signature of the same function in Qt 4: + + \snippet doc/src/snippets/code/doc_src_qt4-styles.qdoc 3 + + In Qt 3, some of the information required to draw a graphical + element was stored in a QStyleOption parameter, while the rest + was deduced by querying the widget. In Qt 4, everything is stored + in the QStyleOption parameter. +*/ |