/****************************************************************************

**

** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

** All rights reserved.

** Contact: Nokia Corporation (qt-info@nokia.com)

**

** This file is part of the QtGui module 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 Technology Preview License Agreement accompanying

** this package.

**

** 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.1, included in the file LGPL_EXCEPTION.txt in this package.

**

** If you have questions regarding the use of this file, please contact

** Nokia at qt-info@nokia.com.

**

**

**

**

**

**

**

**

** $QT_END_LICENSE$

**

****************************************************************************/

#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>

QT_BEGIN_NAMESPACE

static const int MaxBits = 8 * sizeof(QSizePolicy::ControlType);

static int unpackControlTypes(QSizePolicy::ControlTypes controls, QSizePolicy::ControlType *array)

{

    if (!controls)

        return 0;

    // optimization: exactly one bit is set

    if ((controls & (controls - 1)) == 0) {

        array[0] = QSizePolicy::ControlType(uint(controls));

        return 1;

    }

    int count = 0;

    for (int i = 0; i < MaxBits; ++i) {

        if (uint bit = (controls & (0x1 << i)))

            array[count++] = QSizePolicy::ControlType(bit);

    }

    return count;

}

/*!

    \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 the

    QApplication::setStyle() function. It can also be specified by the

    user of the application, using the \c -style command-line option:

    \snippet doc/src/snippets/code/src_gui_styles_qstyle.cpp 0

    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 the

    QWidget::setStyle() function.

    \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 drawItemText(), drawItemPixmap(),

    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:

    \snippet doc/src/snippets/styles/styles.cpp 1

    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.

    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

    \snippet doc/src/snippets/styles/styles.cpp 5

    \dots

    \snippet doc/src/snippets/styles/styles.cpp 7

    instead of

    \snippet doc/src/snippets/styles/styles.cpp 2

    \dots

    \snippet doc/src/snippets/styles/styles.cpp 3

    \section1 Creating a Custom Style

    You can create a custom look and feel for your application by

    creating a custom style. There are two approaches to creating a

    custom style. In the static approach, you either choose an

    existing QStyle class, subclass it, and reimplement virtual

    functions to provide the custom behavior, or you create an entire

    QStyle class from scratch. In the dynamic approach, you modify the

    behavior of your system style at runtime. The static approach is

    described below. The dynamic approach is described in QProxyStyle.

    The first step in the static approach is to pick one of the styles

    provided by Qt from which you will build your custom style. Your

    choice of QStyle class will depend on which style resembles your

    desired style the most. The most general class that you can use as

    a base is QCommonStyle (not QStyle). This is because Qt requires

    its styles to be \l{QCommonStyle}s.

    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:

    \snippet doc/src/snippets/customstyle/customstyle.h 0

    To draw its up and down arrows, QSpinBox uses the

    PE_IndicatorSpinUp and PE_IndicatorSpinDown primitive elements.

    Here's how to reimplement the drawPrimitive() function to draw

    them differently:

    \snippet doc/src/snippets/customstyle/customstyle.cpp 2

    \snippet doc/src/snippets/customstyle/customstyle.cpp 3

    \snippet doc/src/snippets/customstyle/customstyle.cpp 4

    Notice that we don't use the \c widget argument, except to pass it

    on to the QWindowStyle::drawPrimitive() function. 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:

    \snippet doc/src/snippets/customstyle/customstyle.cpp 0

    \dots

    \snippet doc/src/snippets/customstyle/customstyle.cpp 1

    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_IndicatorSpinDown.

    The documentation for the \l{widgets/styles}{Styles} example

    covers this topic in more detail.

    \warning Qt style sheets are currently not supported for custom QStyle

    subclasses. We plan to address this in some future release.

    \section1 Using a Custom Style

    There are several ways of using a custom style in a Qt

    application. The simplest way is to pass the custom style to the

    QApplication::setStyle() static function before creating the

    QApplication object:

    \snippet snippets/customstyle/main.cpp using a custom style

    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 custom style available for use in other

    applications, which may not be yours and hence 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 Qt's \c plugins/styles

    directory. 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:

    \snippet doc/src/snippets/code/src_gui_styles_qstyle.cpp 1

    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

    \section1 Styles in Item Views

    The painting of items in views is performed by a delegate. Qt's

    default delegate, QStyledItemDelegate, is also used for for calculating bounding

    rectangles of items, and their sub-elements for the various kind

    of item \l{Qt::ItemDataRole}{data roles}

    QStyledItemDelegate supports. See the QStyledItemDelegate class

    description to find out which datatypes and roles are supported. You

    can read more about item data roles in \l{Model/View Programming}.

    When QStyledItemDelegate paints its items, it draws

    CE_ItemViewItem, and calculates their size with CT_ItemViewItem.

    Note also that it uses SE_ItemViewItemText to set the size of

    editors. When implementing a style to customize drawing of item

    views, you need to check the implementation of QCommonStyle (and

    any other subclasses from which your style

    inherits). This way, you find out which and how

    other style elements are painted, and you can then reimplement the

    painting of elements that should be drawn differently.

    We include a small example where we customize the drawing of item

    backgrounds.

    \snippet doc/src/snippets/customviewstyle.cpp 0

    The primitive element PE_PanelItemViewItem is responsible for

    painting the background of items, and is called from

    \l{QCommonStyle}'s implementation of CE_ItemViewItem.

    To add support for drawing of new datatypes and item data roles,

    it is necessary to create a custom delegate. But if you only

    need to support the datatypes implemented by the default

    delegate, a custom style does not need an accompanying

    delegate. The QStyledItemDelegate class description gives more

    information on custom delegates.

    The drawing of item view headers is also done by the style, giving

    control over size of header items and row and column sizes.

    \sa QStyleOption, QStylePainter, {Styles Example},

        {Implementing Styles and Style Aware Widgets}, QStyledItemDelegate

*/

