qstyle.cpp

qt-x11-opensource-src-4.1.4.tar.gz源码

/****************************************************************************
**
** Copyright (C) 1992-2006 Trolltech ASA. All rights reserved.
**
** This file is part of the QtGui module of the Qt Toolkit.
**
** This file may be used under the terms of the GNU General Public
** License version 2.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 GNU
** General Public Licensing requirements will be met:
** http://www.trolltech.com/products/qt/opensource.html
**
** If you are unsure which license is appropriate for your use, please
** review the following information:
** http://www.trolltech.com/products/qt/licensing.html or contact the
** sales department at [e-mail].
**
** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
**
****************************************************************************/

#include "qstyle.h"
#include "qapplication.h"
#include "qpainter.h"
#include "qwidget.h"
#include "qbitmap.h"
#include "qpixmapcache.h"
#include "qstyleoption.h"
#include "private/qstyle_p.h"
#ifndef QT_NO_DEBUG
#include "qdebug.h"
#endif

#ifdef Q_WS_X11
#include <qx11info_x11.h>
#endif

#include <limits.h>

/*!
    \class QStyle
    \brief The QStyle class is an abstract base class that encapsulates the look and feel of a GUI.

    \ingroup appearance

    Qt contains a set of QStyle subclasses that emulate the styles of
    the different platforms supported by Qt (QWindowsStyle,
    QMacStyle, QMotifStyle, etc.). By default, these styles are built
    into the QtGui library. Styles can also be made available as
    plugins.

    Qt's built-in widgets use QStyle to perform nearly all of their
    drawing, ensuring that they look exactly like the equivalent
    native widgets. The diagram below shows a QComboBox in eight
    different styles.

    \img qstyle-comboboxes.png Eight combo boxes

    Topics:

    \tableofcontents

    \section1 Setting a Style

    The style of the entire application can be set using
    QApplication::setStyle(). It can also be specified by the user of
    the application, using the \c -style command-line option:

    \code
        ./myapplication -style motif
    \endcode

    If no style is specified, Qt will choose the most appropriate
    style for the user's platform or desktop environment.

    A style can also be set on an individual widget using
    QWidget::setStyle().

    \section1 Developing Style-Aware Custom Widgets

    If you are developing custom widgets and want them to look good on
    all platforms, you can use QStyle functions to perform parts of
    the widget drawing, such as drawItem(), drawPrimitive(),
    drawControl(), and drawComplexControl().

    Most QStyle draw functions 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

    For example, if you want to draw a focus rectangle on your
    widget, you can write:

    \quotefromfile snippets/styles/styles.cpp
    \skipto MyWidget::paintEvent
    \printuntil }

    QStyle 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, you can use QStyle to draw on any paint
    device, not just widgets, by setting the QPainter properly.

    QStyleOption has various subclasses for the various types of
    graphical elements that can be drawn. For example,
    PE_FrameFocusRect expects a QStyleOptionFocusRect argument. This is
    documented for each enum value.

    To ensure that drawing operations are as fast as possible,
    QStyleOption and its subclasses have public data members. See the
    QStyleOption class documentation for details on how to use it.

    For convenience, Qt provides the QStylePainter class, which
    combines a QStyle, a QPainter, and a QWidget. This makes it
    possible to write

    \skipto QStylePainter painter
    \printline painter
    \dots
    \skipto drawPrimitive
    \printline drawPrimitive

    instead of

    \quotefromfile snippets/styles/styles.cpp
    \skipto QPainter painter
    \printline painter
    \dots
    \skipto drawPrimitive
    \printline drawPrimitive

    \section1 Creating a Custom Style

    If you want to design a custom look and feel for your
    application, the first step is to pick one of the base styles
    provided with Qt to build your custom style from. The choice will
    depend on which existing style resembles your style the most.

    Depending on which parts of the base style you want to change,
    you must reimplement the functions that are used to draw those
    parts of the interface. To illustrate this, we will modify the
    look of the spin box arrows drawn by QWindowsStyle. The arrows
    are \e{primitive elements} that are drawn by the drawPrimitive()
    function, so we need to reimplement that function. We need the
    following class declaration:

    \quotefile snippets/customstyle/customstyle.h
    \skipto class CustomStyle
    \printuntil };

    The PE_IndicatorSpinUp and PE_IndicatorSpinDown primitive
    elements are used by QSpinBox to draw its up and down arrows.
    Here's how to reimplement drawPrimitive() to draw them
    differently:

    \quotefile snippets/customstyle/customstyle.cpp
    \skipto CustomStyle::drawPrimitive
    \printuntil QWindowsStyle::drawPrimitive
    \printline }
    \printline }

    Notice that we don't use the \c widget argument, except to pass
    it on to QWindowStyle::drawPrimitive(). As mentioned earlier, the
    information about what is to be drawn and how it should be drawn
    is specified by a QStyleOption object, so there is no need to ask
    the widget.

    If you need to use the \c widget argument to obtain additional
    information, be careful to ensure that it isn't 0 and that it is
    of the correct type before using it. For example:

    \code
        QSpinBox *spinBox = qobject_cast<QSpinBox *>(widget);
        if (spinBox) {
            ...
        }
    \endcode

    When implementing a custom style, you cannot assume that the
    widget is a QSpinBox just because the enum value is called
    PE_IndicatorSpinUp or PE_IndicatorSpinUp.

    The documentation for the \l{widgets/styles}{Styles} example
    covers this topic in more detail.

    \section1 Using a Custom Style

    There are several ways of using a custom style in a Qt
    application. The simplest way is call the
    QApplication::setStyle() static function before creating the
    QApplication object:

    \include snippets/customstyle/main.cpp

    You can call QApplication::setStyle() at any time, but by calling
    it before the constructor, you ensure that the user's preference,
    set using the \c -style command-line option, is respected.

    You may want to make your style available for use in other
    applications, some of which may not be yours and are not available for
    you to recompile. The Qt Plugin system makes it possible to create
    styles as plugins. Styles created as plugins are loaded as shared
    objects at runtime by Qt itself. Please refer to the \link
    plugins-howto.html Qt Plugin\endlink documentation for more
    information on how to go about creating a style plugin.

    Compile your plugin and put it into \c $QTDIR/plugins/styles. We
    now have a pluggable style that Qt can load automatically. To use
    your new style with existing applications, simply start the
    application with the following argument:

    \code
        ./myapplication -style custom
    \endcode

    The application will use the look and feel from the custom style you
    implemented.

    \section1 Right-to-Left Desktops

    Languages written from right to left (such as Arabic and Hebrew)
    usually also mirror the whole layout of widgets, and require the
    light to come from the screen's top-right corner instead of
    top-left.

    If you create a custom style, you should take special care when
    drawing asymmetric elements to make sure that they also look
    correct in a mirrored layout. An easy way to test your styles is
    to run applications with the \c -reverse command-line option or
    to call QApplication::setLayoutDirection() in your \c main()
    function.

    Here are some things to keep in mind when making a style work well in a
    right-to-left environment:

    \list
    \o subControlRect() and subElementRect() return rectangles in screen coordinates
    \o QStyleOption::direction indicates in which direction the item should be drawn in
    \o If a style is not right-to-left aware it will display items as if it were left-to-right
    \o visualRect(), visualPos(), and visualAlignment() are helpful functions that will
       translate from logical to screen representations.
    \o alignedRect() will return a logical rect aligned for the current direction
    \endlist

    \sa QStyleOption, QStylePainter
*/

/*!
    Constructs a style object.
*/
QStyle::QStyle()
{
}


/*!
    \internal

    Constructs a style object.
*/
QStyle::QStyle(QStylePrivate &dd)
    : QObject(dd)
{
}

/*!
    Destroys the style object.
*/
QStyle::~QStyle()
{
}

/*!
    Initializes the appearance of \a widget.

    This function is called for every widget at some point after it
    has been fully created but just \e before it is shown for 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! Reimplementing
    this function gives you a back-door through which you can change
    the appearance of a widget. With Qt 4.0's style engine you will
    rarely need to write your own polish(); instead reimplement
    drawItem(), drawPrimitive(), etc.

    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 are
    expected to work reasonably with all current and \e future
    widgets.

    \sa unpolish()
*/
void QStyle::polish(QWidget * /* widget */)
{
}

/*!
    Undoes the initialization of widget \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.

    \sa polish()
*/
void QStyle::unpolish(QWidget * /* widget */)
{
}

/*!
    \overload