qt3/doc/customstyles.doc

/****************************************************************************
**
** Documentation for creating custom styles with QStyle
**
** Copyright (C) 1992-2008 Trolltech ASA.  All rights reserved.
**
** This file is part of the Qt GUI Toolkit.
**
** This file may be used under the terms of the GNU General
** Public License versions 2.0 or 3.0 as published by the Free
** Software Foundation and appearing in the files LICENSE.GPL2
** and LICENSE.GPL3 included in the packaging of this file.
** Alternatively you may (at your option) use any later version
** of the GNU General Public License if such license has been
** publicly approved by Trolltech ASA (or its successors, if any)
** and the KDE Free Qt Foundation.
**
** Please review the following information to ensure GNU General
** Public Licensing requirements will be met:
** http://trolltech.com/products/qt/licenses/licensing/opensource/.
** If you are unsure which license is appropriate for your use, please
** review the following information:
** http://trolltech.com/products/qt/licenses/licensing/licensingoverview
** or contact the sales department at sales@trolltech.com.
**
** This file may be used under the terms of the Q Public License as
** defined by Trolltech ASA and appearing in the file LICENSE.QPL
** included in the packaging of this file.  Licensees holding valid Qt
** Commercial licenses may use this file in accordance with the Qt
** Commercial License Agreement provided with the Software.
**
** This file is provided "AS IS" with NO WARRANTY OF ANY KIND,
** INCLUDING THE WARRANTIES OF DESIGN, MERCHANTABILITY AND FITNESS FOR
** A PARTICULAR PURPOSE. Trolltech reserves all rights not granted
** herein.
**
**********************************************************************/

/*!
\page customstyles.html

\title Style overview

A style in Qt implements the look and feel found in a GUI for a
particular platform. For example, Windows platforms may use the
Windows or Windows-XP style, Unix platforms may use the Motif style,
and so on.

This is a short guide that describes the steps that are necessary to
get started creating and using custom styles with the Qt 3.x style
API. First, we go through the steps necessary to create a style:
\list 1
\i Pick a base style to inherit from.
\i Re-implement the necessary functions in the derived class.
\endlist
Then we explain how to use the new style from within your own
applications, or as a plugin that can be used by existing Qt
applications.

\section1 Creating a custom style

\section2 1. Pick a base style to inherit from.

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 what look and
feel you are trying to achieve. We recommend that you choose from the
QWindowsStyle derived classes or the QMotifStyle derived classes.
These are the two base look and feel classes in the Qt style engine.
Inheriting directly from QCommonStyle is also an option if you want to
start almost from scratch when implementing your style. In this simple
example we will inherit from QWindowsStyle.

\section2 2. Re-implement the necessary functions in your derived class.

Depending on which parts of the base style you want to change, you
must re-implement the functions that are used to draw those parts
of the interface. If you take a look at the \l{QStyle} documentation,
you will find a list of the different primitives, controls and complex
controls. In this example we will first change the look of the
standard arrows that are used in the QWindowsStyle. The arrows are
PrimitiveElements that are drawn by the drawPrimitive() function,
so we need to re-implement that function. We need the following class
declaration:

\code
#include <qwindowsstyle.h>

class CustomStyle : public QWindowsStyle {
    Q_OBJECT
public:
    CustomStyle();
    ~CustomStyle();

    void drawPrimitive( PrimitiveElement pe,
			QPainter *p,
			const QRect & r,
			const QColorGroup & cg,
			SFlags flags = Style_Default,
			const QStyleOption & = QStyleOption::Default ) const;

private:
    // Disabled copy constructor and operator=
    CustomStyle( const CustomStyle & );
    CustomStyle& operator=( const CustomStyle & );
};
\endcode

Note that we disable the copy constructor and the '=' operator for our
style. QObject is the base class for all style classes in Qt, and a
QObject inherently cannot be copied since there are some aspects of it
that are not copyable.

From the QStyle docs we see that \c PE_ArrowUp, \c PE_ArrowDown, \c
PE_ArrowLeft and \c PE_ArrowRight are the primitives we need to do
something with. We get the following in our drawPrimitive() function:

\code
CustomStyle::CustomStyle()
{
}

CustomStyle::~CustomStyle()
{
}

void CustomStyle::drawPrimitive( PrimitiveElement pe,
				 QPainter * p,
				 const QRect & r,
				 const QColorGroup & cg,
				 SFlags flags,
				 const QStyleOption & opt ) const
{
    // we are only interested in the arrows
    if (pe >= PE_ArrowUp && pe <= PE_ArrowLeft) {
	QPointArray pa( 3 );
	// make the arrow cover half the area it is supposed to be 
	// painted on
	int x = r.x();
	int y = r.y();
	int w = r.width() / 2;
	int h = r.height() / 2;
	x += (r.width() - w) / 2;
	y += (r.height() - h) /2;

	switch( pe ) {
	case PE_ArrowDown:
	    pa.setPoint( 0, x, y );
	    pa.setPoint( 1, x + w, y );
	    pa.setPoint( 2, x + w / 2, y + h );
	    break;
	case PE_ArrowUp:
	    pa.setPoint( 0, x, y + h );
	    pa.setPoint( 1, x + w, y + h );
	    pa.setPoint( 2, x + w / 2, y );
	    break;
	case PE_ArrowLeft:
	    pa.setPoint( 0, x + w, y );
	    pa.setPoint( 1, x + w, y + h );
	    pa.setPoint( 2, x, y + h / 2 );
	    break;
	case PE_ArrowRight:
	    pa.setPoint( 0, x, y );
	    pa.setPoint( 1, x, y + h );
	    pa.setPoint( 2, x + w, y + h / 2 );
	    break;
	default: break;
	    
	}

	// use different colors to indicate that the arrow is 
	// enabled/disabled
	if ( flags & Style_Enabled ) {
	    p->setPen( cg.mid() );
	    p->setBrush( cg.brush( QColorGroup::ButtonText ) );
	} else {
	    p->setPen( cg.buttonText() );
	    p->setBrush( cg.brush( QColorGroup::Mid ) );
	}
	p->drawPolygon( pa );
    } else {
	// let the base style handle the other primitives
	QWindowsStyle::drawPrimitive( pe, p, r, cg, flags, data );
    }
}
\endcode

\section2 Using a custom style

There are several ways of using a custom style in a Qt application.
The simplest way is to include the following lines of code in the
application's main() function:

\code
#include "customstyle.h"

int main( int argc, char ** argv )
{
    QApplication::setStyle( new CustomStyle() );
    // do the usual routine on creating your QApplication object etc.
}
\endcode

Note that you must also include the \c customstyle.h and \c
customstyle.cpp files in your project.

2. Creating and using a pluggable style

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 $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
./application -style custom
\endcode

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

*/