/*!

    Constructs a style object.

*/

QStyle::QStyle()

    : QObject(*new QStylePrivate)

{

    Q_D(QStyle);

    d->proxyStyle = this;

}

/*!

    \internal

    Constructs a style object.

*/

QStyle::QStyle(QStylePrivate &dd)

    : QObject(dd)

{

  Q_D(QStyle);

  d->proxyStyle = this;

}

/*!

    Destroys the style object.

*/

QStyle::~QStyle()

{

}

/*!

    Initializes the appearance of the given \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.

    Note that the default implementation does nothing. Reasonable

    actions in this function might be to call the

    QWidget::setBackgroundMode() function for the widget. Do not use

    the function to set, for example, the geometry; reimplementing

    this function do provide a back-door through which the appearance

    of a widget can be changed, but with Qt 4.0's style engine there

    is rarely necessary to implement this function; reimplement the

    drawItemPixmap(), drawItemText(), drawPrimitive(), etc. instead.

    The QWidget::inherits() function may provide enough information to

    allow class-specific customizations. But because new QStyle

    subclasses are expected to work reasonably with all current and \e

    future widgets, limited use of hard-coded customization is

    recommended.

    \sa unpolish()

*/

void QStyle::polish(QWidget * /* widget */)

{

}

/*!

    Uninitialize the given \a{widget}'s appearance.

    This function is the counterpart to polish(). It is called for

    every polished widget whenever the style is dynamically changed;

    the former style has to unpolish its settings before the new style

    can polish them again.

    Note that unpolish() will only be called if the widget is

    destroyed.  This can cause problems in some cases, e.g, if you

    remove a widget from the UI, cache it, and then reinsert it after

    the style has changed; some of Qt's classes cache their widgets.

    \sa polish()

*/

void QStyle::unpolish(QWidget * /* widget */)

{

}

/*!

    \fn void QStyle::polish(QApplication * application)

    \overload

    Late initialization of the given \a application object.

*/

void QStyle::polish(QApplication * /* app */)

{

}

/*!