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

**

** 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 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 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$

**

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

/*!

    \example qws/simpledecoration

    \title Simple Decoration Example

    \ingroup qt-embedded

    The Simple Decoration example shows how to create a custom window decoration

    for embedded applications.

    \image embedded-simpledecoration-example.png

    By default, Qt for Embedded Linux applications display windows with one of

    the standard window decorations provided by Qt which are perfectly suitable

    for many situations. Nonetheless, for certain applications and devices, it

    is necessary to provide custom window decorations.

    In this document, we examine the fundamental features of custom window

    decorations, and create a simple decoration as an example.

    \section1 Styles and Window Decorations

    On many platforms, the style used for the contents of a window (including

    scroll bars) and the style used for the window decorations (the title bar,

    window borders, close, maximize and other buttons) are handled differently.

    This is usually because each application is responsible for rendering the

    contents of its own windows and the window manager renders the window

    decorations.

    Although the situation is not quite like this on Qt for Embedded Linux

    because QApplication automatically handles window decorations as well,

    there are still two style mechanisms at work: QStyle and its associated

    classes are responsible for rendering widgets and subclasses of QDecoration

    are responsible for rendering window decorations.

    \image embedded-simpledecoration-example-styles.png

    Three decorations are provided with Qt for Embedded Linux: \e default is

    a basic style, \e windows resembles the classic Windows look and feel,

    and \e styled uses the QStyle classes for QMdiSubWindow to draw window

    decorations. Of these, \e styled is the most useful if you want to impose

    a consistent look and feel, but the window decorations may be too large

    for some use cases.

    If none of these built-in decorations are suitable, a custom style can

    easily be created and used. To do this, we simply need to create a

    subclass of QDecorationDefault and apply it to a QApplication instance

    in a running application.

    \section1 MyDecoration Class Definition

    The \c MyDecoration class is a subclass of QDecorationDefault, a subclass

    of QDecoration that provides reasonable default behavior for a decoration:

    \snippet examples/qws/simpledecoration/mydecoration.h decoration class definition

    We only need to implement a constructor and reimplement the

    \l{QDecorationDefault::}{region()} and \l{QDecorationDefault::}{paint()}

    functions to provide our own custom appearance for window decorations.

    To make things fairly general, we provide a number of private variables

    to hold parameters which control certain aspects of the decoration's

    appearance. We also define some data structures that we will use to

    relate buttons in the window decorations to regions.

    \section1 MyDecoration Class Implementation

    In the constructor of the \c MyDecoration class, we set up some default

    values for the decoration, specifying a thin window border, a title

    bar that is just taller than the buttons it will hold, and we create a

    list of buttons that we support:

    \snippet examples/qws/simpledecoration/mydecoration.cpp constructor start

    We map each of these Qt::WindowFlags to QDecoration::DecorationRegion

    enum values to help with the implementation of the

    \l{#Finding Regions}{region() function implementation}.

    \snippet examples/qws/simpledecoration/mydecoration.cpp map window flags to decoration regions

    In this decoration, we implement the buttons used in the decoration as

    pixmaps. To help us relate regions of the window to these, we define

    mappings between each \l{QDecoration::}{DecorationRegion} and its

    corresponding pixmap for two situations: when a window is shown normally

    and when it has been maximized. This is purely for cosmetic purposes.

    \snippet examples/qws/simpledecoration/mydecoration.cpp map decoration regions to pixmaps

    We finish the constructor by defining the regions for buttons that we

    understand. This will be useful when we are asked to give regions for

    window decoration buttons.

    \snippet examples/qws/simpledecoration/mydecoration.cpp constructor end

    \section2 Finding Regions

    Each decoration needs to be able to describe the regions used for parts

    of the window furniture, such as the close button, window borders and

    title bar. We reimplement the \l{QDecorationDefault::}{region()} function

    to do this for our decoration. This function returns a QRegion object

    that describes an arbitrarily-shaped region of the screen that can itself

    be made up of several distinct areas.

    \snippet examples/qws/simpledecoration/mydecoration.cpp region start

    The function is called for a given \e widget, occupying a region specified

    by \e insideRect, and is expected to return a region for the collection of

    \l{QDecoration::}{DecorationRegion} enum values supplied in the

    \e decorationRegion parameter.

    We begin by figuring out how much space in the decoration we will need to

    allocate for buttons, and where to place them:

    \snippet examples/qws/simpledecoration/mydecoration.cpp calculate the positions of buttons based on the window flags used

    In a more sophisticated implementation, we might test the \e decorationRegion

    supplied for regions related to buttons and the title bar, and only perform

    this space allocation if asked for regions related to these.

    We also use the information about the area occupied by buttons to determine

    how large an area we can use for the window title:

    \snippet examples/qws/simpledecoration/mydecoration.cpp calculate the extent of the title

    With these basic calculations done, we can start to compose a region, first

    checking whether we have been asked for all of the window, and we return

    immediately if so.

    \snippet examples/qws/simpledecoration/mydecoration.cpp check for all regions

    We examine each decoration region in turn, adding the corresponding region

    to the \c region object created earlier. We take care to avoid "off by one"

    errors in the coordinate calculations.

    \snippet examples/qws/simpledecoration/mydecoration.cpp compose a region based on the decorations specified

    Unlike the window borders and title bar, the regions occupied by buttons

    many of the window decorations do not occupy fixed places in the window.

    Instead, their locations depend on which other buttons are present.

    We only add regions for buttons we can handle (defined in the \c stateRegions)

    member variable, and only for those that are present (defined in the

    \c buttons hash).

    \snippet examples/qws/simpledecoration/mydecoration.cpp add a region for each button only if it is present

    The fully composed region can then be returned:

    \snippet examples/qws/simpledecoration/mydecoration.cpp region end

    The information returned by this function is used when the decoration is

    painted. Ideally, this function should be implemented to perform all the

    calculations necessary to place elements of the decoration; this makes

    the implementation of the \c paint() function much easier.

    \section2 Painting the Decoration

    The \c paint() function is responsible for drawing each window element

    for a given widget. Information about the decoration region, its state

    and the widget itself is provided along with a QPainter object to use.

    The first check we make is for a call with no regions:

    \snippet examples/qws/simpledecoration/mydecoration.cpp paint start

    We return false to indicate that we have not painted anything. If we paint

    something, we must return true so that the window can be composed, if

    necessary.

    Just as with the \c region() function, we test the decoration region to

    determine which elements need to be drawn. If we paint anything, we set

    the \c handled variable to true so that we can return the correct value

    when we have finished.

    \snippet examples/qws/simpledecoration/mydecoration.cpp paint different regions

    Note that we use our own \c region() implementation to determine where

    to draw decorations.

    Since the \c region() function performs calculations to place buttons, we

    can simply test the window flags against the buttons we support (using the

    \c buttonHintMap defined in the constructor), and draw each button in the

    relevant region:

    \snippet examples/qws/simpledecoration/mydecoration.cpp paint buttons

    Finally, we return the value of \c handled to indicate whether any painting

    was performed:

    \snippet examples/qws/simpledecoration/mydecoration.cpp paint end

    We now have a decoration class that we can use in an application.

    \section1 Using the Decoration

    In the \c main.cpp file, we set up the application as usual, but we also

    create an instance of our decoration and set it as the standard decoration

    for the application:

    \snippet examples/qws/simpledecoration/main.cpp create application

    This causes all windows opened by this application to use our decoration.

    To demonstrate this, we show the analog clock widget from the

    \l{Analog Clock Example}, which we build into the application:

    \snippet examples/qws/simpledecoration/main.cpp start application

    The application can be run either

    \l{Running Qt for Embedded Linux Applications}{as a server or a client

    application}. In both cases, it will use our decoration rather than the

    default one provided with Qt.

    \section1 Notes

    This example does not cache any information about the state or buttons

    used for each window. This means that the \c region() function calculates

    the locations and regions of buttons in cases where it could re-use

    existing information.

    If you run the application as a window server, you may expect client

    applications to use our decoration in preference to the default Qt

    decoration. However, it is up to each application to draw its own

    decoration, so this will not happen automatically. One way to achieve

    this is to compile the decoration with each application that needs it;

    another way is to build the decoration as a plugin, using the

    QDecorationPlugin class, and load it into the server and client

    applications.

*/