1 files changed, 228 insertions, 0 deletions
diff --git a/doc/customstyles.doc b/doc/customstyles.doc
new file mode 100644
index 000000000..e3ce114b9
--- /dev/null
+++ b/doc/customstyles.doc
@@ -0,0 +1,228 @@
+/****************************************************************************
+**
+** 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 retquirements 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. 
+
+*/