diff options
Diffstat (limited to 'doc')
1216 files changed, 84827 insertions, 0 deletions
diff --git a/doc/src/demos/affine.qdoc b/doc/src/demos/affine.qdoc new file mode 100644 index 0000000000..4b402f1375 --- /dev/null +++ b/doc/src/demos/affine.qdoc @@ -0,0 +1,48 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example demos/affine + \title Affine Transformations + + In this demo we show Qt's ability to perform affine transformations + on painting operations. + + \image affine-demo.png + + Transformations can be performed on any kind of graphics drawn using QPainter. + The transformations used to display the vector graphics, images, and text can be adjusted + in the following ways: + + \list + \o Dragging the red circle in the centre of each drawing moves it to a new position. + \o Dragging the displaced red circle causes the current drawing to be rotated about the + central circle. Rotation can also be controlled with the \key Rotate slider. + \o Scaling is controlled with the \key Scale slider. + \o Each drawing can be sheared with the \key Shear slider. + \endlist +*/ diff --git a/doc/src/demos/books.qdoc b/doc/src/demos/books.qdoc new file mode 100644 index 0000000000..837f9f09ee --- /dev/null +++ b/doc/src/demos/books.qdoc @@ -0,0 +1,46 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example demos/books + \title Books Demonstration + + The Books demonstration shows how Qt's SQL classes can be used with the model/view + framework to create rich user interfaces for information stored in a database. + + \image books-demo.png + + Information about a collection of books is held in a database. The books are + catalogued by author, title, genre, and year of publication. Although each of + these fields can be displayed and edited using standard widgets, an additional + field describing an arbitrary rating for the book needs something extra. + + Books are rated using a system where each is allocated a number of stars; the + more a book has, the better it is supposed to be. By clicking on a cell + containing the rating, the number of stars can be modified, and the rating in + the database is updated. +*/ diff --git a/doc/src/demos/boxes.qdoc b/doc/src/demos/boxes.qdoc new file mode 100644 index 0000000000..24bc21b433 --- /dev/null +++ b/doc/src/demos/boxes.qdoc @@ -0,0 +1,49 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example demos/boxes + \title Boxes + + This demo shows Qt's ability to combine advanced OpenGL rendering with the + the \l{Graphics View Framework}. + + \image boxes-demo.png + + Elements in the demo can be controlled using the mouse in the following + ways: + \list + \o Dragging the mouse while pressing the left mouse button rotates the + box in the center. + \o Dragging the mouse while pressing the right mouse button rotates the + satellite boxes. + \o Scrolling the mouse wheel zooms in and out of the scene. + \endlist + + The options pane can be used to fine-tune various parameters in the demo, + including colors and pixel shaders. +*/ diff --git a/doc/src/demos/chip.qdoc b/doc/src/demos/chip.qdoc new file mode 100644 index 0000000000..3d04532d07 --- /dev/null +++ b/doc/src/demos/chip.qdoc @@ -0,0 +1,38 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example demos/chip + \title 40000 Chips + + This demo shows how to visualize a huge scene with 40000 chip items + using Graphics View. It also shows Graphics View's powerful navigation + and interaction features, allowing you to zoom and rotate each of four + views independently, and you can select and move items around the scene. + + \image chip-demo.png +*/ diff --git a/doc/src/demos/composition.qdoc b/doc/src/demos/composition.qdoc new file mode 100644 index 0000000000..9ceb6b5a96 --- /dev/null +++ b/doc/src/demos/composition.qdoc @@ -0,0 +1,44 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example demos/composition + \title Composition Modes + + This demo shows some of the more advanced composition modes supported by Qt. + + \image composition-demo.png + + The two most common forms of composition are \bold{Source} and \bold{SourceOver}. + \bold{Source} is used to draw opaque objects onto a paint device. In this mode, + each pixel in the source replaces the corresponding pixel in the destination. + In \bold{SourceOver} composition mode, the source object is transparent and is + drawn on top of the destination. + + In addition to these standard modes, Qt defines the complete set of composition modes + as defined by X. Porter and Y. Duff. See the QPainter documentation for details. +*/ diff --git a/doc/src/demos/deform.qdoc b/doc/src/demos/deform.qdoc new file mode 100644 index 0000000000..d5d994232f --- /dev/null +++ b/doc/src/demos/deform.qdoc @@ -0,0 +1,51 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example demos/deform + \title Vector Deformation + + This demo shows how to use advanced vector techniques to draw text + using a \c QPainterPath. + + \image deform-demo.png + + We define a vector deformation field in the shape of a lens and apply + this to all points in a path. This means that what is rendered on + screen is not pixel manipulation, but modified vector representations of + the glyphs themselves. This is visible from the high quality of the + antialiased edges for the deformed glyphs. + + To get a fairly complex path we allow the user to type in text and + convert the text to paths. This is done using the + QPainterPath::addText() function. + + The lens is drawn using a single call to QPainter::drawEllipse(), + using a QRadialGradient to fill it with a specialized color + table, giving the effect of the sun's reflection and a drop + shadow. The lens is cached as a pixmap for better performance. +*/ diff --git a/doc/src/demos/digiflip.qdoc b/doc/src/demos/digiflip.qdoc new file mode 100644 index 0000000000..8008ca4e39 --- /dev/null +++ b/doc/src/demos/digiflip.qdoc @@ -0,0 +1,31 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example demos/embedded/digiflip + \title Digiflip Demonstration +*/ diff --git a/doc/src/demos/embeddeddialogs.qdoc b/doc/src/demos/embeddeddialogs.qdoc new file mode 100644 index 0000000000..96e8781e2c --- /dev/null +++ b/doc/src/demos/embeddeddialogs.qdoc @@ -0,0 +1,37 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example demos/embeddeddialogs + \title Embedded Dialogs + + This example shows how to embed standard dialogs into + Graphics View. It also shows how you can customize the + proxy class and add window shadows. + + \image embeddeddialogs-demo.png +*/ diff --git a/doc/src/demos/flickable.qdoc b/doc/src/demos/flickable.qdoc new file mode 100644 index 0000000000..0f336bb101 --- /dev/null +++ b/doc/src/demos/flickable.qdoc @@ -0,0 +1,33 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example demos/embedded/flickable + \title Flickable List Demonstration + + \image flickable-demo.png +*/ diff --git a/doc/src/demos/flightinfo.qdoc b/doc/src/demos/flightinfo.qdoc new file mode 100644 index 0000000000..81eae6c4c5 --- /dev/null +++ b/doc/src/demos/flightinfo.qdoc @@ -0,0 +1,33 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example demos/embedded/flightinfo + \title Flight Info Demonstration + + \image flightinfo-demo.png +*/ diff --git a/doc/src/demos/gradients.qdoc b/doc/src/demos/gradients.qdoc new file mode 100644 index 0000000000..ca991fc388 --- /dev/null +++ b/doc/src/demos/gradients.qdoc @@ -0,0 +1,55 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example demos/gradients + \title Gradients + + In this demo we show the various types of gradients that can + be used in Qt. + + \image gradients-demo.png + + There are three types of gradients: + + \list + \o \bold{Linear} gradients interpolate colors between start and end points. + \o \bold{Radial} gradients interpolate colors between a focal point and the + points on a circle surrounding it. + \o \bold{Conical} gradients interpolate colors around a center point. + \endlist + + The panel on the right contains a color table editor that defines + the colors in the gradient. The three topmost controls determine the red, + green and blue components while the last defines the alpha of the + gradient. You can move points, and add new ones, by clicking with the left + mouse button, and remove points by clicking with the right button. + + There are three default configurations available at the bottom of + the page that are provided as suggestions on how a color table could be + configured. +*/ diff --git a/doc/src/demos/interview.qdoc b/doc/src/demos/interview.qdoc new file mode 100644 index 0000000000..a4f6ee48cc --- /dev/null +++ b/doc/src/demos/interview.qdoc @@ -0,0 +1,37 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example demos/interview + \title Interview + + The Interview demonstration explores the flexibility and scalability of the + model/view framework by presenting an infinitely deep data structure using a model + and three different types of view. + + \image interview-demo.png +*/ diff --git a/doc/src/demos/lightmaps.qdoc b/doc/src/demos/lightmaps.qdoc new file mode 100644 index 0000000000..1f28cd06ff --- /dev/null +++ b/doc/src/demos/lightmaps.qdoc @@ -0,0 +1,33 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example demos/embedded/lightmaps + \title Light Maps Demonstration + + \image lightmaps-demo.png +*/ diff --git a/doc/src/demos/macmainwindow.qdoc b/doc/src/demos/macmainwindow.qdoc new file mode 100644 index 0000000000..060ce40a0d --- /dev/null +++ b/doc/src/demos/macmainwindow.qdoc @@ -0,0 +1,42 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example demos/macmainwindow + \title Mac Main Window Demo + + This demo shows how to create a main window that has the + same appearance as other Mac OS X applications such as Mail or iTunes. + This includes customizing the item views and QSplitter and wrapping native + widgets such as the search field. + + \image macmainwindow.png + + See \c{$QTDIR/demos/macmainwindow} for the source code. +*/ + + diff --git a/doc/src/demos/mainwindow.qdoc b/doc/src/demos/mainwindow.qdoc new file mode 100644 index 0000000000..d6dd358d7e --- /dev/null +++ b/doc/src/demos/mainwindow.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example demos/mainwindow + \title Main Window + + The Main Window demonstration shows Qt's extensive support for tool bars, + dock windows, menus, and other standard application features. + + \image mainwindow-demo.png +*/ diff --git a/doc/src/demos/pathstroke.qdoc b/doc/src/demos/pathstroke.qdoc new file mode 100644 index 0000000000..dd34b1d602 --- /dev/null +++ b/doc/src/demos/pathstroke.qdoc @@ -0,0 +1,47 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example demos/pathstroke + \title Path Stroking + + In this demo we show some of the various types of pens that can be + used in Qt. + + \image pathstroke-demo.png + + Qt defines cap styles for how the end points are treated and join + styles for how path segments are joined together. A standard set of + predefined dash patterns are also included that can be used with + QPen. + + In addition to the predefined patterns available in + QPen we also demonstrate direct use of the + QPainterPathStroker class which can be used to define + custom dash patterns. You can see this by enabling the + \e{Custom Pattern} option. +*/ diff --git a/doc/src/demos/raycasting.qdoc b/doc/src/demos/raycasting.qdoc new file mode 100644 index 0000000000..e4a9dc3aee --- /dev/null +++ b/doc/src/demos/raycasting.qdoc @@ -0,0 +1,33 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example demos/embedded/raycasting + \title Ray Casting Demonstration + + \image raycasting-demo.png +*/ diff --git a/doc/src/demos/spreadsheet.qdoc b/doc/src/demos/spreadsheet.qdoc new file mode 100644 index 0000000000..35d41eca14 --- /dev/null +++ b/doc/src/demos/spreadsheet.qdoc @@ -0,0 +1,37 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example demos/spreadsheet + \title Spreadsheet + + The Spreadsheet demonstration shows how a table view can be used to create a + simple spreadsheet application. Custom delegates are used to render different + types of data in distinctive colors. + + \image spreadsheet-demo.png +*/ diff --git a/doc/src/demos/sqlbrowser.qdoc b/doc/src/demos/sqlbrowser.qdoc new file mode 100644 index 0000000000..74ebe6c973 --- /dev/null +++ b/doc/src/demos/sqlbrowser.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example demos/sqlbrowser + \title SQL Browser + + The SQL Browser demonstration shows how a data browser can be used to visualize + the results of SQL statements on a live database. + + \image sqlbrowser-demo.png +*/ diff --git a/doc/src/demos/styledemo.qdoc b/doc/src/demos/styledemo.qdoc new file mode 100644 index 0000000000..c4e16d1355 --- /dev/null +++ b/doc/src/demos/styledemo.qdoc @@ -0,0 +1,33 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example demos/embedded/styledemo + \title Embedded Styles Demonstration + + \image styledemo-demo.png +*/ diff --git a/doc/src/demos/sub-attaq.qdoc b/doc/src/demos/sub-attaq.qdoc new file mode 100644 index 0000000000..868ade3955 --- /dev/null +++ b/doc/src/demos/sub-attaq.qdoc @@ -0,0 +1,40 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example demos/sub-attaq + \title Sub-Attaq + + This demo shows Qt's ability to combine \l{The Animation Framework}{the animation framework} + and \l{The State Machine Framework}{the state machine framework} to create a game. + + \image sub-attaq-demo.png + + The purpose of the game is to destroy all submarines to win the current level. + The boat can be controlled using left and right keys. To fire a bomb you can press + up and down keys. +*/ diff --git a/doc/src/demos/textedit.qdoc b/doc/src/demos/textedit.qdoc new file mode 100644 index 0000000000..3dce23fad7 --- /dev/null +++ b/doc/src/demos/textedit.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example demos/textedit + \title Text Edit + + The Text Edit demonstration shows Qt's rich text editing facilities in action, + providing an example document for you to experiment with. + + \image textedit-demo.png +*/ diff --git a/doc/src/demos/undo.qdoc b/doc/src/demos/undo.qdoc new file mode 100644 index 0000000000..4905d5c507 --- /dev/null +++ b/doc/src/demos/undo.qdoc @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example demos/undo + \title Undo Framework + + This demo shows Qt's undo framework in action. + + \image undodemo.png + + Qt's undo framework is an implementation of the Command + pattern, which provides advanced undo/redo functionality. + + To show the abilities of the framework, we have implemented a + small diagram application in which the diagram items are geometric + primitives. You can edit the diagram in the following ways: add, + move, change the color of, and delete the items. +*/ diff --git a/doc/src/examples/2dpainting.qdoc b/doc/src/examples/2dpainting.qdoc new file mode 100644 index 0000000000..e90788e38c --- /dev/null +++ b/doc/src/examples/2dpainting.qdoc @@ -0,0 +1,210 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example opengl/2dpainting + \title 2D Painting Example + + The 2D Painting example shows how QPainter and QGLWidget can be used + together to display accelerated 2D graphics on supported hardware. + + \image 2dpainting-example.png + + The QPainter class is used to draw 2D graphics primitives onto + paint devices provided by QPaintDevice subclasses, such as QWidget + and QImage. + + Since QGLWidget is a subclass of QWidget, it is possible + to reimplement its \l{QWidget::paintEvent()}{paintEvent()} and use + QPainter to draw on the device, just as you would with a QWidget. + The only difference is that the painting operations will be accelerated + in hardware if it is supported by your system's OpenGL drivers. + + In this example, we perform the same painting operations on a + QWidget and a QGLWidget. The QWidget is shown with anti-aliasing + enabled, and the QGLWidget will also use anti-aliasing if the + required extensions are supported by your system's OpenGL driver. + + \section1 Overview + + To be able to compare the results of painting onto a QGLWidget subclass + with native drawing in a QWidget subclass, we want to show both kinds + of widget side by side. To do this, we derive subclasses of QWidget and + QGLWidget, using a separate \c Helper class to perform the same painting + operations for each, and lay them out in a top-level widget, itself + provided a the \c Window class. + + \section1 Helper Class Definition + + In this example, the painting operations are performed by a helper class. + We do this because we want the same painting operations to be performed + for both our QWidget subclass and the QGLWidget subclass. + + The \c Helper class is minimal: + + \snippet examples/opengl/2dpainting/helper.h 0 + + Apart from the constructor, it only provides a \c paint() function to paint + using a painter supplied by one of our widget subclasses. + + \section1 Helper Class Implementation + + The constructor of the class sets up the resources it needs to paint + content onto a widget: + + \snippet examples/opengl/2dpainting/helper.cpp 0 + + The actual painting is performed in the \c paint() function. This takes + a QPainter that has already been set up to paint onto a paint device + (either a QWidget or a QGLWidget), a QPaintEvent that provides information + about the region to be painted, and a measure of the elapsed time (in + milliseconds) since the paint device was last updated. + + \snippet examples/opengl/2dpainting/helper.cpp 1 + + We begin painting by filling in the region contained in the paint event + before translating the origin of the coordinate system so that the rest + of the painting operations will be displaced towards the center of the + paint device. + + We draw a spiral pattern of circles, using the elapsed time specified to + animate them so that they appear to move outward and around the coordinate + system's origin: + + \snippet examples/opengl/2dpainting/helper.cpp 2 + + Since the coordinate system is rotated many times during + this process, we \l{QPainter::save()}{save()} the QPainter's state + beforehand and \l{QPainter::restore()}{restore()} it afterwards. + + \snippet examples/opengl/2dpainting/helper.cpp 3 + + We draw some text at the origin to complete the effect. + + \section1 Widget Class Definition + + The \c Widget class provides a basic custom widget that we use to + display the simple animation painted by the \c Helper class. + + \snippet examples/opengl/2dpainting/widget.h 0 + + Apart from the constructor, it only contains a + \l{QWidget::paintEvent()}{paintEvent()} function, that lets us draw + customized content, and a slot that is used to animate its contents. + One member variable keeps track of the \c Helper that the widget uses + to paint its contents, and the other records the elapsed time since + it was last updated. + + \section1 Widget Class Implementation + + The constructor only initializes the member variables, storing the + \c Helper object supplied and calling the base class's constructor, + and enforces a fixed size for the widget: + + \snippet examples/opengl/2dpainting/widget.cpp 0 + + The \c animate() slot is called whenever a timer, which we define later, times + out: + + \snippet examples/opengl/2dpainting/widget.cpp 1 + + Here, we determine the interval that has elapsed since the timer last + timed out, and we add it to any existing value before repainting the + widget. Since the animation used in the \c Helper class loops every second, + we can use the modulo operator to ensure that the \c elapsed variable is + always less than 1000. + + Since the \c Helper class does all of the actual painting, we only have + to implement a paint event that sets up a QPainter for the widget and calls + the helper's \c paint() function: + + \snippet examples/opengl/2dpainting/widget.cpp 2 + + \section1 GLWidget Class Definition + + The \c GLWidget class definition is basically the same as the \c Widget + class except that it is derived from QGLWidget. + + \snippet examples/opengl/2dpainting/glwidget.h 0 + + Again, the member variables record the \c Helper used to paint the + widget and the elapsed time since the previous update. + + \section1 GLWidget Class Implementation + + The constructor differs a little from the \c Widget class's constructor: + + \snippet examples/opengl/2dpainting/glwidget.cpp 0 + + As well as initializing the \c elapsed member variable and storing the + \c Helper object used to paint the widget, the base class's constructor + is called with the format that specifies the \l QGL::SampleBuffers flag. + This enables anti-aliasing if it is supported by your system's OpenGL + driver. + + The \c animate() slot is exactly the same as that provided by the \c Widget + class: + + \snippet examples/opengl/2dpainting/glwidget.cpp 1 + + The \c paintEvent() is almost the same as that found in the \c Widget class: + + \snippet examples/opengl/2dpainting/glwidget.cpp 2 + + Since anti-aliasing will be enabled if available, we only need to set up + a QPainter on the widget and call the helper's \c paint() function to display + the widget's contents. + + \section1 Window Class Definition + + The \c Window class has a basic, minimal definition: + + \snippet examples/opengl/2dpainting/window.h 0 + + It contains a single \c Helper object that will be shared between all + widgets. + + \section1 Window Class Implementation + + The constructor does all the work, creating a widget of each type and + inserting them with labels into a layout: + + \snippet examples/opengl/2dpainting/window.cpp 0 + + A timer with a 50 millisecond time out is constructed for animation purposes, + and connected to the \c animate() slots of the \c Widget and \c GLWidget objects. + Once started, the widgets should be updated at around 20 frames per second. + + \section1 Running the Example + + The example shows the same painting operations performed at the same time + in a \c Widget and a \c GLWidget. The quality and speed of rendering in the + \c GLWidget depends on the level of support for multisampling and hardware + acceleration that your system's OpenGL driver provides. If support for either + of these is lacking, the driver may fall back on a software renderer that + may trade quality for speed. +*/ diff --git a/doc/src/examples/addressbook.qdoc b/doc/src/examples/addressbook.qdoc new file mode 100644 index 0000000000..018ce7096b --- /dev/null +++ b/doc/src/examples/addressbook.qdoc @@ -0,0 +1,442 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example itemviews/addressbook + \title Address Book Example + + The address book example shows how to use proxy models to display + different views onto data from a single model. + + \image addressbook-example.png Screenshot of the Address Book example + + This example provides an address book that allows contacts to be + grouped alphabetically into 9 groups: ABC, DEF, GHI, ... , VW, + ..., XYZ. This is achieved by using multiple views on the same + model, each of which is filtered using an instance of the + QSortFilterProxyModel class. + + + \section1 Overview + + The address book contains 5 classes: \c MainWindow, + \c AddressWidget, \c TableModel, \c NewAddressTab and + \c AddDialog. The \c MainWindow class uses \c AddressWidget as + its central widget and provides \gui File and \gui Tools menus. + + \image addressbook-classes.png Diagram for Address Book Example + + The \c AddressWidget class is a QTabWidget subclass that is used + to manipulate the 10 tabs displayed in the example: the 9 + alphabet group tabs and an instance of \c NewAddressTab. + The \c NewAddressTab class is a subclass of QWidget that + is only used whenever the address book is empty, prompting the + user to add some contacts. \c AddressWidget also interacts with + an instance of \c TableModel to add, edit and remove entries to + the address book. + + \c TableModel is a subclass of QAbstractTableModel that provides + the standard model/view API to access data. It also holds a + QList of \l{QPair}s corresponding to the contacts added. + However, this data is not all visible in a single tab. Instead, + QTableView is used to provide 9 different views of the same + data, according to the alphabet groups. + + QSortFilterProxyModel is the class responsible for filtering + the contacts for each group of contacts. Each proxy model uses + a QRegExp to filter out contacts that do not belong in the + corresponding alphabetical group. The \c AddDialog class is + used to obtain information from the user for the address book. + This QDialog subclass is instantiated by \c NewAddressTab to + add contacts, and by \c AddressWidget to add and edit contacts. + + We begin by looking at the \c TableModel implementation. + + + \section1 TableModel Class Definition + + The \c TableModel class provides standard API to access data in + its QList of \l{QPair}s by subclassing QAbstractTableModel. The + basic functions that must be implemented in order to do so are: + \c rowCount(), \c columnCount(), \c data(), \c headerData(). + For TableModel to be editable, it has to provide implementations + \c insertRows(), \c removeRows(), \c setData() and \c flags() + functions. + + \snippet itemviews/addressbook/tablemodel.h 0 + + Two constructors are used, a default constructor which uses + \c TableModel's own \c {QList<QPair<QString, QString>>} and one + that takes \c {QList<QPair<QString, QString>} as an argument, + for convenience. + + + \section1 TableModel Class Implementation + + We implement the two constructors as defined in the header file. + The second constructor initializes the list of pairs in the + model, with the parameter value. + + \snippet itemviews/addressbook/tablemodel.cpp 0 + + The \c rowCount() and \c columnCount() functions return the + dimensions of the model. Whereas, \c rowCount()'s value will vary + depending on the number of contacts added to the address book, + \c columnCount()'s value is always 2 because we only need space + for the \bold Name and \bold Address columns. + + \note The \c Q_UNUSED() macro prevents the compiler from + generating warnings regarding unused parameters. + + \snippet itemviews/addressbook/tablemodel.cpp 1 + + The \c data() function returns either a \bold Name or + \bold {Address}, based on the contents of the model index + supplied. The row number stored in the model index is used to + reference an item in the list of pairs. Selection is handled + by the QItemSelectionModel, which will be explained with + \c AddressWidget. + + \snippet itemviews/addressbook/tablemodel.cpp 2 + + The \c headerData() function displays the table's header, + \bold Name and \bold Address. If you require numbered entries + for your address book, you can use a vertical header which we + have hidden in this example (see the \c AddressWidget + implementation). + + \snippet itemviews/addressbook/tablemodel.cpp 3 + + The \c insertRows() function is called before new data is added, + otherwise the data will not be displayed. The + \c beginInsertRows() and \c endInsertRows() functions are called + to ensure all connected views are aware of the changes. + + \snippet itemviews/addressbook/tablemodel.cpp 4 + + The \c removeRows() function is called to remove data. Again, + \l{QAbstractItemModel::}{beginRemoveRows()} and + \l{QAbstractItemModel::}{endRemoveRows()} are called to ensure + all connected views are aware of the changes. + + \snippet itemviews/addressbook/tablemodel.cpp 5 + + The \c setData() function is the function that inserts data into + the table, item by item and not row by row. This means that to + fill a row in the address book, \c setData() must be called + twice, as each row has 2 columns. It is important to emit the + \l{QAbstractItemModel::}{dataChanged()} signal as it tells all + connected views to update their displays. + + \snippet itemviews/addressbook/tablemodel.cpp 6 + + The \c flags() function returns the item flags for the given + index. + + \snippet itemviews/addressbook/tablemodel.cpp 7 + + We set the Qt::ItemIsEditable flag because we want to allow the + \c TableModel to be edited. Although for this example we don't + use the editing features of the QTableView object, we enable + them here so that we can reuse the model in other programs. + + The last function in \c {TableModel}, \c getList() returns the + QList<QPair<QString, QString>> object that holds all the + contacts in the address book. We use this function later to + obtain the list of contacts to check for existing entries, write + the contacts to a file and read them back. Further explanation is + given with \c AddressWidget. + + \snippet itemviews/addressbook/tablemodel.cpp 8 + + + \section1 AddressWidget Class Definition + + The \c AddressWidget class is technically the main class + involved in this example as it provides functions to add, edit + and remove contacts, to save the contacts to a file and to load + them from a file. + + \snippet itemviews/addressbook/addresswidget.h 0 + + \c AddressWidget extends QTabWidget in order to hold 10 tabs + (\c NewAddressTab and the 9 alphabet group tabs) and also + manipulates \c table, the \c TableModel object, \c proxyModel, + the QSortFilterProxyModel object that we use to filter the + entries, and \c tableView, the QTableView object. + + + \section1 AddressWidget Class Implementation + + The \c AddressWidget constructor accepts a parent widget and + instantiates \c NewAddressTab, \c TableModel and + QSortFilterProxyModel. The \c NewAddressTab object, which is + used to indicate that the address book is empty, is added + and the rest of the 9 tabs are set up with \c setupTabs(). + + \snippet itemviews/addressbook/addresswidget.cpp 0 + + The \c setupTabs() function is used to set up the 9 alphabet + group tabs, table views and proxy models in + \c AddressWidget. Each proxy model in turn is set to filter + contact names according to the relevant alphabet group using a + \l{Qt::CaseInsensitive}{case-insensitive} QRegExp object. The + table views are also sorted in ascending order using the + corresponding proxy model's \l{QSortFilterProxyModel::}{sort()} + function. + + Each table view's \l{QTableView::}{selectionMode} is set to + QAbstractItemView::SingleSelection and + \l{QTableView::}{selectionBehavior} is set to + QAbstractItemView::SelectRows, allowing the user to select + all the items in one row at the same time. Each QTableView object + is automatically given a QItemSelectionModel that keeps track + of the selected indexes. + + \snippet itemviews/addressbook/addresswidget.cpp 1 + + The QItemSelectionModel class provides a + \l{QItemSelectionModel::selectionChanged()}{selectionChanged} + signal that is connected to \c{AddressWidget}'s + \c selectionChanged() signal. This signal to signal connection + is necessary to enable the \gui{Edit Entry...} and + \gui{Remove Entry} actions in \c MainWindow's Tools menu. This + connection is further explained in \c MainWindow's + implementation. + + Each table view in the address book is added as a tab to the + QTabWidget with the relevant label, obtained from the QStringList + of groups. + + \image addressbook-signals.png Signals and Slots Connections + + We provide 2 \c addEntry() functions: 1 which is intended to be + used to accept user input, and the other which performs the actual + task of adding new entries to the address book. We divide the + responsibility of adding entries into two parts to allow + \c newAddressTab to insert data without having to popup a dialog. + + The first \c addEntry() function is a slot connected to the + \c MainWindow's \gui{Add Entry...} action. This function creates an + \c AddDialog object and then calls the second \c addEntry() + function to actually add the contact to \c table. + + \snippet itemviews/addressbook/addresswidget.cpp 2 + + Basic validation is done in the second \c addEntry() function to + prevent duplicate entries in the address book. As mentioned with + \c TableModel, this is part of the reason why we require the + getter method \c getList(). + + \snippet itemviews/addressbook/addresswidget.cpp 3 + + If the model does not already contain an entry with the same name, + we call \c setData() to insert the name and address into the + first and second columns. Otherwise, we display a QMessageBox + to inform the user. + + \note The \c newAddressTab is removed once a contact is added + as the address book is no longer empty. + + Editing an entry is a way to update the contact's address only, + as the example does not allow the user to change the name of an + existing contact. + + Firstly, we obtain the active tab's QTableView object using + QTabWidget::currentWidget(). Then we extract the + \c selectionModel from the \c tableView to obtain the selected + indexes. + + \snippet itemviews/addressbook/addresswidget.cpp 4a + + Next we extract data from the row the user intends to + edit. This data is displayed in an instance of \c AddDialog + with a different window title. The \c table is only + updated if changes have been made to data in \c aDialog. + + \snippet itemviews/addressbook/addresswidget.cpp 4b + + \image addressbook-editdialog.png Screenshot of Dialog to Edit a Contact + + Entries are removed using the \c removeEntry() function. + The selected row is removed by accessing it through the + QItemSelectionModel object, \c selectionModel. The + \c newAddressTab is re-added to the \c AddressWidget only if + the user removes all the contacts in the address book. + + \snippet itemviews/addressbook/addresswidget.cpp 5 + + The \c writeToFile() function is used to save a file containing + all the contacts in the address book. The file is saved in a + custom \c{.dat} format. The contents of the QList of \l{QPair}s + are written to \c file using QDataStream. If the file cannot be + opened, a QMessageBox is displayed with the related error message. + + \snippet itemviews/addressbook/addresswidget.cpp 6 + + The \c readFromFile() function loads a file containing all the + contacts in the address book, previously saved using + \c writeToFile(). QDataStream is used to read the contents of a + \c{.dat} file into a list of pairs and each of these is added + using \c addEntry(). + + \snippet itemviews/addressbook/addresswidget.cpp 7 + + + \section1 NewAddressTab Class Definition + + The \c NewAddressTab class provides an informative tab telling + the user that the address book is empty. It appears and + disappears according to the contents of the address book, as + mentioned in \c{AddressWidget}'s implementation. + + \image addressbook-newaddresstab.png Screenshot of NewAddressTab + + The \c NewAddressTab class extends QWidget and contains a QLabel + and QPushButton. + + \snippet itemviews/addressbook/newaddresstab.h 0 + + + \section1 NewAddressTab Class Implementation + + The constructor instantiates the \c addButton, + \c descriptionLabel and connects the \c{addButton}'s signal to + the \c{addEntry()} slot. + + \snippet itemviews/addressbook/newaddresstab.cpp 0 + + The \c addEntry() function is similar to \c AddressWidget's + \c addEntry() in the sense that both functions instantiate an + \c AddDialog object. Data from the dialog is extracted and sent + to \c AddressWidget's \c addEntry() slot by emitting the + \c sendDetails() signal. + + \snippet itemviews/addressbook/newaddresstab.cpp 1 + + \image signals-n-slots-aw-nat.png + + + \section1 AddDialog Class Definition + + The \c AddDialog class extends QDialog and provides the user + with a QLineEdit and a QTextEdit to input data into the + address book. + + \snippet itemviews/addressbook/adddialog.h 0 + + \image addressbook-adddialog.png + + + \section1 AddDialog Class Implementation + + The \c AddDialog's constructor sets up the user interface, + creating the necessary widgets and placing them into layouts. + + \snippet itemviews/addressbook/adddialog.cpp 0 + + To give the dialog the desired behavior, we connect the \gui OK + and \gui Cancel buttons to the dialog's \l{QDialog::}{accept()} and + \l{QDialog::}{reject()} slots. Since the dialog only acts as a + container for name and address information, we do not need to + implement any other functions for it. + + + \section1 MainWindow Class Definition + + The \c MainWindow class extends QMainWindow and implements the + menus and actions necessary to manipulate the address book. + + \table + \row \o \inlineimage addressbook-filemenu.png + \o \inlineimage addressbook-toolsmenu.png + \endtable + + \snippet itemviews/addressbook/mainwindow.h 0 + + The \c MainWindow class uses an \c AddressWidget as its central + widget and provides the File menu with \gui Open, \gui Close and + \gui Exit actions, as well as the \gui Tools menu with + \gui{Add Entry...}, \gui{Edit Entry...} and \gui{Remove Entry} + actions. + + + \section1 MainWindow Class Implementation + + The constructor for \c MainWindow instantiates AddressWidget, + sets it as its central widget and calls the \c createMenus() + function. + + \snippet itemviews/addressbook/mainwindow.cpp 0 + + The \c createMenus() function sets up the \gui File and + \gui Tools menus, connecting the actions to their respective slots. + Both the \gui{Edit Entry...} and \gui{Remove Entry} actions are + disabled by default as such actions cannot be carried out on an empty + address book. They are only enabled when one or more contacts + are added. + + \snippet itemviews/addressbook/mainwindow.cpp 1a + \dots + \codeline + \snippet itemviews/addressbook/mainwindow.cpp 1b + + Apart from connecting all the actions' signals to their + respective slots, we also connect \c AddressWidget's + \c selectionChanged() signal to its \c updateActions() slot. + + The \c openFile() function allows the user to choose a file with + the \l{QFileDialog::getOpenFileName()}{open file dialog}. The chosen + file has to be a custom \c{.dat} file that contains address book + contacts. This function is a slot connected to \c openAct in the + \gui File menu. + + \snippet itemviews/addressbook/mainwindow.cpp 2 + + The \c saveFile() function allows the user to save a file with + the \l{QFileDialog::getSaveFileName()}{save file dialog}. This function + is a slot connected to \c saveAct in the \gui File menu. + + \snippet itemviews/addressbook/mainwindow.cpp 3 + + The \c updateActions() function enables and disables + \gui{Edit Entry...} and \gui{Remove Entry} depending on the contents of + the address book. If the address book is empty, these actions + are disabled; otherwise, they are enabled. This function is a slot + is connected to the \c AddressWidget's \c selectionChanged() + signal. + + \snippet itemviews/addressbook/mainwindow.cpp 4 + + + \section1 main() Function + + The main function for the address book instantiates QApplication + and opens a \c MainWindow before running the event loop. + + \snippet itemviews/addressbook/main.cpp 0 +*/ diff --git a/doc/src/examples/analogclock.qdoc b/doc/src/examples/analogclock.qdoc new file mode 100644 index 0000000000..f213998b6f --- /dev/null +++ b/doc/src/examples/analogclock.qdoc @@ -0,0 +1,154 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example widgets/analogclock + \title Analog Clock Example + + The Analog Clock example shows how to draw the contents of a custom + widget. + + \image analogclock-example.png Screenshot of the Analog Clock example + + This example also demonstrates how the transformation and scaling + features of QPainter can be used to make drawing custom widgets + easier. + + \section1 AnalogClock Class Definition + + The \c AnalogClock class provides a clock widget with hour and minute + hands that is automatically updated every few seconds. + We subclass \l QWidget and reimplement the standard + \l{QWidget::paintEvent()}{paintEvent()} function to draw the clock face: + + \snippet examples/widgets/analogclock/analogclock.h 0 + + \section1 AnalogClock Class Implementation + + \snippet examples/widgets/analogclock/analogclock.cpp 1 + + When the widget is constructed, we set up a one-second timer to + keep track of the current time, and we connect it to the standard + \l{QWidget::update()}{update()} slot so that the clock face is + updated when the timer emits the \l{QTimer::timeout()}{timeout()} + signal. + + Finally, we resize the widget so that it is displayed at a + reasonable size. + + \snippet examples/widgets/analogclock/analogclock.cpp 8 + \snippet examples/widgets/analogclock/analogclock.cpp 10 + + The \c paintEvent() function is called whenever the widget's + contents need to be updated. This happens when the widget is + first shown, and when it is covered then exposed, but it is also + executed when the widget's \l{QWidget::update()}{update()} slot + is called. Since we connected the timer's + \l{QTimer::timeout()}{timeout()} signal to this slot, it will be + called at least once every five seconds. + + Before we set up the painter and draw the clock, we first define + two lists of \l {QPoint}s and two \l{QColor}s that will be used + for the hour and minute hands. The minute hand's color has an + alpha component of 191, meaning that it's 75% opaque. + + We also determine the length of the widget's shortest side so that we + can fit the clock face inside the widget. It is also useful to determine + the current time before we start drawing. + + \snippet examples/widgets/analogclock/analogclock.cpp 11 + \snippet examples/widgets/analogclock/analogclock.cpp 12 + \snippet examples/widgets/analogclock/analogclock.cpp 13 + \snippet examples/widgets/analogclock/analogclock.cpp 14 + + The contents of custom widgets are drawn with a QPainter. + Painters can be used to draw on any QPaintDevice, but they are + usually used with widgets, so we pass the widget instance to the + painter's constructor. + + We call QPainter::setRenderHint() with QPainter::Antialiasing to + turn on antialiasing. This makes drawing of diagonal lines much + smoother. + + The translation moves the origin to the center of the widget, and + the scale operation ensures that the following drawing operations + are scaled to fit within the widget. We use a scale factor that + let's us use x and y coordinates between -100 and 100, and that + ensures that these lie within the length of the widget's shortest + side. + + To make our code simpler, we will draw a fixed size clock face that will + be positioned and scaled so that it lies in the center of the widget. + + The painter takes care of all the transformations made during the + paint event, and ensures that everything is drawn correctly. Letting + the painter handle transformations is often easier than performing + manual calculations just to draw the contents of a custom widget. + + \img analogclock-viewport.png + + We draw the hour hand first, using a formula that rotates the coordinate + system counterclockwise by a number of degrees determined by the current + hour and minute. This means that the hand will be shown rotated clockwise + by the required amount. + + \snippet examples/widgets/analogclock/analogclock.cpp 15 + \snippet examples/widgets/analogclock/analogclock.cpp 16 + + We set the pen to be Qt::NoPen because we don't want any outline, + and we use a solid brush with the color appropriate for + displaying hours. Brushes are used when filling in polygons and + other geometric shapes. + + \snippet examples/widgets/analogclock/analogclock.cpp 17 + \snippet examples/widgets/analogclock/analogclock.cpp 19 + + We save and restore the transformation matrix before and after the + rotation because we want to place the minute hand without having to + take into account any previous rotations. + + \snippet examples/widgets/analogclock/analogclock.cpp 20 + \codeline + \snippet examples/widgets/analogclock/analogclock.cpp 21 + + We draw markers around the edge of the clock for each hour. We + draw each marker then rotate the coordinate system so that the + painter is ready for the next one. + + \snippet examples/widgets/analogclock/analogclock.cpp 22 + \snippet examples/widgets/analogclock/analogclock.cpp 23 + + The minute hand is rotated in a similar way to the hour hand. + + \snippet examples/widgets/analogclock/analogclock.cpp 25 + \codeline + \snippet examples/widgets/analogclock/analogclock.cpp 26 + + Again, we draw markers around the edge of the clock, but this + time to indicate minutes. We skip multiples of 5 to avoid drawing + minute markers on top of hour markers. +*/ diff --git a/doc/src/examples/animatedtiles.qdoc b/doc/src/examples/animatedtiles.qdoc new file mode 100644 index 0000000000..00fe99908f --- /dev/null +++ b/doc/src/examples/animatedtiles.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example animation/animatedtiles + \title Animated Tiles Example + + The Animated Tiles example animates items in a graphics scene. + + \image animatedtiles-example.png +*/ + diff --git a/doc/src/examples/appchooser.qdoc b/doc/src/examples/appchooser.qdoc new file mode 100644 index 0000000000..ce8bfa6dbc --- /dev/null +++ b/doc/src/examples/appchooser.qdoc @@ -0,0 +1,38 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example animation/appchooser + \title Application Chooser Example + + The Application Chooser example shows how to use the Qt state + machine and the animation framework to select between + applications. + + \image appchooser-example.png + +*/ diff --git a/doc/src/examples/application.qdoc b/doc/src/examples/application.qdoc new file mode 100644 index 0000000000..f6a7b9963e --- /dev/null +++ b/doc/src/examples/application.qdoc @@ -0,0 +1,396 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example mainwindows/application + \title Application Example + + The Application example shows how to implement a standard GUI + application with menus, toolbars, and a status bar. The example + itself is a simple text editor program built around QPlainTextEdit. + + \image application.png Screenshot of the Application example + + Nearly all of the code for the Application example is in the \c + MainWindow class, which inherits QMainWindow. QMainWindow + provides the framework for windows that have menus, toolbars, + dock windows, and a status bar. The application provides + \menu{File}, \menu{Edit}, and \menu{Help} entries in the menu + bar, with the following popup menus: + + \image application-menus.png The Application example's menu system + + The status bar at the bottom of the main window shows a + description of the menu item or toolbar button under the cursor. + + To keep the example simple, recently opened files aren't shown in + the \menu{File} menu, even though this feature is desired in 90% + of applications. The \l{mainwindows/recentfiles}{Recent Files} + example shows how to implement this. Furthermore, this example + can only load one file at a time. The \l{mainwindows/sdi}{SDI} + and \l{mainwindows/mdi}{MDI} examples shows how to lift these + restrictions. + + \section1 MainWindow Class Definition + + Here's the class definition: + + \snippet examples/mainwindows/application/mainwindow.h 0 + + The public API is restricted to the constructor. In the \c + protected section, we reimplement QWidget::closeEvent() to detect + when the user attempts to close the window, and warn the user + about unsaved changes. In the \c{private slots} section, we + declare slots that correspond to menu entries, as well as a + mysterious \c documentWasModified() slot. Finally, in the \c + private section of the class, we have various members that will + be explained in due time. + + \section1 MainWindow Class Implementation + + \snippet examples/mainwindows/application/mainwindow.cpp 0 + + We start by including \c <QtGui>, a header file that contains the + definition of all classes in the \l QtCore and \l QtGui + libraries. This saves us from the trouble of having to include + every class individually. We also include \c mainwindow.h. + + You might wonder why we don't include \c <QtGui> in \c + mainwindow.h and be done with it. The reason is that including + such a large header from another header file can rapidly degrade + performances. Here, it wouldn't do any harm, but it's still + generally a good idea to include only the header files that are + strictly necessary from another header file. + + \snippet examples/mainwindows/application/mainwindow.cpp 1 + \snippet examples/mainwindows/application/mainwindow.cpp 2 + + In the constructor, we start by creating a QPlainTextEdit widget as a + child of the main window (the \c this object). Then we call + QMainWindow::setCentralWidget() to tell that this is going to be + the widget that occupies the central area of the main window, + between the toolbars and the status bar. + + Then we call \c createActions(), \c createMenus(), \c + createToolBars(), and \c createStatusBar(), four private + functions that set up the user interface. After that, we call \c + readSettings() to restore the user's preferences. + + We establish a signal-slot connection between the QPlainTextEdit's + document object and our \c documentWasModified() slot. Whenever + the user modifies the text in the QPlainTextEdit, we want to update + the title bar to show that the file was modified. + + At the end, we set the window title using the private + \c setCurrentFile() function. We'll come back to this later. + + \target close event handler + \snippet examples/mainwindows/application/mainwindow.cpp 3 + \snippet examples/mainwindows/application/mainwindow.cpp 4 + + When the user attempts to close the window, we call the private + function \c maybeSave() to give the user the possibility to save + pending changes. The function returns true if the user wants the + application to close; otherwise, it returns false. In the first + case, we save the user's preferences to disk and accept the close + event; in the second case, we ignore the close event, meaning + that the application will stay up and running as if nothing + happened. + + \snippet examples/mainwindows/application/mainwindow.cpp 5 + \snippet examples/mainwindows/application/mainwindow.cpp 6 + + The \c newFile() slot is invoked when the user selects + \menu{File|New} from the menu. We call \c maybeSave() to save any + pending changes and if the user accepts to go on, we clear the + QPlainTextEdit and call the private function \c setCurrentFile() to + update the window title and clear the + \l{QWidget::windowModified}{windowModified} flag. + + \snippet examples/mainwindows/application/mainwindow.cpp 7 + \snippet examples/mainwindows/application/mainwindow.cpp 8 + + The \c open() slot is invoked when the user clicks + \menu{File|Open}. We pop up a QFileDialog asking the user to + choose a file. If the user chooses a file (i.e., \c fileName is + not an empty string), we call the private function \c loadFile() + to actually load the file. + + \snippet examples/mainwindows/application/mainwindow.cpp 9 + \snippet examples/mainwindows/application/mainwindow.cpp 10 + + The \c save() slot is invoked when the user clicks + \menu{File|Save}. If the user hasn't provided a name for the file + yet, we call \c saveAs(); otherwise, we call the private function + \c saveFile() to actually save the file. + + \snippet examples/mainwindows/application/mainwindow.cpp 11 + \snippet examples/mainwindows/application/mainwindow.cpp 12 + + In \c saveAs(), we start by popping up a QFileDialog asking the + user to provide a name. If the user clicks \gui{Cancel}, the + returned file name is empty, and we do nothing. + + \snippet examples/mainwindows/application/mainwindow.cpp 13 + \snippet examples/mainwindows/application/mainwindow.cpp 14 + + The application's About box is done using one statement, using + the QMessageBox::about() static function and relying on its + support for an HTML subset. + + The \l{QObject::tr()}{tr()} call around the literal string marks + the string for translation. It is a good habit to call + \l{QObject::tr()}{tr()} on all user-visible strings, in case you + later decide to translate your application to other languages. + The \l{Internationalization with Qt} overview convers + \l{QObject::tr()}{tr()} in more detail. + + \snippet examples/mainwindows/application/mainwindow.cpp 15 + \snippet examples/mainwindows/application/mainwindow.cpp 16 + + The \c documentWasModified() slot is invoked each time the text + in the QPlainTextEdit changes because of user edits. We call + QWidget::setWindowModified() to make the title bar show that the + file was modified. How this is done varies on each platform. + + \snippet examples/mainwindows/application/mainwindow.cpp 17 + \snippet examples/mainwindows/application/mainwindow.cpp 18 + \dots + \snippet examples/mainwindows/application/mainwindow.cpp 22 + + The \c createActions() private function, which is called from the + \c MainWindow constructor, creates \l{QAction}s. The code is very + repetitive, so we show only the actions corresponding to + \menu{File|New}, \menu{File|Open}, and \menu{Help|About Qt}. + + A QAction is an object that represents one user action, such as + saving a file or invoking a dialog. An action can be put in a + QMenu or a QToolBar, or both, or in any other widget that + reimplements QWidget::actionEvent(). + + An action has a text that is shown in the menu, an icon, a + shortcut key, a tooltip, a status tip (shown in the status bar), + a "What's This?" text, and more. It emits a + \l{QAction::triggered()}{triggered()} signal whenever the user + invokes the action (e.g., by clicking the associated menu item or + toolbar button). We connect this signal to a slot that performs + the actual action. + + The code above contains one more idiom that must be explained. + For some of the actions, we specify an icon as a QIcon to the + QAction constructor. The QIcon constructor takes the file name + of an image that it tries to load. Here, the file name starts + with \c{:}. Such file names aren't ordinary file names, but + rather path in the executable's stored resources. We'll come back + to this when we review the \c application.qrc file that's part of + the project. + + \snippet examples/mainwindows/application/mainwindow.cpp 23 + \snippet examples/mainwindows/application/mainwindow.cpp 24 + + The \gui{Edit|Cut} and \gui{Edit|Copy} actions must be available + only when the QPlainTextEdit contains selected text. We disable them + by default and connect the QPlainTextEdit::copyAvailable() signal to + the QAction::setEnabled() slot, ensuring that the actions are + disabled when the text editor has no selection. + + \snippet examples/mainwindows/application/mainwindow.cpp 25 + \snippet examples/mainwindows/application/mainwindow.cpp 27 + + Creating actions isn't sufficient to make them available to the + user; we must also add them to the menu system. This is what \c + createMenus() does. We create a \menu{File}, an \menu{Edit}, and + a \menu{Help} menu. QMainWindow::menuBar() lets us access the + window's menu bar widget. We don't have to worry about creating + the menu bar ourselves; the first time we call this function, the + QMenuBar is created. + + Just before we create the \menu{Help} menu, we call + QMenuBar::addSeparator(). This has no effect for most widget + styles (e.g., Windows and Mac OS X styles), but for Motif-based + styles this makes sure that \menu{Help} is pushed to the right + side of the menu bar. Try running the application with various + styles and see the results: + + \snippet doc/src/snippets/code/doc_src_examples_application.qdoc 0 + + Let's now review the toolbars: + + \snippet examples/mainwindows/application/mainwindow.cpp 30 + + Creating toolbars is very similar to creating menus. The same + actions that we put in the menus can be reused in the toolbars. + + \snippet examples/mainwindows/application/mainwindow.cpp 32 + \snippet examples/mainwindows/application/mainwindow.cpp 33 + + QMainWindow::statusBar() returns a pointer to the main window's + QStatusBar widget. Like with \l{QMainWindow::menuBar()}, the + widget is automatically created the first time the function is + called. + + \snippet examples/mainwindows/application/mainwindow.cpp 34 + \snippet examples/mainwindows/application/mainwindow.cpp 36 + + The \c readSettings() function is called from the constructor to + load the user's preferences and other application settings. The + QSettings class provides a high-level interface for storing + settings permanently on disk. On Windows, it uses the (in)famous + Windows registry; on Mac OS X, it uses the native XML-based + CFPreferences API; on Unix/X11, it uses text files. + + The QSettings constructor takes arguments that identify your + company and the name of the product. This ensures that the + settings for different applications are kept separately. + + We use QSettings::value() to extract the value of the "pos" and + "size" settings. The second argument to QSettings::value() is + optional and specifies a default value for the setting if there + exists none. This value is used the first time the application is + run. + + When restoring the position and size of a window, it's important + to call QWidget::resize() before QWidget::move(). The reason why + is given in the \l{Window Geometry} overview. + + \snippet examples/mainwindows/application/mainwindow.cpp 37 + \snippet examples/mainwindows/application/mainwindow.cpp 39 + + The \c writeSettings() function is called from \c closeEvent(). + Writing settings is similar to reading them, except simpler. The + arguments to the QSettings constructor must be the same as in \c + readSettings(). + + \snippet examples/mainwindows/application/mainwindow.cpp 40 + \snippet examples/mainwindows/application/mainwindow.cpp 41 + + The \c maybeSave() function is called to save pending changes. If + there are pending changes, it pops up a QMessageBox giving the + user to save the document. The options are QMessageBox::Yes, + QMessageBox::No, and QMessageBox::Cancel. The \gui{Yes} button is + made the default button (the button that is invoked when the user + presses \key{Return}) using the QMessageBox::Default flag; the + \gui{Cancel} button is made the escape button (the button that is + invoked when the user presses \key{Esc}) using the + QMessageBox::Escape flag. + + The \c maybeSave() function returns \c true in all cases, except + when the user clicks \gui{Cancel}. The caller must check the + return value and stop whatever it was doing if the return value + is \c false. + + \snippet examples/mainwindows/application/mainwindow.cpp 42 + \snippet examples/mainwindows/application/mainwindow.cpp 43 + + In \c loadFile(), we use QFile and QTextStream to read in the + data. The QFile object provides access to the bytes stored in a + file. + + We start by opening the file in read-only mode. The QFile::Text + flag indicates that the file is a text file, not a binary file. + On Unix and Mac OS X, this makes no difference, but on Windows, + it ensures that the "\\r\\n" end-of-line sequence is converted to + "\\n" when reading. + + If we successfully opened the file, we use a QTextStream object + to read in the data. QTextStream automatically converts the 8-bit + data into a Unicode QString and supports various encodings. If no + encoding is specified, QTextStream assumes the file is written + using the system's default 8-bit encoding (for example, Latin-1; + see QTextCodec::codecForLocale() for details). + + Since the call to QTextStream::readAll() might take some time, we + set the cursor to be Qt::WaitCursor for the entire application + while it goes on. + + At the end, we call the private \c setCurrentFile() function, + which we'll cover in a moment, and we display the string "File + loaded" in the status bar for 2 seconds (2000 milliseconds). + + \snippet examples/mainwindows/application/mainwindow.cpp 44 + \snippet examples/mainwindows/application/mainwindow.cpp 45 + + Saving a file is very similar to loading one. Here, the + QFile::Text flag ensures that on Windows, "\\n" is converted into + "\\r\\n" to conform to the Windows convension. + + \snippet examples/mainwindows/application/mainwindow.cpp 46 + \snippet examples/mainwindows/application/mainwindow.cpp 47 + + The \c setCurrentFile() function is called to reset the state of + a few variables when a file is loaded or saved, or when the user + starts editing a new file (in which case \c fileName is empty). + We update the \c curFile variable, clear the + QTextDocument::modified flag and the associated \c + QWidget:windowModified flag, and update the window title to + contain the new file name (or \c untitled.txt). + + The \c strippedName() function call around \c curFile in the + QWidget::setWindowTitle() call shortens the file name to exclude + the path. Here's the function: + + \snippet examples/mainwindows/application/mainwindow.cpp 48 + \snippet examples/mainwindows/application/mainwindow.cpp 49 + + \section1 The main() Function + + The \c main() function for this application is typical of + applications that contain one main window: + + \snippet examples/mainwindows/application/main.cpp 0 + + \section1 The Resource File + + As you will probably recall, for some of the actions, we + specified icons with file names starting with \c{:} and mentioned + that such file names aren't ordinary file names, but path in the + executable's stored resources. These resources are compiled + + The resources associated with an application are specified in a + \c .qrc file, an XML-based file format that lists files on the + disk. Here's the \c application.qrc file that's used by the + Application example: + + \quotefile mainwindows/application/application.qrc + + The \c .png files listed in the \c application.qrc file are files + that are part of the Application example's source tree. Paths are + relative to the directory where the \c application.qrc file is + located (the \c mainwindows/application directory). + + The resource file must be mentioned in the \c application.pro + file so that \c qmake knows about it: + + \snippet examples/mainwindows/application/application.pro 0 + + \c qmake will produce make rules to generate a file called \c + qrc_application.cpp that is linked into the application. This + file contains all the data for the images and other resources as + static C++ arrays of compressed binary data. See + \l{resources.html}{The Qt Resource System} for more information + about resources. +*/ diff --git a/doc/src/examples/arrowpad.qdoc b/doc/src/examples/arrowpad.qdoc new file mode 100644 index 0000000000..5e9cc9ae5a --- /dev/null +++ b/doc/src/examples/arrowpad.qdoc @@ -0,0 +1,223 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example linguist/arrowpad + \title Arrow Pad Example + + This example is a slightly more involved and introduces a key \e + {Qt Linguist} concept: "contexts". It also shows how to use two + or more languages. + + \image linguist-arrowpad_en.png + + We will use two translations, French and Dutch, although there is no + effective limit on the number of possible translations that can be used + with an application. The relevant lines of \c arrowpad.pro are + + \snippet examples/linguist/arrowpad/arrowpad.pro 0 + \codeline + \snippet examples/linguist/arrowpad/arrowpad.pro 1 + + Run \c lupdate; it should produce two identical message files + \c arrowpad_fr.ts and \c arrowpad_nl.ts. These files will contain all the source + texts marked for translation with \c tr() calls and their contexts. + + See the \l{Qt Linguist manual} for more information about + translating Qt application. + + \section1 Line by Line Walkthrough + + In \c arrowpad.h we define the \c ArrowPad subclass which is a + subclass of QWidget. In the screenshot above, the central + widget with the four buttons is an \c ArrowPad. + + \snippet examples/linguist/arrowpad/arrowpad.h 0 + \snippet examples/linguist/arrowpad/arrowpad.h 1 + \snippet examples/linguist/arrowpad/arrowpad.h 2 + + When \c lupdate is run it not only extracts the source texts but it + also groups them into contexts. A context is the name of the class in + which the source text appears. Thus, in this example, "ArrowPad" is a + context: it is the context of the texts in the \c ArrowPad class. + The \c Q_OBJECT macro defines \c tr(x) in \c ArrowPad like this: + + \snippet doc/src/snippets/code/doc_src_examples_arrowpad.cpp 0 + + Knowing which class each source text appears in enables \e {Qt + Linguist} to group texts that are logically related together, e.g. + all the text in a dialog will have the context of the dialog's class + name and will be shown together. This provides useful information for + the translator since the context in which text appears may influence how + it should be translated. For some translations keyboard + accelerators may need to be changed and having all the source texts in a + particular context (class) grouped together makes it easier for the + translator to perform any accelerator changes without introducing + conflicts. + + In \c arrowpad.cpp we implement the \c ArrowPad class. + + \snippet examples/linguist/arrowpad/arrowpad.cpp 0 + \snippet examples/linguist/arrowpad/arrowpad.cpp 1 + \snippet examples/linguist/arrowpad/arrowpad.cpp 2 + \snippet examples/linguist/arrowpad/arrowpad.cpp 3 + + We call \c ArrowPad::tr() for each button's label since the labels are + user-visible text. + + \image linguist-arrowpad_en.png + + \snippet examples/linguist/arrowpad/mainwindow.h 0 + \snippet examples/linguist/arrowpad/mainwindow.h 1 + + In the screenshot above, the whole window is a \c MainWindow. + This is defined in the \c mainwindow.h header file. Here too, we + use \c Q_OBJECT, so that \c MainWindow will become a context in + \e {Qt Linguist}. + + \snippet examples/linguist/arrowpad/mainwindow.cpp 0 + + In the implementation of \c MainWindow, \c mainwindow.cpp, we create + an instance of our \c ArrowPad class. + + \snippet examples/linguist/arrowpad/mainwindow.cpp 1 + + We also call \c MainWindow::tr() twice, once for the action and + once for the shortcut. + + Note the use of \c tr() to support different keys in other + languages. "Ctrl+Q" is a good choice for Quit in English, but a + Dutch translator might want to use "Ctrl+A" (for Afsluiten) and a + German translator "Strg+E" (for Beenden). When using \c tr() for + \key Ctrl key accelerators, the two argument form should be used + with the second argument describing the function that the + accelerator performs. + + Our \c main() function is defined in \c main.cpp as usual. + + \snippet examples/linguist/arrowpad/main.cpp 2 + \snippet examples/linguist/arrowpad/main.cpp 3 + + We choose which translation to use according to the current locale. + QLocale::system() can be influenced by setting the \c LANG + environment variable, for example. Notice that the use of a naming + convention that incorporates the locale for \c .qm message files, + (and TS files), makes it easy to implement choosing the + translation file according to locale. + + If there is no QM message file for the locale chosen the original + source text will be used and no error raised. + + \section1 Translating to French and Dutch + + We'll begin by translating the example application into French. Start + \e {Qt Linguist} with \c arrowpad_fr.ts. You should get the seven source + texts ("\&Up", "\&Left", etc.) grouped in two contexts ("ArrowPad" + and "MainWindow"). + + Now, enter the following translations: + + \list + \o \c ArrowPad + \list + \o \&Up - \&Haut + \o \&Left - \&Gauche + \o \&Right - \&Droite + \o \&Down - \&Bas + \endlist + \o \c MainWindow + \list + \o E\&xit - \&Quitter + \o Ctrl+Q - Ctrl+Q + \o \&File - \&Fichier + \endlist + \endlist + + It's quickest to press \key{Alt+D} (which clicks the \gui {Done \& Next} + button) after typing each translation, since this marks the + translation as done and moves on to the next source text. + + Save the file and do the same for Dutch working with \c arrowpad_nl.ts: + + \list + \o \c ArrowPad + \list + \o \&Up - \&Omhoog + \o \&Left - \&Links + \o \&Right - \&Rechts + \o \&Down - Omlaa\&g + \endlist + \o \c MainWindow + \list + \o E\&xit - \&Afsluiten + \o Ctrl+Q - Ctrl+A + \o File - \&Bestand + \endlist + \endlist + + We have to convert the \c tt1_fr.ts and \c tt1_nl.ts translation source + files into QM files. We could use \e {Qt Linguist} as we've done + before; however using the command line tool \c lrelease ensures that + \e all the QM files for the application are created without us + having to remember to load and \gui File|Release each one + individually from \e {Qt Linguist}. + + Type + + \snippet doc/src/snippets/code/doc_src_examples_arrowpad.qdoc 1 + + This should create both \c arrowpad_fr.qm and \c arrowpad_nl.qm. Set the \c + LANG environment variable to \c fr. In Unix, one of the two following + commands should work + + \snippet doc/src/snippets/code/doc_src_examples_arrowpad.qdoc 2 + + In Windows, either modify \c autoexec.bat or run + + \snippet doc/src/snippets/code/doc_src_examples_arrowpad.qdoc 3 + + When you run the program, you should now see the French version: + + \image linguist-arrowpad_fr.png + + Try the same with Dutch, by setting \c LANG=nl. Now the Dutch + version should appear: + + \image linguist-arrowpad_nl.png + + \section1 Exercises + + Mark one of the translations in \e {Qt Linguist} as not done, i.e. + by unchecking the "done" checkbox; run \c lupdate, then \c lrelease, + then the example. What effect did this change have? + + Set \c LANG=fr_CA (French Canada) and run the example program again. + Explain why the result is the same as with \c LANG=fr. + + Change one of the accelerators in the Dutch translation to eliminate the + conflict between \e \&Bestand and \e \&Boven. +*/ diff --git a/doc/src/examples/basicdrawing.qdoc b/doc/src/examples/basicdrawing.qdoc new file mode 100644 index 0000000000..7df061d566 --- /dev/null +++ b/doc/src/examples/basicdrawing.qdoc @@ -0,0 +1,454 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example painting/basicdrawing + \title Basic Drawing Example + + The Basic Drawing example shows how to display basic graphics + primitives in a variety of styles using the QPainter class. + + QPainter performs low-level painting on widgets and other paint + devices. The class can draw everything from simple lines to + complex shapes like pies and chords. It can also draw aligned text + and pixmaps. Normally, it draws in a "natural" coordinate system, + but it can in addition do view and world transformation. + + \image basicdrawing-example.png + + The example provides a render area, displaying the currently + active shape, and lets the user manipulate the rendered shape and + its appearance using the QPainter parameters: The user can change + the active shape (\gui Shape), and modify the QPainter's pen (\gui + {Pen Width}, \gui {Pen Style}, \gui {Pen Cap}, \gui {Pen Join}), + brush (\gui {Brush Style}) and render hints (\gui + Antialiasing). In addition the user can rotate a shape (\gui + Transformations); behind the scenes we use QPainter's ability to + manipulate the coordinate system to perform the rotation. + + The Basic Drawing example consists of two classes: + + \list + \o \c RenderArea is a custom widget that renders multiple + copies of the currently active shape. + \o \c Window is the application's main window displaying a + \c RenderArea widget in addition to several parameter widgets. + \endlist + + First we will review the \c Window class, then we will take a + look at the \c RenderArea class. + + \section1 Window Class Definition + + The Window class inherits QWidget, and is the application's main + window displaying a \c RenderArea widget in addition to several + parameter widgets. + + \snippet examples/painting/basicdrawing/window.h 0 + + We declare the various widgets, and three private slots updating + the \c RenderArea widget: The \c shapeChanged() slot updates the + \c RenderArea widget when the user changes the currently active + shape. We call the \c penChanged() slot when either of the + QPainter's pen parameters changes. And the \c brushChanged() slot + updates the \c RenderArea widget when the user changes the + painter's brush style. + + \section1 Window Class Implementation + + In the constructor we create and initialize the various widgets + appearing in the main application window. + + \snippet examples/painting/basicdrawing/window.cpp 1 + + First we create the \c RenderArea widget that will render the + currently active shape. Then we create the \gui Shape combobox, + and add the associated items (i.e. the different shapes a QPainter + can draw). + + \snippet examples/painting/basicdrawing/window.cpp 2 + + QPainter's pen is a QPen object; the QPen class defines how a + painter should draw lines and outlines of shapes. A pen has + several properties: Width, style, cap and join. + + A pen's width can be \e zero or greater, but the most common width + is zero. Note that this doesn't mean 0 pixels, but implies that + the shape is drawn as smoothly as possible although perhaps not + mathematically correct. + + We create a QSpinBox for the \gui {Pen Width} parameter. + + \snippet examples/painting/basicdrawing/window.cpp 3 + + The pen style defines the line type. The default style is solid + (Qt::SolidLine). Setting the style to none (Qt::NoPen) tells the + painter to not draw lines or outlines. The pen cap defines how + the end points of lines are drawn. And the pen join defines how + two lines join when multiple connected lines are drawn. The cap + and join only apply to lines with a width of 1 pixel or greater. + + We create \l {QComboBox}es for each of the \gui {Pen Style}, \gui + {Pen Cap} and \gui {Pen Join} parameters, and adds the associated + items (i.e the values of the Qt::PenStyle, Qt::PenCapStyle and + Qt::PenJoinStyle enums respectively). + + \snippet examples/painting/basicdrawing/window.cpp 4 + + The QBrush class defines the fill pattern of shapes drawn by a + QPainter. The default brush style is Qt::NoBrush. This style tells + the painter to not fill shapes. The standard style for filling is + Qt::SolidPattern. + + We create a QComboBox for the \gui {Brush Style} parameter, and add + the associated items (i.e. the values of the Qt::BrushStyle enum). + + \snippet examples/painting/basicdrawing/window.cpp 5 + \snippet examples/painting/basicdrawing/window.cpp 6 + + Antialiasing is a feature that "smoothes" the pixels to create + more even and less jagged lines, and can be applied using + QPainter's render hints. QPainter::RenderHints are used to specify + flags to QPainter that may or may not be respected by any given + engine. + + We simply create a QCheckBox for the \gui Antialiasing option. + + \snippet examples/painting/basicdrawing/window.cpp 7 + + The \gui Transformations option implies a manipulation of the + coordinate system that will appear as if the rendered shape is + rotated in three dimensions. + + We use the QPainter::translate(), QPainter::rotate() and + QPainter::scale() functions to implement this feature represented + in the main application window by a simple QCheckBox. + + \snippet examples/painting/basicdrawing/window.cpp 8 + + Then we connect the parameter widgets with their associated slots + using the static QObject::connect() function, ensuring that the \c + RenderArea widget is updated whenever the user changes the shape, + or any of the other parameters. + + \snippet examples/painting/basicdrawing/window.cpp 9 + \snippet examples/painting/basicdrawing/window.cpp 10 + + Finally, we add the various widgets to a layout, and call the \c + shapeChanged(), \c penChanged(), and \c brushChanged() slots to + initialize the application. We also turn on antialiasing. + + \snippet examples/painting/basicdrawing/window.cpp 11 + + The \c shapeChanged() slot is called whenever the user changes the + currently active shape. + + First we retrieve the shape the user has chosen using the + QComboBox::itemData() function. This function returns the data for + the given role in the given index in the combobox. We use + QComboBox::currentIndex() to retrieve the index of the shape, and + the role is defined by the Qt::ItemDataRole enum; \c IdRole is an + alias for Qt::UserRole. + + Note that Qt::UserRole is only the first role that can be used for + application-specific purposes. If you need to store different data + in the same index, you can use different roles by simply + incrementing the value of Qt::UserRole, for example: 'Qt::UserRole + + 1' and 'Qt::UserRole + 2'. However, it is a good programming + practice to give each role their own name: 'myFirstRole = + Qt::UserRole + 1' and 'mySecondRole = Qt::UserRole + 2'. Even + though we only need a single role in this particular example, we + add the following line of code to the beginning of the \c + window.cpp file. + + \snippet examples/painting/basicdrawing/window.cpp 0 + + The QComboBox::itemData() function returns the data as a QVariant, + so we need to cast the data to \c RenderArea::Shape. If there is + no data for the given role, the function returns + QVariant::Invalid. + + In the end we call the \c RenderArea::setShape() slot to update + the \c RenderArea widget. + + \snippet examples/painting/basicdrawing/window.cpp 12 + + We call the \c penChanged() slot whenever the user changes any of + the pen parameters. Again we use the QComboBox::itemData() + function to retrieve the parameters, and then we call the \c + RenderArea::setPen() slot to update the \c RenderArea widget. + + \snippet examples/painting/basicdrawing/window.cpp 13 + + The brushChanged() slot is called whenever the user changes the + brush parameter which we retrieve using the QComboBox::itemData() + function as before. + + \snippet examples/painting/basicdrawing/window.cpp 14 + + If the brush parameter is a gradient fill, special actions are + required. + + The QGradient class is used in combination with QBrush to specify + gradient fills. Qt currently supports three types of gradient + fills: linear, radial and conical. Each of these is represented by + a subclass of QGradient: QLinearGradient, QRadialGradient and + QConicalGradient. + + So if the brush style is Qt::LinearGradientPattern, we first + create a QLinearGradient object with interpolation area between + the coordinates passed as arguments to the constructor. The + positions are specified using logical coordinates. Then we set the + gradient's colors using the QGradient::setColorAt() function. The + colors is defined using stop points which are composed by a + position (between 0 and 1) and a QColor. The set of stop points + describes how the gradient area should be filled. A gradient can + have an arbitrary number of stop points. + + In the end we call \c RenderArea::setBrush() slot to update the \c + RenderArea widget's brush with the QLinearGradient object. + + \snippet examples/painting/basicdrawing/window.cpp 15 + + A similar pattern of actions, as the one used for QLinearGradient, + is used in the cases of Qt::RadialGradientPattern and + Qt::ConicalGradientPattern. + + The only difference is the arguments passed to the constructor: + Regarding the QRadialGradient constructor the first argument is + the center, and the second the radial gradient's radius. The third + argument is optional, but can be used to define the focal point of + the gradient inside the circle (the default focal point is the + circle center). Regarding the QConicalGradient constructor, the + first argument specifies the center of the conical, and the second + specifies the start angle of the interpolation. + + \snippet examples/painting/basicdrawing/window.cpp 16 + + If the brush style is Qt::TexturePattern we create a QBrush from a + QPixmap. Then we call \c RenderArea::setBrush() slot to update the + \c RenderArea widget with the newly created brush. + + \snippet examples/painting/basicdrawing/window.cpp 17 + + Otherwise we simply create a brush with the given style and a + green color, and then call \c RenderArea::setBrush() slot to + update the \c RenderArea widget with the newly created brush. + + \section1 RenderArea Class Definition + + The \c RenderArea class inherits QWidget, and renders multiple + copies of the currently active shape using a QPainter. + + \snippet examples/painting/basicdrawing/renderarea.h 0 + + First we define a public \c Shape enum to hold the different + shapes that can be rendered by the widget (i.e the shapes that can + be rendered by a QPainter). Then we reimplement the constructor as + well as two of QWidget's public functions: \l + {QWidget::minimumSizeHint()}{minimumSizeHint()} and \l + {QWidget::sizeHint()}{sizeHint()}. + + We also reimplement the QWidget::paintEvent() function to be able + to draw the currently active shape according to the specified + parameters. + + We declare several private slots: The \c setShape() slot changes + the \c RenderArea's shape, the \c setPen() and \c setBrush() slots + modify the widget's pen and brush, and the \c setAntialiased() and + \c setTransformed() slots modify the widget's respective + properties. + + \section1 RenderArea Class Implementation + + In the constructor we initialize some of the widget's variables. + + \snippet examples/painting/basicdrawing/renderarea.cpp 0 + + We set its shape to be a \gui Polygon, its antialiased property to + be false and we load an image into the widget's pixmap + variable. In the end we set the widget's background role, defining + the brush from the widget's \l {QWidget::palette}{palette} that + will be used to render the background. QPalette::Base is typically + white. + + \snippet examples/painting/basicdrawing/renderarea.cpp 2 + + The \c RenderArea inherits QWidget's \l + {QWidget::sizeHint()}{sizeHint} property holding the recommended + size for the widget. If the value of this property is an invalid + size, no size is recommended. + + The default implementation of the QWidget::sizeHint() function + returns an invalid size if there is no layout for the widget, and + returns the layout's preferred size otherwise. + + Our reimplementation of the function returns a QSize with a 400 + pixels width and a 200 pixels height. + + \snippet examples/painting/basicdrawing/renderarea.cpp 1 + + \c RenderArea also inherits QWidget's + \l{QWidget::minimumSizeHint()}{minimumSizeHint} property holding + the recommended minimum size for the widget. Again, if the value + of this property is an invalid size, no size is recommended. + + The default implementation of QWidget::minimumSizeHint() returns + an invalid size if there is no layout for the widget, and returns + the layout's minimum size otherwise. + + Our reimplementation of the function returns a QSize with a 100 + pixels width and a 100 pixels height. + + \snippet examples/painting/basicdrawing/renderarea.cpp 3 + \codeline + \snippet examples/painting/basicdrawing/renderarea.cpp 4 + \codeline + \snippet examples/painting/basicdrawing/renderarea.cpp 5 + + The public \c setShape(), \c setPen() and \c setBrush() slots are + called whenever we want to modify a \c RenderArea widget's shape, + pen or brush. We set the shape, pen or brush according to the + slot parameter, and call QWidget::update() to make the changes + visible in the \c RenderArea widget. + + The QWidget::update() slot does not cause an immediate + repaint; instead it schedules a paint event for processing when Qt + returns to the main event loop. + + \snippet examples/painting/basicdrawing/renderarea.cpp 6 + \codeline + \snippet examples/painting/basicdrawing/renderarea.cpp 7 + + With the \c setAntialiased() and \c setTransformed() slots we + change the state of the properties according to the slot + parameter, and call the QWidget::update() slot to make the changes + visible in the \c RenderArea widget. + + \snippet examples/painting/basicdrawing/renderarea.cpp 8 + + Then we reimplement the QWidget::paintEvent() function. The first + thing we do is to create the graphical objects we will need to + draw the various shapes. + + We create a vector of four \l {QPoint}s. We use this vector to + render the \gui Points, \gui Polyline and \gui Polygon + shapes. Then we create a QRect, defining a rectangle in the plane, + which we use as the bounding rectangle for all the shapes excluding + the \gui Path and the \gui Pixmap. + + We also create a QPainterPath. The QPainterPath class provides a + container for painting operations, enabling graphical shapes to be + constructed and reused. A painter path is an object composed of a + number of graphical building blocks, such as rectangles, ellipses, + lines, and curves. For more information about the QPainterPath + class, see the \l {painting/painterpaths}{Painter Paths} + example. In this example, we create a painter path composed of one + straight line and a Bezier curve. + + In addition we define a start angle and an arc length that we will + use when drawing the \gui Arc, \gui Chord and \gui Pie shapes. + + \snippet examples/painting/basicdrawing/renderarea.cpp 9 + + We create a QPainter for the \c RenderArea widget, and set the + painters pen and brush according to the \c RenderArea's pen and + brush. If the \gui Antialiasing parameter option is checked, we + also set the painter's render hints. QPainter::Antialiasing + indicates that the engine should antialias edges of primitives if + possible. + + \snippet examples/painting/basicdrawing/renderarea.cpp 10 + + Finally, we render the multiple copies of the \c RenderArea's + shape. The number of copies is depending on the size of the \c + RenderArea widget, and we calculate their positions using two \c + for loops and the widgets height and width. + + For each copy we first save the current painter state (pushes the + state onto a stack). Then we translate the coordinate system, + using the QPainter::translate() function, to the position + determined by the variables of the \c for loops. If we omit this + translation of the coordinate system all the copies of the shape + will be rendered on top of each other in the top left cormer of + the \c RenderArea widget. + + \snippet examples/painting/basicdrawing/renderarea.cpp 11 + + If the \gui Transformations parameter option is checked, we do an + additional translation of the coordinate system before we rotate + the coordinate system 60 degrees clockwise using the + QPainter::rotate() function and scale it down in size using the + QPainter::scale() function. In the end we translate the coordinate + system back to where it was before we rotated and scaled it. + + Now, when rendering the shape, it will appear as if it was rotated + in three dimensions. + + \snippet examples/painting/basicdrawing/renderarea.cpp 12 + + Next, we identify the \c RenderArea's shape, and render it using + the associated QPainter drawing function: + + \list + \o QPainter::drawLine(), + \o QPainter::drawPoints(), + \o QPainter::drawPolyline(), + \o QPainter::drawPolygon(), + \o QPainter::drawRect(), + \o QPainter::drawRoundedRect(), + \o QPainter::drawEllipse(), + \o QPainter::drawArc(), + \o QPainter::drawChord(), + \o QPainter::drawPie(), + \o QPainter::drawPath(), + \o QPainter::drawText() or + \o QPainter::drawPixmap() + \endlist + + Before we started rendering, we saved the current painter state + (pushes the state onto a stack). The rationale for this is that we + calculate each shape copy's position relative to the same point in + the coordinate system. When translating the coordinate system, we + lose the knowledge of this point unless we save the current + painter state \e before we start the translating process. + + \snippet examples/painting/basicdrawing/renderarea.cpp 13 + + Then, when we are finished rendering a copy of the shape we can + restore the original painter state, with its associated coordinate + system, using the QPainter::restore() function. In this way we + ensure that the next shape copy will be rendered in the correct + position. + + We could translate the coordinate system back using + QPainter::translate() instead of saving the painter state. But + since we in addition to translating the coordinate system (when + the \gui Transformation parameter option is checked) both rotate + and scale the coordinate system, the easiest solution is to save + the current painter state. +*/ diff --git a/doc/src/examples/basicgraphicslayouts.qdoc b/doc/src/examples/basicgraphicslayouts.qdoc new file mode 100644 index 0000000000..0110e29951 --- /dev/null +++ b/doc/src/examples/basicgraphicslayouts.qdoc @@ -0,0 +1,164 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example graphicsview/basicgraphicslayouts + \title Basic Graphics Layouts Example + + The Basic Graphics Layouts example shows how to use the layout classes + in QGraphicsView: QGraphicsLinearLayout and QGraphicsGridLayout. + In addition to that it shows how to write your own custom layout item. + + \image basicgraphicslayouts-example.png Screenshot of the Basic Layouts Example + + \section1 Window Class Definition + + The \c Window class is a subclass of QGraphicsWidget. It has a + constructor with a QGraphicsWidget \a parent as its parameter. + + \snippet examples/graphicsview/basicgraphicslayouts/window.h 0 + + \section1 Window Class Implementation + + The constructor of \c Window instantiates a QGraphicsLinearLayout object, + \c windowLayout, with vertical orientation. We instantiate another + QGraphicsLinearLayout object, \c linear, whose parent is \c windowLayout. + Next, we create a \c LayoutItem object, \c item and add it to \c linear + with the \l{QGraphicsLinearLayout::}{addItem()} function. We also provide + \c item with a \l{QGraphicsLinearLayout::setStretchFactor()} + {stretchFactor}. + + \snippet examples/graphicsview/basicgraphicslayouts/window.cpp 0 + + We repeat the process: + + \list + \o create a new \c LayoutItem, + \o add the item \c linear, and + \o provide a stretch factor. + \endlist + + \snippet examples/graphicsview/basicgraphicslayouts/window.cpp 1 + + We then add \c linear to \c windowLayout, nesting two + QGraphicsLinearLayout objects. Apart from the QGraphicsLinearLayout, we + also use a QGraphicsGridLayout object, \c grid, which is a 4x3 grid with + some cells spanning to other rows. + + We create seven \c LayoutItem objects and place them into \c grid with + the \l{QGraphicsGridLayout::}{addItem()} function as shown in the code + snippet below: + + \snippet examples/graphicsview/basicgraphicslayouts/window.cpp 2 + + The first item we add to \c grid is placed in the top left cell, + spanning four rows. The next two items are placed in the second column, + and they span two rows. Each item's \l{QGraphicsWidget::}{maximumHeight()} + and \l{QGraphicsWidget::}{minimumHeight()} are set to be equal so that + they do not expand vertically. As a result, these items will not + fit vertically in their cells. So, we specify that they should be + vertically aligned in the center of the cell using Qt::AlignVCenter. + + Finally, \c grid itself is added to \c windowLayout. Unlike + QGridLayout::addItem(), QGraphicsGridLayout::addItem() requires a row + and a column for its argument, specifying which cell the item should be + positioned in. Also, if the \c rowSpan and \c columnSpan arguments + are omitted, they will default to 1. + + Note that we do not specify a parent for each \c LayoutItem that we + construct, as all these items will be added to \c windowLayout. When we + add an item to a layout, it will be automatically reparented to the widget + on which the layout is installed. + + \snippet examples/graphicsview/basicgraphicslayouts/window.cpp 3 + + Now that we have set up \c grid and added it to \c windowLayout, we + install \c windowLayout onto the window object using + QGraphicsWidget::setLayout() and we set the window title. + + \section1 LayoutItem Class Definition + + The \c LayoutItem class is a subclass of QGraphicsLayoutItem and + QGraphicsItem. It has a constructor, a destructor, and some required + reimplementations. + Since it inherits QGraphicsLayoutItem it must reimplement + {QGraphicsLayoutItem::setGeometry()}{setGeometry()} and + {QGraphicsLayoutItem::sizeHint()}{sizeHint()}. + In addition to that it inherits QGraphicsItem, so it must reimplement + {QGraphicsItem::boundingRect()}{boundingRect()} and + {QGraphicsItem::paint()}{paint()}. + + \snippet examples/graphicsview/basicgraphicslayouts/layoutitem.h 0 + + The \c LayoutItem class also has a private instance of QPixmap, \c m_pix. + + \section1 LayoutItem Class Implementation + + In \c{LayoutItem}'s constructor, \c m_pix is instantiated and the + \c{block.png} image is loaded into it. + + \snippet examples/graphicsview/basicgraphicslayouts/layoutitem.cpp 0 + + We use the Q_UNUSED() macro to prevent the compiler from generating + warnings regarding unused parameters. + + \snippet examples/graphicsview/basicgraphicslayouts/layoutitem.cpp 1 + + The idea behind the \c paint() function is to paint the + background rect then paint a rect around the pixmap. + + \snippet examples/graphicsview/basicgraphicslayouts/layoutitem.cpp 2 + + The reimplementation of \l{QGraphicsItem::}{boundingRect()} + will set the top left corner at (0,0), and the size of it will be + the size of the layout items + \l{QGraphicsLayoutItem::}{geometry()}. This is the area that + we paint within. + + \snippet examples/graphicsview/basicgraphicslayouts/layoutitem.cpp 3 + + + The reimplementation of \l{QGraphicsLayoutItem::setGeometry()}{setGeometry()} + simply calls its baseclass implementation. However, since this will change + the boundingRect we must also call + \l{QGraphicsItem::prepareGeometryChange()}{prepareGeometryChange()}. + Finally, we move the item according to \c geom.topLeft(). + + \snippet examples/graphicsview/basicgraphicslayouts/layoutitem.cpp 4 + + + Since we don't want the size of the item to be smaller than the pixmap, we + must make sure that we return a size hint that is larger than \c m_pix. + We also add some extra space around for borders that we will paint later. + Alternatively, you could scale the pixmap to prevent the item from + becoming smaller than the pixmap. + The preferred size is the same as the minimum size hint, while we set + maximum to be a large value + + \snippet examples/graphicsview/basicgraphicslayouts/layoutitem.cpp 5 + +*/
\ No newline at end of file diff --git a/doc/src/examples/basiclayouts.qdoc b/doc/src/examples/basiclayouts.qdoc new file mode 100644 index 0000000000..c6e2ae1a74 --- /dev/null +++ b/doc/src/examples/basiclayouts.qdoc @@ -0,0 +1,190 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example layouts/basiclayouts + \title Basic Layouts Example + + The Basic Layouts example shows how to use the standard layout + managers that are available in Qt: QBoxLayout, QGridLayout and + QFormLayout. + + \image basiclayouts-example.png Screenshot of the Basic Layouts example + + The QBoxLayout class lines up widgets horizontally or vertically. + QHBoxLayout and QVBoxLayout are convenience subclasses of QBoxLayout. + QGridLayout lays out widgets in cells by dividing the available space + into rows and columns. QFormLayout, on the other hand, lays out its + children in a two-column form with labels in the left column and + input fields in the right column. + + \section1 Dialog Class Definition + + \snippet examples/layouts/basiclayouts/dialog.h 0 + + The \c Dialog class inherits QDialog. It is a custom widget that + displays its child widgets using the geometry managers: + QHBoxLayout, QVBoxLayout, QGridLayout and QFormLayout. + + We declare four private functions to simplify the class + constructor: The \c createMenu(), \c createHorizontalGroupBox(), + \c createGridGroupBox() and \c createFormGroupBox() functions create + several widgets that the example uses to demonstrate how the layout + affects their appearances. + + \section1 Dialog Class Implementation + + \snippet examples/layouts/basiclayouts/dialog.cpp 0 + + In the constructor, we first use the \c createMenu() function to + create and populate a menu bar and the \c createHorizontalGroupBox() + function to create a group box containing four buttons with a + horizontal layout. Next we use the \c createGridGroupBox() function + to create a group box containing several line edits and a small text + editor which are displayed in a grid layout. Finally, we use the + \c createFormGroupBox() function to create a group box with + three labels and three input fields: a line edit, a combo box and + a spin box. + + \snippet examples/layouts/basiclayouts/dialog.cpp 1 + + We also create a big text editor and a dialog button box. The + QDialogButtonBox class is a widget that presents buttons in a + layout that is appropriate to the current widget style. The + preferred buttons can be specified as arguments to the + constructor, using the QDialogButtonBox::StandardButtons enum. + + Note that we don't have to specify a parent for the widgets when + we create them. The reason is that all the widgets we create here + will be added to a layout, and when we add a widget to a layout, + it is automatically reparented to the widget the layout is + installed on. + + \snippet examples/layouts/basiclayouts/dialog.cpp 2 + + The main layout is a QVBoxLayout object. QVBoxLayout is a + convenience class for a box layout with vertical orientation. + + In general, the QBoxLayout class takes the space it gets (from its + parent layout or from the parent widget), divides it up into a + series of boxes, and makes each managed widget fill one box. If + the QBoxLayout's orientation is Qt::Horizontal the boxes are + placed in a row. If the orientation is Qt::Vertical, the boxes are + placed in a column. The corresponding convenience classes are + QHBoxLayout and QVBoxLayout, respectively. + + \snippet examples/layouts/basiclayouts/dialog.cpp 3 + + When we call the QLayout::setMenuBar() function, the layout places + the provided menu bar at the top of the parent widget, and outside + the widget's \l {QWidget::contentsRect()}{content margins}. All + child widgets are placed below the bottom edge of the menu bar. + + \snippet examples/layouts/basiclayouts/dialog.cpp 4 + + We use the QBoxLayout::addWidget() function to add the widgets to + the end of layout. Each widget will get at least its minimum size + and at most its maximum size. It is possible to specify a stretch + factor in the \l {QBoxLayout::addWidget()}{addWidget()} function, + and any excess space is shared according to these stretch + factors. If not specified, a widget's stretch factor is 0. + + \snippet examples/layouts/basiclayouts/dialog.cpp 5 + + We install the main layout on the \c Dialog widget using the + QWidget::setLayout() function, and all of the layout's widgets are + automatically reparented to be children of the \c Dialog widget. + + \snippet examples/layouts/basiclayouts/dialog.cpp 6 + + In the private \c createMenu() function we create a menu bar, and + add a pull-down \gui File menu containing an \gui Exit option. + + \snippet examples/layouts/basiclayouts/dialog.cpp 7 + + When we create the horizontal group box, we use a QHBoxLayout as + the internal layout. We create the buttons we want to put in the + group box, add them to the layout and install the layout on the + group box. + + \snippet examples/layouts/basiclayouts/dialog.cpp 8 + + In the \c createGridGroupBox() function we use a QGridLayout which + lays out widgets in a grid. It takes the space made available to + it (by its parent layout or by the parent widget), divides it up + into rows and columns, and puts each widget it manages into the + correct cell. + + \snippet examples/layouts/basiclayouts/dialog.cpp 9 + + For each row in the grid we create a label and an associated line + edit, and add them to the layout. The QGridLayout::addWidget() + function differ from the corresponding function in QBoxLayout: It + needs the row and column specifying the grid cell to put the + widget in. + + \snippet examples/layouts/basiclayouts/dialog.cpp 10 + + QGridLayout::addWidget() can in addition take arguments + specifying the number of rows and columns the cell will be + spanning. In this example, we create a small editor which spans + three rows and one column. + + For both the QBoxLayout::addWidget() and QGridLayout::addWidget() + functions it is also possible to add a last argument specifying + the widget's alignment. By default it fills the whole cell. But we + could, for example, align a widget with the right edge by + specifying the alignment to be Qt::AlignRight. + + \snippet examples/layouts/basiclayouts/dialog.cpp 11 + + Each column in a grid layout has a stretch factor. The stretch + factor is set using QGridLayout::setColumnStretch() and determines + how much of the available space the column will get over and above + its necessary minimum. + + In this example, we set the stretch factors for columns 1 and 2. + The stretch factor is relative to the other columns in this grid; + columns with a higher stretch factor take more of the available + space. So column 2 in our grid layout will get more of the + available space than column 1, and column 0 will not grow at all + since its stretch factor is 0 (the default). + + Columns and rows behave identically; there is an equivalent + stretch factor for rows, as well as a QGridLayout::setRowStretch() + function. + + \snippet examples/layouts/basiclayouts/dialog.cpp 12 + + In the \c createFormGroupBox() function, we use a QFormLayout + to neatly arrange objects into two columns - name and field. + There are three QLabel objects for names with three + corresponding input widgets as fields: a QLineEdit, a QComboBox + and a QSpinBox. Unlike QBoxLayout::addWidget() and + QGridLayout::addWidget(), we use QFormLayout::addRow() to add widgets + to the layout. +*/ diff --git a/doc/src/examples/basicsortfiltermodel.qdoc b/doc/src/examples/basicsortfiltermodel.qdoc new file mode 100644 index 0000000000..58dbf36fed --- /dev/null +++ b/doc/src/examples/basicsortfiltermodel.qdoc @@ -0,0 +1,37 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example itemviews/basicsortfiltermodel + \title Basic Sort/Filter Model Example + + The Basic Sort/Filter Model example illustrates how to use + QSortFilterProxyModel to perform basic sorting and filtering. + + \image basicsortfiltermodel-example.png Screenshot of the Basic Sort/Filter Model Example + +*/ diff --git a/doc/src/examples/bearermonitor.qdoc b/doc/src/examples/bearermonitor.qdoc new file mode 100644 index 0000000000..cc4a78267f --- /dev/null +++ b/doc/src/examples/bearermonitor.qdoc @@ -0,0 +1,35 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example network/bearermonitor + \title Bearer Monitor Example + + The Bearer Monitor example shows how to use the Bearer Management API. + + \image bearermonitor-example.png Screenshot of the Bearer Monitor example +*/ diff --git a/doc/src/examples/blockingfortuneclient.qdoc b/doc/src/examples/blockingfortuneclient.qdoc new file mode 100644 index 0000000000..7c282980b9 --- /dev/null +++ b/doc/src/examples/blockingfortuneclient.qdoc @@ -0,0 +1,216 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example network/blockingfortuneclient + \title Blocking Fortune Client Example + + The Blocking Fortune Client example shows how to create a client for a + network service using QTcpSocket's synchronous API in a non-GUI thread. + + \image blockingfortuneclient-example.png + + QTcpSocket supports two general approaches to network programming: + + \list + + \o \e{The asynchronous (non-blocking) approach.} Operations are scheduled + and performed when control returns to Qt's event loop. When the operation + is finished, QTcpSocket emits a signal. For example, + QTcpSocket::connectToHost() returns immediately, and when the connection + has been established, QTcpSocket emits + \l{QTcpSocket::connected()}{connected()}. + + \o \e{The synchronous (blocking) approach.} In non-GUI and multithreaded + applications, you can call the \c waitFor...() functions (e.g., + QTcpSocket::waitForConnected()) to suspend the calling thread until the + operation has completed, instead of connecting to signals. + + \endlist + + The implementation is very similar to the + \l{network/fortuneclient}{Fortune Client} example, but instead of having + QTcpSocket as a member of the main class, doing asynchronous networking in + the main thread, we will do all network operations in a separate thread + and use QTcpSocket's blocking API. + + The purpose of this example is to demonstrate a pattern that you can use + to simplify your networking code, without losing responsiveness in your + user interface. Use of Qt's blocking network API often leads to + simpler code, but because of its blocking behavior, it should only be used + in non-GUI threads to prevent the user interface from freezing. But + contrary to what many think, using threads with QThread does not + necessarily add unmanagable complexity to your application. + + We will start with the FortuneThread class, which handles the network + code. + + \snippet examples/network/blockingfortuneclient/fortunethread.h 0 + + FortuneThread is a QThread subclass that provides an API for scheduling + requests for fortunes, and it has signals for delivering fortunes and + reporting errors. You can call requestNewFortune() to request a new + fortune, and the result is delivered by the newFortune() signal. If any + error occurs, the error() signal is emitted. + + It's important to notice that requestNewFortune() is called from the main, + GUI thread, but the host name and port values it stores will be accessed + from FortuneThread's thread. Because we will be reading and writing + FortuneThread's data members from different threads concurrently, we use + QMutex to synchronize access. + + \snippet examples/network/blockingfortuneclient/fortunethread.cpp 2 + + The requestNewFortune() function stores the host name and port of the + fortune server as member data, and we lock the mutex with QMutexLocker to + protect this data. We then start the thread, unless it is already + running. We will come back to the QWaitCondition::wakeOne() call later. + + \snippet examples/network/blockingfortuneclient/fortunethread.cpp 4 + \snippet examples/network/blockingfortuneclient/fortunethread.cpp 5 + + In the run() function, we start by acquiring the mutex lock, fetching the + host name and port from the member data, and then releasing the lock + again. The case that we are protecting ourselves against is that \c + requestNewFortune() could be called at the same time as we are fetching + this data. QString is \l reentrant but \e not \l{thread-safe}, and we must + also avoid the unlikely risk of reading the host name from one request, + and port of another. And as you might have guessed, FortuneThread can only + handle one request at a time. + + The run() function now enters a loop: + + \snippet examples/network/blockingfortuneclient/fortunethread.cpp 6 + + The loop will continue requesting fortunes for as long as \e quit is + false. We start our first request by creating a QTcpSocket on the stack, + and then we call \l{QTcpSocket::connectToHost()}{connectToHost()}. This + starts an asynchronous operation which, after control returns to Qt's + event loop, will cause QTcpSocket to emit + \l{QTcpSocket::connected()}{connected()} or + \l{QTcpSocket::error()}{error()}. + + \snippet examples/network/blockingfortuneclient/fortunethread.cpp 8 + + But since we are running in a non-GUI thread, we do not have to worry + about blocking the user interface. So instead of entering an event loop, + we simply call QTcpSocket::waitForConnected(). This function will wait, + blocking the calling thread, until QTcpSocket emits connected() or an + error occurs. If connected() is emitted, the function returns true; if the + connection failed or timed out (which in this example happens after 5 + seconds), false is returned. QTcpSocket::waitForConnected(), like the + other \c waitFor...() functions, is part of QTcpSocket's \e{blocking + API}. + + After this statement, we have a connected socket to work with. Now it's + time to see what the fortune server has sent us. + + \snippet examples/network/blockingfortuneclient/fortunethread.cpp 9 + \snippet examples/network/blockingfortuneclient/fortunethread.cpp 10 + + This step is to read the size of the packet. Although we are only reading + two bytes here, and the \c while loop may seem to overdo it, we present this + code to demonstrate a good pattern for waiting for data using + QTcpSocket::waitForReadyRead(). It goes like this: For as long as we still + need more data, we call waitForReadyRead(). If it returns false, + we abort the operation. After this statement, we know that we have received + enough data. + + \snippet examples/network/blockingfortuneclient/fortunethread.cpp 11 + + Now we can create a QDataStream object, passing the socket to + QDataStream's constructor, and as in the other client examples we set + the stream protocol version to QDataStream::Qt_4_0, and read the size + of the packet. + + \snippet examples/network/blockingfortuneclient/fortunethread.cpp 12 + \snippet examples/network/blockingfortuneclient/fortunethread.cpp 13 + + Again, we'll use a loop that waits for more data by calling + QTcpSocket::waitForReadyRead(). In this loop, we're waiting until + QTcpSocket::bytesAvailable() returns the full packet size. + + \snippet examples/network/blockingfortuneclient/fortunethread.cpp 14 + + Now that we have all the data that we need, we can use QDataStream to + read the fortune string from the packet. The resulting fortune is + delivered by emitting newFortune(). + + \snippet examples/network/blockingfortuneclient/fortunethread.cpp 15 + + The final part of our loop is that we acquire the mutex so that we can + safely read from our member data. We then let the thread go to sleep by + calling QWaitCondition::wait(). At this point, we can go back to + requestNewFortune() and look closed at the call to wakeOne(): + + \snippet examples/network/blockingfortuneclient/fortunethread.cpp 1 + \dots + \snippet examples/network/blockingfortuneclient/fortunethread.cpp 3 + + What happened here was that because the thread falls asleep waiting for a + new request, we needed to wake it up again when a new request + arrives. QWaitCondition is often used in threads to signal a wakeup call + like this. + + \snippet examples/network/blockingfortuneclient/fortunethread.cpp 0 + + Finishing off the FortuneThread walkthrough, this is the destructor that + sets \e quit to true, wakes up the thread and waits for the thread to exit + before returning. This lets the \c while loop in run() will finish its current + iteration. When run() returns, the thread will terminate and be destroyed. + + Now for the BlockingClient class: + + \snippet examples/network/blockingfortuneclient/blockingclient.h 0 + + BlockingClient is very similar to the Client class in the + \l{network/fortuneclient}{Fortune Client} example, but in this class + we store a FortuneThread member instead of a pointer to a QTcpSocket. + When the user clicks the "Get Fortune" button, the same slot is called, + but its implementation is slightly different: + + \snippet examples/network/blockingfortuneclient/blockingclient.cpp 0 + \snippet examples/network/blockingfortuneclient/blockingclient.cpp 1 + + We connect our FortuneThread's two signals newFortune() and error() (which + are somewhat similar to QTcpSocket::readyRead() and QTcpSocket::error() in + the previous example) to requestNewFortune() and displayError(). + + \snippet examples/network/blockingfortuneclient/blockingclient.cpp 2 + + The requestNewFortune() slot calls FortuneThread::requestNewFortune(), + which \e shedules the request. When the thread has received a new fortune + and emits newFortune(), our showFortune() slot is called: + + \snippet examples/network/blockingfortuneclient/blockingclient.cpp 3 + \codeline + \snippet examples/network/blockingfortuneclient/blockingclient.cpp 4 + + Here, we simply display the fortune we received as the argument. + + \sa {Fortune Client Example}, {Fortune Server Example} +*/ diff --git a/doc/src/examples/blurpicker.qdoc b/doc/src/examples/blurpicker.qdoc new file mode 100644 index 0000000000..205041cc64 --- /dev/null +++ b/doc/src/examples/blurpicker.qdoc @@ -0,0 +1,33 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example effects/blurpicker + \title Blur Picker Effect Example + + \image blurpickereffect-example.png +*/ diff --git a/doc/src/examples/borderlayout.qdoc b/doc/src/examples/borderlayout.qdoc new file mode 100644 index 0000000000..c81f9ec59b --- /dev/null +++ b/doc/src/examples/borderlayout.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example layouts/borderlayout + \title Border Layout Example + + The Border Layout example shows how to create a custom layout that arranges + child widgets according to a simple set of rules. + + \image borderlayout-example.png +*/ diff --git a/doc/src/examples/broadcastreceiver.qdoc b/doc/src/examples/broadcastreceiver.qdoc new file mode 100644 index 0000000000..ea3c331032 --- /dev/null +++ b/doc/src/examples/broadcastreceiver.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example network/broadcastreceiver + \title Broadcast Receiver Example + + The Broadcast Receiever example shows how to receive information that is broadcasted + over a local network. + + \image broadcastreceiver-example.png +*/ diff --git a/doc/src/examples/broadcastsender.qdoc b/doc/src/examples/broadcastsender.qdoc new file mode 100644 index 0000000000..3ceb33317d --- /dev/null +++ b/doc/src/examples/broadcastsender.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example network/broadcastsender + \title Broadcast Sender Example + + The Broadcast Sender example shows how to broadcast information to multiple clients + on a local network. + + \image broadcastsender-example.png +*/ diff --git a/doc/src/examples/cachedtable.qdoc b/doc/src/examples/cachedtable.qdoc new file mode 100644 index 0000000000..d8b3f134b2 --- /dev/null +++ b/doc/src/examples/cachedtable.qdoc @@ -0,0 +1,197 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example sql/cachedtable + \title Cached Table Example + + The Cached Table example shows how a table view can be used to access a database, + caching any changes to the data until the user explicitly submits them using a + push button. + + \image cachedtable-example.png + + The example consists of a single class, \c TableEditor, which is a + custom dialog widget that allows the user to modify data stored in + a database. We will first review the class definiton and how to + use the class, then we will take a look at the implementation. + + \section1 TableEditor Class Definition + + The \c TableEditor class inherits QDialog making the table editor + widget a top-level dialog window. + + \snippet examples/sql/cachedtable/tableeditor.h 0 + + The \c TableEditor constructor takes two arguments: The first is a + pointer to the parent widget and is passed on to the base class + constructor. The other is a reference to the database table the \c + TableEditor object will operate on. + + Note the QSqlTableModel variable declaration: As we will see in + this example, the QSqlTableModel class can be used to provide data + to view classes such as QTableView. The QSqlTableModel class + provides an editable data model making it possible to read and + write database records from a single table. It is build on top of + the lower-level QSqlQuery class which provides means of executing + and manipulating SQL statements. + + We are also going to show how a table view can be used to cache + any changes to the data until the user explicitly requests to + submit them. For that reason we need to declare a \c submit() slot + in additon to the model and the editor's buttons. + + \table 100% + \header \o Connecting to a Database + \row + \o + + Before we can use the \c TableEditor class, we must create a + connection to the database containing the table we want to edit: + + \snippet examples/sql/cachedtable/main.cpp 0 + + The \c createConnection() function is a helper function provided + for convenience. It is defined in the \c connection.h file which + is located in the \c sql example directory (all the examples in + the \c sql directory use this function to connect to a database). + + \snippet examples/sql/connection.h 0 + + The \c createConnection function opens a connection to an + in-memory SQLITE database and creates a test table. If you want + to use another database, simply modify this function's code. + \endtable + + \section1 TableEditor Class Implementation + + The class implementation consists of only two functions, the + constructor and the \c submit() slot. In the constructor we create + and customize the data model and the various window elements: + + \snippet examples/sql/cachedtable/tableeditor.cpp 0 + + First we create the data model and set the SQL database table we + want the model to operate on. Note that the + QSqlTableModel::setTable() function does not select data from the + table; it only fetches its field information. For that reason we + call the QSqlTableModel::select() function later on, populating + the model with data from the table. The selection can be + customized by specifying filters and sort conditions (see the + QSqlTableModel class documentation for more details). + + We also set the model's edit strategy. The edit strategy dictates + when the changes done by the user in the view, are actually + applied to the database. Since we want to cache the changes in the + table view (i.e. in the model) until the user explicitly submits + them, we choose the QSqlTableModel::OnManualSubmit strategy. The + alternatives are QSqlTableModel::OnFieldChange and + QSqlTableModel::OnRowChange. + + Finally, we set up the labels displayed in the view header using + the \l {QSqlQueryModel::setHeaderData()}{setHeaderData()} function + that the model inherits from the QSqlQueryModel class. + + \snippet examples/sql/cachedtable/tableeditor.cpp 1 + + Then we create a table view. The QTableView class provides a + default model/view implementation of a table view, i.e. it + implements a table view that displays items from a model. It also + allows the user to edit the items, storing the changes in the + model. To create a read only view, set the proper flag using the + \l {QAbstractItemView::editTriggers}{editTriggers} property the + view inherits from the QAbstractItemView class. + + To make the view present our data, we pass our model to the view + using the \l {QAbstractItemView::setModel()}{setModel()} function. + + \snippet examples/sql/cachedtable/tableeditor.cpp 2 + + The \c {TableEditor}'s buttons are regular QPushButton objects. We + add them to a button box to ensure that the buttons are presented + in a layout that is appropriate to the current widget style. The + rationale for this is that dialogs and message boxes typically + present buttons in a layout that conforms to the interface + guidelines for that platform. Invariably, different platforms have + different layouts for their dialogs. QDialogButtonBox allows a + developer to add buttons to it and will automatically use the + appropriate layout for the user's desktop environment. + + Most buttons for a dialog follow certain roles. When adding a + button to a button box using the \l + {QDialogButtonBox}{addButton()} function, the button's role must + be specified using the QDialogButtonBox::ButtonRole + enum. Alternatively, QDialogButtonBox provides several standard + buttons (e.g. \gui OK, \gui Cancel, \gui Save) that you can + use. They exist as flags so you can OR them together in the + constructor. + + \snippet examples/sql/cachedtable/tableeditor.cpp 3 + + We connect the \gui Quit button to the table editor's \l + {QWidget::close()}{close()} slot, and the \gui Submit button to + our private \c submit() slot. The latter slot will take care of + the data transactions. Finally, we connect the \gui Revert button + to our model's \l {QSqlTableModel::revertAll()}{revertAll()} slot, + reverting all pending changes (i.e., restoring the original data). + + \snippet examples/sql/cachedtable/tableeditor.cpp 4 + + In the end we add the button box and the table view to a layout, + install the layout on the table editor widget, and set the + editor's window title. + + \snippet examples/sql/cachedtable/tableeditor.cpp 5 + + The \c submit() slot is called whenever the users hit the \gui + Submit button to save their changes. + + First, we begin a transaction on the database using the + QSqlDatabase::transaction() function. A database transaction is a + unit of interaction with a database management system or similar + system that is treated in a coherent and reliable way independent + of other transactions. A pointer to the used database can be + obtained using the QSqlTableModel::database() function. + + Then, we try to submit all the pending changes, i.e. the model's + modified items. If no error occurs, we commit the transaction to + the database using the QSqlDatabase::commit() function (note that + on some databases, this function will not work if there is an + active QSqlQuery on the database). Otherwise we perform a rollback + of the transaction using the QSqlDatabase::rollback() function and + post a warning to the user. + + \table 100% + \row + \o + \bold {See also:} + + A complete list of Qt's SQL \l {Database Classes}, and the \l + {Model/View Programming} documentation. + + \endtable +*/ diff --git a/doc/src/examples/calculator.qdoc b/doc/src/examples/calculator.qdoc new file mode 100644 index 0000000000..653a6452b4 --- /dev/null +++ b/doc/src/examples/calculator.qdoc @@ -0,0 +1,375 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example widgets/calculator + \title Calculator Example + + The example shows how to use signals and slots to implement the + functionality of a calculator widget, and how to use QGridLayout + to place child widgets in a grid. + + \image calculator-example.png Screenshot of the Calculator example + + The example consists of two classes: + + \list + \o \c Calculator is the calculator widget, with all the + calculator functionality. + \o \c Button is the widget used for each of the calculator + button. It derives from QToolButton. + \endlist + + We will start by reviewing \c Calculator, then we will take a + look at \c Button. + + \section1 Calculator Class Definition + + \snippet examples/widgets/calculator/calculator.h 0 + + The \c Calculator class provides a simple calculator widget. It + inherits from QDialog and has several private slots associated + with the calculator's buttons. QObject::eventFilter() is + reimplemented to handle mouse events on the calculator's display. + + Buttons are grouped in categories according to their behavior. + For example, all the digit buttons (labeled \gui 0 to \gui 9) + append a digit to the current operand. For these, we connect + multiple buttons to the same slot (e.g., \c digitClicked()). The + categories are digits, unary operators (\gui{Sqrt}, \gui{x\unicode{178}}, + \gui{1/x}), additive operators (\gui{+}, \gui{-}), and + multiplicative operators (\gui{\unicode{215}}, \gui{\unicode{247}}). The other buttons + have their own slots. + + \snippet examples/widgets/calculator/calculator.h 1 + \snippet examples/widgets/calculator/calculator.h 2 + + The private \c createButton() function is used as part of the + widget construction. \c abortOperation() is called whenever a + division by zero occurs or when a square root operation is + applied to a negative number. \c calculate() applies a binary + operator (\gui{+}, \gui{-}, \gui{\unicode{215}}, or \gui{\unicode{247}}). + + \snippet examples/widgets/calculator/calculator.h 3 + \snippet examples/widgets/calculator/calculator.h 4 + \snippet examples/widgets/calculator/calculator.h 5 + \snippet examples/widgets/calculator/calculator.h 6 + \snippet examples/widgets/calculator/calculator.h 7 + \snippet examples/widgets/calculator/calculator.h 8 + + These variables, together with the contents of the calculator + display (a QLineEdit), encode the state of the calculator: + + \list + \o \c sumInMemory contains the value stored in the calculator's memory + (using \gui{MS}, \gui{M+}, or \gui{MC}). + \o \c sumSoFar stores the value accumulated so far. When the user + clicks \gui{=}, \c sumSoFar is recomputed and shown on the + display. \gui{Clear All} resets \c sumSoFar to zero. + \o \c factorSoFar stores a temporary value when doing + multiplications and divisions. + \o \c pendingAdditiveOperator stores the last additive operator + clicked by the user. + \o \c pendingMultiplicativeOperator stores the last multiplicative operator + clicked by the user. + \o \c waitingForOperand is \c true when the calculator is + expecting the user to start typing an operand. + \endlist + + Additive and multiplicative operators are treated differently + because they have different precedences. For example, \gui{1 + 2 \unicode{247} + 3} is interpreted as \gui{1 + (2 \unicode{247} 3)} because \gui{\unicode{247}} has higher + precedence than \gui{+}. + + The table below shows the evolution of the calculator state as + the user enters a mathematical expression. + + \table + \header \o User Input \o Display \o Sum so Far \o Add. Op. \o Factor so Far \o Mult. Op. \o Waiting for Operand? + \row \o \o 0 \o 0 \o \o \o \o \c true + \row \o \gui{1} \o 1 \o 0 \o \o \o \o \c false + \row \o \gui{1 +} \o 1 \o 1 \o \gui{+} \o \o \o \c true + \row \o \gui{1 + 2} \o 2 \o 1 \o \gui{+} \o \o \o \c false + \row \o \gui{1 + 2 \unicode{247}} \o 2 \o 1 \o \gui{+} \o 2 \o \gui{\unicode{247}} \o \c true + \row \o \gui{1 + 2 \unicode{247} 3} \o 3 \o 1 \o \gui{+} \o 2 \o \gui{\unicode{247}} \o \c false + \row \o \gui{1 + 2 \unicode{247} 3 -} \o 1.66667 \o 1.66667 \o \gui{-} \o \o \o \c true + \row \o \gui{1 + 2 \unicode{247} 3 - 4} \o 4 \o 1.66667 \o \gui{-} \o \o \o \c false + \row \o \gui{1 + 2 \unicode{247} 3 - 4 =} \o -2.33333 \o 0 \o \o \o \o \c true + \endtable + + Unary operators, such as \gui Sqrt, require no special handling; + they can be applied immediately since the operand is already + known when the operator button is clicked. + + \snippet examples/widgets/calculator/calculator.h 9 + \codeline + \snippet examples/widgets/calculator/calculator.h 10 + + Finally, we declare the variables associated with the display and the + buttons used to display numerals. + + \section1 Calculator Class Implementation + + \snippet examples/widgets/calculator/calculator.cpp 0 + + In the constructor, we initialize the calculator's state. The \c + pendingAdditiveOperator and \c pendingMultiplicativeOperator + variables don't need to be initialized explicitly, because the + QString constructor initializes them to empty strings. + + \snippet examples/widgets/calculator/calculator.cpp 1 + \snippet examples/widgets/calculator/calculator.cpp 2 + + We create the QLineEdit representing the calculator's display and + set up some of its properties. In particular, we set it to be + read-only. + + We also enlarge \c{display}'s font by 8 points. + + \snippet examples/widgets/calculator/calculator.cpp 4 + + For each button, we call the private \c createButton() function with + the proper text label and a slot to connect to the button. + + \snippet examples/widgets/calculator/calculator.cpp 5 + \snippet examples/widgets/calculator/calculator.cpp 6 + + The layout is handled by a single QGridLayout. The + QLayout::setSizeConstraint() call ensures that the \c Calculator + widget is always shown as its optimal size (its + \l{QWidget::sizeHint()}{size hint}), preventing the user from + resizing the calculator. The size hint is determined by the size + and \l{QWidget::sizePolicy()}{size policy} of the child widgets. + + Most child widgets occupy only one cell in the grid layout. For + these, we only need to pass a row and a column to + QGridLayout::addWidget(). The \c display, \c backspaceButton, \c + clearButton, and \c clearAllButton widgets occupy more than one + column; for these we must also pass a row span and a column + span. + + \snippet examples/widgets/calculator/calculator.cpp 7 + + Pressing one of the calculator's digit buttons will emit the + button's \l{QToolButton::clicked()}{clicked()} signal, which will + trigger the \c digitClicked() slot. + + First, we find out which button sent the signal using + QObject::sender(). This function returns the sender as a QObject + pointer. Since we know that the sender is a \c Button object, we + can safely cast the QObject. We could have used a C-style cast or + a C++ \c static_cast<>(), but as a defensive programming + technique we use a \l qobject_cast(). The advantage is that if + the object has the wrong type, a null pointer is returned. + Crashes due to null pointers are much easier to diagnose than + crashes due to unsafe casts. Once we have the button, we extract + the operator using QToolButton::text(). + + The slot needs to consider two situations in particular. If \c + display contains "0" and the user clicks the \gui{0} button, it + would be silly to show "00". And if the calculator is in + a state where it is waiting for a new operand, + the new digit is the first digit of that new operand; in that case, + any result of a previous calculation must be cleared first. + + At the end, we append the new digit to the value in the display. + + \snippet examples/widgets/calculator/calculator.cpp 8 + \snippet examples/widgets/calculator/calculator.cpp 9 + + The \c unaryOperatorClicked() slot is called whenever one of the + unary operator buttons is clicked. Again a pointer to the clicked + button is retrieved using QObject::sender(). The operator is + extracted from the button's text and stored in \c + clickedOperator. The operand is obtained from \c display. + + Then we perform the operation. If \gui Sqrt is applied to a + negative number or \gui{1/x} to zero, we call \c + abortOperation(). If everything goes well, we display the result + of the operation in the line edit and we set \c waitingForOperand + to \c true. This ensures that if the user types a new digit, the + digit will be considered as a new operand, instead of being + appended to the current value. + + \snippet examples/widgets/calculator/calculator.cpp 10 + \snippet examples/widgets/calculator/calculator.cpp 11 + + The \c additiveOperatorClicked() slot is called when the user + clicks the \gui{+} or \gui{-} button. + + Before we can actually do something about the clicked operator, + we must handle any pending operations. We start with the + multiplicative operators, since these have higher precedence than + additive operators: + + \snippet examples/widgets/calculator/calculator.cpp 12 + \snippet examples/widgets/calculator/calculator.cpp 13 + + If \gui{\unicode{215}} or \gui{\unicode{247}} has been clicked earlier, without clicking + \gui{=} afterward, the current value in the display is the right + operand of the \gui{\unicode{215}} or \gui{\unicode{247}} operator and we can finally + perform the operation and update the display. + + \snippet examples/widgets/calculator/calculator.cpp 14 + \snippet examples/widgets/calculator/calculator.cpp 15 + + If \gui{+} or \gui{-} has been clicked earlier, \c sumSoFar is + the left operand and the current value in the display is the + right operand of the operator. If there is no pending additive + operator, \c sumSoFar is simply set to be the text in the + display. + + \snippet examples/widgets/calculator/calculator.cpp 16 + \snippet examples/widgets/calculator/calculator.cpp 17 + + Finally, we can take care of the operator that was just clicked. + Since we don't have the right-hand operand yet, we store the clicked + operator in the \c pendingAdditiveOperator variable. We will + apply the operation later, when we have a right operand, with \c + sumSoFar as the left operand. + + \snippet examples/widgets/calculator/calculator.cpp 18 + + The \c multiplicativeOperatorClicked() slot is similar to \c + additiveOperatorClicked(). We don't need to worry about pending + additive operators here, because multiplicative operators have + precedence over additive operators. + + \snippet examples/widgets/calculator/calculator.cpp 20 + + Like in \c additiveOperatorClicked(), we start by handing any + pending multiplicative and additive operators. Then we display \c + sumSoFar and reset the variable to zero. Resetting the variable + to zero is necessary to avoid counting the value twice. + + \snippet examples/widgets/calculator/calculator.cpp 22 + + The \c pointClicked() slot adds a decimal point to the content in + \c display. + + \snippet examples/widgets/calculator/calculator.cpp 24 + + The \c changeSignClicked() slot changes the sign of the value in + \c display. If the current value is positive, we prepend a minus + sign; if the current value is negative, we remove the first + character from the value (the minus sign). + + \snippet examples/widgets/calculator/calculator.cpp 26 + + The \c backspaceClicked() removes the rightmost character in the + display. If we get an empty string, we show "0" and set \c + waitingForOperand to \c true. + + \snippet examples/widgets/calculator/calculator.cpp 28 + + The \c clear() slot resets the current operand to zero. It is + equivalent to clicking \gui Backspace enough times to erase the + entire operand. + + \snippet examples/widgets/calculator/calculator.cpp 30 + + The \c clearAll() slot resets the calculator to its initial state. + + \snippet examples/widgets/calculator/calculator.cpp 32 + + The \c clearMemory() slot erases the sum kept in memory, \c + readMemory() displays the sum as an operand, \c setMemory() + replace the sum in memory with the current sum, and \c + addToMemory() adds the current value to the value in memory. For + \c setMemory() and \c addToMemory(), we start by calling \c + equalClicked() to update \c sumSoFar and the value in the + display. + + \snippet examples/widgets/calculator/calculator.cpp 34 + + The private \c createButton() function is called from the + constructor to create calculator buttons. + + \snippet examples/widgets/calculator/calculator.cpp 36 + + The private \c abortOperation() function is called whenever a + calculation fails. It resets the calculator state and displays + "####". + + \snippet examples/widgets/calculator/calculator.cpp 38 + + The private \c calculate() function performs a binary operation. + The right operand is given by \c rightOperand. For additive + operators, the left operand is \c sumSoFar; for multiplicative + operators, the left operand is \c factorSoFar. The function + return \c false if a division by zero occurs. + + \section1 Button Class Definition + + Let's now take a look at the \c Button class: + + \snippet examples/widgets/calculator/button.h 0 + + The \c Button class has a convenience constructor that takes a + text label and a parent widget, and it reimplements QWidget::sizeHint() + to provide more space around the text than the amount QToolButton + normally provides. + + \section1 Button Class Implementation + + \snippet examples/widgets/calculator/button.cpp 0 + + The buttons' appearance is determined by the layout of the + calculator widget through the size and + \l{QWidget::sizePolicy}{size policy} of the layout's child + widgets. The call to the + \l{QWidget::setSizePolicy()}{setSizePolicy()} function in the + constructor ensures that the button will expand horizontally to + fill all the available space; by default, \l{QToolButton}s don't + expand to fill available space. Without this call, the different + buttons in a same column would have different widths. + + \snippet examples/widgets/calculator/button.cpp 1 + \snippet examples/widgets/calculator/button.cpp 2 + + In \l{QWidget::sizeHint()}{sizeHint()}, we try to return a size + that looks good for most buttons. We reuse the size hint of the + base class (QToolButton) but modify it in the following ways: + + \list + \o We add 20 to the \l{QSize::height()}{height} component of the size hint. + \o We make the \l{QSize::width()}{width} component of the size + hint at least as much as the \l{QSize::width()}{height}. + \endlist + + This ensures that with most fonts, the digit and operator buttons + will be square, without truncating the text on the + \gui{Backspace}, \gui{Clear}, and \gui{Clear All} buttons. + + The screenshot below shows how the \c Calculator widget would + look like if we \e didn't set the horizontal size policy to + QSizePolicy::Expanding in the constructor and if we didn't + reimplement QWidget::sizeHint(). + + \image calculator-ugly.png The Calculator example with default size policies and size hints + +*/ diff --git a/doc/src/examples/calendar.qdoc b/doc/src/examples/calendar.qdoc new file mode 100644 index 0000000000..8acef03a5a --- /dev/null +++ b/doc/src/examples/calendar.qdoc @@ -0,0 +1,223 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example richtext/calendar + \title Calendar Example + + The Calendar example shows how to create rich text content and display it using + a rich text editor. + + \image calendar-example.png + + Specifically, the example demonstrates the following: + + \list + \o Use of a text editor with a text document + \o Insertion of tables and frames into a document + \o Navigation within a table + \o Insert text in different styles + \endlist + + The rich text editor used to display the document is used within a main window + application. + + \section1 MainWindow Class Definition + + The \c MainWindow class provides a text editor widget and some controls to + allow the user to change the month and year shown. The font size used for the + text can also be adjusted. + + \snippet examples/richtext/calendar/mainwindow.h 0 + + The private \c insertCalendar() function performs most of the work, relying on + the \c fontSize and \c selectedDate variables to write useful information to + the \c editor. + + \section1 MainWindow Class Implementation + + The \c MainWindow constructor sets up the user interface and initializes + variables used to generate a calendar for each month. + + \snippet examples/richtext/calendar/mainwindow.cpp 0 + + We begin by setting default values for the selected date that will be highlighted + in the calendar and the font size to be used. Since we are using a QMainWindow + for the user interface, we construct a widget for use as the central widget. + + The user interface will include a line of controls above the generated calendar; + we construct a label and a combobox to allow the month to be selected, and a + spin box for the year. These widgets are configured to provide a reasonable range + of values for the user to try: + + \snippet examples/richtext/calendar/mainwindow.cpp 1 + + We use the \c selectedDate object to obtain the current month and year, and we + set these in the combobox and spin box: + + The font size is displayed in a spin box which we restrict to a sensible range + of values: + + \snippet examples/richtext/calendar/mainwindow.cpp 2 + + We construct an editor and use the \c insertCalendar() function to create + a calendar for it. Each calendar is displayed in the same text editor; in + this example we use a QTextBrowser since we do not allow the calendar to be + edited. + + The controls used to set the month, year, and font size will not have any + effect on the appearance of the calendar unless we make some signal-slot + connections: + + \snippet examples/richtext/calendar/mainwindow.cpp 3 + + The signals are connected to some simple slots in the \c MainWindow class + which we will describe later. + + We create layouts to manage the widgets we constructed: + + \snippet examples/richtext/calendar/mainwindow.cpp 4 + + Finally, the central widget is set for the window. + + Each calendar is created for the editor by the \c insertCalendar() function + which uses the date and font size, defined by the private \a selectedDate + and \c fontSize variables, to produce a suitable plan for the specified + month and year. + + \snippet examples/richtext/calendar/mainwindow.cpp 5 + + We begin by clearing the editor's rich text document, and obtain a text + cursor from the editor that we will use to add content. We also create a + QDate object based on the currently selected date. + + The calendar is made up of a table with a gray background color that contains + seven columns: one for each day of the week. It is placed in the center of the + page with equal space to the left and right of it. All of these properties are + set in a QTextTableFormat object: + + \snippet examples/richtext/calendar/mainwindow.cpp 6 + + Each cell in the table will be padded and spaced to make the text easier to + read. + + We want the columns to have equal widths, so we provide a vector containing + percentage widths for each of them and set the constraints in the + QTextTableFormat: + + \snippet examples/richtext/calendar/mainwindow.cpp 7 + + The constraints used for the column widths are only useful if the table has + an appropriate number of columns. With the format for the table defined, we + construct a new table with one row and seven columns at the current cursor + position: + + \snippet examples/richtext/calendar/mainwindow.cpp 8 + + We only need one row to start with; more can be added as we need them. Using + this approach means that we do not need to perform any date calculations + until we add cells to the table. + + When inserting objects into a document with the cursor's insertion functions, + the cursor is automatically moved inside the newly inserted object. This means + that we can immediately start modifying the table from within: + + \snippet examples/richtext/calendar/mainwindow.cpp 9 + + Since the table has an outer frame, we obtain the frame and its format so that + we can customize it. After making the changes we want, we set the frame's format + using the modified format object. We have given the table an outer border one + pixel wide. + + \snippet examples/richtext/calendar/mainwindow.cpp 10 + + In a similar way, we obtain the cursor's current character format and + create customized formats based on it. + + We do not set the format on the cursor because this would change the default + character format; instead, we use the customized formats explicitly when we + insert text. The following loop inserts the days of the week into the table + as bold text: + + \snippet examples/richtext/calendar/mainwindow.cpp 11 + + For each day of the week, we obtain an existing table cell in the first row + (row 0) using the table's \l{QTextTable::cellAt()}{cellAt()} function. Since + we start counting the days of the week at day 1 (Monday), we subtract 1 from + \c weekDay to ensure that we obtain the cell for the correct column of the + table. + + Before text can be inserted into a cell, we must obtain a cursor with the + correct position in the document. The cell provides a function for this + purpose, and we use this cursor to insert text using the \c boldFormat + character format that we created earlier: + + \snippet examples/richtext/calendar/mainwindow.cpp 12 + + Inserting text into document objects usually follows the same pattern. + Each object can provide a new cursor that corresponds to the first valid + position within itself, and this can be used to insert new content. We + continue to use this pattern as we insert the days of the month into the + table. + + Since every month has more than seven days, we insert a single row to begin + and add days until we reach the end of the month. If the current date is + encountered, it is inserted with a special format (created earlier) that + makes it stand out: + + \snippet examples/richtext/calendar/mainwindow.cpp 13 + + We add a new row to the table at the end of each week only if the next week + falls within the currently selected month. + + For each calendar that we create, we change the window title to reflect the + currently selected month and year: + + \snippet examples/richtext/calendar/mainwindow.cpp 14 + + The \c insertCalendar() function relies on up-to-date values for the month, + year, and font size. These are set in the following slots: + + \snippet examples/richtext/calendar/mainwindow.cpp 15 + + The \c setFontSize() function simply changes the private \c fontSize variable + before updating the calendar. + + \snippet examples/richtext/calendar/mainwindow.cpp 16 + + The \c setMonth slot is called when the QComboBox used to select the month is + updated. The value supplied is the currently selected row in the combobox. + We add 1 to this value to obtain a valid month number, and create a new QDate + based on the existing one. The calendar is then updated to use this new date. + + \snippet examples/richtext/calendar/mainwindow.cpp 17 + + The \c setYear() slot is called when the QDateTimeEdit used to select the + year is updated. The value supplied is a QDate object; this makes + the construction of a new value for \c selectedDate simple. We update the + calendar afterwards to use this new date. +*/ diff --git a/doc/src/examples/calendarwidget.qdoc b/doc/src/examples/calendarwidget.qdoc new file mode 100644 index 0000000000..da195648a4 --- /dev/null +++ b/doc/src/examples/calendarwidget.qdoc @@ -0,0 +1,291 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \title Calendar Widget Example + \example widgets/calendarwidget + + The Calendar Widget example shows use of \c QCalendarWidget. + + \image calendarwidgetexample.png + + QCalendarWidget displays one calendar month + at a time and lets the user select a date. + The calendar consists of four components: a navigation + bar that lets the user change the month that is + displayed, a grid where each cell represents one day + in the month, and two headers that display weekday names + and week numbers. + + The Calendar Widget example displays a QCalendarWidget and lets the user + configure its appearance and behavior using + \l{QComboBox}es, \l{QCheckBox}es, and \l{QDateEdit}s. In + addition, the user can influence the formatting of individual dates + and headers. + + The properties of the QCalendarWidget are summarized in the table + below. + + \table + \header \o Property + \o Description + \row \o \l{QCalendarWidget::}{selectedDate} + \o The currently selected date. + \row \o \l{QCalendarWidget::}{minimumDate} + \o The earliest date that can be selected. + \row \o \l{QCalendarWidget::}{maximumDate} + \o The latest date that can be selected. + \row \o \l{QCalendarWidget::}{firstDayOfWeek} + \o The day that is displayed as the first day of the week + (usually Sunday or Monday). + \row \o \l{QCalendarWidget::}{gridVisible} + \o Whether the grid should be shown. + \row \o \l{QCalendarWidget::}{selectionMode} + \o Whether the user can select a date or not. + \row \o \l{QCalendarWidget::}{horizontalHeaderFormat} + \o The format of the day names in the horizontal header + (e.g., "M", "Mon", or "Monday"). + \row \o \l{QCalendarWidget::}{verticalHeaderFormat} + \o The format of the vertical header. + \row \o \l{QCalendarWidget::}{navigationBarVisible} + \o Whether the navigation bar at the top of the calendar + widget is shown. + \endtable + + The example consists of one class, \c Window, which creates and + lays out the QCalendarWidget and the other widgets that let the + user configure the QCalendarWidget. + + \section1 Window Class Definition + + Here is the definition of the \c Window class: + + \snippet examples/widgets/calendarwidget/window.h 0 + \dots + \snippet examples/widgets/calendarwidget/window.h 1 + + As is often the case with classes that represent self-contained + windows, most of the API is private. We will review the private + members as we stumble upon them in the implementation. + + \section1 Window Class Implementation + + Let's now review the class implementation, starting with the constructor: + + \snippet examples/widgets/calendarwidget/window.cpp 0 + + We start by creating the four \l{QGroupBox}es and their child + widgets (including the QCalendarWidget) using four private \c + create...GroupBox() functions, described below. Then we arrange + the group boxes in a QGridLayout. + + We set the grid layout's resize policy to QLayout::SetFixedSize to + prevent the user from resizing the window. In that mode, the + window's size is set automatically by QGridLayout based on the + size hints of its contents widgets. + + To ensure that the window isn't automatically resized every time + we change a property of the QCalendarWidget (e.g., hiding the + navigation bar, trhe vertical header, or the grid), we set the + minimum height of row 0 and the minimum width of column 0 to the + initial size of the QCalendarWidget. + + Let's move on to the \c createPreviewGroupBox() function: + + \snippet examples/widgets/calendarwidget/window.cpp 9 + + The \gui Preview group box contains only one widget: the + QCalendarWidget. We set it up, connect its + \l{QCalendarWidget::}{currentPageChanged()} signal to our \c + reformatCalendarPage() slot to make sure that every new page gets + the formatting specified by the user. + + The \c createGeneralOptionsGroupBox() function is somewhat large + and several widgets are set up the same way; we look at parts of + its implementation here and skip the rest: + + \snippet examples/widgets/calendarwidget/window.cpp 10 + \dots + + We start with the setup of the \gui{Week starts on} combobox. + This combobox controls which day should be displayed as the first + day of the week. + + The QComboBox class lets us attach user data as a QVariant to + each item. The data can later be retrieved with QComboBox's + \l{QComboBox::}{itemData()} function. QVariant doesn't directly + support the Qt::DayOfWeek data type, but it supports \c int, and + C++ will happily convert any enum value to \c int. + + \dots + \snippet examples/widgets/calendarwidget/window.cpp 11 + \dots + + After creating the widgets, we connect the signals and slots. We + connect the comboboxes to private slots of \c Window or to + public slots provided by QComboBox. + + \dots + \snippet examples/widgets/calendarwidget/window.cpp 12 + + At the end of the function, we call the slots that update the calendar to ensure + that the QCalendarWidget is synchronized with the other widgets on startup. + + Let's now take a look at the \c createDatesGroupBox() private function: + + \snippet examples/widgets/calendarwidget/window.cpp 13 + + In this function, we create the \gui {Minimum Date}, \gui {Maximum Date}, + and \gui {Current Date} editor widgets, + which control the calendar's minimum, maximum, and selected dates. + The calendar's minimum and maximum dates have already been + set in \c createPrivewGroupBox(); we can then set the widgets + default values to the calendars values. + + \snippet examples/widgets/calendarwidget/window.cpp 14 + \dots + \snippet examples/widgets/calendarwidget/window.cpp 15 + + We connect the \c currentDateEdit's + \l{QDateEdit::}{dateChanged()} signal directly to the calendar's + \l{QCalendarWidget::}{setSelectedDate()} slot. When the calendar's + selected date changes, either as a result of a user action or + programmatically, our \c selectedDateChanged() slot updates + the \gui {Current Date} editor. We also need to react when the user + changes the \gui{Minimum Date} and \gui{Maximum Date} editors. + + Here is the \c createTextFormatsGroup() function: + + \snippet examples/widgets/calendarwidget/window.cpp 16 + + We set up the \gui {Weekday Color} and \gui {Weekend Color} comboboxes + using \c createColorCombo(), which instantiates a QComboBox and + populates it with colors ("Red", "Blue", etc.). + + \snippet examples/widgets/calendarwidget/window.cpp 17 + + The \gui {Header Text Format} combobox lets the user change the + text format (bold, italic, or plain) used for horizontal and + vertical headers. The \gui {First Friday in blue} and \gui {May 1 + in red} check box affect the rendering of specific dates. + + \snippet examples/widgets/calendarwidget/window.cpp 18 + + We connect the check boxes and comboboxes to various private + slots. The \gui {First Friday in blue} and \gui {May 1 in red} + check boxes are both connected to \c reformatCalendarPage(), + which is also called when the calendar switches month. + + \dots + \snippet examples/widgets/calendarwidget/window.cpp 19 + + At the end of \c createTextFormatsGroupBox(), we call private + slots to synchronize the QCalendarWidget with the other widgets. + + We're now done reviewing the four \c create...GroupBox() + functions. Let's now take a look at the other private functions + and slots. + + \snippet examples/widgets/calendarwidget/window.cpp 20 + + In \c createColorCombo(), we create a combobox and populate it with + standard colors. The second argument to QComboBox::addItem() + is a QVariant storing user data (in this case, QColor objects). + + This function was used to set up the \gui {Weekday Color} + and \gui {Weekend Color} comboboxes. + + \snippet examples/widgets/calendarwidget/window.cpp 1 + + When the user changes the \gui {Week starts on} combobox's + value, \c firstDayChanged() is invoked with the index of the + combobox's new value. We retrieve the custom data item + associated with the new current item using + \l{QComboBox::}{itemData()} and cast it to a Qt::DayOfWeek. + + \c selectionModeChanged(), \c horizontalHeaderChanged(), and \c + verticalHeaderChanged() are very similar to \c firstDayChanged(), + so they are omitted. + + \snippet examples/widgets/calendarwidget/window.cpp 2 + + The \c selectedDateChanged() updates the \gui{Current Date} + editor to reflect the current state of the QCalendarWidget. + + \snippet examples/widgets/calendarwidget/window.cpp 3 + + When the user changes the minimum date, we tell the + QCalenderWidget. We also update the \gui {Maximum Date} editor, + because if the new minimum date is later than the current maximum + date, QCalendarWidget will automatically adapt its maximum date + to avoid a contradicting state. + + \snippet examples/widgets/calendarwidget/window.cpp 4 + + \c maximumDateChanged() is implemented similarly to \c + minimumDateChanged(). + + \snippet examples/widgets/calendarwidget/window.cpp 5 + + Each combobox item has a QColor object as user data corresponding to the + item's text. After fetching the colors from the comboboxes, we + set the text format of each day of the week. + + The text format of a column in the calendar is given as a + QTextCharFormat, which besides the foreground color lets us + specify various character formatting information. In this + example, we only show a subset of the possibilities. + + \snippet examples/widgets/calendarwidget/window.cpp 6 + + \c weekendFormatChanged() is the same as \c + weekdayFormatChanged(), except that it affects Saturday and + Sunday instead of Monday to Friday. + + \snippet examples/widgets/calendarwidget/window.cpp 7 + + The \c reformatHeaders() slot is called when the user + changes the text format of + the headers. We compare the current text of the \gui {Header Text Format} + combobox to determine which format to apply. (An alternative would + have been to store \l{QTextCharFormat} values alongside the combobox + items.) + + \snippet examples/widgets/calendarwidget/window.cpp 8 + + In \c reformatCalendarPage(), we set the text format of the first + Friday in the month and May 1 in the current year. The text + formats that are actually used depend on which check boxes are + checked. + + QCalendarWidget lets us set the text format of individual dates + with the \l{QCalendarWidget::}{setDateTextFormat()}. We chose to + set the dates when the calendar page changes, i.e., a new month is + displayed. We check which of the \c mayFirstCheckBox and \c + firstDayCheckBox, if any, are checked + and set the text formats accordingly. +*/ diff --git a/doc/src/examples/charactermap.qdoc b/doc/src/examples/charactermap.qdoc new file mode 100644 index 0000000000..1324517252 --- /dev/null +++ b/doc/src/examples/charactermap.qdoc @@ -0,0 +1,274 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\example widgets/charactermap +\title Character Map Example + +The Character Map example shows how to create a custom widget that can +both display its own content and respond to user input. + +The example displays an array of characters which the user can click on +to enter text in a line edit. The contents of the line edit can then be +copied into the clipboard, and pasted into other applications. The +purpose behind this sort of tool is to allow users to enter characters +that may be unavailable or difficult to locate on their keyboards. + +\image charactermap-example.png Screenshot of the Character Map example + +The example consists of the following classes: + +\list +\i \c CharacterWidget displays the available characters in the current + font and style. +\i \c MainWindow provides a standard main window that contains font and + style information, a view onto the characters, a line edit, and a push + button for submitting text to the clipboard. +\endlist + +\section1 CharacterWidget Class Definition + +The \c CharacterWidget class is used to display an array of characters in +a user-specified font and style. For flexibility, we subclass QWidget and +reimplement only the functions that we need to provide basic rendering +and interaction features. + +The class definition looks like this: + +\snippet examples/widgets/charactermap/characterwidget.h 0 + +The widget does not contain any other widgets, so it must provide its own +size hint to allow its contents to be displayed correctly. +We reimplement \l{QWidget::paintEvent()} to draw custom content. We also +reimplement \l{QWidget::mousePressEvent()} to allow the user to interact +with the widget. + +The updateFont() and updateStyle() slots are used to update the font and +style of the characters in the widget whenever the user changes the +settings in the application. +The class defines the characterSelected() signal so that other parts +of the application are informed whenever the user selects a character in +the widget. +As a courtesy, the widget provides a tooltip that shows the current +character value. We reimplement the \l{QWidget::mouseMoveEvent()} event +handler and define showToolTip() to enable this feature. + +The \c columns, \c displayFont and \c currentKey private data members +are used to record the number of columns to be shown, the current font, +and the currently highlighted character in the widget. + +\section1 CharacterWidget Class Implementation + +Since the widget is to be used as a simple canvas, the constructor just +calls the base class constructor and defines some default values for +private data members. + +\snippet examples/widgets/charactermap/characterwidget.cpp 0 + +We initialize \c currentKey with a value of -1 to indicate +that no character is initially selected. We enable mouse tracking to +allow us to follow the movement of the cursor across the widget. + +The class provides two functions to allow the font and style to be set up. +Each of these modify the widget's display font and call update(): + +\snippet examples/widgets/charactermap/characterwidget.cpp 1 +\codeline +\snippet examples/widgets/charactermap/characterwidget.cpp 2 + +We use a fixed size font for the display. Similarly, a fixed size hint is +provided by the sizeHint() function: + +\snippet examples/widgets/charactermap/characterwidget.cpp 3 + +Three standard event functions are implemented so that the widget +can respond to clicks, provide tooltips, and render the available +characters. The paintEvent() shows how the contents of the widget are +arranged and displayed: + +\snippet examples/widgets/charactermap/characterwidget.cpp 6 + +A QPainter is created for the widget and, in all cases, we ensure that the +widget's background is painted. The painter's font is set to the +user-specified display font. + +The area of the widget that needs to be redrawn is used to determine which +characters need to be displayed: + +\snippet examples/widgets/charactermap/characterwidget.cpp 7 + +Using integer division, we obtain the row and column numbers of each +characters that should be displayed, and we draw a square on the widget +for each character displayed. + +\snippet examples/widgets/charactermap/characterwidget.cpp 8 +\snippet examples/widgets/charactermap/characterwidget.cpp 9 + +The symbols for each character in the array are drawn within each square, +with the symbol for the most recently selected character displayed in red: + +\snippet examples/widgets/charactermap/characterwidget.cpp 10 + +We do not need to take into account the difference between the area +displayed in the viewport and the area we are drawing on because +everything outside the visible area will be clipped. + +The mousePressEvent() defines how the widget responds to mouse clicks. + +\snippet examples/widgets/charactermap/characterwidget.cpp 5 + +We are only interested when the user clicks with the left mouse button +over the widget. When this happens, we calculate which character was +selected and emit the characterSelected() signal. +The character's number is found by dividing the x and y-coordinates of +the click by the size of each character's grid square. Since the number +of columns in the widget is defined by the \c columns variable, we +simply multiply the row index by that value and add the column number +to obtain the character number. + +If any other mouse button is pressed, the event is passed on to the +QWidget base class. This ensures that the event can be handled properly +by any other interested widgets. + +The mouseMoveEvent() maps the mouse cursor's position in global +coordinates to widget coordinates, and determines the character that +was clicked by performing the calculation + +\snippet examples/widgets/charactermap/characterwidget.cpp 4 + +The tooltip is given a position defined in global coordinates. + +\section1 MainWindow Class Definition + +The \c MainWindow class provides a minimal user interface for the example, +with only a constructor, slots that respond to signals emitted by standard +widgets, and some convenience functions that are used to set up the user +interface. + +The class definition looks like this: + +\snippet examples/widgets/charactermap/mainwindow.h 0 + +The main window contains various widgets that are used to control how +the characters will be displayed, and defines the findFonts() function +for clarity and convenience. The findStyles() slot is used by the widgets +to determine the styles that are available, insertCharacter() inserts +a user-selected character into the window's line edit, and +updateClipboard() synchronizes the clipboard with the contents of the +line edit. + +\section1 MainWindow Class Implementation + +In the constructor, we set up the window's central widget and fill it with +some standard widgets (two comboboxes, a line edit, and a push button). +We also construct a CharacterWidget custom widget, and add a QScrollArea +so that we can view its contents: + +\snippet examples/widgets/charactermap/mainwindow.cpp 0 + +QScrollArea provides a viewport onto the \c CharacterWidget when we set +its widget and handles much of the work needed to provide a scrolling +viewport. + +The font combo box is automatically popuplated with a list of available +fonts. We list the available styles for the current font in the style +combobox using the following function: + +\snippet examples/widgets/charactermap/mainwindow.cpp 1 + +The line edit and push button are used to supply text to the clipboard: + +\snippet examples/widgets/charactermap/mainwindow.cpp 2 + +We also obtain a clipboard object so that we can send text entered by the +user to other applications. + +Most of the signals emitted in the example come from standard widgets. +We connect these signals to slots in this class, and to the slots provided +by other widgets. + +\snippet examples/widgets/charactermap/mainwindow.cpp 4 + +The font combobox's +\l{QFontComboBox::currentFontChanged()}{currentFontChanged()} signal is +connected to the findStyles() function so that the list of available styles +can be shown for each font that is used. Since both the font and the style +can be changed by the user, the font combobox's currentFontChanged() signal +and the style combobox's +\l{QComboBox::currentIndexChanged()}{currentIndexChanged()} are connected +directly to the character widget. + +The final two connections allow characters to be selected in the character +widget, and text to be inserted into the clipboard: + +\snippet examples/widgets/charactermap/mainwindow.cpp 5 + +The character widget emits the characterSelected() custom signal when +the user clicks on a character, and this is handled by the insertCharacter() +function in this class. The clipboard is changed when the push button emits +the clicked() signal, and we handle this with the updateClipboard() function. + +The remaining code in the constructor sets up the layout of the central widget, +and provides a window title: + +\snippet examples/widgets/charactermap/mainwindow.cpp 6 + +The font combobox is automatically populated with a list of available font +families. The styles that can be used with each font are found by the +findStyles() function. This function is called whenever the user selects a +different font in the font combobox. + +\snippet examples/widgets/charactermap/mainwindow.cpp 7 + +We begin by recording the currently selected style, and we clear the +style combobox so that we can insert the styles associated with the +current font family. + +\snippet examples/widgets/charactermap/mainwindow.cpp 8 + +We use the font database to collect the styles that are available for the +current font, and insert them into the style combobox. The current item is +reset if the original style is not available for this font. + +The last two functions are slots that respond to signals from the character +widget and the main window's push button. The insertCharacter() function is +used to insert characters from the character widget when the user clicks a +character: + +\snippet examples/widgets/charactermap/mainwindow.cpp 9 + +The character is inserted into the line edit at the current cursor position. + +The main window's "To clipboard" push button is connected to the +updateClipboard() function so that, when it is clicked, the clipboard is +updated to contain the contents of the line edit: + +\snippet examples/widgets/charactermap/mainwindow.cpp 10 + +We copy all the text from the line edit to the clipboard, but we do not clear +the line edit. +*/ diff --git a/doc/src/examples/chart.qdoc b/doc/src/examples/chart.qdoc new file mode 100644 index 0000000000..7bed1e855c --- /dev/null +++ b/doc/src/examples/chart.qdoc @@ -0,0 +1,82 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example itemviews/chart + \title Chart Example + + The Chart example shows how to create a custom view for the model/view framework. + + \image chart-example.png + + In this example, the items in a table model are represented as slices in a pie chart, + relying on the flexibility of the model/view architecture to handle custom editing + and selection features. + + \bold{Note that you only need to create a new view class if your data requires a + specialized representation.} You should first consider using a standard QListView, + QTableView, or QTreeView with a custom QItemDelegate subclass if you need to + represent data in a special way. + + \omit + \section1 PieView Class Definition + + The \c PieView class is a subclass of QAbstractItemView. The base class provides + much of the functionality required by view classes, so we only need to provide + implementations for three public functions: visualRect(), scrollTo(), and + indexAt(). However, the view needs to maintain strict control over its look and + feel, so we also provide implementations for a number of other functions: + + \snippet examples/itemviews/chart/pieview.h 0 + + + + \section1 PieView Class Implementation + + The paint event renders the data from the standard item model as a pie chart. + We interpret the data in the following way: + + \list + \o Column 0 contains data in two different roles: + The \l{Qt::ItemDataRole}{DisplayRole} contains a label, and the + \l{Qt::ItemDataRole}{DecorationRole} contains the color of the pie slice. + \o Column 1 contains a quantity which we will convert to the angular extent of + the slice. + \endlist + + The figure is always drawn with the chart on the left and the key on + the right. This means that we must try and obtain an area that is wider + than it is tall. We do this by imposing a particular aspect ratio on + the chart and applying it to the available vertical space. This ensures + that we always obtain the maximum horizontal space for the aspect ratio + used. + We also apply fixed size margin around the figure. + + We use logical coordinates to draw the chart and key, and position them + on the view using viewports. + \endomit +*/ diff --git a/doc/src/examples/classwizard.qdoc b/doc/src/examples/classwizard.qdoc new file mode 100644 index 0000000000..16a1039b39 --- /dev/null +++ b/doc/src/examples/classwizard.qdoc @@ -0,0 +1,190 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example dialogs/classwizard + \title Class Wizard Example + + The License Wizard example shows how to implement linear + wizards using QWizard. + + \image classwizard.png Screenshot of the Class Wizard example + + Most wizards have a linear structure, with page 1 followed by + page 2 and so on until the last page. Some wizards are more + complex in that they allow different traversal paths based on the + information provided by the user. The + \l{dialogs/licensewizard}{License Wizard} example shows how to + create such wizards. + + The Class Wizard example consists of the following classes: + + \list + \o \c ClassWizard inherits QWizard and provides a + three-step wizard that generates the skeleton of a C++ class + based on the user's input. + \o \c IntroPage, \c ClassInfoPage, \c CodeStylePage, \c + OutputFilesPage, and \c ConclusionPage are QWizardPage + subclasses that implement the wizard pages. + \endlist + + \section1 ClassWizard Class Definition + + \image classwizard-flow.png The Class Wizard pages + + We will see how to subclass QWizard to implement our own wizard. + The concrete wizard class is called \c ClassWizard and provides + five pages: + + \list + \o The first page is an introduction page, telling the user what + the wizard is going to do. + \o The second page asks for a class name and a base class, and + allows the user to specify whether the class should have a \c + Q_OBJECT macro and what constructors it should provide. + \o The third page allows the user to set some options related to the code + style, such as the macro used to protect the header file from + multiple inclusion (e.g., \c MYDIALOG_H). + \o The fourth page allows the user to specify the names of the + output files. + \o The fifth page is a conclusion page. + \endlist + + Although the program is just an example, if you press \gui Finish + (\gui Done on Mac OS X), actual C++ source files will actually be + generated. + + \section1 The ClassWizard Class + + Here's the \c ClassWizard definition: + + \snippet examples/dialogs/classwizard/classwizard.h 0 + + The class reimplements QDialog's \l{QDialog::}{accept()} slot. + This slot is called when the user clicks \gui{Finish}. + + Here's the constructor: + + \snippet examples/dialogs/classwizard/classwizard.cpp 1 + + We instantiate the five pages and insert them into the wizard + using QWizard::addPage(). The order in which they are inserted + is also the order in which they will be shown later on. + + We call QWizard::setPixmap() to set the banner and the + background pixmaps for all pages. The banner is used as a + background for the page header when the wizard's style is + \l{QWizard::}{ModernStyle}; the background is used as the + dialog's background in \l{QWizard::}{MacStyle}. (See \l{Elements + of a Wizard Page} for more information.) + + \snippet examples/dialogs/classwizard/classwizard.cpp 3 + \snippet examples/dialogs/classwizard/classwizard.cpp 4 + \dots + \snippet examples/dialogs/classwizard/classwizard.cpp 5 + \snippet examples/dialogs/classwizard/classwizard.cpp 6 + + If the user clicks \gui Finish, we extract the information from + the various pages using QWizard::field() and generate the files. + The code is long and tedious (and has barely anything to do with + noble art of designing wizards), so most of it is skipped here. + See the actual example in the Qt distribution for the details if + you're curious. + + \section1 The IntroPage Class + + The pages are defined in \c classwizard.h and implemented in \c + classwizard.cpp, together with \c ClassWizard. We will start with + the easiest page: + + \snippet examples/dialogs/classwizard/classwizard.h 1 + \codeline + \snippet examples/dialogs/classwizard/classwizard.cpp 7 + + A page inherits from QWizardPage. We set a + \l{QWizardPage::}{title} and a + \l{QWizard::WatermarkPixmap}{watermark pixmap}. By not setting + any \l{QWizardPage::}{subTitle}, we ensure that no header is + displayed for this page. (On Windows, it is customary for wizards + to display a watermark pixmap on the first and last pages, and to + have a header on the other pages.) + + Then we create a QLabel and add it to a layout. + + \section1 The ClassInfoPage Class + + The second page is defined and implemented as follows: + + \snippet examples/dialogs/classwizard/classwizard.h 2 + \codeline + \snippet examples/dialogs/classwizard/classwizard.cpp 9 + \dots + \snippet examples/dialogs/classwizard/classwizard.cpp 12 + \dots + \snippet examples/dialogs/classwizard/classwizard.cpp 13 + + First, we set the page's \l{QWizardPage::}{title}, + \l{QWizardPage::}{subTitle}, and \l{QWizard::LogoPixmap}{logo + pixmap}. The logo pixmap is displayed in the page's header in + \l{QWizard::}{ClassicStyle} and \l{QWizard::}{ModernStyle}. + + Then we create the child widgets, create \l{Registering and Using + Fields}{wizard fields} associated with them, and put them into + layouts. The \c className field is created with an asterisk (\c + *) next to its name. This makes it a \l{mandatory field}, that + is, a field that must be filled before the user can press the + \gui Next button (\gui Continue on Mac OS X). The fields' values + can be accessed from any other page using QWizardPage::field(), + or from the wizard code using QWizard::field(). + + \section1 The CodeStylePage Class + + The third page is defined and implemented as follows: + + \snippet examples/dialogs/classwizard/classwizard.h 3 + \codeline + \snippet examples/dialogs/classwizard/classwizard.cpp 14 + \dots + \snippet examples/dialogs/classwizard/classwizard.cpp 15 + \codeline + \snippet examples/dialogs/classwizard/classwizard.cpp 16 + + The code in the constructor is very similar to what we did for \c + ClassInfoPage, so we skipped most of it. + + The \c initializePage() function is what makes this class + interesting. It is reimplemented from QWizardPage and is used to + initialize some of the page's fields with values from the + previous page (namely, \c className and \c baseClass). For + example, if the class name on page 2 is \c SuperDuperWidget, the + default macro name on page 3 is \c SUPERDUPERWIDGET_H. + + The \c OutputFilesPage and \c ConclusionPage classes are very + similar to \c CodeStylePage, so we won't review them here. + + \sa QWizard, {License Wizard Example}, {Trivial Wizard Example} +*/ diff --git a/doc/src/examples/codecs.qdoc b/doc/src/examples/codecs.qdoc new file mode 100644 index 0000000000..fd73c7b160 --- /dev/null +++ b/doc/src/examples/codecs.qdoc @@ -0,0 +1,37 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example tools/codecs + \title Codecs Example + + The Codecs example demonstrates the principles behind importing and exporting text + using codecs to ensure that characters are encoded properly, avoiding loss of data + and retaining the correct symbols used in various scripts. + + \image codecs-example.png +*/ diff --git a/doc/src/examples/codeeditor.qdoc b/doc/src/examples/codeeditor.qdoc new file mode 100644 index 0000000000..23a2fd4140 --- /dev/null +++ b/doc/src/examples/codeeditor.qdoc @@ -0,0 +1,195 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example widgets/codeeditor + \title Code Editor Example + + The Code Editor example shows how to create a simple editor that + has line numbers and that highlights the current line. + + \image codeeditor-example.png + + As can be seen from the image, the editor displays the line + numbers in an area to the left of the area for editing. The editor + will highlight the line containing the cursor. + + We implement the editor in \c CodeEditor, which is a widget that + inherits QPlainTextEdit. We keep a separate widget in \c + CodeEditor (\c LineNumberArea) onto which we draw the line + numbers. + + QPlainTextEdit inherits from QAbstractScrollArea, and editing + takes place within its \l{QAbstractScrollArea::}{viewport()}'s + margins. We make room for our line number area by setting the left + margin of the viewport to the size we need to draw the line + numbers. + + When it comes to editing code, we prefer QPlainTextEdit over + QTextEdit because it is optimized for handling plain text. See + the QPlainTextEdit class description for details. + + QPlainTextEdit lets us add selections in addition to the + selection the user can make with the mouse or keyboard. We use + this functionality to highlight the current line. More on this + later. + + We will now move on to the definitions and implementations of \c + CodeEditor and \c LineNumberArea. Let's start with the \c + LineNumberArea class. + + \section1 The LineNumberArea Class + + We paint the line numbers on this widget, and place it over the \c + CodeEditor's \l{QAbstractScrollArea::}{viewport()}'s left margin + area. + + We need to use protected functions in QPlainTextEdit while + painting the area. So to keep things simple, we paint the area in + the \c CodeEditor class. The area also asks the editor to + calculate its size hint. + + Note that we could simply paint the line numbers directly on the + code editor, and drop the LineNumberArea class. However, the + QWidget class helps us to \l{QWidget::}{scroll()} its contents. + Also, having a separate widget is the right choice if we wish to + extend the editor with breakpoints or other code editor features. + The widget would then help in the handling of mouse events. + + \snippet widgets/codeeditor/codeeditor.h extraarea + + \section1 CodeEditor Class Definition + + Here is the code editor's class definition: + + \snippet widgets/codeeditor/codeeditor.h codeeditordefinition + + In the editor we resize and draw the line numbers on the \c + LineNumberArea. We need to do this when the number of lines in the + editor changes, and when the editor's viewport() is scrolled. Of + course, it is also done when the editor's size changes. We do + this in \c updateLineNumberWidth() and \c updateLineNumberArea(). + + Whenever, the cursor's position changes, we highlight the current + line in \c highlightCurrentLine(). + + \section1 CodeEditor Class Implementation + + We will now go through the code editors implementation, starting + off with the constructor. + + \snippet widgets/codeeditor/codeeditor.cpp constructor + + In the constructor we connect our slots to signals in + QPlainTextEdit. It is necessary to calculate the line number area + width and highlight the first line when the editor is created. + + \snippet widgets/codeeditor/codeeditor.cpp extraAreaWidth + + The \c lineNumberAreaWidth() function calculates the width of the + \c LineNumberArea widget. We take the number of digits in the last + line of the editor and multiply that with the maximum width of a + digit. + + \snippet widgets/codeeditor/codeeditor.cpp slotUpdateExtraAreaWidth + + When we update the width of the line number area, we simply call + QAbstractScrollArea::setViewportMargins(). + + \snippet widgets/codeeditor/codeeditor.cpp slotUpdateRequest + + This slot is invoked when the editors viewport has been scrolled. + The QRect given as argument is the part of the editing area that + is do be updated (redrawn). \c dy holds the number of pixels the + view has been scrolled vertically. + + \snippet widgets/codeeditor/codeeditor.cpp resizeEvent + + When the size of the editor changes, we also need to resize the + line number area. + + \snippet widgets/codeeditor/codeeditor.cpp cursorPositionChanged + + When the cursor position changes, we highlight the current line, + i.e., the line containing the cursor. + + QPlainTextEdit gives the possibility to have more than one + selection at the same time. we can set the character format + (QTextCharFormat) of these selections. We clear the cursors + selection before setting the new new + QPlainTextEdit::ExtraSelection, else several lines would get + highlighted when the user selects multiple lines with the mouse. + \omit ask someone how this works \endomit + + One sets the selection with a text cursor. When using the + FullWidthSelection property, the current cursor text block (line) + will be selected. If you want to select just a portion of the text + block, the cursor should be moved with QTextCursor::movePosition() + from a position set with \l{QTextCursor::}{setPosition()}. + + \snippet widgets/codeeditor/codeeditor.cpp extraAreaPaintEvent_0 + + The \c lineNumberAreaPaintEvent() is called from \c LineNumberArea + whenever it receives a paint event. We start off by painting the + widget's background. + + \snippet widgets/codeeditor/codeeditor.cpp extraAreaPaintEvent_1 + + We will now loop through all visible lines and paint the line + numbers in the extra area for each line. Notice that in a plain + text edit each line will consist of one QTextBlock; though, if + line wrapping is enabled, a line may span several rows in the text + edit's viewport. + + We get the top and bottom y-coordinate of the first text block, + and adjust these values by the height of the current text block in + each iteration in the loop. + + \snippet widgets/codeeditor/codeeditor.cpp extraAreaPaintEvent_2 + + Notice that we check if the block is visible in addition to check + if it is in the areas viewport - a block can, for example, be + hidden by a window placed over the text edit. + + \section1 Suggestions for Extending the Code Editor + + No self-respecting code editor is without a syntax + highligther; the \l{Syntax Highlighter Example} shows how to + create one. + + In addition to line numbers, you can add more to the extra area, + for instance, break points. + + QSyntaxHighlighter gives the possibility to add user data to each + text block with + \l{QSyntaxHighlighter::}{setCurrentBlockUserData()}. This can be + used to implement parenthesis matching. In the \c + highlightCurrentLine(), the data of the currentBlock() can be + fetched with QTextBlock::userData(). Matching parentheses can be + highlighted with an extra selection. + +*/ diff --git a/doc/src/examples/coloreditorfactory.qdoc b/doc/src/examples/coloreditorfactory.qdoc new file mode 100644 index 0000000000..804b0225cd --- /dev/null +++ b/doc/src/examples/coloreditorfactory.qdoc @@ -0,0 +1,155 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example itemviews/coloreditorfactory + \title Color Editor Factory Example + + This example shows how to create an editor that can be used by + a QItemDelegate. + + \image coloreditorfactoryimage.png + + When editing data in a QListView, QTableView, or QTreeView, + editors are created and displayed by a \l{Delegate + Classes}{delegate}. QItemDelegate, which is the default delegate + used by Qt's \l{View Classes}{item views}, uses a + QItemEditorFactory to create editors for it. A unique instance + provided by QItemEditorFactory is by default installed on all + item delegates. + + An item editor factory contains a collection of + QItemEditorCreatorBase instances, which are specialized factories + that produce editors for one particular QVariant data type (all + models in Qt store their data in \l{QVariant}s). An editor can be any + Qt or custom widget. + + In this example, we will create an editor (implemented in the \c + ColorListEditor class) that can edit the QColor data type and be + used by \l{QItemDelegate}s. We do this by creating a new + QItemEditorCreatorBase that produces \c ColorListEditors and + register it with a new factory, which we set as the default editor + item factory (the unique factory instance). To test our editor, we + have implemented the \c Window class, which displays a + QTableWidget in which \l{QColor}s can be edited. + + \section1 Window Class Implementation + + In the Window class, we create the item editor creator + base for our color editor and add it to the default factory. + We also create a QTableWidget in which our editor can be + tested. It is filled with some data and displayed in a window. + + We take a closer look at the constructor: + + \snippet examples/itemviews/coloreditorfactory/window.cpp 0 + + The QStandardItemEditorCreator is a convenience class that + inherits QItemEditorCreatorBase. Its constructor takes a template + class, of which instances are returned from + \l{QItemEditorCreatorBase::}{createWidget()}. The creator uses a + constructor that takes a QWidget as its only parameter; the + template class must provide this. This way, there is no need to + subclass QStandardItemEditorCreator. + + After the new factory has been set, all standard item delegates + will use it (i.e, also delegates that were created before the new + default factory was set). + + The \c createGUI() function sets up the table and fills it + with data. + + \section1 ColorListEditor Definition + + The ColorListEditor inherits QComboBox and lets the user + select a QColor from its popup list. + + \snippet examples/itemviews/coloreditorfactory/colorlisteditor.h 0 + + QItemDelegate manages the interaction between the editor and + the model, i.e., it retrieves data to edit from the model and + store data from the editor in the model. The data that is edited + by an editor is stored in the editor's user data property, and the + delegate uses Qt's \l{Qt's Property System}{property system} to + access it by name. We declare our user data property with the + Q_PROPERTY macro. The property is set to be the user type with the + USER keyword. + + \section1 ColorListEditor Implementation + + The constructor of \c ColorListEditor simply calls \c + populateList(), which we will look at later. We move on to the + \c color() function: + + \snippet examples/itemviews/coloreditorfactory/colorlisteditor.cpp 0 + + We return the data that is selected in the combobox. The data + is stored in the Qt::DecorationRole as the color is then also + displayed in the popup list (as shown in the image above). + + \snippet examples/itemviews/coloreditorfactory/colorlisteditor.cpp 1 + + The \c findData() function searches the items in the combobox + and returns the index of the item that has \c color in the + Qt::Decoration role. + + \snippet examples/itemviews/coloreditorfactory/colorlisteditor.cpp 2 + + Qt knows some predefined colors by name. We simply loop + through these to fill our editor with items. + + \section1 Further Customization of Item View Editors + + You can customize Qt's \l{Model/View Programming}{model view + framework} in many ways. The procedure shown in this example is + usually sufficient to provide custom editors. Further + customization is achieved by subclassing QItemEditorFactory + and QItemEditorCreatorBase. It is also possible to subclass + QItemDelegate if you don't wish to use a factory at all. + + Possible suggestions are: + + \list + \o If the editor widget has no user property defined, the delegate + asks the factory for the property name, which it in turn + asks the item editor creator for. In this case, you can use + the QItemEditorCreator class, which takes the property + name to use for editing as a constructor argument. + \o If the editor requires other constructors or other + initialization than provided by QItemEditorCreatorBase, you + must reimplement + QItemEditorCreatorBase::createWidget(). + \o You could also subclass QItemEditorFactory if you only want + to provide editors for certain kinds of data or use another + method of creating the editors than using creator bases. + \endlist + + In this example, we use a standard QVariant data type. You can + also use custom types. In the \l{Star Delegate Example}, we + show how to store a custom data type in a QVariant and paint + and edit it in a class that inherits QItemDelegate. +*/ diff --git a/doc/src/examples/combowidgetmapper.qdoc b/doc/src/examples/combowidgetmapper.qdoc new file mode 100644 index 0000000000..897d135580 --- /dev/null +++ b/doc/src/examples/combowidgetmapper.qdoc @@ -0,0 +1,167 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example itemviews/combowidgetmapper + \title Combo Widget Mapper Example + + The Delegate Widget Mapper example shows how to use a custom delegate to + map information from a model to specific widgets on a form. + + \image combowidgetmapper-example.png + + In the \l{Simple Widget Mapper Example}, we showed the basic use of a + widget mapper to relate data exposed by a model to simple input widgets + in a user interface. However, sometimes we want to use input widgets that + expose data as choices to the user, such as QComboBox, and we need a way + to relate their input to the values stored in the model. + + This example is very similar to the \l{Simple Widget Mapper Example}. + Again, we create a \c Window class with an almost identical user interface, + except that, instead of providing a spin box so that each person's age + can be entered, we provide a combo box to allow their addresses to be + classified as "Home", "Work" or "Other". + + \section1 Window Class Definition + + The class provides a constructor, a slot to keep the buttons up to date, + and a private function to set up the model: + + \snippet examples/itemviews/combowidgetmapper/window.h Window definition + + In addition to the QDataWidgetMapper object and the controls used to make + up the user interface, we use a QStandardItemModel to hold our data and + a QStringListModel to hold information about the types of address that + can be applied to each person's data. + + \section1 Window Class Implementation + + The constructor of the \c Window class can be explained in three parts. + In the first part, we set up the widgets used for the user interface: + + \snippet examples/itemviews/combowidgetmapper/window.cpp Set up widgets + + Note that we set up the mapping the combo box in the same way as for other + widgets, but that we apply its own model to it so that it will display + data from its own model, the \c typeModel, rather than from the model + containing data about each person. + + Next, we set up the widget mapper, relating each input widget to a column + in the model specified by the call to \l{QDataWidgetMapper::}{setModel()}: + + \snippet examples/itemviews/combowidgetmapper/window.cpp Set up the mapper + + For the combo box, we pass an extra argument to tell the widget mapper + which property to relate to values from the model. As a result, the user + is able to select an item from the combo box, and the corresponding + value stored in the widget's \c currentIndex property will be stored in + the model. + + \omit + However, we also set a delegate on the mapper. As with \l{Delegate Classes}, + this changes the way that data is presented to the user. In this case, the + delegate acts as a proxy between the mapper and the input widgets, + translating the data into a suitable form for the combo box but not + interfering with the other input widgets. The implementation is shown later. + \endomit + + The rest of the constructor is very similar to that of the + \l{Simple Widget Mapper Example}: + + \snippet examples/itemviews/combowidgetmapper/window.cpp Set up connections and layouts + + The model is initialized in the window's \c{setupModel()} function. Here, + we create a standard model with 5 rows and 3 columns. In each row, we + insert a name, address, and a value that indicates the type of address. + The address types are stored in a string list model. + + \snippet examples/itemviews/combowidgetmapper/window.cpp Set up the model + + As we insert each row into the model, like a record in a database, we + store values that correspond to items in \c typeModel for each person's + address type. When the widget mapper reads these values from the final + column of each row, it will need to use them as references to values in + \c typeModel, as shown in the following diagram. This is where the + delegate is used. + + \image widgetmapper-combo-mapping.png + + We show the implementation of the \c{updateButtons()} slot for + completeness: + + \snippet examples/itemviews/combowidgetmapper/window.cpp Slot for updating the buttons + + \omit + \section1 Delegate Class Definition and Implementation + + The delegate we use to mediate interaction between the widget mapper and + the input widgets is a small QItemDelegate subclass: + + \snippet examples/itemviews/combowidgetmapper/delegate.h Delegate class definition + + This provides implementations of the two standard functions used to pass + data between editor widgets and the model (see the \l{Delegate Classes} + documentation for a more general description of these functions). + + Since we only provide an empty implementation of the constructor, we + concentrate on the other two functions. + + The \l{QItemDelegate::}{setEditorData()} implementation takes the data + referred to by the model index supplied and processes it according to + the presence of a \c currentIndex property in the editor widget: + + \snippet examples/itemviews/combowidgetmapper/delegate.cpp setEditorData implementation + + If, like QComboBox, the editor widget has this property, it is set using + the value from the model. Since we are passing around QVariant values, + the strings stored in the model are automatically converted to the integer + values needed for the \c currentIndex property. + + As a result, instead of showing "0", "1" or "2" in the combo box, one of + its predefined set of items is shown. We call QItemDelegate::setEditorData() + for widgets without the \c currentIndex property. + + The \l{QItemDelegate::}{setModelData()} implementation performs the reverse + process, taking the value stored in the widget's \c currentIndex property + and storing it back in the model: + + \snippet examples/itemviews/combowidgetmapper/delegate.cpp setModelData implementation + \endomit + + \section1 Summary and Further Reading + + The use of a separate model for the combo box provides a menu of choices + that are separate from the data stored in the main model. Using a named + mapping that relates the combo box's \c currentIndex property to a column + in the model effectively allows us to store a look-up value in the model. + + However, when reading the model outside the context of the widget mapper, + we need to know about the \c typeModel to make sense of these look-up + values. It would be useful to be able to store both the data and the + choices held by the \c typeModel in one place. + This is covered by the \l{SQL Widget Mapper Example}. +*/ diff --git a/doc/src/examples/completer.qdoc b/doc/src/examples/completer.qdoc new file mode 100644 index 0000000000..348c203e15 --- /dev/null +++ b/doc/src/examples/completer.qdoc @@ -0,0 +1,249 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example tools/completer + \title Completer Example + + The Completer example shows how to provide string-completion facilities + for an input widget based on data provided by a model. + + \image completer-example.png + + This example uses a custom item model, \c FileSystemModel, and a QCompleter object. + QCompleter is a class that provides completions based on an item model. The + type of model, the completion mode, and the case sensitivity can be + selected using combo boxes. + + \section1 The Resource File + + The Completer example requires a resource file in order to store the + \e{countries.txt} and \e{words.txt}. The resource file contains the + following code: + + \quotefile examples/tools/completer/completer.qrc + + \section1 FileSystemModel Class Definition + + The \c FileSystemModel class is a subclass of QFileSystemModel, which provides a data + model for the local filesystem. + + \snippet examples/tools/completer/fsmodel.h 0 + + This class only has a constructor and a \c data() function as it is only + created to enable \c data() to return the entire file path for the + display role, unlike \l{QFileSystemModel}'s \c data() function that only returns + the folder and not the drive label. This is further explained in + \c FileSystemModel's implementation. + + \section1 FileSystemModel Class Implementation + + The constructor for the \c FileSystemModel class is used to pass \a parent to + QFileSystemModel. + + \snippet examples/tools/completer/fsmodel.cpp 0 + + As mentioned earlier, the \c data() function is reimplemented in order to + get it to return the entire file parth for the display role. For example, + with a QFileSystemModel, you will see "Program Files" in the view. However, with + \c FileSystemModel, you will see "C:\\Program Files". + + \snippet examples/tools/completer/fsmodel.cpp 1 + + The screenshots below illustrate this difference: + + \table + \row \o \inlineimage completer-example-qdirmodel.png + \o \inlineimage completer-example-dirmodel.png + \endtable + + The Qt::EditRole, which QCompleter uses to look for matches, is left + unchanged. + + \section1 MainWindow Class Definition + + The \c MainWindow class is a subclass of QMainWindow and implements five + private slots - \c about(), \c changeCase(), \c changeMode(), \c changeModel(), + and \c changeMaxVisible(). + + \snippet examples/tools/completer/mainwindow.h 0 + + Within the \c MainWindow class, we have two private functions: + \c createMenu() and \c modelFromFile(). We also declare the private widgets + needed - three QComboBox objects, a QCheckBox, a QCompleter, a QLabel, and + a QLineEdit. + + \snippet examples/tools/completer/mainwindow.h 1 + + \section1 MainWindow Class Implementation + + The constructor of \c MainWindow constructs a \c MainWindow with a parent + widget and initializes the private members. The \c createMenu() function + is then invoked. + + We set up three QComboBox objects, \c modelComb, \c modeCombo and + \c caseCombo. By default, the \c modelCombo is set to QFileSystemModel, + the \c modeCombo is set to "Filtered Popup" and the \c caseCombo is set + to "Case Insensitive". + + \snippet examples/tools/completer/mainwindow.cpp 0 + + The \c maxVisibleSpinBox is created and determines the number of visible + item in the completer + + The \c wrapCheckBox is then set up. This \c checkBox determines if the + \c{completer}'s \l{QCompleter::setWrapAround()}{setWrapAround()} property + is enabled or disabled. + + \snippet examples/tools/completer/mainwindow.cpp 1 + + We instantiate \c contentsLabel and set its size policy to + \l{QSizePolicy::Fixed}{fixed}. The combo boxes' \l{QComboBox::activated()} + {activated()} signals are then connected to their respective slots. + + \snippet examples/tools/completer/mainwindow.cpp 2 + + The \c lineEdit is set up and then we arrange all the widgets using a + QGridLayout. The \c changeModel() function is called, to initialize the + \c completer. + + \snippet examples/tools/completer/mainwindow.cpp 3 + + The \c createMenu() function is used to instantiate the QAction objects + needed to fill the \c fileMenu and \c helpMenu. The actions' + \l{QAction::triggered()}{triggered()} signals are connected to their + respective slots. + + \snippet examples/tools/completer/mainwindow.cpp 4 + + The \c modelFromFile() function accepts the \a fileName of a file and + processes it depending on its contents. + + We first validate the \c file to ensure that it can be opened in + QFile::ReadOnly mode. If this is unsuccessful, the function returns an + empty QStringListModel. + + \snippet examples/tools/completer/mainwindow.cpp 5 + + The mouse cursor is then overriden with Qt::WaitCursor before we fill + a QStringList object, \c words, with the contents of \c file. Once this + is done, we restore the mouse cursor. + + \snippet examples/tools/completer/mainwindow.cpp 6 + + As mentioned earlier, the resources file contains two files - + \e{countries.txt} and \e{words.txt}. If the \c file read is \e{words.txt}, + we return a QStringListModel with \c words as its QStringList and + \c completer as its parent. + + \snippet examples/tools/completer/mainwindow.cpp 7 + + If the \c file read is \e{countries.txt}, then we require a + QStandardItemModel with \c words.count() rows, 2 columns, and \c completer + as its parent. + + \snippet examples/tools/completer/mainwindow.cpp 8 + + A standard line in \e{countries.txt} is: + \quotation + Norway NO + \endquotation + + Hence, to populate the QStandardItemModel object, \c m, we have to + split the country name and its symbol. Once this is done, we return + \c m. + + \snippet examples/tools/completer/mainwindow.cpp 9 + + The \c changeMode() function sets the \c{completer}'s mode, depending on + the value of \c index. + + \snippet examples/tools/completer/mainwindow.cpp 10 + + The \c changeModel() function changes the item model used based on the + model selected by the user. + + A \c switch statement is used to change the item model based on the index + of \c modelCombo. If \c case is 0, we use an unsorted QFileSystemModel, providing + us with a file path excluding the drive label. + + \snippet examples/tools/completer/mainwindow.cpp 11 + + Note that we create the model with \c completer as the parent as this + allows us to replace the model with a new model. The \c completer will + ensure that the old one is deleted the moment a new model is assigned + to it. + + If \c case is 1, we use the \c DirModel we defined earlier, resulting in + full paths for the files. + + \snippet examples/tools/completer/mainwindow.cpp 12 + + When \c case is 2, we attempt to complete names of countries. This requires + a QTreeView object, \c treeView. The country names are extracted from + \e{countries.txt} and set the popup used to display completions to + \c treeView. + + \snippet examples/tools/completer/mainwindow.cpp 13 + + The screenshot below shows the Completer with the country list model. + + \image completer-example-country.png + + If \c case is 3, we attempt to complete words. This is done using a + QStringListModel that contains data extracted from \e{words.txt}. The + model is sorted \l{QCompleter::CaseInsensitivelySortedModel} + {case insensitively}. + + The screenshot below shows the Completer with the word list model. + + \image completer-example-word.png + + Once the model type is selected, we call the \c changeMode() function and + the \c changeCase() function and set the wrap option accordingly. The + \c{wrapCheckBox}'s \l{QCheckBox::clicked()}{clicked()} signal is connected + to the \c{completer}'s \l{QCompleter::setWrapAround()}{setWrapAround()} + slot. + + \snippet examples/tools/completer/mainwindow.cpp 14 + + The \c changeMaxVisible() update the maximum number of visible items in + the completer. + + \snippet examples/tools/completer/mainwindow.cpp 15 + + The \c about() function provides a brief description about the example. + + \snippet examples/tools/completer/mainwindow.cpp 16 + + \section1 \c main() Function + + The \c main() function instantiates QApplication and \c MainWindow and + invokes the \l{QWidget::show()}{show()} function. + + \snippet examples/tools/completer/main.cpp 0 + */ diff --git a/doc/src/examples/complexpingpong.qdoc b/doc/src/examples/complexpingpong.qdoc new file mode 100644 index 0000000000..fb6db7b86e --- /dev/null +++ b/doc/src/examples/complexpingpong.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example dbus/complexpingpong + \title Complex Ping Pong Example + + The Complex Ping Pong example improves on the \l{D-Bus Ping Pong Example} by providing + a more useful demonstration of D-Bus interfaces. + + \quotefile doc/src/snippets/complexpingpong-example.txt +*/ diff --git a/doc/src/examples/concentriccircles.qdoc b/doc/src/examples/concentriccircles.qdoc new file mode 100644 index 0000000000..315469b6eb --- /dev/null +++ b/doc/src/examples/concentriccircles.qdoc @@ -0,0 +1,231 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example painting/concentriccircles + \title Concentric Circles Example + + The Concentric Circles example shows the improved rendering + quality that can be obtained using floating point precision and + anti-aliasing when drawing custom widgets. The example also shows + how to do simple animations. + + The application's main window displays several widgets which are + drawn using the various combinations of precision and + anti-aliasing. + + \image concentriccircles-example.png + + Anti-aliasing is one of QPainter's render hints. The + QPainter::RenderHints are used to specify flags to QPainter that + may, or may not, be respected by any given + engine. QPainter::Antialiasing indicates that the engine should + anti-alias the edges of primitives if possible, i.e. put + additional pixels around the original ones to smooth the edges. + + The difference between floating point precision and integer + precision is a matter of accuracy, and is visible in the + application's main window: Even though the logic that is + calculating the circles' geometry is the same, floating points + ensure that the white spaces between each circle are of the same + size, while integers make two and two circles appear as if they + belong together. The reason is that the integer based precision + rely on rounding off non-integer calculations. + + The example consists of two classes: + + \list + \o \c CircleWidget is a custom widget which renders several animated + concentric circles. + \o \c Window is the application's main window displaying four \c + {CircleWidget}s drawn using different combinations of precision + and aliasing. + \endlist + + First we will review the CircleWidget class, then we will take a + look at the Window class. + + \section1 CircleWidget Class Definition + + The CircleWidget class inherits QWidget, and is a custom widget + which renders several animated concentric circles. + + \snippet examples/painting/concentriccircles/circlewidget.h 0 + + We declare the \c floatBased and \c antialiased variables to hold + whether an instance of the class should be rendered with integer + or float based precision, and whether the rendering should be + anti-aliased or not. We also declare functions setting each of + these variables. + + In addition we reimplement the QWidget::paintEvent() function to + apply the various combinations of precision and anti-aliasing when + rendering, and to support the animation. We reimplement the + QWidget::minimumSizeHint() and QWidget::sizeHint() functions to + give the widget a reasonable size within our application. + + We declare the private \c nextAnimationFrame() slot, and the + associated \c frameNo variable holding the number of "animation + frames" for the widget, to facilitate the animation. + + \section1 CircleWidget Class Implementation + + In the constructor we make the widget's rendering integer based + and aliased by default: + + \snippet examples/painting/concentriccircles/circlewidget.cpp 0 + + We initialize the widget's \c frameNo variable, and set the + widget's background color using the QWidget::setBackgroundColor() + function which takes a \l {QPalette::ColorRole}{color role} as + argument; the QPalette::Base color role is typically white. + + Then we set the widgets size policy using the + QWidget::setSizePolicy() function. QSizePolicy::Expanding means + that the widget's \l {QWidget::sizeHint()}{sizeHint()} is a + sensible size, but that the widget can be shrunk and still be + useful. The widget can also make use of extra space, so it should + get as much space as possible. + + \snippet examples/painting/concentriccircles/circlewidget.cpp 1 + \codeline + \snippet examples/painting/concentriccircles/circlewidget.cpp 2 + + The public \c setFloatBased() and \c setAntialiased() functions + update the widget's rendering preferences, i.e. whether the widget + should be rendered with integer or float based precision, and + whether the rendering should be anti-aliased or not. + + The functions also generate a paint event by calling the + QWidget::update() function, forcing a repaint of the widget with + the new rendering preferences. + + \snippet examples/painting/concentriccircles/circlewidget.cpp 3 + \codeline + \snippet examples/painting/concentriccircles/circlewidget.cpp 4 + + The default implementations of the QWidget::minimumSizeHint() and + QWidget::sizeHint() functions return invalid sizes if there is no + layout for the widget, otherwise they return the layout's minimum and + preferred size, respectively. + + We reimplement the functions to give the widget minimum and + preferred sizes which are reasonable within our application. + + \snippet examples/painting/concentriccircles/circlewidget.cpp 5 + + The nextAnimationFrame() slot simply increments the \c frameNo + variable's value, and calls the QWidget::update() function which + schedules a paint event for processing when Qt returns to the main + event loop. + + \snippet examples/painting/concentriccircles/circlewidget.cpp 6 + + A paint event is a request to repaint all or part of the + widget. The \c paintEvent() function is an event handler that can + be reimplemented to receive the widget's paint events. We + reimplement the event handler to apply the various combinations of + precision and anti-aliasing when rendering the widget, and to + support the animation. + + First, we create a QPainter for the widget, and set its + antialiased flag to the widget's preferred aliasing. We also + translate the painters coordinate system, preparing to draw the + widget's cocentric circles. The translation ensures that the + center of the circles will be equivalent to the widget's center. + + \snippet examples/painting/concentriccircles/circlewidget.cpp 7 + + When painting a circle, we use the number of "animation frames" to + determine the alpha channel of the circle's color. The alpha + channel specifies the color's transparency effect, 0 represents a + fully transparent color, while 255 represents a fully opaque + color. + + \snippet examples/painting/concentriccircles/circlewidget.cpp 8 + + If the calculated alpha channel is fully transparent, we don't + draw anything since that would be equivalent to drawing a white + circle on a white background. Instead we skip to the next circle + still creating a white space. If the calculated alpha channel is + fully opaque, we set the pen (the QColor passed to the QPen + constructor is converted into the required QBrush by default) and + draw the circle. If the widget's preferred precision is float + based, we specify the circle's bounding rectangle using QRectF and + double values, otherwise we use QRect and integers. + + The animation is controlled by the public \c nextAnimationFrame() + slot: Whenever the \c nextAnimationFrame() slot is called the + number of frames is incremented and a paint event is + scheduled. Then, when the widget is repainted, the alpha-blending + of the circles' colors change and the circles appear as animated. + + \section1 Window Class Definition + + The Window class inherits QWidget, and is the application's main + window rendering four \c {CircleWidget}s using different + combinations of precision and aliasing. + + \snippet examples/painting/concentriccircles/window.h 0 + + We declare the various components of the main window, i.e., the text + labels and a double array that will hold reference to the four \c + {CircleWidget}s. In addition we declare the private \c + createLabel() function to simplify the constructor. + + \section1 Window Class Implementation + + \snippet examples/painting/concentriccircles/window.cpp 0 + + In the constructor, we first create the various labels and put + them in a QGridLayout. + + \snippet examples/painting/concentriccircles/window.cpp 1 + + Then we create a QTimer. The QTimer class is a high-level + programming interface for timers, and provides repetitive and + single-shot timers. + + We create a timer to facilitate the animation of our concentric + circles; when we create the four CircleWidget instances (and add + them to the layout), we connect the QTimer::timeout() signal to + each of the widgets' \c nextAnimationFrame() slots. + + \snippet examples/painting/concentriccircles/window.cpp 2 + + Before we set the layout and window title for our main window, we + make the timer start with a timeout interval of 100 milliseconds, + using the QTimer::start() function. That means that the + QTimer::timeout() signal will be emitted, forcing a repaint of the + four \c {CircleWidget}s, every 100 millisecond which is the reason + the circles appear as animated. + + \snippet examples/painting/concentriccircles/window.cpp 3 + + The private \c createLabel() function is implemented to simlify + the constructor. +*/ diff --git a/doc/src/examples/configdialog.qdoc b/doc/src/examples/configdialog.qdoc new file mode 100644 index 0000000000..ff4c8a68d2 --- /dev/null +++ b/doc/src/examples/configdialog.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example dialogs/configdialog + \title Config Dialog Example + + The Config Dialog examples shows how a configuration dialog can be created by + using an icon view with a stacked widget. + + \image configdialog-example.png +*/ diff --git a/doc/src/examples/contiguouscache.qdoc b/doc/src/examples/contiguouscache.qdoc new file mode 100644 index 0000000000..2200b92e9a --- /dev/null +++ b/doc/src/examples/contiguouscache.qdoc @@ -0,0 +1,83 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example tools/contiguouscache + \title Contiguous Cache Example + + The Contiguous Cache example shows how to use QContiguousCache to manage memory usage for + very large models. In some environments memory is limited and, even when it + isn't, users still dislike an application using excessive memory. + Using QContiguousCache to manage a list, rather than loading + the entire list into memory, allows the application to limit the amount + of memory it uses, regardless of the size of the data set it accesses + + The simplest way to use QContiguousCache is to cache as items are requested. When + a view requests an item at row N it is also likely to ask for items at rows near + to N. + + \snippet examples/tools/contiguouscache/randomlistmodel.cpp 0 + + After getting the row, the class determines if the row is in the bounds + of the contiguous cache's current range. It would have been equally valid to + simply have the following code instead. + + \code + while (row > m_rows.lastIndex()) + m_rows.append(fetchWord(m_rows.lastIndex()+1); + while (row < m_rows.firstIndex()) + m_rows.prepend(fetchWord(m_rows.firstIndex()-1); + \endcode + + However a list will often jump rows if the scroll bar is used directly, resulting in + the code above causing every row between the old and new rows to be fetched. + + Using QContiguousCache::lastIndex() and QContiguousCache::firstIndex() allows + the example to determine what part of the list the cache is currently caching. + These values don't represent the indexes into the cache's own memory, but rather + a virtual infinite array that the cache represents. + + By using QContiguousCache::append() and QContiguousCache::prepend() the code ensures + that items that may be still on the screen are not lost when the requested row + has not moved far from the current cache range. QContiguousCache::insert() can + potentially remove more than one item from the cache as QContiguousCache does not + allow for gaps. If your cache needs to quickly jump back and forth between + rows with significant gaps between them consider using QCache instead. + + And thats it. A perfectly reasonable cache, using minimal memory for a very large + list. In this case the accessor for getting the words into the cache + generates random information rather than fixed information. This allows you + to see how the cache range is kept for a local number of rows when running the + example. + + \snippet examples/tools/contiguouscache/randomlistmodel.cpp 1 + + It is also worth considering pre-fetching items into the cache outside of the + application's paint routine. This can be done either with a separate thread + or using a QTimer to incrementally expand the range of the cache prior to + rows being requested out of the current cache range. +*/ diff --git a/doc/src/examples/customcompleter.qdoc b/doc/src/examples/customcompleter.qdoc new file mode 100644 index 0000000000..d1f555f515 --- /dev/null +++ b/doc/src/examples/customcompleter.qdoc @@ -0,0 +1,187 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example tools/customcompleter + \title Custom Completer Example + + The Custom Completer example shows how to provide string-completion + facilities for an input widget based on data provided by a model. The + completer pops up suggestions for possible words based on the first three + characters input by the user and the user's choice of word is inserted + into the \c TextEdit using QTextCursor. + + \image customcompleter-example.png + + \section1 Setting Up The Resource File + + The Custom Completer example requires a resource file, \e wordlist.txt, + that has a list of words to help QCompleter complete words. This file + contains the following: + + \quotefile examples/tools/customcompleter/customcompleter.qrc + + \section1 TextEdit Class Definition + + The \c TextEdit class is a subclass of QTextEdit with a custom + \c insertCompletion() slot and it reimplements the + \l{QAbstractScrollArea::keyPressEvent()}{keyPressEvent()} and the + \l{QWidget::focusInEvent()}{focusInEvent()} functions. \c TextEdit also + contains a private function \c textUnderCursor() and a private instance + of QCompleter, \c c. + + \snippet examples/tools/customcompleter/textedit.h 0 + + \section1 TextEdit Class Implementation + + The constructor for \c TextEdit constructs a \c TextEdit with a parent and + initializes \c c. The instructions to use the completer is displayed on + the \c TextEdit object, using the + \l{QTextEdit::setPlainText()}{setPlainText()} function. + + \snippet examples/tools/customcompleter/textedit.cpp 0 + + In addition, \c TextEdit also includes a default destructor: + + \snippet examples/tools/customcompleter/textedit.cpp 1 + + The \c setCompleter() function accepts a \a completer and sets it up. + We use \c{if (c)} to check if \c c has been initialized. If it has been + initialized, the QObject::disconnect() function is invoked to disconnect + the signal from the slot. This is to ensure that no previous completer + object is still connected to the slot. + + \snippet examples/tools/customcompleter/textedit.cpp 2 + + We then instantiate \c c with \a completer and set it as \c{TextEdit}'s + widget. The completion mode and case sensitivity are also set and then + we connect the \l{QCompleter::activated()}{activated()} signal to the + \c insertCompletion() slot. + + The \c completer() function is a getter function that returns \c c. + + \snippet examples/tools/customcompleter/textedit.cpp 3 + + The completer pops up the options available, based on the contents of + \e wordlist.txt, but the text cursor is responsible for filling in the + missing characters, according to the user's choice of word. + + Suppose the user inputs "ACT" and accepts the completer's suggestion of + "ACTUAL". The \c completion string is then sent to \c insertCompletion() + by the completer's \l{QCompleter::activated()}{activated()} signal. + + The \c insertCompletion() function is responsible for completing the word + using a QTextCursor object, \c tc. It validates to ensure that the + completer's widget is \c TextEdit before using \c tc to insert the extra + characters to complete the word. + + \snippet examples/tools/customcompleter/textedit.cpp 4 + + The figure below illustrates this process: + + \image customcompleter-insertcompletion.png + + \c{completion.length()} = 6 + + \c{c->completionPrefix().length()}=3 + + The difference between these two values is \c extra, which is 3. This + means that the last three characters from the right, "U", "A", and "L", + will be inserted by \c tc. + + The \c textUnderCursor() function uses a QTextCursor, \c tc, to select a + word under the cursor and return it. + + \snippet examples/tools/customcompleter/textedit.cpp 5 + + The \c TextEdit class reimplements \l{QWidget::focusInEvent()} + {focusInEvent()} function, which is an event handler used to receive + keyboard focus events for the widget. + + \snippet examples/tools/customcompleter/textedit.cpp 6 + + The \l{QAbstractScrollArea::keyPressEvent()}{keyPressEvent()} is + reimplemented to ignore key events like Qt::Key_Enter, Qt::Key_Return, + Qt::Key_Escape, Qt::Key_Tab, and Qt::Key_Backtab so the completer can + handle them. + + If there is an active completer, we cannot process the shortcut, Ctrl+E. + + \snippet examples/tools/customcompleter/textedit.cpp 7 + + We also handle other modifiers and shortcuts for which we do not want the + completer to respond to. + + \snippet examples/tools/customcompleter/textedit.cpp 8 + + Finally, we pop up the completer. + + \section1 MainWindow Class Definition + + The \c MainWindow class is a subclass of QMainWindow and implements a + private slot, \c about(). This class also has two private functions, + \c createMenu() and \c modelFromFile() as well as private instances of + QCompleter and \c TextEdit. + + \snippet examples/tools/customcompleter/mainwindow.h 0 + + \section1 MainWindow Class Implementation + + The constructor constructs a \c MainWindow with a parent and initializes + the \c completer. It also instantiates a \c TextEdit and sets its + completer. A QStringListModel, obtained from \c modelFromFile(), is used + to populate the \c completer. The \c{MainWindow}'s central widget is set + to \c TextEdit and its size is set to 500 x 300. + + \snippet examples/tools/customcompleter/mainwindow.cpp 0 + + The \c createMenu() function creates the necessary QAction objects needed + for the "File" and "Help" menu and their \l{QAction::triggered()} + {triggered()} signals are connected to the \c quit(), \c about(), and + \c aboutQt() slots respectively. + + \snippet examples/tools/customcompleter/mainwindow.cpp 1 + + The \c modelFromFile() function accepts a \a fileName and attempts to + extract the contents of this file into a QStringListModel. We display the + Qt::WaitCursor when we are populating the QStringList, \c words, and + restore the mouse cursor when we are done. + + \snippet examples/tools/customcompleter/mainwindow.cpp 2 + + The \c about() function provides a brief description about the Custom + Completer example. + + \snippet examples/tools/customcompleter/mainwindow.cpp 3 + + \section1 \c main() Function + + The \c main() function instantiates \c MainWindow and invokes the + \l{QWidget::show()}{show()} function. + + \snippet examples/tools/customcompleter/main.cpp 0 +*/ diff --git a/doc/src/examples/customsortfiltermodel.qdoc b/doc/src/examples/customsortfiltermodel.qdoc new file mode 100644 index 0000000000..e8cd5edabd --- /dev/null +++ b/doc/src/examples/customsortfiltermodel.qdoc @@ -0,0 +1,289 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example itemviews/customsortfiltermodel + \title Custom Sort/Filter Model Example + + The Custom Sort/Filter Model example illustrates how to subclass + QSortFilterProxyModel to perform advanced sorting and filtering. + + \image customsortfiltermodel-example.png Screenshot of the Custom Sort/Filter Model Example + + The QSortFilterProxyModel class provides support for sorting and + filtering data passed between another model and a view. + + The model transforms the structure of a source model by mapping + the model indexes it supplies to new indexes, corresponding to + different locations, for views to use. This approach allows a + given source model to be restructured as far as views are + concerned, without requiring any transformations on the underlying + data and without duplicating the data in memory. + + The Custom Sort/Filter Model example consists of two classes: + + \list + + \o The \c MySortFilterProxyModel class provides a custom proxy + model. + + \o The \c Window class provides the main application window, + using the custom proxy model to sort and filter a standard + item model. + + \endlist + + We will first take a look at the \c MySortFilterProxyModel class + to see how the custom proxy model is implemented, then we will + take a look at the \c Window class to see how the model is + used. Finally we will take a quick look at the \c main() function. + + \section1 MySortFilterProxyModel Class Definition + + The \c MySortFilterProxyModel class inherits the + QSortFilterProxyModel class. + + Since QAbstractProxyModel and its subclasses are derived from + QAbstractItemModel, much of the same advice about subclassing + normal models also applies to proxy models. + + On the other hand, it is worth noting that many of + QSortFilterProxyModel's default implementations of functions are + written so that they call the equivalent functions in the relevant + source model. This simple proxying mechanism may need to be + overridden for source models with more complex behavior; in this + example we derive from the QSortFilterProxyModel class to ensure + that our filter can recognize a valid range of dates, and to + control the sorting behavior. + + \snippet examples/itemviews/customsortfiltermodel/mysortfilterproxymodel.h 0 + + We want to be able to filter our data by specifying a given period + of time. For that reason, we implement the custom \c + setFilterMinimumDate() and \c setFilterMaximumDate() functions as + well as the corresponding \c filterMinimumDate() and \c + filterMaximumDate() functions. We reimplement + QSortFilterProxyModel's \l + {QSortFilterProxyModel::filterAcceptsRow()}{filterAcceptsRow()} + function to only accept rows with valid dates, and + QSortFilterProxyModel::lessThan() to be able to sort the senders + by their email adresses. Finally, we implement a \c dateInRange() + convenience function that we will use to determine if a date is + valid. + + \section1 MySortFilterProxyModel Class Implementation + + The \c MySortFilterProxyModel constructor is trivial, passing the + parent parameter on to the base class constructor: + + \snippet examples/itemviews/customsortfiltermodel/mysortfilterproxymodel.cpp 0 + + The most interesting parts of the \c MySortFilterProxyModel + implementation are the reimplementations of + QSortFilterProxyModel's \l + {QSortFilterProxyModel::filterAcceptsRow()}{filterAcceptsRow()} + and \l {QSortFilterProxyModel::lessThan()}{lessThan()} + functions. Let's first take a look at our customized \c lessThan() + function. + + \snippet examples/itemviews/customsortfiltermodel/mysortfilterproxymodel.cpp 4 + + We want to sort the senders by their email adresses. The \l + {QSortFilterProxyModel::}{lessThan()} function is used as the < + operator when sorting. The default implementation handles a + collection of types including QDateTime and String, but in order + to be able to sort the senders by their email adresses we must + first identify the adress within the given string: + + \snippet examples/itemviews/customsortfiltermodel/mysortfilterproxymodel.cpp 6 + + We use QRegExp to define a pattern for the adresses we are looking + for. The QRegExp::indexIn() function attempts to find a match in + the given string and returns the position of the first match, or + -1 if there was no match. If the given string contains the + pattern, we use QRegExp's \l {QRegExp::cap()}{cap()} function to + retrieve the actual adress. The \l {QRegExp::cap()}{cap()} + function returns the text captured by the \e nth + subexpression. The entire match has index 0 and the parenthesized + subexpressions have indexes starting from 1 (excluding + non-capturing parentheses). + + \snippet examples/itemviews/customsortfiltermodel/mysortfilterproxymodel.cpp 3 + + The \l + {QSortFilterProxyModel::filterAcceptsRow()}{filterAcceptsRow()} + function, on the other hand, is expected to return true if the + given row should be included in the model. In our example, a row + is accepted if either the subject or the sender contains the given + regular expression, and the date is valid. + + \snippet examples/itemviews/customsortfiltermodel/mysortfilterproxymodel.cpp 7 + + We use our custom \c dateInRange() function to determine if a date + is valid. + + To be able to filter our data by specifying a given period of + time, we also implement functions for getting and setting the + minimum and maximum dates: + + \snippet examples/itemviews/customsortfiltermodel/mysortfilterproxymodel.cpp 1 + \codeline + \snippet examples/itemviews/customsortfiltermodel/mysortfilterproxymodel.cpp 2 + + The get functions, \c filterMinimumDate() and \c + filterMaximumDate(), are trivial and implemented as inline + function in the header file. + + This completes our custom proxy model. Let's see how we can use it + in an application. + + \section1 Window Class Definition + + The \c CustomFilter class inherits QWidget, and provides this + example's main application window: + + \snippet examples/itemviews/customsortfiltermodel/window.h 0 + + We implement two private slots, \c textFilterChanged() and \c + dateFilterChanged(), to respond to the user changing the filter + pattern, case sensitivity or any of the dates. In addition, we + implement a public \c setSourceModel() convenience function to set + up the model/ view relation. + + \section1 Window Class Implementation + + In this example, we have chosen to create and set the source model + in the \c main () function (which we will come back to later). So + when constructing the main application window, we assume that a + source model already exists and start by creating an instance of + our custom proxy model: + + \snippet examples/itemviews/customsortfiltermodel/window.cpp 0 + + We set the \l + {QSortFilterProxyModel::dynamicSortFilter}{dynamicSortFilter} + property that holds whether the proxy model is dynamically sorted + and filtered. By setting this property to true, we ensure that the + model is sorted and filtered whenever the contents of the source + model change. + + The main application window shows views of both the source model + and the proxy model. The source view is quite simple: + + \snippet examples/itemviews/customsortfiltermodel/window.cpp 1 + + The QTreeView class provides a default model/view implementation + of a tree view; our view implements a tree representation of items + in the application's source model. + + \snippet examples/itemviews/customsortfiltermodel/window.cpp 2 + + The QTreeView class provides a default model/view implementation + of a tree view; our view implements a tree representation of items + in the application's source model. We add our view widget to a + layout that we install on a corresponding group box. + + The proxy model view, on the other hand, contains several widgets + controlling the various aspects of transforming the source model's + data structure: + + \snippet examples/itemviews/customsortfiltermodel/window.cpp 3 + \snippet examples/itemviews/customsortfiltermodel/window.cpp 4 + + Note that whenever the user changes one of the filtering options, + we must explicitly reapply the filter. This is done by connecting + the various editors to functions that update the proxy model. + + \snippet examples/itemviews/customsortfiltermodel/window.cpp 5 + + The sorting will be handled by the view. All we have to do is to + enable sorting for our proxy view by setting the + QTreeView::sortingEnabled property (which is false by + default). Then we add all the filtering widgets and the proxy view + to a layout that we install on a corresponding group box. + + \snippet examples/itemviews/customsortfiltermodel/window.cpp 6 + + Finally, after putting our two group boxes into another layout + that we install on our main application widget, we customize the + application window. + + As mentioned above, we create the source model in the \c main () + function, calling the \c Window::setSourceModel() function to make + the application use it: + + \snippet examples/itemviews/customsortfiltermodel/window.cpp 7 + + The QSortFilterProxyModel::setSourceModel() function makes the + proxy model process the data in the given model, in this case out + mail model. The \l {QAbstractItemView::}{setModel()} that the + view widget inherits from the QAbstractItemModel class, sets the + model for the view to present. Note that the latter function will + also create and set a new selection model. + + \snippet examples/itemviews/customsortfiltermodel/window.cpp 8 + + The \c textFilterChanged() function is called whenever the user + changes the filter pattern or the case sensitivity. + + We first retrieve the preferred syntax (the QRegExp::PatternSyntax + enum is used to interpret the meaning of the given pattern), then + we determine the preferred case sensitivity. Based on these + preferences and the current filter pattern, we set the proxy + model's \l {QSortFilterProxyModel::}{filterRegExp} property. The + \l {QSortFilterProxyModel::}{filterRegExp} property holds the + regular expression used to filter the contents of the source + model. Note that calling QSortFilterProxyModel's \l + {QSortFilterProxyModel::}{setFilterRegExp()} function also updates + the model. + + \snippet examples/itemviews/customsortfiltermodel/window.cpp 9 + + The \c dateFilterChanged() function is called whenever the user + modifies the range of valid dates. We retrieve the new dates from + the user interface, and call the corresponding functions (provided + by our custom proxy model) to set the proxy model's minimum and + maximum dates. As we explained above, calling these functions also + updates the model. + + \section1 The Main() Function + + In this example, we have separated the application from the source + model by creating the model in the \c main () function. First we + create the application, then we create the source model: + + \snippet examples/itemviews/customsortfiltermodel/main.cpp 0 + + The \c createMailModel() function is a convenience function + provided to simplify the constructor. All it does is to create and + return a model describing a collection of emails. The model is an + instance of the QStandardItemModel class, i.e., a generic model + for storing custom data typically used as a repository for + standard Qt data types. Each mail description is added to the + model using \c addMail(), another convenience function. See \l + {itemviews/customsortfiltermodel/main.cpp}{main.cpp} for details. +*/ diff --git a/doc/src/examples/customtype.qdoc b/doc/src/examples/customtype.qdoc new file mode 100644 index 0000000000..326d1d42ab --- /dev/null +++ b/doc/src/examples/customtype.qdoc @@ -0,0 +1,143 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example tools/customtype + \title Custom Type Example + + The Custom Type example shows how to integrate a custom type into Qt's + meta-object system. + + Contents: + + \tableofcontents + + \section1 Overview + + Qt provides a range of standard value types that are used to provide + rich and meaningful APIs. These types are integrated with the meta-object + system, enabling them to be stored in QVariant objects, written out in + debugging information and sent between components in signal-slot + communication. + + Custom types can also be integrated with the meta-object system as long as + they are written to conform to some simple guidelines. In this example, we + introduce a simple \c Message class, we describe how we make it work with + QVariant, and we show how it can be extended to generate a printable + representation of itself for use in debugging output. + + \section1 The Message Class Definition + + The \c Message class is a simple value class that contains two pieces + of information (a QString and a QStringList), each of which can be read + using trivial getter functions: + + \snippet examples/tools/customtype/message.h custom type definition + + The default constructor, copy constructor and destructor are + all required, and must be public, if the type is to be integrated into the + meta-object system. Other than this, we are free to implement whatever we + need to make the type do what we want, so we also include a constructor + that lets us set the type's data members. + + To enable the type to be used with QVariant, we declare it using the + Q_DECLARE_METATYPE() macro: + + \snippet examples/tools/customtype/message.h custom type meta-type declaration + + We do not need to write any additional code to accompany this macro. + + To allow us to see a readable description of each \c Message object when it + is sent to the debug output stream, we define a streaming operator: + + \snippet examples/tools/customtype/message.h custom type streaming operator + + This facility is useful if you need to insert tracing statements in your + code for debugging purposes. + + \section1 The Message Class Implementation + + The implementation of the default constructor, copy constructor and destructor + are straightforward for the \c Message class: + + \snippet examples/tools/customtype/message.cpp Message class implementation + + The streaming operator is implemented in the following way: + + \snippet examples/tools/customtype/message.cpp custom type streaming operator + + Here, we want to represent each value depending on how many lines are stored + in the message body. We stream text to the QDebug object passed to the + operator and return the QDebug object obtained from its maybeSpace() member + function; this is described in more detail in the + \l{Creating Custom Qt Types#Making the Type Printable}{Creating Custom Qt Types} + document. + + We include the code for the getter functions for completeness: + + \snippet examples/tools/customtype/message.cpp getter functions + + With the type fully defined, implemented, and integrated with the + meta-object system, we can now use it. + + \section1 Using the Message + + In the example's \c{main()} function, we show how a \c Message object can + be printed to the console by sending it to the debug stream: + + \snippet examples/tools/customtype/main.cpp printing a custom type + + You can use the type with QVariant in exactly the same way as you would + use standard Qt value types. Here's how to store a value using the + QVariant::setValue() function: + + \snippet examples/tools/customtype/main.cpp storing a custom value + + Alternatively, the QVariant::fromValue() and qVariantSetValue() functions + can be used if you are using a compiler without support for member template + functions. + + The value can be retrieved using the QVariant::value() member template + function: + + \snippet examples/tools/customtype/main.cpp retrieving a custom value + + Alternatively, the qVariantValue() template function can be used if + you are using a compiler without support for member template functions. + + \section1 Further Reading + + The custom \c Message type can also be used with direct signal-slot + connections; see the \l{Custom Type Sending Example} for a demonstration + of this. + To register a custom type for use with queued signals and slots, such as + those used in cross-thread communication, see the + \l{Queued Custom Type Example}. + + More information on using custom types with Qt can be found in the + \l{Creating Custom Qt Types} document. +*/ diff --git a/doc/src/examples/customtypesending.qdoc b/doc/src/examples/customtypesending.qdoc new file mode 100644 index 0000000000..ce4f42d727 --- /dev/null +++ b/doc/src/examples/customtypesending.qdoc @@ -0,0 +1,121 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example tools/customtypesending + \title Custom Type Sending Example + + The Custom Type Sending example shows how to use a custom type with signals + and slots. + + \image customtypesending-example.png + + \section1 Overview + + In the \l{Custom Type Example}, we showed how to integrate custom types + with the meta-object system, enabling them to be stored in QVariant + objects, written out in debugging information and used in signal-slot + communication. + + In this example, we demonstrate that the preparations made to the + \c Message class and its declaration with Q_DECLARE_METATYPE() enable it + to be used with direct signal-slot connections. We do this by creating + a \c Window class containing signals and slots whose signatures include + \c Message arguments. + + \section1 The Window and Message Class Definitions + + We define a simple \c Window class with a signal and public slot that + allow a \c Message object to be sent via a signal-slot connection: + + \snippet examples/tools/customtypesending/window.h Window class definition + + The window will contain a text editor to show the contents of a message + and a push button that the user can click to send a message. To facilitate + this, we also define the \c sendMessage() slot. We also keep a \c Message + instance in the \c thisMessage private variable which holds the actual + message to be sent. + + The \c Message class is defined in the following way: + + \snippet examples/tools/customtypesending/message.h custom type definition + + The type is declared to the meta-type system with the Q_DECLARE_METATYPE() + macro: + + \snippet examples/tools/customtypesending/message.h custom type meta-type declaration + + This will make the type available for use in direct signal-slot connections. + + \section1 The Window Class Implementation + + The \c Window constructor sets up a user interface containing a text + editor and a push button. + + \snippet examples/tools/customtypesending/window.cpp Window constructor + + The button's \l{QPushButton::}{clicked()} signal is connected to the + window's \c{sendMessage()} slot, which emits the \c{messageSent(Message)} + signal with the \c Message held by the \c thisMessage variable: + + \snippet examples/tools/customtypesending/window.cpp sending a message + + We implement a slot to allow the message to be received, and this also + lets us set the message in the window programatically: + + \snippet examples/tools/customtypesending/window.cpp receiving a message + + In this function, we simply assign the new message to \c thisMessage + and update the text in the editor. + + \section1 Making the Connection + + In the example's \c{main()} function, we perform the connection between + two instances of the \c Window class: + + \snippet examples/tools/customtypesending/main.cpp main function + + We set the message for the first window and connect the + \c{messageSent(Message)} signal from each window to the other's + \c{setMessage(Message)} slot. Since the signals and slots mechanism is only + concerned with the type, we can simplify the signatures of both the + signal and slot when we make the connection. + + When the user clicks on the \gui{Send message} button in either window, + the message shown will be emitted in a signal that the other window will + receive and display. + + \section1 Further Reading + + Although the custom \c Message type can be used with direct signals and + slots, an additional registration step needs to be performed if you want + to use it with queued signal-slot connections. See the + \l{Queued Custom Type Example} for details. + + More information on using custom types with Qt can be found in the + \l{Creating Custom Qt Types} document. +*/ diff --git a/doc/src/examples/dbscreen.qdoc b/doc/src/examples/dbscreen.qdoc new file mode 100644 index 0000000000..cfcdecd68f --- /dev/null +++ b/doc/src/examples/dbscreen.qdoc @@ -0,0 +1,186 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example qws/dbscreen + \title Double Buffered Graphics Driver Example + + The Double Buffered Graphics Driver example shows how to write your own + double buffered graphics driver and add it to Qt for Embedded Linux. + + Similar to the \l{Accelerated Graphics Driver Example}, there are three steps + to writing and implementing this graphics driver: + + \list 1 + \o \l {Step 1: Creating a Custom Graphics Driver} + {Creating a Custom Graphics Driver} + + \o \l {Step 2: Implementing the Back Buffer} + {Implementing the Back Buffer} + + \o \l {Step 3: Creating the Driver Plugin} + {Creating the Driver Plugin} + + \endlist + + After compiling the example code, install the graphics driver plugin with + the command \c {make install}. To start an application using the graphics + driver, you can either set the environment variable \l QWS_DISPLAY and + then run the application, or you can just run the application using the + \c -display switch. + + Note that this is a minimal example and this driver will not work well + with widgets painting themself directly to the screen (e.g. widgets with + the Qt::WA_PaintOnScreen window attribute set). Also, the example requires + the Linux framebuffer to be set up correctly and with the correct device + permissions. For further information, refer to + \l{Testing the Linux Framebuffer}. + + \section1 Step 1: Creating a Custom Graphics Driver + + Usually, a custom graphics driver is created by subclassing the QScreen + class, the base class for implementing screen or graphics drivers in + Qt for Embedded Linux. In this example, however, we subclass the QLinuxFbScreen + class instead, to ensure that our driver uses the Linux framebuffer. + + For our graphics driver, the \c DBScreen class, we reimplement five + functions belonging to QScreen: + + \list + \o \l{QScreen::initDevice()}{initDevice()}, + \o \l{QScreen::shutdownDevice()}{shutdownDevice()}, + \o \l{QScreen::blit()}{blit()}, + \o \l{QScreen::solidFill()}{solidFill()}, and + \o \l{QScreen::exposeRegion()}{exposeRegion()}. + \endlist + + \snippet examples/qws/dbscreen/dbscreen.h 0 + + In addition to the abovementioned functions, there is a private instance + of QPainter and QImage - \c painter, used for drawing operations on + the back buffer, and \c image, the back buffer itself. + + \section1 Step 2: Implementing the Back Buffer + + The graphics driver must carry out three main functions: + + \list 1 + \o Allocate the back buffer on startup and deallocate it on shutdown. + \o Draw to the back buffer instead of directly to the screen + (which is what QLinuxFbScreen does). + \o Copy the back buffer to the screen whenever a screen update is + done. + \endlist + + \section2 Device initializing and shutdown + + We first reimplement \c initDevice() and \c shutdownDevice(). + + The \c initDevice() function initializes the framebuffer. We reimplement + this function to enable accelerated drivers to set up the graphic card. + For this example, we first call the super class' implementation to set up + the Linux framebuffer. If this call returns \c false, we return \c false. + Otherwise, we initialize the screen cursor with + QScreenCursor::initSoftwareCursor() as well as instantiate \c image and + \c painter. Then, we return \c true. + + \snippet examples/qws/dbscreen/dbscreen.cpp 0 + + The \c shutdownDevice() function's default implementation only hides the + mouse cursor. Hence, we reimplement it to carry out the necessary cleanup + before the Qt for Embedded Linux server exits. + + \snippet examples/qws/dbscreen/dbscreen.cpp 1 + + Again, we call the super class implementation to shutdown the Linux + framebuffer prior to deleting \c image and \c painter. + + \section2 Drawing to the back buffer + + We move on to the drawing functions - \c solidFill() and \c blit(). In + QLinuxFbScreen, these functions draw directly to the Linux framebuffer; + but in our driver we reimplement them to draw to the back buffer instead. + + \snippet examples/qws/dbscreen/dbscreen.cpp 2 + + The \c solidFill() function is called from \c exposeRegion() to fill the + given \c region of the screen with the specified \c color. In this + example, we use \c painter to fill rectangles in \c image, the back + buffer, according to the given region. + + \snippet examples/qws/dbscreen/dbscreen.cpp 3 + + The \c blit() function is also called from \c exposeRegion() to copy the + given QRegion object, \c region, in the given QImage object, \c image, to + the QPoint object specified by \c topLeft. Once again we use \c painter + to draw in the back buffer, \c image. + + \section2 Displaying the buffer on the screen + + The \c exposeRegion() function is called by the Qt for Embedded Linux server + whenever a screen update is required. The given \c region is the screen + region that needs to be updated and \c changing is is the index into + QWSServer::clientWindows() of the window that caused the update. + + \snippet examples/qws/dbscreen/dbscreen.cpp 4 + + In our implementation, we first call the super class implementation to + ensure that \c solidFill() and \c blit() will be called correctly. This + causes the changed areas to be updated in the back buffer. We then call + the super class' implementation of \c blit() to copy the updated region + from the back buffer into the Linux framebuffer. + + \section1 Step 3: Creating the Driver Plugin + + Qt provides a high level API for writing Qt extentions. One of the plugin + base classes provided is QScreenDriverPlugin, which we use in this example + to create our screen driver plugin. + + \snippet examples/qws/dbscreen/dbscreendriverplugin.cpp 0 + + There are only two functions to reimplement: + + \list + \o \l{QScreenDriverPlugin::create()}{create()} - creates a driver + matching the given key + \o \l{QScreenDriverPlugin::create()}{keys()} - returns a list of + valid keys representing the drivers supported by the plugin + \endlist + + \snippet examples/qws/dbscreen/dbscreendriverplugin.cpp 1 + \codeline + \snippet examples/qws/dbscreen/dbscreendriverplugin.cpp 2 + + Our plugin will only support one driver, \c dbscreen. + + Lastly, we export the plugin. + + \snippet examples/qws/dbscreen/dbscreendriverplugin.cpp 3 + + For detailed information about the Qt plugin system see + \l{How to Create Qt Plugins.} +*/ diff --git a/doc/src/examples/dbus-chat.qdoc b/doc/src/examples/dbus-chat.qdoc new file mode 100644 index 0000000000..8d10a721ae --- /dev/null +++ b/doc/src/examples/dbus-chat.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example dbus/dbus-chat + \title D-Bus Chat Example + + The D-Bus Chat example shows how to use D-Bus to communicate between two + applications. + + \image dbus-chat-example.png +*/ diff --git a/doc/src/examples/diagramscene.qdoc b/doc/src/examples/diagramscene.qdoc new file mode 100644 index 0000000000..fca31ca33f --- /dev/null +++ b/doc/src/examples/diagramscene.qdoc @@ -0,0 +1,834 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example graphicsview/diagramscene + \title Diagram Scene Example + + This example shows use of Qt's graphics framework. + + \image diagramscene.png + + The Diagram Scene example is an application in which you can + create a flowchart diagram. It is possible to add flowchart shapes + and text and connect the shapes by arrows as shown in the image + above. The shapes, arrows, and text can be given different + colors, and it is possible to change the font, style, and + underline of the text. + + The Qt graphics view framework is designed to manage and display + custom 2D graphics items. The main classes of the framework are + QGraphicsItem, QGraphicsScene and QGraphicsView. The graphics + scene manages the items and provides a surface for them. + QGraphicsView is a widget that is used to render a scene on the + screen. See the \l{Graphics View Framework} for a more detailed + description of the framework. + + In this example we show how to create such custom graphics + scenes and items by implementing classes that inherit + QGraphicsScene and QGraphicsItem. + + In particular we show how to: + + \list + \o Create custom graphics items. + \o Handle mouse events and movement of items. + \o Implement a graphics scene that can manage our custom items. + \o Custom painting of items. + \o Create a movable and editable text item. + \endlist + + The example consists of the following classes: + \list + \o \c MainWindow creates the widgets and display + them in a QMainWindow. It also manages the interaction + between the widgets and the graphics scene, view and + items. + \o \c DiagramItem inherits QGraphicsPolygonItem and + represents a flowchart shape. + \o \c TextDiagramItem inherits QGraphicsTextItem and + represents text items in the diagram. The class adds + support for moving the item with the mouse, which is not + supported by QGraphicsTextItem. + \o \c Arrow inherits QGraphicsLineItem and is an arrow + that connect two DiagramItems. + \o \c DiagramScene inherits QGraphicsDiagramScene and + provides support for \c DiagramItem, \c Arrow and + \c DiagramTextItem (In addition to the support already + handled by QGraphicsScene). + \endlist + + \section1 MainWindow Class Definition + + \snippet examples/graphicsview/diagramscene/mainwindow.h 0 + + The \c MainWindow class creates and lays out the widgets in a + QMainWindow. The class forwards input from the widgets to the + DiagramScene. It also updates its widgets when the diagram + scene's text item changes, or a diagram item or a diagram text item + is inserted into the scene. + + The class also deletes items from the scene and handles the + z-ordering, which decides the order in which items are drawn when + they overlap each other. + + \section1 MainWindow Class Implementation + + + We start with a look at the constructor: + + \snippet examples/graphicsview/diagramscene/mainwindow.cpp 0 + + In the constructor we call methods to create the widgets and + layouts of the example before we create the diagram scene. + The toolbars must be created after the scene as they connect + to its signals. We then lay the widgets out in the window. + + We connect to the \c itemInserted() and \c textInserted() slots of + the diagram scenes as we want to uncheck the buttons in the tool + box when an item is inserted. When an item is selected in + the scene we receive the \c itemSelected() signal. We use this to + update the widgets that display font properties if the item + selected is a \c DiagramTextItem. + + The \c createToolBox() function creates and lays out the widgets + of the \c toolBox QToolBox. We will not examine it with a + high level of detail as it does not deal with graphics framework + specific functionality. Here is its implementation: + + \snippet examples/graphicsview/diagramscene/mainwindow.cpp 21 + + This part of the function sets up the tabbed widget item that + contains the flowchart shapes. An exclusive QButtonGroup always + keeps one button checked; we want the group to allow all buttons + to be unchecked. + We still use a button group since we can associate user + data, which we use to store the diagram type, with each button. + The \c createCellWidget() function sets up the buttons in the + tabbed widget item and is examined later. + + The buttons of the background tabbed widget item is set up in the + same way, so we skip to the creation of the tool box: + + \snippet examples/graphicsview/diagramscene/mainwindow.cpp 22 + + We set the preferred size of the toolbox as its maximum. This + way, more space is given to the graphics view. + + Here is the \c createActions() function: + + \snippet examples/graphicsview/diagramscene/mainwindow.cpp 23 + + We show an example of the creation of an action. The + functionality the actions trigger is discussed in the slots we + connect the actions to. You can see the \l{Application + Example}{application example} if you need a high-level + introduction to actions. + + The is the \c createMenus() function: + + \snippet examples/graphicsview/diagramscene/mainwindow.cpp 24 + + We create the three menus' of the example. + + The \c createToolbars() function sets up the examples tool + bars. The three \l{QToolButton}s in the \c colorToolBar, the \c + fontColorToolButton, \c fillColorToolButton, and \c + lineColorToolButton, are interesting as we create icons for them + by drawing on a QPixmap with a QPainter. We show how the \c + fillColorToolButton is created. This button lets the user select a + color for the diagram items. + + \snippet examples/graphicsview/diagramscene/mainwindow.cpp 25 + \dots + \snippet examples/graphicsview/diagramscene/mainwindow.cpp 26 + + We set the menu of the tool button with + \l{QToolButton::}{setMenu()}. We need the \c fillAction QAction + object to always be pointing to the selected action of the menu. + The menu is created with the \c createColorMenu() function and, as + we shall see later, contains one menu item for each color that the + items can have. When the user presses the button, which trigger + the \l{QToolButton::}{clicked()} signal, we can set the color of + the selected item to the color of \c fillAction. It is with \c + createColorToolButtonIcon() we create the icon for the button. + + \dots + \snippet examples/graphicsview/diagramscene/mainwindow.cpp 27 + + Here is the \c createBackgroundCellWidget() function: + + \snippet examples/graphicsview/diagramscene/mainwindow.cpp 28 + + This function creates \l{QWidget}s containing a tool button + and a label. The widgets created with this function are used for + the background tabbed widget item in the tool box. + + Here is the \c createCellWidget() function: + + \snippet examples/graphicsview/diagramscene/mainwindow.cpp 29 + + This function returns a QWidget containing a QToolButton with + an image of one of the \c DiagramItems, i.e., flowchart shapes. + The image is created by the \c DiagramItem through the \c image() + function. The QButtonGroup class lets us attach an id (int) with + each button; we store the diagram's type, i.e., the + DiagramItem::DiagramType enum. We use the stored diagram type when + we create new diagram items for the scene. The widgets created + with this function is used in the tool box. + + Here is the \c createColorMenu() function: + + \snippet examples/graphicsview/diagramscene/mainwindow.cpp 30 + + This function creates a color menu that is used as the + drop-down menu for the tool buttons in the \c colorToolBar. We + create an action for each color that we add to the menu. We fetch + the actions data when we set the color of items, lines, and text. + + Here is the \c createColorToolButtonIcon() function: + + \snippet examples/graphicsview/diagramscene/mainwindow.cpp 31 + + This function is used to create the QIcon of the \c + fillColorToolButton, \c fontColorToolButton, and \c + lineColorToolButton. The \a imageFile string is either the text, + flood-fill, or line symbol that is used for the buttons. Beneath + the image we draw a filled rectangle using \a color. + + Here is the \c createColorIcon() function: + + \snippet examples/graphicsview/diagramscene/mainwindow.cpp 32 + + This function creates an icon with a filled rectangle in the + color of \a color. It is used for creating icons for the color + menus in the \c fillColorToolButton, \c fontColorToolButton, and + \c lineColorToolButton. + + Here is the \c backgroundButtonGroupClicked() slot: + + \snippet examples/graphicsview/diagramscene/mainwindow.cpp 1 + + In this function we set the QBrush that is used to draw the + background of the diagramscene. The background can be a grid of + squares of blue, gray, or white tiles, or no grid at all. We have + \l{QPixmap}s of the tiles from png files that we create the brush + with. + + When one of the buttons in the background tabbed widget item is + clicked we change the brush; we find out which button it is by + checking its text. + + Here is the implementation of \c buttonGroupClicked(): + + \snippet examples/graphicsview/diagramscene/mainwindow.cpp 2 + + This slot is called when a button in \c buttonGroup is checked. + When a button is checked the user can click on the graphics view + and a \c DiagramItem of the selected type will be inserted into + the \c DiagramScene. We must loop through the buttons in the group + to uncheck other buttons as only one button is allowed to be + checked at a time. + + \c QButtonGroup assigns an id to each button. We have set the id + of each button to the diagram type, as given by DiagramItem::DiagramType + that will be inserted into the scene when it is clicked. We can + then use the button id when we set the diagram type with + \c setItemType(). In the case of text we assigned an id that has a + value that is not in the DiagramType enum. + + Here is the implementation of \c deleteItem(): + + \snippet examples/graphicsview/diagramscene/mainwindow.cpp 3 + + This slot deletes the selected item, if any, from the scene. It + deletes the arrows first in order to avoid to delete them twice. If + the item to be deleted is a \c DiagramItem, we also need to delete + arrows connected to it; we don't want arrows in the scene that + aren't connected to items in both ends. + + This is the implementation of pointerGroupClicked(): + + \snippet examples/graphicsview/diagramscene/mainwindow.cpp 4 + + The \c pointerTypeGroup decides whether the scene is in ItemMove + or InsertLine mode. This button group is exclusive, i.e., only + one button is checked at any time. As with the \c buttonGroup above + we have assigned an id to the buttons that matches values of the + DiagramScene::Mode enum, so that we can use the id to set the + correct mode. + + Here is the \c bringToFront() slot: + + \snippet examples/graphicsview/diagramscene/mainwindow.cpp 5 + + Several items may collide, i.e., overlap, with each other in + the scene. This slot is called when the user requests that an + item should be placed on top of the items it collides with. + \l{QGraphicsItem}{QGrapicsItems} have a z-value that decides the + order in which items are stacked in the scene; you can think of it + as the z-axis in a 3D coordinate system. When items collide the + items with higher z-values will be drawn on top of items with + lower values. When we bring an item to the front we can loop + through the items it collides with and set a z-value that is + higher than all of them. + + Here is the \c sendToBack() slot: + + \snippet examples/graphicsview/diagramscene/mainwindow.cpp 6 + + This slot works in the same way as \c bringToFront() described + above, but sets a z-value that is lower than items the item that + should be send to the back collides with. + + This is the implementation of \c itemInserted(): + + \snippet examples/graphicsview/diagramscene/mainwindow.cpp 7 + + This slot is called from the \c DiagramScene when an item has been + added to the scene. We set the mode of the scene back to the mode + before the item was inserted, which is ItemMove or InsertText + depending on which button is checked in the \c pointerTypeGroup. + We must also uncheck the button in the in the \c buttonGroup. + + Here is the implementation of \c textInserted(): + + \snippet examples/graphicsview/diagramscene/mainwindow.cpp 8 + + We simply set the mode of the scene back to the mode it had before + the text was inserted. + + Here is the \c currentFontChanged() slot: + + \snippet examples/graphicsview/diagramscene/mainwindow.cpp 9 + + When the user requests a font change, by using one of the + widgets in the \c fontToolBar, we create a new QFont object and + set its properties to match the state of the widgets. This is done + in \c handleFontChange(), so we simply call that slot. + + Here is the \c fontSizeChanged() slot: + + \snippet examples/graphicsview/diagramscene/mainwindow.cpp 10 + + When the user requests a font change, by using one of the + widgets in the \c fontToolBar, we create a new QFont object and + set its properties to match the state of the widgets. This is done + in \c handleFontChange(), so we simply call that slot. + + Here is the implementation of \c sceneScaleChanged(): + + \snippet examples/graphicsview/diagramscene/mainwindow.cpp 11 + + The user can increase or decrease the scale, with the \c + sceneScaleCombo, the scene is drawn in. + It is not the scene itself that changes its scale, but only the + view. + + Here is the \c textColorChanged() slot: + + \snippet examples/graphicsview/diagramscene/mainwindow.cpp 12 + + This slot is called when an item in the drop-down menu of the \c + fontColorToolButton is pressed. We need to change the icon on + the button to the color of the selected QAction. We keep a pointer + to the selected action in \c textAction. It is in \c + textButtonTriggered() we change the text color to the color of \c + textAction, so we call that slot. + + Here is the \c itemColorChanged() implementation: + + \snippet examples/graphicsview/diagramscene/mainwindow.cpp 13 + + This slot handles requests for changing the color of \c + DiagramItems in the same manner as \c textColorChanged() does for + \c DiagramTextItems. + + Here is the implementation of \c lineColorChanged(): + + \snippet examples/graphicsview/diagramscene/mainwindow.cpp 14 + + This slot handles requests for changing the color of \c Arrows in + the same manner that \c textColorChanged() does it for \c + DiagramTextItems. + + Here is the \c textButtonTriggered() slot: + + \snippet examples/graphicsview/diagramscene/mainwindow.cpp 15 + + \c textAction points to the QAction of the currently selected menu item + in the \c fontColorToolButton's color drop-down menu. We have set + the data of the action to the QColor the action represents, so we + can simply fetch this when we set the color of text with \c + setTextColor(). + + Here is the \c fillButtonTriggered() slot: + + \snippet examples/graphicsview/diagramscene/mainwindow.cpp 16 + + \c fillAction points to the selected menu item in the drop-down + menu of \c fillColorToolButton(). We can therefore use the data of + this action when we set the item color with \c setItemColor(). + + Here is the \c lineButtonTriggered() slot: + + \snippet examples/graphicsview/diagramscene/mainwindow.cpp 17 + + \c lineAction point to the selected item in the drop-down menu of + \c lineColorToolButton. We use its data when we set the arrow + color with \c setLineColor(). + + Here is the \c handleFontChange() function: + + \snippet examples/graphicsview/diagramscene/mainwindow.cpp 18 + + \c handleFontChange() is called when any of the widgets that show + font properties changes. We create a new QFont object and set its + properties based on the widgets. We then call the \c setFont() + function of \c DiagramScene; it is the scene that set the font of + the \c DiagramTextItems it manages. + + Here is the \c itemSelected() slot: + + \snippet examples/graphicsview/diagramscene/mainwindow.cpp 19 + + This slot is called when an item in the \c DiagramScene is + selected. In the case of this example it is only text items that + emit signals when they are selected, so we do not need to check + what kind of graphics \a item is. + + We set the state of the widgets to match the properties of the + font of the selected text item. + + This is the \c about() slot: + + \snippet examples/graphicsview/diagramscene/mainwindow.cpp 20 + + This slot displays an about box for the example when the user + selects the about menu item from the help menu. + + \section1 DiagramScene Class Definition + + The \c DiagramScene class inherits QGraphicsScene and adds + functionality to handle \c DiagramItems, \c Arrows, and \c + DiagramTextItems in addition to the items handled by its super + class. + + + \snippet examples/graphicsview/diagramscene/diagramscene.h 0 + + In the \c DiagramScene a mouse click can give three different + actions: the item under the mouse can be moved, an item may be + inserted, or an arrow may be connected between to diagram items. + Which action a mouse click has depends on the mode, given by the + Mode enum, the scene is in. The mode is set with the \c setMode() + function. + + The scene also sets the color of its items and the font of its + text items. The colors and font used by the scene can be set with + the \c setLineColor(), \c setTextColor(), \c setItemColor() and \c + setFont() functions. The type of \c DiagramItem, given by the + DiagramItem::DiagramType function, to be created when an item is + inserted is set with the \c setItemType() slot. + + The \c MainWindow and \c DiagramScene share responsibility for + the examples functionality. \c MainWindow handles the following + tasks: the deletion of items, text, and arrows; moving diagram + items to the back and front; and setting the scale of the scene. + + \section1 DiagramScene Class Implementation + + + We start with the constructor: + + \snippet examples/graphicsview/diagramscene/diagramscene.cpp 0 + + The scene uses \c myItemMenu to set the context menu when it + creates \c DiagramItems. We set the default mode to \c + DiagramScene::MoveItem as this gives the default behavior of + QGraphicsScene. + + Here is the \c setLineColor() function: + + \snippet examples/graphicsview/diagramscene/diagramscene.cpp 1 + + The \c isItemChange function returns true if an \c Arrow item is + selected in the scene in which case we want to change its color. + When the \c DiagramScene creates and adds new arrows to the scene + it will also use the new \a color. + + Here is the \c setTextColor() function: + + \snippet examples/graphicsview/diagramscene/diagramscene.cpp 2 + + This function sets the color of \c DiagramTextItems equal to the + way \c setLineColor() sets the color of \c Arrows. + + Here is the \c setItemColor() function: + + \snippet examples/graphicsview/diagramscene/diagramscene.cpp 3 + + This function sets the color the scene will use when creating + \c DiagramItems. It also changes the color of a selected \c + DiagramItem. + + This is the implementation of \c setFont(): + + \snippet examples/graphicsview/diagramscene/diagramscene.cpp 4 + + Set the font to use for new and selected, if a text item is + selected, \c DiagramTextItems. + + This is the implementation of \c editorLostFocus() slot: + + \snippet examples/graphicsview/diagramscene/diagramscene.cpp 5 + + \c DiagramTextItems emit a signal when they loose focus, which is + connected to this slot. We remove the item if it has no text. + If not, we would leak memory and confuse the user as the items + will be edited when pressed on by the mouse. + + The \c mousePressEvent() function handles mouse press event's + different depending on which mode the \c DiagramScene is in. We + examine its implementation for each mode: + + \snippet examples/graphicsview/diagramscene/diagramscene.cpp 6 + + We simply create a new \c DiagramItem and add it to the scene at + the position the mouse was pressed. Note that the origin of its + local coordinate system will be under the mouse pointer position. + + \snippet examples/graphicsview/diagramscene/diagramscene.cpp 7 + + The user adds \c Arrows to the scene by stretching a line between + the items the arrow should connect. The start of the line is fixed + in the place the user clicked the mouse and the end follows the + mouse pointer as long as the button is held down. When the user + releases the mouse button an \c Arrow will be added to the scene + if there is a \c DiagramItem under the start and end of the line. + We will see how this is implemented later; here we simply add the + line. + + \snippet examples/graphicsview/diagramscene/diagramscene.cpp 8 + + The \c DiagramTextItem is editable when the + Qt::TextEditorInteraction flag is set, else it is movable by the + mouse. We always want the text to be drawn on top of the other + items in the scene, so we set the value to a number higher + than other items in the scene. + + \snippet examples/graphicsview/diagramscene/diagramscene.cpp 9 + + We are in MoveItem mode if we get to the default switch; we + can then call the QGraphicsScene implementation, which + handles movement of items with the mouse. We make this call even + if we are in another mode making it possible to add an item and + then keep the mouse button pressed down and start moving + the item. In the case of text items, this is not possible as they + do not propagate mouse events when they are editable. + + This is the \c mouseMoveEvent() function: + + \snippet examples/graphicsview/diagramscene/diagramscene.cpp 10 + + We must draw the line if we are in InsertMode and the mouse button + is pressed down (the line is not 0). As discussed in \c + mousePressEvent() the line is drawn from the position the mouse + was pressed to the current position of the mouse. + + If we are in MoveItem mode, we call the QGraphicsScene + implementation, which handles movement of items. + + In the \c mouseReleaseEvent() function we need to check if an arrow + should be added to the scene: + + \snippet examples/graphicsview/diagramscene/diagramscene.cpp 11 + + First we need to get the items (if any) under the line's start + and end points. The line itself is the first item at these points, + so we remove it from the lists. As a precaution, we check if the + lists are empty, but this should never happen. + + \snippet examples/graphicsview/diagramscene/diagramscene.cpp 12 + + Now we check if there are two different \c DiagramItems under + the lines start and end points. If there are we can create an \c + Arrow with the two items. The arrow is then added to each item and + finally the scene. The arrow must be updated to adjust its start + and end points to the items. We set the z-value of the arrow to + -1000.0 because we always want it to be drawn under the items. + + \snippet examples/graphicsview/diagramscene/diagramscene.cpp 13 + + Here is the \c isItemChange() function: + + \snippet examples/graphicsview/diagramscene/diagramscene.cpp 14 + + The scene has single selection, i.e., only one item can be + selected at any given time. The foreach will then loop one time + with the selected item or none if no item is selected. \c + isItemChange() is used to check whether a selected item exists + and also is of the specified diagram \a type. + + \section1 DiagramItem Class Definition + + + \snippet examples/graphicsview/diagramscene/diagramitem.h 0 + + The \c DiagramItem represents a flowchart shape in the \c + DiagramScene. It inherits QGraphicsPolygonItem and has a polygon + for each shape. The enum DiagramType has a value for each of the + flowchart shapes. + + The class has a list of the arrows that are connected to it. + This is necessary because only the item knows when it is being + moved (with the \c itemChanged() function) at which time the + arrows must be updated. The item can also draw itself onto a + QPixmap with the \c image() function. This is used for the tool + buttons in \c MainWindow, see \c createColorToolButtonIcon() in + \c MainWindow. + + The Type enum is a unique identifier of the class. It is used by + \c qgraphicsitem_cast(), which does dynamic casts of graphics + items. The UserType constant is the minimum value a custom + graphics item type can be. + + \section1 DiagramItem Class Implementation + + + We start with a look at the constructor: + + \snippet examples/graphicsview/diagramscene/diagramitem.cpp 0 + + In the constructor we create the items polygon according to + \a diagramType. \l{QGraphicsItem}s are not movable or selectable + by default, so we must set these properties. + + Here is the \c removeArrow() function: + + \snippet examples/graphicsview/diagramscene/diagramitem.cpp 1 + + \c removeArrow() is used to remove \c Arrow items when they + or \c DiagramItems they are connected to are removed from the + scene. + + Here is the \c removeArrows() function: + + \snippet examples/graphicsview/diagramscene/diagramitem.cpp 2 + + This function is called when the item is removed from the scene + and removes all arrows that are connected to this item. The arrow + must be removed from the \c arrows list of both its start and end + item. + + Here is the \c addArrow() function: + + \snippet examples/graphicsview/diagramscene/diagramitem.cpp 3 + + This function simply adds the \a arrow to the items \c arrows list. + + Here is the \c image() function: + + \snippet examples/graphicsview/diagramscene/diagramitem.cpp 4 + + This function draws the polygon of the item onto a QPixmap. In + this example we use this to create icons for the tool buttons in + the tool box. + + Here is the \c contextMenuEvent() function: + + \snippet examples/graphicsview/diagramscene/diagramitem.cpp 5 + + We show the context menu. As right mouse clicks, which shows the + menu, don't select items by default we set the item selected with + \l{QGraphicsItem::}{setSelected()}. This is necessary since an + item must be selected to change its elevation with the + \c bringToFront and \c sendToBack actions. + + This is the implementation of \c itemChange(): + + \snippet examples/graphicsview/diagramscene/diagramitem.cpp 6 + + If the item has moved, we need to update the positions of the + arrows connected to it. The implementation of QGraphicsItem does + nothing, so we just return \a value. + + \section1 DiagramTextItem Class Definition + + The \c TextDiagramItem class inherits QGraphicsTextItem and + adds the possibility to move editable text items. Editable + QGraphicsTextItems are designed to be fixed in place and editing + starts when the user single clicks on the item. With \c + DiagramTextItem the editing starts with a double click leaving + single click available to interact with and move it. + + \snippet examples/graphicsview/diagramscene/diagramtextitem.h 0 + + We use \c itemChange() and \c focusOutEvent() to notify the + \c DiagramScene when the text item loses focus and gets selected. + + We reimplement the functions that handle mouse events to make it + possible to alter the mouse behavior of QGraphicsTextItem. + + \section1 DiagramTextItem Implementation + + We start with the constructor: + + \snippet examples/graphicsview/diagramscene/diagramtextitem.cpp 0 + + We simply set the item movable and selectable, as these flags are + off by default. + + Here is the \c itemChange() function: + + \snippet examples/graphicsview/diagramscene/diagramtextitem.cpp 1 + + When the item is selected we emit the selectedChanged signal. The + \c MainWindow uses this signal to update the widgets that display + font properties to the font of the selected text item. + + Here is the \c focusOutEvent() function: + + \snippet examples/graphicsview/diagramscene/diagramtextitem.cpp 2 + + \c DiagramScene uses the signal emitted when the text item looses + focus to remove the item if it is empty, i.e., it contains no + text. + + This is the implementation of \c mouseDoubleClickEvent(): + + \snippet examples/graphicsview/diagramscene/diagramtextitem.cpp 5 + + When we receive a double click event, we make the item editable by calling + QGraphicsTextItem::setTextInteractionFlags(). We then forward the + double-click to the item itself. + + \section1 Arrow Class Definition + + The \c Arrow class is a graphics item that connects two \c + DiagramItems. It draws an arrow head to one of the items. To + achieve this the item needs to paint itself and also re implement + methods used by the graphics scene to check for collisions and + selections. The class inherits QGraphicsLine item, and draws the + arrowhead and moves with the items it connects. + + \snippet examples/graphicsview/diagramscene/arrow.h 0 + + The item's color can be set with \c setColor(). + + \c boundingRect() and \c shape() are reimplemented + from QGraphicsLineItem and are used by the scene + to check for collisions and selections. + + Calling \c updatePosition() causes the arrow to recalculate its + position and arrow head angle. \c paint() is reimplemented so that + we can paint an arrow rather than just a line between items. + + \c myStartItem and \c myEndItem are the diagram items that the + arrow connects. The arrow is drawn with its head to the end item. + \c arrowHead is a polygon with three vertices's we use to draw the + arrow head. + + \section1 Arrow Class Implementation + + The constructor of the \c Arrow class looks like this: + + \snippet examples/graphicsview/diagramscene/arrow.cpp 0 + + We set the start and end diagram items of the arrow. The arrow + head will be drawn where the line intersects the end item. + + Here is the \c boundingRect() function: + + \snippet examples/graphicsview/diagramscene/arrow.cpp 1 + + We need to reimplement this function because the arrow is + larger than the bounding rectangle of the QGraphicsLineItem. The + graphics scene uses the bounding rectangle to know which regions + of the scene to update. + + Here is the \c shape() function: + + \snippet examples/graphicsview/diagramscene/arrow.cpp 2 + + The shape function returns a QPainterPath that is the exact + shape of the item. The QGraphicsLineItem::shape() returns a path + with a line drawn with the current pen, so we only need to add + the arrow head. This function is used to check for collisions and + selections with the mouse. + + Here is the \c updatePosition() slot: + + \snippet examples/graphicsview/diagramscene/arrow.cpp 3 + + This slot updates the arrow by setting the start and end + points of its line to the center of the items it connects. + + Here is the \c paint() function: + + \snippet examples/graphicsview/diagramscene/arrow.cpp 4 + + If the start and end items collide we do not draw the arrow; the + algorithm we use to find the point the arrow should be drawn at + may fail if the items collide. + + We first set the pen and brush we will use for drawing the arrow. + + \snippet examples/graphicsview/diagramscene/arrow.cpp 5 + + We then need to find the position at which to draw the + arrowhead. The head should be drawn where the line and the end + item intersects. This is done by taking the line between each + point in the polygon and check if it intersects with the line of + the arrow. Since the line start and end points are set to the + center of the items the arrow line should intersect one and only + one of the lines of the polygon. Note that the points in the + polygon are relative to the local coordinate system of the item. + We must therefore add the position of the end item to make the + coordinates relative to the scene. + + \snippet examples/graphicsview/diagramscene/arrow.cpp 6 + + We calculate the angle between the x-axis and the line of the + arrow. We need to turn the arrow head to this angle so that it + follows the direction of the arrow. If the angle is negative we + must turn the direction of the arrow. + + We can then calculate the three points of the arrow head polygon. + One of the points is the end of the line, which now is the + intersection between the arrow line and the end polygon. Then we + clear the \c arrowHead polygon from the previous calculated arrow + head and set these new points. + + \snippet examples/graphicsview/diagramscene/arrow.cpp 7 + + If the line is selected, we draw two dotted lines that are + parallel with the line of the arrow. We do not use the default + implementation, which uses \l{QGraphicsItem::}{boundingRect()} + because the QRect bounding rectangle is considerably larger than + the line. +*/ diff --git a/doc/src/examples/digitalclock.qdoc b/doc/src/examples/digitalclock.qdoc new file mode 100644 index 0000000000..027abc754a --- /dev/null +++ b/doc/src/examples/digitalclock.qdoc @@ -0,0 +1,74 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example widgets/digitalclock + \title Digital Clock Example + + The Digital Clock example shows how to use QLCDNumber to display a + number with LCD-like digits. + + \image digitalclock-example.png Screenshot of the Digital Clock example + + This example also demonstrates how QTimer can be used to update a widget + at regular intervals. + + \section1 DigitalClock Class Definition + + The \c DigitalClock class provides a clock widget showing the time with + hours and minutes separated by a blinking colon. We subclass QLCDNumber + and implement a private slot called \c showTime() to update the clock + display: + + \snippet examples/widgets/digitalclock/digitalclock.h 0 + + \section1 DigitalClock Class Implementation + + \snippet examples/widgets/digitalclock/digitalclock.cpp 0 + + In the constructor, we first change the look of the LCD numbers. The + QLCDNumber::Filled style produces raised segments filled with the + foreground color (typically black). We also set up a one-second timer + to keep track of the current time, and we connect + its \l{QTimer::timeout()}{timeout()} signal to the private \c showTime() slot + so that the display is updated every second. Then, we + call the \c showTime() slot; without this call, there would be a one-second + delay at startup before the time is shown. + + \snippet examples/widgets/digitalclock/digitalclock.cpp 1 + \snippet examples/widgets/digitalclock/digitalclock.cpp 2 + + The \c showTime() slot is called whenever the clock display needs + to be updated. + + The current time is converted into a string with the format "hh:mm". + When QTime::second() is a even number, the colon in the string is + replaced with a space. This makes the colon appear and vanish every + other second. + + Finally, we call QLCDNumber::display() to update the widget. +*/ diff --git a/doc/src/examples/dirview.qdoc b/doc/src/examples/dirview.qdoc new file mode 100644 index 0000000000..25e148bbbc --- /dev/null +++ b/doc/src/examples/dirview.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example itemviews/dirview + \title Dir View Example + + The Dir View example shows a tree view onto the local filing system. It uses the + QDirModel class to provide supply file and directory information. + + \image dirview-example.png +*/ diff --git a/doc/src/examples/dockwidgets.qdoc b/doc/src/examples/dockwidgets.qdoc new file mode 100644 index 0000000000..98c1216b6b --- /dev/null +++ b/doc/src/examples/dockwidgets.qdoc @@ -0,0 +1,163 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example mainwindows/dockwidgets + \title Dock Widgets Example + + The Dock Widgets example shows how to add dock windows to an + application. It also shows how to use Qt's rich text engine. + + \image dockwidgets-example.png Screenshot of the Dock Widgets example + + The application presents a simple business letter template, and has + a list of customer names and addresses and a list of standard + phrases in two dock windows. The user can click a customer to have + their name and address inserted into the template, and click one or + more of the standard phrases. Errors can be corrected by clicking + the Undo button. Once the letter has been prepared it can be printed + or saved as HTML. + + \section1 MainWindow Class Definition + + Here's the class definition: + + \snippet examples/mainwindows/dockwidgets/mainwindow.h 0 + + We will now review each function in turn. + + \section1 MainWindow Class Implementation + + \snippet examples/mainwindows/dockwidgets/mainwindow.cpp 0 + + We start by including \c <QtGui>, a header file that contains the + definition of all classes in the \l QtCore and \l QtGui + libraries. This saves us from having to include + every class individually and is especially convenient if we add new + widgets. We also include \c mainwindow.h. + + \snippet examples/mainwindows/dockwidgets/mainwindow.cpp 1 + + In the constructor, we start by creating a QTextEdit widget. Then we call + QMainWindow::setCentralWidget(). This function passes ownership of + the QTextEdit to the \c MainWindow and tells the \c MainWindow that + the QTextEdit will occupy the \c MainWindow's central area. + + Then we call \c createActions(), \c createMenus(), \c + createToolBars(), \c createStatusBar(), and \c createDockWindows() + to set up the user interface. Finally we call \c setWindowTitle() to + give the application a title, and \c newLetter() to create a new + letter template. + + We won't quote the \c createActions(), \c createMenus(), \c + createToolBars(), and \c createStatusBar() functions since they + follow the same pattern as all the other Qt examples. + + \snippet examples/mainwindows/dockwidgets/mainwindow.cpp 9 + + We create the customers dock window first, and in addition to a + window title, we also pass it a \c this pointer so that it becomes a + child of \c MainWindow. Normally we don't have to pass a parent + because widgets are parented automatically when they are laid out: + but dock windows aren't laid out using layouts. + + We've chosen to restrict the customers dock window to the left and + right dock areas. (So the user cannot drag the dock window to the + top or bottom dock areas.) The user can drag the dock window out of + the dock areas entirely so that it becomes a free floating window. + We can change this (and whether the dock window is moveable or + closable) using QDockWidget::setFeatures(). + + Once we've created the dock window we create a list widget with the + dock window as parent, then we populate the list and make it the + dock window's widget. Finally we add the dock widget to the \c + MainWindow using \c addDockWidget(), choosing to put it in the right + dock area. + + We undertake a similar process for the paragraphs dock window, + except that we don't restrict which dock areas it can be dragged to. + + Finally we set up the signal-slot connections. If the user clicks a + customer or a paragraph their \c currentTextChanged() signal will be + emitted and we connect these to \c insertCustomer() and + addParagraph() passing the text that was clicked. + + We briefly discuss the rest of the implementation, but have now + covered everything relating to dock windows. + + \snippet examples/mainwindows/dockwidgets/mainwindow.cpp 2 + + In this function we clear the QTextEdit so that it is empty. Next we + create a QTextCursor on the QTextEdit. We move the cursor to the + start of the document and create and format a frame. We then create + some character formats and a table format. We insert a table into + the document and insert the company's name and address into a table + using the table and character formats we created earlier. Then we + insert the skeleton of the letter including two markers \c NAME and + \c ADDRESS. We will also use the \c{Yours sincerely,} text as a marker. + + \snippet examples/mainwindows/dockwidgets/mainwindow.cpp 6 + + If the user clicks a customer we split the customer details into + pieces. We then look for the \c NAME marker using the \c find() + function. This function selects the text it finds, so when we call + \c insertText() with the customer's name the name replaces the marker. + We then look for the \c ADDRESS marker and replace it with each line + of the customer's address. Notice that we wrapped all the insertions + between a \c beginEditBlock() and \c endEditBlock() pair. This means + that the entire name and address insertion is treated as a single + operation by the QTextEdit, so a single undo will revert all the + insertions. + + \snippet examples/mainwindows/dockwidgets/mainwindow.cpp 7 + + This function works in a similar way to \c insertCustomer(). First + we look for the marker, in this case, \c {Yours sincerely,}, and then + replace it with the standard paragraph that the user clicked. Again + we use a \c beginEditBlock() ... \c endEditBlock() pair so that the + insertion can be undone as a single operation. + + \snippet examples/mainwindows/dockwidgets/mainwindow.cpp 3 + + Qt's QTextDocument class makes printing documents easy. We simply + take the QTextEdit's QTextDocument, set up the printer and print the + document. + + \snippet examples/mainwindows/dockwidgets/mainwindow.cpp 4 + + QTextEdit can output its contents in HTML format, so we prompt the + user for the name of an HTML file and if they provide one we simply + write the QTextEdit's contents in HTML format to the file. + + \snippet examples/mainwindows/dockwidgets/mainwindow.cpp 5 + + If the focus is in the QTextEdit, pressing \key Ctrl+Z undoes as + expected. But for the user's convenience we provide an + application-wide undo function that simply calls the QTextEdit's + undo: this means that the user can undo regardless of where the + focus is in the application. +*/ diff --git a/doc/src/examples/dombookmarks.qdoc b/doc/src/examples/dombookmarks.qdoc new file mode 100644 index 0000000000..78e63fe48d --- /dev/null +++ b/doc/src/examples/dombookmarks.qdoc @@ -0,0 +1,40 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example xml/dombookmarks + \title DOM Bookmarks Example + + The DOM Bookmarks example provides a reader for XML Bookmark Exchange Language (XBEL) + files that uses Qt's DOM-based XML API to read and parse the files. The SAX Bookmarks + example provides an alternative way to read this type of file. + + \image dombookmarks-example.png + + See the \l{http://pyxml.sourceforge.net/topics/xbel/}{XML Bookmark Exchange Language + Resource Page} for more information about XBEL files. +*/ diff --git a/doc/src/examples/dragdroprobot.qdoc b/doc/src/examples/dragdroprobot.qdoc new file mode 100644 index 0000000000..bcf0fe7a82 --- /dev/null +++ b/doc/src/examples/dragdroprobot.qdoc @@ -0,0 +1,365 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example graphicsview/dragdroprobot + \title Drag and Drop Robot Example + + This GraphicsView example shows how to implement Drag and Drop in a + QGraphicsItem subclass, as well as how to animate items using Qt's + \l{Animation Framework}. + + \image dragdroprobot-example.png + + Graphics View provides the QGraphicsScene class for managing and + interacting with a large number of custom-made 2D graphical items derived + from the QGraphicsItem class, and a QGraphicsView widget for visualizing + the items, with support for zooming and rotation. + + This example consists of a \c Robot class, a \c ColorItem class, and a main + function: the \c Robot class describes a simple robot consisting of several + \c RobotPart derived limbs, including \c RobotHead and \c RobotLimb, the \c + ColorItem class provides a draggable colored ellipse, and the \c main() + function provides the main application window. + + We will first review the \c Robot class to see how to assemble the + different parts so that they can be individually rotated and animated using + QPropertyAnimation, and we will then review the \c ColorItem class to + demonstrate how to implement Drag and Drop between items. Finally we will + review the main() function to see how we can put all the pieces together, + to form the final application. + + \section1 Robot Class Definition + + The robot consists of three main classes: the \c RobotHead, the \c + RobotTorso, and the \c RobotLimb, which is used for the upper and lower + arms and legs. All parts derive from the \c RobotPart class, which in turn + inherits \c QGraphicsObject. The \c Robot class itself has no visual + appearance and serves only as a root node for the robot. + + Let's start with the \c RobotPart class declaration. + + \snippet examples/graphicsview/dragdroprobot/robot.h 0 + + This base class inherits QGraphicsObject. QGraphicsObject provides signals + and slots through inheriting QObject, and it also declares QGraphicsItem's + properties using Q_PROPERTY, which makes the properties accessible for + QPropertyAnimation. + + RobotPart also implements the three most important event handlers for + accepting drop events: + \l{QGraphicsItem::dragEnterEvent()}{dragEnterEvent()}, + \l{QGraphicsItem::dragLeaveEvent()}{dragLeaveEvent()}, and + \l{QGraphicsItem::dropEvent()}{dropEvent()}. + + The color is stored as a member variable, along with the \c dragOver + variable, which we will use later to indicate visually that the limb can + accept colors that are is dragged onto it. + + \snippet examples/graphicsview/dragdroprobot/robot.cpp 0 + + \c RobotPart's constructor initializes the dragOver member and sets the + color to Qt::lightGray. In the constructor body we enable support for + accepting drop events by calling + \l{QGraphicsItem::setAcceptDrops()}{setAcceptDrops(true)}. + + The rest of this class's implementation is to support Drag and Drop. + + \snippet examples/graphicsview/dragdroprobot/robot.cpp 1 + + The \l{QGraphicsItem::dragEnterEvent()}{dragEnterEvent()} handler is called + when a Drag and Drop element is dragged into the robot part's area. + + The handler implementation determines whether or not this item as a whole + can accept the mime data assiciated with the incoming drag object. \c + RobotPart provides a base behavior for all parts that accepts color drops. + So if the incoming drag object contains a color, the event is accepted, we + set \c dragOver to \c true and call update() to help provide positive + visual feedback to the user; otherwise the event is ignored, which in turn + allows the event to propagate to parent elements. + + \snippet examples/graphicsview/dragdroprobot/robot.cpp 2 + + The \l{QGraphicsItem::dragLeaveEvent()}{dragLeaveEvent()} handler is called + when a Drag and Drop element is dragged away from the robot part's area. + Our implementation simply resets \e dragOver to false and calls + \l{QGraphicsItem::update()}{update()} to help provide visual feedback that + the drag has left this item. + + \snippet examples/graphicsview/dragdroprobot/robot.cpp 3 + + The \l{QGraphicsItem::dropEvent()}{dropEvent()} handler is called when a + Drag and Drop element is dropped onto an item (i.e., when the mouse button + is released over the item while dragging). + + We reset \c dragOver to false, assign the item's new color, and call + \l{QGraphicsItem::update()}{update()}. + + The declaration and implementation of \c RobotHead, \c RobotTorso, and \c + RobotLimb are practically identical. We will review \c RobotHead in detail, + as this class has one minor difference, and leave the other classes as an + exercise for the reader. + + \snippet examples/graphicsview/dragdroprobot/robot.h 1 + + The \c RobotHead class inherits \c RobotPart and provides the necessary + implementations of \l{QGraphicsItem::boundingRect()}{boundingRect()} and + \l{QGraphicsItem::paint()}{paint()}. It also reimplements + \l{QGraphicsItem::dragEnterEvent()}{dragEnterEvent()} and dropEvent() to + provide special handling of image drops. + + The class contains a private pixmap member that we can use to implement + support for accepting image drops. + + \snippet examples/graphicsview/dragdroprobot/robot.cpp 4 + + \c RobotHead has a rather plain constructor that simply forwards to + \c RobotPart's constructor. + + \snippet examples/graphicsview/dragdroprobot/robot.cpp 5 + + The \l{QGraphicsItem::boundingRect()}{boundingRect()} reimplementation + returns the extents for the head. Because we want the center of rotation to + be the bottom center of the item, we have chosen a bounding rectangle that + starts at (-15, -50) and extends to 30 units wide and 50 units tall. When + rotating the head, the "neck" will stay still while the top of the head + tilts from side to side. + + \snippet examples/graphicsview/dragdroprobot/robot.cpp 6 + + In \l{QGraphicsItem::paint()}{paint()} we draw the actual head. The + implementation is split into two sections; if an image has been dropped + onto the head, we draw the image, otherwise we draw a round rectangular + robot head with simple vector graphics. + + For performance reasons, depending on the complexity of what is painted, it + can often be faster to draw the head as an image rather than using a + sequence of vector operations. + + \snippet examples/graphicsview/dragdroprobot/robot.cpp 7 + + The robot head can accept image drops. In order to support this, its + reimplementation of \l{QGraphicsItem::dragEnterEvent()}{dragEnterEvent()} + checks if the drag object contains image data, and if it does, then the + event is accepted. Otherwise we fall back to the base \c RobotPart + implementation. + + \snippet examples/graphicsview/dragdroprobot/robot.cpp 8 + + To follow up on image support, we must also implement + \l{QGraphicsItem::dropEvent()}{dropEvent()}. We check if the drag object + contains image data, and if it does, we store this data as a member pixmap + and call \l{QGraphicsItem::update()}{update()}. This pixmap is used inside + the \l{QGraphicsItem::paint()}{paint()} implementation that we reviewed + before. + + \c RobotTorso and \c RobotLimb are similar to \c RobotHead, so let's + skip directly to the \c Robot class. + + \snippet examples/graphicsview/dragdroprobot/robot.h 4 + + The \c Robot class also inherits \c RobotPart, and like the other parts it + also implements \l{QGraphicsItem::boundingRect()}{boundingRect()} and + \l{QGraphicsItem::paint()}{paint()}. It provides a rather special + implementation, though: + + \snippet examples/graphicsview/dragdroprobot/robot.cpp 9 + + Because the \c Robot class is only used as a base node for the rest of the + robot, it has no visual representation. Its + \l{QGraphicsItem::boundingRect()}{boundingRect()} implementation can + therefore return a null QRectF, and its paint() function does nothing. + + \snippet examples/graphicsview/dragdroprobot/robot.cpp 10 + + The constuctor starts by setting the flag + \l{QGraphicsItem::ItemHasNoContents}{ItemHasNoContents}, which is a minor + optimization for items that have no visual appearance. + + We then construct all the robot parts (head, torso, and upper/lower arms + and legs). The stacking order is very important, and we use the + parent-child hierarchy to ensure the elements rotate and move properly. We + construct the torso first, as this is the root element. We then construct + the head and pass the torso to \c HeadItem's constructor. This will make + the head a child of the torso; if you rotate the torso, the head will + follow. The same pattern is applied to the rest of the limbs. + + \snippet examples/graphicsview/dragdroprobot/robot.cpp 11 + + Each robot part is carefully positioned. For example, the upper left arm is + moved precisely to the top-left area of the torso, and the upper right arm + is moved to the top-right area. + + \snippet examples/graphicsview/dragdroprobot/robot.cpp 12 + + The next section creates all animation objects. This snippet shows the two + animations that operate on the head's scale and rotation. The two + QPropertyAnimation instances simply set the object, property, and + respective start and end values. + + All animations are controlled by one top-level parallel animation group. + The scale and rotation animations are added to this group. + + The rest of the animations are defined in a similar way. + + \snippet examples/graphicsview/dragdroprobot/robot.cpp 13 + + Finally we set an easing curve and duration on each animation, ensure the + toplevel animation group loops forever, and start the toplevel animation. + + \section1 ColorItem Class Definition + + The \c ColorItem class represents a circular item that can be pressed to + drag colors onto robot parts. + + \snippet examples/graphicsview/dragdroprobot/coloritem.h 0 + + This class is very simple. It does not use animations, and has no need for + properties nor signals and slots, so to save resources, it's most natural + that it inherits QGraphicsItem (as opposed to QGraphicsObject). + + It declares the mandatory \l{QGraphicsItem::boundingRect()}{boundingRect()} + and \l{QGraphicsItem::paint()}{paint()} functions, and adds + reimplementations of + \l{QGraphicsItem::mousePressEvent()}{mousePressEvent()}, + \l{QGraphicsItem::mouseMoveEvent()}{mouseMoveEvent()}, and + \l{QGraphicsItem::mouseReleaseEvent()}{mouseReleaseEvent()}. It contains a + single private color member. + + Let's take a look at its implementation. + + \snippet examples/graphicsview/dragdroprobot/coloritem.cpp 0 + + \c ColorItem's constructor assigns an opaque random color to its color + member by making use of qrand(). For improved usability, it assigns a + tooltip that provides a useful hint to the user, and it also sets a + suitable cursor. This ensures that the cursor will chance to + Qt::OpenHandCursor when the mouse pointer hovers over the item. + + Finally, we call + \l{QGraphicsItem::setAcceptedMouseButtons()}{setAcceptedMouseButtons()} to + ensure that this item can only process Qt::LeftButton. This simplifies the + mouse event handlers greatly, as we can always assume that only the left + mouse button is pressed and released. + + \snippet examples/graphicsview/dragdroprobot/coloritem.cpp 1 + + The item's bounding rect is a fixed 30x30 units centered around the item's + origin (0, 0), and adjusted by 0.5 units in all directions to allow a + scalable pen to draw its outline. For a final visual touch the bounds + also compensate with a few units down and to the right to make room + for a simple dropshadow. + + \snippet examples/graphicsview/dragdroprobot/coloritem.cpp 2 + + The \l{QGraphicsItem::paint()}{paint()} implementation draws an ellipse + with a 1-unit black outline, a plain color fill, and a dark gray + dropshadow. + + \snippet examples/graphicsview/dragdroprobot/coloritem.cpp 3 + + The \l{QGraphicsItem::mousePressEvent()}{mousePressEvent()} handler is + called when you press the mouse button inside the item's area. Our + implementation simply sets the cursor to Qt::ClosedHandCursor. + + \snippet examples/graphicsview/dragdroprobot/coloritem.cpp 4 + + The \l{QGraphicsItem::mouseReleaseEvent()}{mouseReleaseEvent()} handler is + called when you release the mouse button after having pressed it inside an + item's area. Our implementation sets the cursor back to Qt::OpenHandCursor. + The mouse press and release event handlers together provide useful visual + feedback to the user: when you move the mouse pointer over a \c CircleItem, + the cursor changes to an open hand. Pressing the item will show a closed + hand cursor. Releasing will restore to an open hand cursor again. + + \snippet examples/graphicsview/dragdroprobot/coloritem.cpp 5 + + The \l{QGraphicsItem::mouseMoveEvent()}{mouseMoveEvent()} handler is called + when you move the mouse around after pressing the mouse button inside the + \c ColorItem's area. This implementation provides the most important piece + of logic for \c CircleItem: the code that starts and manages drags. + + The implementation starts by checking if the mouse has been dragged far + enough to eliminate mouse jitter noise. We only want to start a drag if the + mouse has been dragged farther than the application start drag distance. + + Continuing, we create a QDrag object, passing the event + \l{QGraphicsSceneEvent::widget()}{widget} (i.e., the QGraphicsView + viewport) to its constructor. Qt will ensure that this object is deleted at + the right time. We also create a QMimeData instance that can contain our + color or image data, and assign this to the drag object. + + \snippet examples/graphicsview/dragdroprobot/coloritem.cpp 6 + + This snippet has a somewhat random outcome: once in a while, a special + image is assigned to the drag object's mime data. The pixmap is also + assiged as the drag object's pixmap. This will ensure that you can see the + image that is being dragged as a pixmap under the mouse cursor. + + \snippet examples/graphicsview/dragdroprobot/coloritem.cpp 7 + + Otherwise, and this is the most common outcome, a simple color is assigned + to the drag object's mime data. We render this \c ColorItem into a new + pixmap to give the user visual feedback that the color is being "dragged". + + \snippet examples/graphicsview/dragdroprobot/coloritem.cpp 8 + + Finally we execute the drag. QDrag::exec() will reenter the event loop, and + only exit if the drag has either been dropped, or canceled. In any case we + reset the cursor to Qt::OpenHandCursor. + + \section1 The main() Function + + Now that the \c Robot and \c ColorItem classes are complete, we can put all + the pieces together inside the main() function. + + \snippet examples/graphicsview/dragdroprobot/main.cpp 0 + + We start off by constructing QApplication, and initializing the random + number generator. This ensures that the color items have different colors + every time the application starts. + + \snippet examples/graphicsview/dragdroprobot/main.cpp 1 + + We construct a fixed size scene, and create 10 \c ColorItem instances + arranged in a circle. Each item is added to the scene. + + In the center of this circle we create one \c Robot instance. The + robot is scaled and moved up a few units. It is then added to the scene. + + \snippet examples/graphicsview/dragdroprobot/main.cpp 2 + + Finally we create a QGraphicsView window, and assign the scene to it. + + For increased visual quality, we enable antialiasing. We also choose to use + bounding rectangle updates to simplify visual update handling. + The view is given a fixed sand-colored background, and a window title. + + We then show the view. The animations start immediately after + control enters the event loop. +*/ + diff --git a/doc/src/examples/draggableicons.qdoc b/doc/src/examples/draggableicons.qdoc new file mode 100644 index 0000000000..e940d422cd --- /dev/null +++ b/doc/src/examples/draggableicons.qdoc @@ -0,0 +1,90 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example draganddrop/draggableicons + \title Draggable Icons Example + + The Draggable Icons example shows how to drag and drop image data between widgets + in the same application, and between different applications. + + \image draggableicons-example.png + + In many situations where drag and drop is used, the user starts dragging from + a particular widget and drops the payload onto another widget. In this example, + we subclass QLabel to create labels that we use as drag sources, and place them + inside \l{QWidget}s that serve as both containers and drop sites. + + In addition, when a drag and drop operation occurs, we want to send more than + just an image. We also want to send information about where the user clicked in + the image so that the user can place it precisely on the drop target. This level + of detail means that we must create a custom MIME type for our data. + + \section1 DragWidget Class Definition + + The icon widgets that we use to display icons are subclassed from QLabel: + + \snippet examples/draganddrop/draggableicons/dragwidget.h 0 + + Since the QLabel class provides most of what we require for the icon, we + only need to reimplement the \l QWidget::mousePressEvent() to provide + drag and drop facilities. + + \section1 DragWidget Class Implementation + + The \c DragWidget constructor sets an attribute on the widget that ensures + that it will be deleted when it is closed: + + \snippet examples/draganddrop/draggableicons/dragwidget.cpp 0 + + To enable dragging from the icon, we need to act on a mouse press event. + We do this by reimplementing \l QWidget::mousePressEvent() and setting up + a QDrag object. + + \snippet examples/draganddrop/draggableicons/dragwidget.cpp 1 + + Since we will be sending pixmap data for the icon and information about the + user's click in the icon widget, we construct a QByteArray and package up the + details using a QDataStream. + + For interoperability, drag and drop operations describe the data they contain + using MIME types. In Qt, we describe this data using a QMimeData object: + + \snippet examples/draganddrop/draggableicons/dragwidget.cpp 2 + + We choose an unofficial MIME type for this purpose, and supply the QByteArray + to the MIME data object. + + The drag and drop operation itself is handled by a QDrag object: + + \snippet examples/draganddrop/draggableicons/dragwidget.cpp 3 + + Here, we pass the data to the drag object, set a pixmap that will be shown + alongside the cursor during the operation, and define the position of a hot + spot that places the position of this pixmap under the cursor. + +*/ diff --git a/doc/src/examples/draggabletext.qdoc b/doc/src/examples/draggabletext.qdoc new file mode 100644 index 0000000000..d4ea3859ab --- /dev/null +++ b/doc/src/examples/draggabletext.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example draganddrop/draggabletext + \title Draggable Text Example + + The Draggable Text example shows how to drag and drop textual data between widgets + in the same application, and between different applications. + + \image draggabletext-example.png +*/ diff --git a/doc/src/examples/drilldown.qdoc b/doc/src/examples/drilldown.qdoc new file mode 100644 index 0000000000..8739270945 --- /dev/null +++ b/doc/src/examples/drilldown.qdoc @@ -0,0 +1,536 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example sql/drilldown + \title Drill Down Example + + The Drill Down example shows how to read data from a database as + well as submit changes, using the QSqlRelationalTableModel and + QDataWidgetMapper classes. + + \image drilldown-example.png Screenshot of the Drill Down Example + + When running the example application, a user can retrieve + information about each of Nokia's Qt offices by clicking the + corresponding image. The application pops up an information window + displaying the data, and allows the users to alter the location + description as well as the image. The main view will be updated + when the users submit their changes. + + The example consists of three classes: + + \list + \o \c ImageItem is a custom graphics item class used to + display the office images. + + \o \c View is the main application widget allowing the user to + browse through the various locations. + + \o \c InformationWindow displays the requested information, + allowing the users to alter it and submit their changes to the + database. + \endlist + + We will first take a look at the \c InformationWindow class to see + how you can read and modify data from a database. Then we will + review the main application widget, i.e., the \c View class, and + the associated \c ImageItem class. + + \section1 InformationWindow Class Definition + + The \c InformationWindow class is a custom widget inheriting + QWidget: + + \snippet examples/sql/drilldown/informationwindow.h 0 + + When we create an information window, we pass the associated + location ID, a parent, and a pointer to the database, to the + constructor. We will use the database pointer to populate our + window with data, while passing the parent parameter on to the + base class. The ID is stored for future reference. + + Once a window is created, we will use the public \c id() function + to locate it whenever information for the given location is + requested. We will also use the ID to update the main application + widget when the users submit their changes to the database, i.e., + we will emit a signal carrying the ID and file name as parameters + whenever the users changes the associated image. + + \snippet examples/sql/drilldown/informationwindow.h 1 + + Since we allow the users to alter some of the location data, we + must provide functionality for reverting and submitting their + changes. The \c enableButtons() slot is provided for convenience + to enable and disable the various buttons when required. + + \snippet examples/sql/drilldown/informationwindow.h 2 + + The \c createButtons() function is also a convenience function, + provided to simplify the constructor. As mentioned above we store + the location ID for future reference. We also store the name of + the currently displayed image file to be able to determine when to + emit the \c imageChanged() signal. + + The information window uses the QLabel class to display the office + location and the country. The associated image file is displayed + using a QComboBox instance while the description is displayed using + QTextEdit. In addition, the window has three buttons to control + the data flow and whether the window is shown or not. + + Finally, we declare a \e mapper. The QDataWidgetMapper class + provides mapping between a section of a data model to widgets. We + will use the mapper to extract data from the given database, + updating the database whenever the user modifies the data. + + \section1 InformationWindow Class Implementation + + The constructor takes three arguments: a location ID, a database + pointer and a parent widget. The database pointer is actually a + pointer to a QSqlRelationalTableModel object providing an editable + data model (with foreign key support) for our database table. + + \snippet examples/sql/drilldown/informationwindow.cpp 0 + \snippet examples/sql/drilldown/informationwindow.cpp 1 + + First we create the various widgets required to display the data + contained in the database. Most of the widgets are created in a + straight forward manner. But note the combobox displaying the + name of the image file: + + \snippet examples/sql/drilldown/informationwindow.cpp 2 + + In this example, the information about the offices are stored in a + database table called "offices". When creating the model, + we will use a foreign key to establish a relation between this + table and a second data base table, "images", containing the names + of the available image files. We will get back to how this is done + when reviewing the \c View class. The rationale for creating such + a relation though, is that we want to ensure that the user only + can choose between predefined image files. + + The model corresponding to the "images" database table, is + available through the QSqlRelationalTableModel's \l + {QSqlRelationalTableModel::}{relationModel()} function, requiring + the foreign key (in this case the "imagefile" column number) as + argument. We use QComboBox's \l {QComboBox::}{setModel()} function + to make the combobox use the "images" model. And, since this model + has two columns ("locationid" and "file"), we also specify which + column we want to be visible using the QComboBox::setModelColumn() + function. + + \snippet examples/sql/drilldown/informationwindow.cpp 3 + + Then we create the mapper. The QDataWidgetMapper class allows us + to create data-aware widgets by mapping them to sections of an + item model. + + The \l {QDataWidgetMapper::}{addMapping()} function adds a mapping + between the given widget and the specified section of the + model. If the mapper's orientation is horizontal (the default) the + section is a column in the model, otherwise it is a row. We call + the \l {QDataWidgetMapper::}{setCurrentIndex()} function to + initialize the widgets with the data associated with the given + location ID. Every time the current index changes, all the widgets + are updated with the contents from the model. + + We also set the mapper's submit policy to + QDataWidgetMapper::ManualSubmit. This means that no data is + submitted to the database until the user expliclity requests a + submit (the alternative is QDataWidgetMapper::AutoSubmit, + automatically submitting changes when the corresponding widget + looses focus). Finally, we specify the item delegate the mapper + view should use for its items. The QSqlRelationalDelegate class + represents a delegate that unlike the default delegate, enables + combobox functionality for fields that are foreign keys into other + tables (like "imagefile" in our "trolltechoffices" table). + + \snippet examples/sql/drilldown/informationwindow.cpp 4 + + Finally, we connect the "something's changed" signals in the + editors to our custom \c enableButtons() slot, enabling the users + to either submit or revert their changes. We add all the widgets + into a layout, store the location ID and the name of the displayed + image file for future reference, and set the window title and + initial size. + + Note that we also set the Qt::Window window flag to indicate that + our widget is in fact a window, with a window system frame and a + title bar. + + \snippet examples/sql/drilldown/informationwindow.cpp 5 + + When a window is created, it is not deleted until the main + application exits (i.e., if the user closes the information + window, it is only hidden). For this reason we do not want to + create more than one \c InformationWindow object for each + location, and we provide the public \c id() function to be able to + determine whether a window already exists for a given location + when the user requests information about it. + + \snippet examples/sql/drilldown/informationwindow.cpp 6 + + The \c revert() slot is triggered whenever the user hits the \gui + Revert button. + + Since we set the QDataWidgetMapper::ManualSubmit submit policy, + none of the user's changes are written back to the model unless + the user expliclity choose to submit all of them. Nevertheless, we + can use the QDataWidgetMapper's \l {QDataWidgetMapper::}{revert()} + slot to reset the editor widgets, repopulating all widgets with + the current data of the model. + + \snippet examples/sql/drilldown/informationwindow.cpp 7 + + Likewise, the \c submit() slot is triggered whenever the users + decide to submit their changes by pressing the \gui Submit button. + + We use QDataWidgetMapper's \l {QDataWidgetMapper::}{submit()} slot + to submit all changes from the mapped widgets to the model, + i.e. to the database. For every mapped section, the item delegate + will then read the current value from the widget and set it in the + model. Finally, the \e model's \l {QAbstractItemModel::}{submit()} + function is invoked to let the model know that it should submit + whatever it has cached to the permanent storage. + + Note that before any data is submitted, we check if the user has + chosen another image file using the previously stored \c + displayedImage variable as reference. If the current and stored + file names differ, we store the new file name and emit the \c + imageChanged() signal. + + \snippet examples/sql/drilldown/informationwindow.cpp 8 + + The \c createButtons() function is provided for convenience, i.e., + to simplify the constructor. + + We make the \gui Close button the default button, i.e., the button + that is pressed when the user presses \gui Enter, and connect its + \l {QPushButton::}{clicked()} signal to the widget's \l + {QWidget::}{close()} slot. As mentioned above closing the window + only hides the widget; it is not deleted. We also connect the \gui + Submit and \gui Revert buttons to the corresponding \c submit() + and \c revert() slots. + + \snippet examples/sql/drilldown/informationwindow.cpp 9 + + The QDialogButtonBox class is a widget that presents buttons in a + layout that is appropriate to the current widget style. Dialogs + like our information window, typically present buttons in a layout + that conforms to the interface guidelines for that + platform. Invariably, different platforms have different layouts + for their dialogs. QDialogButtonBox allows us to add buttons, + automatically using the appropriate layout for the user's desktop + environment. + + Most buttons for a dialog follow certain roles. We give the \gui + Submit and \gui Revert buttons the \l + {QDialogButtonBox::ButtonRole}{reset} role, i.e., indicating that + pressing the button resets the fields to the default values (in + our case the information contained in the database). The \l + {QDialogButtonBox::ButtonRole}{reject} role indicates that + clicking the button causes the dialog to be rejected. On the other + hand, since we only hide the information window, any changes that + the user has made wil be preserved until the user expliclity + revert or submit them. + + \snippet examples/sql/drilldown/informationwindow.cpp 10 + + The \c enableButtons() slot is called to enable the buttons + whenever the user changes the presented data. Likewise, when the + data the user choose to submit the changes, the buttons are + disabled to indicate that the current data is stored in the + database. + + This completes the \c InformationWindow class. Let's take a look + at how we have used it in our example application. + + \section1 View Class Definition + + The \c View class represents the main application window and + inherits QGraphicsView: + + \snippet examples/sql/drilldown/view.h 0 + \codeline + \snippet examples/sql/drilldown/view.h 1 + + The QGraphicsView class is part of the \l {Graphics View + Framework} which we will use to display the images of Nokia's + Qt offices. To be able to respond to user interaction; + i.e., showing the + appropriate information window whenever the user clicks one of the + office images, we reimplement QGraphicsView's \l + {QGraphicsView::}{mouseReleaseEvent()} function. + + Note that the constructor expects the names of two database + tables: One containing the detailed information about the offices, + and another containing the names of the available image files. We + also provide a private \c updateImage() slot to catch \c + {InformationWindow}'s \c imageChanged() signal that is emitted + whenever the user changes a location's image. + + \snippet examples/sql/drilldown/view.h 2 + + The \c addItems() function is a convenience function provided to + simplify the constructor. It is called only once, creating the + various items and adding them to the view. + + The \c findWindow() function, on the other hand, is frequently + used. It is called from the \c showInformation() function to + detemine whether a window is already created for the given + location (whenever we create an \c InformationWindow object, we + store a reference to it in the \c informationWindows list). The + latter function is in turn called from our custom \c + mouseReleaseEvent() implementation. + + \snippet examples/sql/drilldown/view.h 3 + + Finally we declare a QSqlRelationalTableModel pointer. As + previously mentioned, the QSqlRelationalTableModel class provides + an editable data model with foreign key support. There are a + couple of things you should keep in mind when using the + QSqlRelationalTableModel class: The table must have a primary key + declared and this key cannot contain a relation to another table, + i.e., it cannot be a foreign key. Note also that if a relational + table contains keys that refer to non-existent rows in the + referenced table, the rows containing the invalid keys will not be + exposed through the model. It is the user's or the database's + responsibility to maintain referential integrity. + + \section1 View Class Implementation + + Although the constructor requests the names of both the table + containing office details as well as the table containing the + names of the available image files, we only have to create a + QSqlRelationalTableModel object for the office table: + + \snippet examples/sql/drilldown/view.cpp 0 + + The reason is that once we have a model with the office details, + we can create a relation to the available image files using + QSqlRelationalTableModel's \l + {QSqlRelationalTableModel::}{setRelation()} function. This + function creates a foreign key for the given model column. The key + is specified by the provided QSqlRelation object constructed by + the name of the table the key refers to, the field the key is + mapping to and the field that should be presented to the user. + + Note that setting the table only specifies which table the model + operates on, i.e., we must explicitly call the model's \l + {QSqlRelationalTableModel::}{select()} function to populate our + model. + + \snippet examples/sql/drilldown/view.cpp 1 + + Then we create the contents of our view, i.e., the scene and its + items. The location labels are regular QGraphicsTextItem objects, + and the "Qt" logo is represented by a QGraphicsPixmapItem + object. The images, on the other hand, are instances of the \c + ImageItem class (derived from QGraphicsPixmapItem). We will get + back to this shortly when reviewing the \c addItems() function. + + Finally, we set the main application widget's size constraints and + window title. + + \snippet examples/sql/drilldown/view.cpp 3 + + The \c addItems() function is called only once, i.e., when + creating the main application window. For each row in the database + table, we first extract the corresponding record using the model's + \l {QSqlRelationalTableModel::}{record()} function. The QSqlRecord + class encapsulates both the functionality and characteristics of a + database record, and supports adding and removing fields as well + as setting and retrieving field values. The QSqlRecord::value() + function returns the value of the field with the given name or + index as a QVariant object. + + For each record, we create a label item as well as an image item, + calculate their position and add them to the scene. The image + items are represented by instances of the \c ImageItem class. The + reason we must create a custom item class is that we want to catch + the item's hover events, animating the item when the mouse cursor + is hovering over the image (by default, no items accept hover + events). Please see the \l{Graphics View Framework} documentation + and the \l{Graphics View Examples} for more details. + + \snippet examples/sql/drilldown/view.cpp 5 + + We reimplement QGraphicsView's \l + {QGraphicsView::}{mouseReleaseEvent()} event handler to respond to + user interaction. If the user clicks any of the image items, this + function calls the private \c showInformation() function to pop up + the associated information window. + + The \l {Graphics View Framework} provides the qgraphicsitem_cast() + function to determine whether the given QGraphicsItem instance is + of a given type. Note that if the event is not related to any of + our image items, we pass it on to the base class implementation. + + \snippet examples/sql/drilldown/view.cpp 6 + + The \c showInformation() function is given an \c ImageItem object + as argument, and starts off by extracting the item's location + ID. Then it determines if there already is created an information + window for this location. If it is, and the window is visible, it + ensures that the window is raised to the top of the widget stack + and activated. If the window exists but is hidden, calling its \l + {QWidget::}{show()} slot gives the same result. + + If no window for the given location exists, we create one by + passing the location ID, a pointer to the model, and our view as a + parent, to the \c InformationWindow constructor. Note that we + connect the information window's \c imageChanged() signal to \e + this widget's \c updateImage() slot, before we give it a suitable + position and add it to the list of existing windows. + + \snippet examples/sql/drilldown/view.cpp 7 + + The \c updateImage() slot takes a location ID and the name of an + image files as arguments. It filters out the image items, and + updates the one that correspond to the given location ID, with the + provided image file. + + \snippet examples/sql/drilldown/view.cpp 8 + + The \c findWindow() function simply searches through the list of + existing windows, returning a pointer to the window that matches + the given location ID, or 0 if the window doesn't exists. + + Finally, let's take a quick look at our custom \c ImageItem class: + + \section1 ImageItem Class Definition + + The \c ImageItem class is provided to facilitate animation of the + image items. It inherits QGraphicsPixmapItem and reimplements its + hover event handlers: + + \snippet examples/sql/drilldown/imageitem.h 0 + + In addition, we implement a public \c id() function to be able to + identify the associated location and a public \c adjust() function + that can be called to ensure that the image item is given the + preferred size regardless of the original image file. + + The animation is implemented using the QTimeLine class together + with the event handlers and the private \c setFrame() slot: The + image item will expand when the mouse cursor hovers over it, + returning back to its orignal size when the cursor leaves its + borders. + + Finally, we store the location ID that this particular record is + associated with as well as a z-value. In the \l {Graphics View + Framework}, an item's z-value determines its position in the item + stack. An item of high z-value will be drawn on top of an item + with a lower z-value if they share the same parent item. We also + provide an \c updateItemPosition() function to refresh the view + when required. + + \section1 ImageItem Class Implementation + + The \c ImageItem class is really only a QGraphicsPixmapItem with + some additional features, i.e., we can pass most of the + constructor's arguments (the pixmap, parent and scene) on to the + base class constructor: + + \snippet examples/sql/drilldown/imageitem.cpp 0 + + Then we store the ID for future reference, and ensure that our + item will accept hover events. Hover events are delivered when + there is no current mouse grabber item. They are sent when the + mouse cursor enters an item, when it moves around inside the item, + and when the cursor leaves an item. As we mentioned earlier, none + of the \l {Graphics View Framework}'s items accept hover + event's by default. + + The QTimeLine class provides a timeline for controlling + animations. Its \l {QTimeLine::}{duration} property holds the + total duration of the timeline in milliseconds. By default, the + time line runs once from the beginning and towards the end. The + QTimeLine::setFrameRange() function sets the timeline's frame + counter; when the timeline is running, the \l + {QTimeLine::}{frameChanged()} signal is emitted each time the + frame changes. We set the duration and frame range for our + animation, and connect the time line's \l + {QTimeLine::}{frameChanged()} and \l {QTimeLine::}{finished()} + signals to our private \c setFrame() and \c updateItemPosition() + slots. + + Finally, we call \c adjust() to ensure that the item is given the + preferred size. + + \snippet examples/sql/drilldown/imageitem.cpp 1 + \codeline + \snippet examples/sql/drilldown/imageitem.cpp 2 + + Whenever the mouse cursor enters or leave the image item, the + corresponding event handlers are triggered: We first set the time + line's direction, making the item expand or shrink, + respectively. Then we alter the item's z-value if it is not already + set to the expected value. + + In the case of hover \e enter events, we immediately update the + item's position since we want the item to appear on top of all + other items as soon as it starts expanding. In the case of hover + \e leave events, on the other hand, we postpone the actual update + to achieve the same result. But remember that when we constructed + our item, we connected the time line's \l + {QTimeLine::}{finished()} signal to the \c updateItemPosition() + slot. In this way the item is given the correct position in the + item stack once the animation is completed. Finally, if the time + line is not already running, we start it. + + \snippet examples/sql/drilldown/imageitem.cpp 3 + + When the time line is running, it triggers the \c setFrame() slot + whenever the current frame changes due to the connection we + created in the item constructor. It is this slot that controls the + animation, expanding or shrinking the image item step by step. + + We first call the \c adjust() function to ensure that we start off + with the item's original size. Then we scale the item with a + factor depending on the animation's progress (using the \c frame + parameter). Note that by default, the transformation will be + relative to the item's top-left corner. Since we want the item to + be transformed relative to its center, we must translate the + coordinate system before we scale the item. + + In the end, only the following convenience functions remain: + + \snippet examples/sql/drilldown/imageitem.cpp 4 + \codeline + \snippet examples/sql/drilldown/imageitem.cpp 5 + \codeline + \snippet examples/sql/drilldown/imageitem.cpp 6 + + The \c adjust() function defines and applies a transformation + matrix, ensuring that our image item appears with the preferred + size regardless of the size of the source image. The \c id() + function is trivial, and is simply provided to be able to identify + the item. In the \c updateItemPosition() slot we call the + QGraphicsItem::setZValue() function, setting the elevation (i.e., + the position) of the item. +*/ diff --git a/doc/src/examples/dropsite.qdoc b/doc/src/examples/dropsite.qdoc new file mode 100644 index 0000000000..d8c17e1793 --- /dev/null +++ b/doc/src/examples/dropsite.qdoc @@ -0,0 +1,249 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example draganddrop/dropsite + \title Drop Site Example + + The example shows how to distinguish the various MIME formats available + in a drag and drop operation. + + \image dropsite-example.png Screenshot of the Drop Site example + + The Drop Site example accepts drops from other applications, and displays + the MIME formats provided by the drag object. + + There are two classes, \c DropArea and \c DropSiteWindow, and a \c main() + function in this example. A \c DropArea object is instantiated in + \c DropSiteWindow; a \c DropSiteWindow object is then invoked in the + \c main() function. + + \section1 DropArea Class Definition + + The \c DropArea class is a subclass of QLabel with a public slot, + \c clear(), and a \c changed() signal. + + \snippet draganddrop/dropsite/droparea.h DropArea header part1 + + In addition, \c DropArea also contains a private instance of QLabel and + reimplementations of four \l{QWidget} event handlers: + + \list 1 + \o \l{QWidget::dragEnterEvent()}{dragEnterEvent()} + \o \l{QWidget::dragMoveEvent()}{dragMoveEvent()} + \o \l{QWidget::dragLeaveEvent()}{dragLeaveEvent()} + \o \l{QWidget::dropEvent()}{dropEvent()} + \endlist + + These event handlers are further explained in the implementation of the + \c DropArea class. + + \snippet draganddrop/dropsite/droparea.h DropArea header part2 + + \section1 DropArea Class Implementation + + In the \c DropArea constructor, we set the \l{QWidget::setMinimumSize()} + {minimum size} to 200x200 pixels, the \l{QFrame::setFrameStyle()} + {frame style} to both QFrame::Sunken and QFrame::StyledPanel, and we align + its contents to the center. + + \snippet draganddrop/dropsite/droparea.cpp DropArea constructor + + Also, we enable drop events in \c DropArea by setting the + \l{QWidget::acceptDrops()}{acceptDrops} property to \c true. Then, + we enable the \l{QWidget::autoFillBackground()}{autoFillBackground} + property and invoke the \c clear() function. + + The \l{QWidget::dragEnterEvent()}{dragEnterEvent()} event handler is + called when a drag is in progress and the mouse enters the \c DropArea + object. For the \c DropSite example, when the mouse enters \c DropArea, + we set its text to "<drop content>" and highlight its background. + + \snippet draganddrop/dropsite/droparea.cpp dragEnterEvent() function + + Then, we invoke \l{QDropEvent::acceptProposedAction()} + {acceptProposedAction()} on \a event, setting the drop action to the one + proposed. Lastly, we emit the \c changed() signal, with the data that was + dropped and its MIME type information as a parameter. + + For \l{QWidget::dragMoveEvent()}{dragMoveEvent()}, we just accept the + proposed QDragMoveEvent object, \a event, with + \l{QDropEvent::acceptProposedAction()}{acceptProposedAction()}. + + \snippet draganddrop/dropsite/droparea.cpp dragMoveEvent() function + + The \c DropArea class's implementation of \l{QWidget::dropEvent()} + {dropEvent()} extracts the \a{event}'s mime data and displays it + accordingly. + + \snippet draganddrop/dropsite/droparea.cpp dropEvent() function part1 + + The \c mimeData object can contain one of the following objects: an image, + HTML text, plain text, or a list of URLs. + + \snippet draganddrop/dropsite/droparea.cpp dropEvent() function part2 + + \list + \o If \c mimeData contains an image, we display it in \c DropArea with + \l{QLabel::setPixmap()}{setPixmap()}. + \o If \c mimeData contains HTML, we display it with + \l{QLabel::setText()}{setText()} and set \c{DropArea}'s text format + as Qt::RichText. + \o If \c mimeData contains plain text, we display it with + \l{QLabel::setText()}{setText()} and set \c{DropArea}'s text format + as Qt::PlainText. In the event that \c mimeData contains URLs, we + iterate through the list of URLs to display them on individual + lines. + \o If \c mimeData contains other types of objects, we set + \c{DropArea}'s text, with \l{QLabel::setText()}{setText()} to + "Cannot display data" to inform the user. + \endlist + + We then set \c{DropArea}'s \l{QWidget::backgroundRole()}{backgroundRole} to + QPalette::Dark and we accept \c{event}'s proposed action. + + \snippet draganddrop/dropsite/droparea.cpp dropEvent() function part3 + + The \l{QWidget::dragLeaveEvent()}{dragLeaveEvent()} event handler is + called when a drag is in progress and the mouse leaves the widget. + + \snippet draganddrop/dropsite/droparea.cpp dragLeaveEvent() function + + For \c{DropArea}'s implementation, we clear invoke \c clear() and then + accept the proposed event. + + The \c clear() function sets the text in \c DropArea to "<drop content>" + and sets the \l{QWidget::backgroundRole()}{backgroundRole} to + QPalette::Dark. Lastly, it emits the \c changed() signal. + + \snippet draganddrop/dropsite/droparea.cpp clear() function + + \section1 DropSiteWindow Class Definition + + The \c DropSiteWindow class contains a constructor and a public slot, + \c updateFormatsTable(). + + \snippet draganddrop/dropsite/dropsitewindow.h DropSiteWindow header + + The class also contains a private instance of \c DropArea, \c dropArea, + QLabel, \c abstractLabel, QTableWidget, \c formatsTable, QDialogButtonBox, + \c buttonBox, and two QPushButton objects, \c clearButton and + \c quitButton. + + \section1 DropSiteWindow Class Implementation + + In the constructor of \c DropSiteWindow, we instantiate \c abstractLabel + and set its \l{QLabel::setWordWrap()}{wordWrap} property to \c true. We + also call the \l{QLabel::adjustSize()}{adjustSize()} function to adjust + \c{abstractLabel}'s size according to its contents. + + \snippet draganddrop/dropsite/dropsitewindow.cpp constructor part1 + + Then we instantiate \c dropArea and connect its \c changed() signal to + \c{DropSiteWindow}'s \c updateFormatsTable() slot. + + \snippet draganddrop/dropsite/dropsitewindow.cpp constructor part2 + + We now set up the QTableWidget object, \c formatsTable. Its + horizontal header is set using a QStringList object, \c labels. The number + of columms are set to two and the table is not editable. Also, the + \c{formatTable}'s horizontal header is formatted to ensure that its second + column stretches to occupy additional space available. + + \snippet draganddrop/dropsite/dropsitewindow.cpp constructor part3 + + Two QPushButton objects, \c clearButton and \c quitButton, are instantiated + and added to \c buttonBox - a QDialogButtonBox object. We use + QDialogButtonBox here to ensure that the push buttons are presented in a + layout that conforms to the platform's style. + + \snippet draganddrop/dropsite/dropsitewindow.cpp constructor part4 + + The \l{QPushButton::clicked()}{clicked()} signals for \c quitButton and + \c clearButton are connected to \l{QWidget::close()}{close()} and + \c clear(), respectively. + + For the layout, we use a QVBoxLayout, \c mainLayout, to arrange our widgets + vertically. We also set the window title to "Drop Site" and the minimum + size to 350x500 pixels. + + \snippet draganddrop/dropsite/dropsitewindow.cpp constructor part5 + + We move on to the \c updateFormatsTable() function. This function updates + the \c formatsTable, displaying the MIME formats of the object dropped onto + the \c DropArea object. First, we set \l{QTableWidget}'s + \l{QTableWidget::setRowCount()}{rowCount} property to 0. Then, we validate + to ensure that the QMimeData object passed in is a valid object. + + \snippet draganddrop/dropsite/dropsitewindow.cpp updateFormatsTable() part1 + + Once we are sure that \c mimeData is valid, we iterate through its + supported formats using the \l{The foreach Keyword}{foreach keyword}. + This keyword has the following format: + + \snippet doc/src/snippets/code/doc_src_examples_dropsite.qdoc 0 + + In our example, \c format is the \a variable and the \a container is a + QStringList, obtained from \c mimeData->formats(). + + \note The \l{QMimeData::formats()}{formats()} function returns a + QStringList object, containing all the formats supported by the + \c mimeData. + + \snippet draganddrop/dropsite/dropsitewindow.cpp updateFormatsTable() part2 + + Within each iteration, we create a QTableWidgetItem, \c formatItem and we + set its \l{QTableWidgetItem::setFlags()}{flags} to Qt::ItemIsEnabled, and + its \l{QTableWidgetItem::setTextAlignment()}{text alignment} to Qt::AlignTop + and Qt::AlignLeft. + + A QString object, \c text, is customized to display data according to the + contents of \c format. We invoke {QString}'s \l{QString::simplified()} + {simplified()} function on \c text, to obtain a string that has no + additional space before, after or in between words. + + \snippet draganddrop/dropsite/dropsitewindow.cpp updateFormatsTable() part3 + + If \c format contains a list of URLs, we iterate through them, using spaces + to separate them. On the other hand, if \c format contains an image, we + display the data by converting the text to hexadecimal. + + \snippet draganddrop/dropsite/dropsitewindow.cpp updateFormatsTable() part4 + + Once \c text has been customized to contain the appropriate data, we insert + both \c format and \c text into \c formatsTable with + \l{QTableWidget::setItem()}{setItem()}. Lastly, we invoke + \l{QTableView::resizeColumnToContents()}{resizeColumnToContents()} on + \c{formatsTable}'s first column. + + \section1 The main() Function + + Within the \c main() function, we instantiate \c DropSiteWindow and invoke + its \l{QWidget::show()}{show()} function. + + \snippet draganddrop/dropsite/main.cpp main() function +*/ diff --git a/doc/src/examples/dynamiclayouts.qdoc b/doc/src/examples/dynamiclayouts.qdoc new file mode 100644 index 0000000000..b0fa9338b3 --- /dev/null +++ b/doc/src/examples/dynamiclayouts.qdoc @@ -0,0 +1,34 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example layouts/dynamiclayouts + \title Dynamic Layouts Example + + The Dynamic Layouts example shows how to move widgets around in + existing layouts. +*/ diff --git a/doc/src/examples/easing.qdoc b/doc/src/examples/easing.qdoc new file mode 100644 index 0000000000..b8d70eeca1 --- /dev/null +++ b/doc/src/examples/easing.qdoc @@ -0,0 +1,37 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example animation/easing + \title Easing Curves Example + + The Easing Curves example shows how to use easing curves to + control the speed of an animation. + + \image easing-example.png + +*/ diff --git a/doc/src/examples/echoplugin.qdoc b/doc/src/examples/echoplugin.qdoc new file mode 100644 index 0000000000..7c56b21ecf --- /dev/null +++ b/doc/src/examples/echoplugin.qdoc @@ -0,0 +1,208 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example tools/echoplugin + \title Echo Plugin Example + + This example shows how to create a Qt plugin. + + \image echopluginexample.png + + There are two kinds of plugins in Qt: plugins that extend Qt + itself and plugins that extend applications written in Qt. In this + example, we show the procedure of implementing plugins that extend + applications. When you create a plugin you declare an interface, + which is a class with only pure virtual functions. This interface + is inherited by the class that implements the plugin. The class is + stored in a shared library and can therefore be loaded by + applications at run-time. When loaded, the plugin is dynamically + cast to the interface using Qt's \l{Meta-Object + System}{meta-object system}. The plugin \l{How to Create Qt + Plugins}{overview document} gives a high-level introduction to + plugins. + + We have implemented a plugin, the \c EchoPlugin, which implements + the \c EchoInterface. The interface consists of \c echo(), which + takes a QString as argument. The \c EchoPlugin returns the string + unaltered (i.e., it works as the familiar echo command found in + both Unix and Windows). + + We test the plugin in \c EchoWindow: when you push the QPushButton + (as seen in the image above), the application sends the text in + the QLineEdit to the plugin, which echoes it back to the + application. The answer from the plugin is displayed in the + QLabel. + + + \section1 EchoWindow Class Definition + + The \c EchoWindow class lets us test the \c EchoPlugin through a + GUI. + + \snippet examples/tools/echoplugin/echowindow/echowindow.h 0 + + We load the plugin in \c loadPlugin() and cast it to \c + EchoInterface. When the user clicks the \c button we take the + text in \c lineEdit and call the interface's \c echo() with it. + + + \section1 EchoWindow Class Implementation + + We start with a look at the constructor: + + \snippet examples/tools/echoplugin/echowindow/echowindow.cpp 0 + + We create the widgets and set a title for the window. We then load + the plugin. \c loadPlugin() returns false if the plugin could not + be loaded, in which case we disable the widgets. If you wish a + more detailed error message, you can use + \l{QPluginLoader::}{errorString()}; we will look more closely at + QPluginLoader later. + + Here is the implementation of \c sendEcho(): + + \snippet examples/tools/echoplugin/echowindow/echowindow.cpp 1 + + This slot is called when the user pushes \c button or presses + enter in \c lineEdit. We call \c echo() of the echo interface. In + our example this is the \c EchoPlugin, but it could be any plugin + that inherit the \c EchoInterface. We take the QString returned + from \c echo() and display it in the \c label. + + Here is the implementation of \c createGUI(): + + \snippet examples/tools/echoplugin/echowindow/echowindow.cpp 2 + + We create the widgets and lay them out in a grid layout. We + connect the label and line edit to our \c sendEcho() slot. + + Here is the \c loadPlugin() function: + + \snippet examples/tools/echoplugin/echowindow/echowindow.cpp 3 + + Access to plugins at run-time is provided by QPluginLoader. You + supply it with the filename of the shared library the plugin is + stored in and call \l{QPluginLoader::}{instance()}, which loads + and returns the root component of the plugin (i.e., it resolves + the type of the plugin and creates a QObject instance of it). If + the plugin was not successfully loaded, it will be null, so we + return false. If it was loaded correctly, we can cast the plugin + to our \c EchoInterface and return true. In the case that the + plugin loaded does not implement the \c EchoInterface, \c + instance() will return null, but this cannot happen in our + example. Notice that the location of the plugin is not the same + for all platforms. + + + \section1 EchoInterface Class Definition + + The \c EchoInterface defines the functions that the plugin will + provide. An interface is a class that only consists of pure + virtual functions. If non virtual functions were present in the + class you would get misleading compile errors in the moc files. + + \snippet examples/tools/echoplugin/echowindow/echointerface.h 0 + + We declare \c echo(). In our \c EchoPlugin we use this method to + return, or echo, \a message. + + We use the Q_DECLARE_INTERFACE macro to let \l{Meta-Object + System}{Qt's meta object system} aware of the interface. We do + this so that it will be possible to identify plugins that + implements the interface at run-time. The second argument is a + string that must identify the interface in a unique way. + + + \section1 EchoPlugin Class Definition + + We inherit both QObject and \c EchoInterface to make this class a + plugin. The Q_INTERFACES macro tells Qt which interfaces the class + implements. In our case we only implement the \c EchoInterface. + If a class implements more than one interface, they are given as + a comma separated list. + + \snippet examples/tools/echoplugin/plugin/echoplugin.h 0 + + + \section1 EchoPlugin Class Implementation + + Here is the implementation of \c echo(): + + \snippet examples/tools/echoplugin/plugin/echoplugin.cpp 0 + + We simply return the functions parameter. + + \snippet examples/tools/echoplugin/plugin/echoplugin.cpp 1 + + We use the Q_EXPORT_PLUGIN2 macro to let Qt know that the \c + EchoPlugin class is a plugin. The first parameter is the name of + the plugin; it is usual to give the plugin and the library file it + is stored in the same name. + + \section1 The \c main() function + + \snippet examples/tools/echoplugin/echowindow/main.cpp 0 + + We create an \c EchoWindow and display it as a top-level window. + + \section1 The Profiles + + When creating plugins the profiles need to be adjusted. + We show here what changes need to be done. + + The profile in the echoplugin directory uses the \c subdirs + template and simply includes includes to directories in which + the echo window and echo plugin lives: + + \snippet examples/tools/echoplugin/echoplugin.pro 0 + + The profile for the echo window does not need any plugin specific + settings. We move on to the plugin profile: + + \snippet examples/tools/echoplugin/plugin/plugin.pro 0 + + We need to set the TEMPLATE as we now want to make a library + instead of an executable. We also need to tell qmake that we are + creating a plugin. The \c EchoInterface that the plugin implements + lives in the \c echowindow directory, so we need to add that + directory to the include path. We set the TARGET of the project, + which is the name of the library file in which the plugin will be + stored; qmake appends the appropriate file extension depending on + the platform. By convention the target should have the same name + as the plugin (set with Q_EXPORT_PLUGIN2) + + \section1 Further reading and examples + + You can find an overview of the macros needed to create plugins + \l{Macros for Defining Plugins}{here}. + + We give an example of a plugin that extend Qt in the \l{Style + Plugin Example}{style plugin} example. The \l{Plug & Paint + Example}{plug and paint} example shows how to create static + plugins. +*/ diff --git a/doc/src/examples/editabletreemodel.qdoc b/doc/src/examples/editabletreemodel.qdoc new file mode 100644 index 0000000000..5edc91be54 --- /dev/null +++ b/doc/src/examples/editabletreemodel.qdoc @@ -0,0 +1,445 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example itemviews/editabletreemodel + \title Editable Tree Model Example + + This example shows how to implement a simple item-based tree model that can + be used with other classes the model/view framework. + + \image itemviews-editabletreemodel.png + + The model supports editable items, custom headers, and the ability to + insert and remove rows and columns. With these features, it is also + possible to insert new child items, and this is shown in the supporting + example code. + + \note The model only shows the basic principles used when creating an + editable, hierarchical model. You may wish to use the \l{ModelTest} + project to test production models. + + \section1 Overview + + As described in the \l{Model Subclassing Reference}, models must + provide implementations for the standard set of model functions: + \l{QAbstractItemModel::}{flags()}, \l{QAbstractItemModel::}{data()}, + \l{QAbstractItemModel::}{headerData()}, and + \l{QAbstractItemModel::}{rowCount()}. In addition, hierarchical models, + such as this one, need to provide implementations of + \l{QAbstractItemModel::}{index()} and \l{QAbstractItemModel::}{parent()}. + + An editable model needs to provide implementations of + \l{QAbstractItemModel::}{setData()} and + \l{QAbstractItemModel::}{headerData()}, and must return a suitable + combination of flags from its \l{QAbstractItemModel::}{flags()} function. + + Since this example allows the dimensions of the model to be changed, + we must also implement \l{QAbstractItemModel::}{insertRows()}, + \l{QAbstractItemModel::}{insertColumns()}, + \l{QAbstractItemModel::}{removeRows()}, and + \l{QAbstractItemModel::}{removeColumns()}. + + \section1 Design + + As with the \l{itemviews/simpletreemodel}{Simple Tree Model} example, + the model simply acts as a wrapper around a collection + of instances of a \c TreeItem class. Each \c TreeItem is designed to + hold data for a row of items in a tree view, so it contains a list of + values corresponding to the data shown in each column. + + Since QTreeView provides a row-oriented view onto a model, it is + natural to choose a row-oriented design for data structures that + will supply data via a model to this kind of view. Although this makes + the tree model less flexible, and possibly less useful for use with + more sophisticated views, it makes it less complex to design and easier + to implement. + + \target Relations-between-internal-items + \table + \row \o \inlineimage itemviews-editabletreemodel-items.png + \o \bold{Relations between internal items} + + When designing a data structure for use with a custom model, it is useful + to expose each item's parent via a function like + \l{TreeItem::parent}{TreeItem::parent()} because it will make + writing the model's own \l{QAbstractItemModel::}{parent()} function easier. + Similarly, a function like \l{TreeItem::child}{TreeItem::child()} is + helpful when implementing the model's \l{QAbstractItemModel::}{index()} + function. As a result, each \c TreeItem maintains information about + its parent and children, making it possible for us to traverse the tree + structure. + + The diagram shows how \c TreeItem instances are connected via their + \l{TreeItem::parent}{parent()} and \l{TreeItem::child}{child()} + functions. + + In the example shown, two top-level items, \bold{A} and + \bold{B}, can be obtained from the root item by calling its child() + function, and each of these items return the root node from their + parent() functions, though this is only shown for item \bold{A}. + \endtable + + Each \c TreeItem stores data for each column in the row it represents + in its \c itemData private member (a list of QVariant objects). + Since there is a one-to-one mapping between each column in the view + and each entry in the list, we provide a simple + \l{TreeItem::data}{data()} function to read entries in the \c itemData + list and a \l{TreeItem::setData}{setData()} function to allow them to + be modified. + As with other functions in the item, this simplifies the implemention + of the model's \l{QAbstractItemModel::}{data()} and + \l{QAbstractItemModel::}{setData()} functions. + + We place an item at the root of the tree of items. This root item + corresponds to the null model index, \l{QModelIndex::}{QModelIndex()}, + that is used to represent the parent of a top-level item when handling + model indexes. + Although the root item does not have a visible representation in any of + the standard views, we use its internal list of QVariant objects to + store a list of strings that will be passed to views for use as + horizontal header titles. + + \table + \row \o \inlineimage itemviews-editabletreemodel-model.png + \o \bold{Accessing data via the model} + + In the case shown in the diagram, the piece of information represented + by \bold{a} can be obtained using the standard model/view API: + + \snippet doc/src/snippets/code/doc_src_examples_editabletreemodel.cpp 0 + + Since each items holds pieces of data for each column in a given row, + there can be many model indexes that map to the same \c TreeItem object. + For example, the information represented by \bold{b} can be obtained + using the following code: + + \snippet doc/src/snippets/code/doc_src_examples_editabletreemodel.cpp 1 + + The same underlying \c TreeItem would be accessed to obtain information + for the other model indexes in the same row as \bold{b}. + \endtable + + In the model class, \c TreeModel, we relate \c TreeItem objects to + model indexes by passing a pointer for each item when we create its + corresponding model index with QAbstractItemModel::createIndex() in + our \l{TreeModel::index}{index()} and \l{TreeModel::parent}{parent()} + implementations. + We can retrieve pointers stored in this way by calling the + \l{QModelIndex::}{internalPointer()} function on the relevant model + index - we create our own \l{TreeModel::getItem}{getItem()} function to + do this work for us, and call it from our \l{TreeModel::data}{data()} + and \l{TreeModel::parent}{parent()} implementations. + + Storing pointers to items is convenient when we control how they are + created and destroyed since we can assume that an address obtained from + \l{QModelIndex::}{internalPointer()} is a valid pointer. + However, some models need to handle items that are obtained from other + components in a system, and in many cases it is not possible to fully + control how items are created or destroyed. In such situations, a pure + pointer-based approach needs to be supplemented by safeguards to ensure + that the model does not attempt to access items that have been deleted. + + \table + \row \o \bold{Storing information in the underlying data structure} + + Several pieces of data are stored as QVariant objects in the \c itemData + member of each \c TreeItem instance + + The diagram shows how pieces of information, + represented by the labels \bold{a}, \bold{b} and \bold{c} in the + previous two diagrams, are stored in items \bold{A}, \bold{B} and + \bold{C} in the underlying data structure. Note that pieces of + information from the same row in the model are all obtained from the + same item. Each element in a list corresponds to a piece of information + exposed by each column in a given row in the model. + + \o \inlineimage itemviews-editabletreemodel-values.png + \endtable + + Since the \c TreeModel implementation has been designed for use with + QTreeView, we have added a restriction on the way it uses \c TreeItem + instances: each item must expose the same number of columns of data. + This makes viewing the model consistent, allowing us to use the root + item to determine the number of columns for any given row, and only + adds the requirement that we create items containing enough data for + the total number of columns. As a result, inserting and removing + columns are time-consuming operations because we need to traverse the + entire tree to modify every item. + + An alternative approach would be to design the \c TreeModel class so + that it truncates or expands the list of data in individual \c TreeItem + instances as items of data are modified. However, this "lazy" resizing + approach would only allow us to insert and remove columns at the end of + each row and would not allow columns to be inserted or removed at + arbitrary positions in each row. + + \target Relating-items-using-model-indexes + \table + \row + \o \inlineimage itemviews-editabletreemodel-indexes.png + \o \bold{Relating items using model indexes} + + As with the \l{itemviews/simpletreemodel}{Simple Tree Model} example, + the \c TreeModel needs to be able to take a model index, find the + corresponding \c TreeItem, and return model indexes that correspond to + its parents and children. + + In the diagram, we show how the model's \l{TreeModel::parent}{parent()} + implementation obtains the model index corresponding to the parent of + an item supplied by the caller, using the items shown in a + \l{Relations-between-internal-items}{previous diagram}. + + A pointer to item \bold{C} is obtained from the corresponding model index + using the \l{QModelIndex::internalPointer()} function. The pointer was + stored internally in the index when it was created. Since the child + contains a pointer to its parent, we use its \l{TreeItem::parent}{parent()} + function to obtain a pointer to item \bold{B}. The parent model index is + created using the QAbstractItemModel::createIndex() function, passing + the pointer to item \bold{B} as the internal pointer. + \endtable + + \section1 TreeItem Class Definition + + The \c TreeItem class provides simple items that contain several + pieces of data, and which can provide information about their parent + and child items: + + \snippet examples/itemviews/editabletreemodel/treeitem.h 0 + + We have designed the API to be similar to that provided by + QAbstractItemModel by giving each item functions to return the number + of columns of information, read and write data, and insert and remove + columns. However, we make the relationship between items explicit by + providing functions to deal with "children" rather than "rows". + + Each item contains a list of pointers to child items, a pointer to its + parent item, and a list of QVariant objects that correspond to + information held in columns in a given row in the model. + + \section1 TreeItem Class Implementation + + Each \c TreeItem is constructed with a list of data and an optional + parent item: + + \snippet examples/itemviews/editabletreemodel/treeitem.cpp 0 + + Initially, each item has no children. These are added to the item's + internal \c childItems member using the \c insertChildren() function + described later. + + The destructor ensures that each child added to the item is deleted + when the item itself is deleted: + + \snippet examples/itemviews/editabletreemodel/treeitem.cpp 1 + + \target TreeItem::parent + Since each item stores a pointer to its parent, the \c parent() function + is trivial: + + \snippet examples/itemviews/editabletreemodel/treeitem.cpp 9 + + \target TreeItem::child + Three functions provide information about the children of an item. + \c child() returns a specific child from the internal list of children: + + \snippet examples/itemviews/editabletreemodel/treeitem.cpp 2 + + The \c childCount() function returns the total number of children: + + \snippet examples/itemviews/editabletreemodel/treeitem.cpp 3 + + The \c childNumber() function is used to determine the index of the child + in its parent's list of children. It accesses the parent's \c childItems + member directly to obtain this information: + + \snippet examples/itemviews/editabletreemodel/treeitem.cpp 4 + + The root item has no parent item; for this item, we return zero to be + consistent with the other items. + + The \c columnCount() function simply returns the number of elements in + the internal \c itemData list of QVariant objects: + + \snippet examples/itemviews/editabletreemodel/treeitem.cpp 5 + + \target TreeItem::data + Data is retrieved using the \c data() function, which accesses the + appropriate element in the \c itemData list: + + \snippet examples/itemviews/editabletreemodel/treeitem.cpp 6 + + \target TreeItem::setData + Data is set using the \c setData() function, which only stores values + in the \c itemData list for valid list indexes, corresponding to column + values in the model: + + \snippet examples/itemviews/editabletreemodel/treeitem.cpp 11 + + To make implementation of the model easier, we return true to indicate + whether the data was set successfully, or false if an invalid column + + Editable models often need to be resizable, enabling rows and columns to + be inserted and removed. The insertion of rows beneath a given model index + in the model leads to the insertion of new child items in the corresponding + item, handled by the \c insertChildren() function: + + \snippet examples/itemviews/editabletreemodel/treeitem.cpp 7 + + This ensures that new items are created with the required number of columns + and inserted at a valid position in the internal \c childItems list. + Items are removed with the \c removeChildren() function: + + \snippet examples/itemviews/editabletreemodel/treeitem.cpp 10 + + As discussed above, the functions for inserting and removing columns are + used differently to those for inserting and removing child items because + they are expected to be called on every item in the tree. We do this by + recursively calling this function on each child of the item: + + \snippet examples/itemviews/editabletreemodel/treeitem.cpp 8 + + \section1 TreeModel Class Definition + + The \c TreeModel class provides an implementation of the QAbstractItemModel + class, exposing the necessary interface for a model that can be edited and + resized. + + \snippet examples/itemviews/editabletreemodel/treemodel.h 0 + + The constructor and destructor are specific to this model. + + \snippet examples/itemviews/editabletreemodel/treemodel.h 1 + + Read-only tree models only need to provide the above functions. The + following public functions provide support for editing and resizing: + + \snippet examples/itemviews/editabletreemodel/treemodel.h 2 + + To simplify this example, the data exposed by the model is organized into + a data structure by the model's \l{TreeModel::setupModelData}{setupModelData()} + function. Many real world models will not process the raw data at all, but + simply work with an existing data structure or library API. + + \section1 TreeModel Class Implementation + + The constructor creates a root item and initializes it with the header + data supplied: + + \snippet examples/itemviews/editabletreemodel/treemodel.cpp 0 + + We call the internal \l{TreeModel::setupModelData}{setupModelData()} + function to convert the textual data supplied to a data structure we can + use with the model. Other models may be initialized with a ready-made + data structure, or use an API to a library that maintains its own data. + + The destructor only has to delete the root item; all child items will + be recursively deleted by the \c TreeItem destructor. + + \snippet examples/itemviews/editabletreemodel/treemodel.cpp 1 + + \target TreeModel::getItem + Since the model's interface to the other model/view components is based + on model indexes, and the internal data structure is item-based, many of + the functions implemented by the model need to be able to convert any + given model index to its corresponding item. For convenience and + consistency, we have defined a \c getItem() function to perform this + repetitive task: + + \snippet examples/itemviews/editabletreemodel/treemodel.cpp 4 + + This function assumes that each model index it is passed corresponds to + a valid item in memory. If the index is invalid, or its internal pointer + does not refer to a valid item, the root item is returned instead. + + The model's \c rowCount() implementation is simple: it first uses the + \c getItem() function to obtain the relevant item, then returns the + number of children it contains: + + \snippet examples/itemviews/editabletreemodel/treemodel.cpp 8 + + By contrast, the \c columnCount() implementation does not need to look + for a particular item because all items are defined to have the same + number of columns associated with them. + + \snippet examples/itemviews/editabletreemodel/treemodel.cpp 2 + + As a result, the number of columns can be obtained directly from the root + item. + + To enable items to be edited and selected, the \c flags() function needs + to be implemented so that it returns a combination of flags that includes + the Qt::ItemIsEditable and Qt::ItemIsSelectable flags as well as + Qt::ItemIsEnabled: + + \snippet examples/itemviews/editabletreemodel/treemodel.cpp 3 + + \target TreeModel::index + The model needs to be able to generate model indexes to allow other + components to request data and information about its structure. This task + is performed by the \c index() function, which is used to obtain model + indexes corresponding to children of a given parent item: + + \snippet examples/itemviews/editabletreemodel/treemodel.cpp 5 + + In this model, we only return model indexes for child items if the parent + index is invalid (corresponding to the root item) or if it has a zero + column number. + + We use the custom \l{TreeModel::getItem}{getItem()} function to obtain + a \c TreeItem instance that corresponds to the model index supplied, and + request its child item that corresponds to the specified row. + + \snippet examples/itemviews/editabletreemodel/treemodel.cpp 6 + + Since each item contains information for an entire row of data, we create + a model index to uniquely identify it by calling + \l{QAbstractItemModel::}{createIndex()} it with the row and column numbers + and a pointer to the item. In the \l{TreeModel::data}{data()} function, + we will use the item pointer and column number to access the data + associated with the model index; in this model, the row number is not + needed to identify data. + + \target TreeModel::parent + The \c parent() function supplies model indexes for parents of items + by finding the corresponding item for a given model index, using its + \l{TreeItem::parent}{parent()} function to obtain its parent item, + then creating a model index to represent the parent. (See + \l{Relating-items-using-model-indexes}{the above diagram}). + + \snippet examples/itemviews/editabletreemodel/treemodel.cpp 7 + + Items without parents, including the root item, are handled by returning + a null model index. Otherwise, a model index is created and returned as + in the \l{TreeModel::index}{index()} function, with a suitable row number, + but with a zero column number to be consistent with the scheme used in + the \l{TreeModel::index}{index()} implementation. + + \target TreeModel::data + \target TreeModel::setupModelData + +*/ diff --git a/doc/src/examples/elasticnodes.qdoc b/doc/src/examples/elasticnodes.qdoc new file mode 100644 index 0000000000..bba6d90a9d --- /dev/null +++ b/doc/src/examples/elasticnodes.qdoc @@ -0,0 +1,430 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example graphicsview/elasticnodes + \title Elastic Nodes Example + + This GraphicsView example shows how to implement edges between nodes in a + graph, with basic interaction. You can click to drag a node around, and + zoom in and out using the mouse wheel or the keyboard. Hitting the space + bar will randomize the nodes. The example is also resolution independent; + as you zoom in, the graphics remain crisp. + + \image elasticnodes-example.png + + Graphics View provides the QGraphicsScene class for managing and + interacting with a large number of custom-made 2D graphical items derived + from the QGraphicsItem class, and a QGraphicsView widget for visualizing + the items, with support for zooming and rotation. + + This example consists of a \c Node class, an \c Edge class, a \c + GraphWidget test, and a \c main function: the \c Node class represents + draggable yellow nodes in a grid, the \c Edge class represents the lines + between the nodes, the \c GraphWidget class represents the application + window, and the \c main() function creates and shows this window, and runs + the event loop. + + \section1 Node Class Definition + + The \c Node class serves three purposes: + + \list + \o Painting a yellow gradient "ball" in two states: sunken and raised. + \o Managing connections to other nodes. + \o Calculating forces pulling and pushing the nodes in the grid. + \endlist + + Let's start by looking at the \c Node class declaration. + + \snippet examples/graphicsview/elasticnodes/node.h 0 + + The \c Node class inherits QGraphicsItem, and reimplements the two + mandatory functions \l{QGraphicsItem::boundingRect()}{boundingRect()} and + \l{QGraphicsItem::paint()}{paint()} to provide its visual appearance. It + also reimplements \l{QGraphicsItem::shape()}{shape()} to ensure its hit + area has an elliptic shape (as opposed to the default bounding rectangle). + + For edge management purposes, the node provides a simple API for adding + edges to a node, and for listing all connected edges. + + The \l{QGraphicsItem::advance()}{advance()} reimplementation is called + whenever the scene's state advances by one step. The calculateForces() + function is called to calculate the forces that push and pull on this node + and its neighbors. + + The \c Node class also reimplements + \l{QGraphicsItem::itemChange()}{itemChange()} to react to state changes (in + this case, position changes), and + \l{QGraphicsItem::mousePressEvent()}{mousePressEvent()} and + \l{QGraphicsItem::mouseReleaseEvent()}{mouseReleaseEvent()} to update the + item's visual appearance. + + We will start reviewing the \c Node implementation by looking at its + constructor: + + \snippet examples/graphicsview/elasticnodes/node.cpp 0 + + In the constructor, we set the + \l{QGraphicsItem::ItemIsMovable}{ItemIsMovable} flag to allow the item to + move in response to mouse dragging, and + \l{QGraphicsItem::ItemSendsGeometryChanges}{ItemSendsGeometryChanges} to + enable \l{QGraphicsItem::itemChange()}{itemChange()} notifications for + position and transformation changes. We also enable + \l{QGraphicsItem::DeviceCoordinateCache}{DeviceCoordinateCache} to speed up + rendering performance. To ensure that the nodes are always stacked on top + of edges, we finally set the item's Z value to -1. + + \c Node's constructor takes a \c GraphWidget pointer and stores this as a + member variable. We will revisit this pointer later on. + + \snippet examples/graphicsview/elasticnodes/node.cpp 1 + + The addEdge() function adds the input edge to a list of attached edges. The + edge is then adjusted so that the end points for the edge match the + positions of the source and destination nodes. + + The edges() function simply returns the list of attached edges. + + \snippet examples/graphicsview/elasticnodes/node.cpp 2 + + There are two ways to move a node. The \c calculateForces() function + implements the elastic effect that pulls and pushes on nodes in the grid. + In addition, the user can directly move one node around with the mouse. + Because we do not want the two approaches to operate at the same time on + the same node, we start \c calculateForces() by checking if this \c Node is + the current mouse grabber item (i.e., QGraphicsScene::mouseGrabberItem()). + Because we need to find all neighboring (but not necessarily connected) + nodes, we also make sure the item is part of a scene in the first place. + + \snippet examples/graphicsview/elasticnodes/node.cpp 3 + + The "elastic" effect comes from an algorithm that applies pushing and + pulling forces. The effect is impressive, and surprisingly simple to + implement. + + The algorithm has two steps: the first is to calculate the forces that push + the nodes apart, and the second is to subtract the forces that pull the + nodes together. First we need to find all the nodes in the graph. We call + QGraphicsScene::items() to find all items in the scene, and then use + qgraphicsitem_cast() to look for \c Node instances. + + We make use of \l{QGraphicsItem::mapFromItem()}{mapFromItem()} to create a + temporary vector pointing from this node to each other node, in \l{The + Graphics View Coordinate System}{local coordinates}. We use the decomposed + components of this vector to determine the direction and strength of force + that should apply to the node. The forces accumulate for each node, and are + then adjusted so that the closest nodes are given the strongest force, with + rapid degradation when distance increases. The sum of all forces is stored + in \c xvel (X-velocity) and \c yvel (Y-velocity). + + \snippet examples/graphicsview/elasticnodes/node.cpp 4 + + The edges between the nodes represent forces that pull the nodes together. + By visiting each edge that is connected to this node, we can use a similar + approach as above to find the direction and strength of all pulling forces. + These forces are subtracted from \c xvel and \c yvel. + + \snippet examples/graphicsview/elasticnodes/node.cpp 5 + + In theory, the sum of pushing and pulling forces should stabilize to + precisely 0. In practise, however, they never do. To circumvent errors in + numerical precision, we simply force the sum of forces to be 0 when they + are less than 0.1. + + \snippet examples/graphicsview/elasticnodes/node.cpp 6 + + The final step of \c calculateForces() determines the node's new position. + We add the force to the node's current position. We also make sure the new + position stays inside of our defined boundaries. We don't actually move the + item in this function; that's done in a separate step, from \c advance(). + + \snippet examples/graphicsview/elasticnodes/node.cpp 7 + + The \c advance() function updates the item's current position. It is called + from \c GraphWidget::timerEvent(). If the node's position changed, the + function returns true; otherwise false is returned. + + \snippet examples/graphicsview/elasticnodes/node.cpp 8 + + The \c Node's bounding rectangle is a 20x20 sized rectangle centered around + its origin (0, 0), adjusted by 2 units in all directions to compensate for + the node's outline stroke, and by 3 units down and to the right to make + room for a simple drop shadow. + + \snippet examples/graphicsview/elasticnodes/node.cpp 9 + + The shape is a simple ellipse. This ensures that you must click inside the + node's elliptic shape in order to drag it around. You can test this effect + by running the example, and zooming far in so that the nodes are very + large. Without reimplementing \l{QGraphicsItem::shape()}{shape()}, the + item's hit area would be identical to its bounding rectangle (i.e., + rectangular). + + \snippet examples/graphicsview/elasticnodes/node.cpp 10 + + This function implements the node's painting. We start by drawing a simple + dark gray elliptic drop shadow at (-7, -7), that is, (3, 3) units down and + to the right from the top-left corner (-10, -10) of the ellipse. + + We then draw an ellipse with a radial gradient fill. This fill is either + Qt::yellow to Qt::darkYellow when raised, or the opposite when sunken. In + sunken state we also shift the center and focal point by (3, 3) to + emphasize the impression that something has been pushed down. + + Drawing filled ellipses with gradients can be quite slow, especially when + using complex gradients such as QRadialGradient. This is why this example + uses \l{QGraphicsItem::DeviceCoordinateCache}{DeviceCoordinateCache}, a + simple yet effective measure that prevents unnecessary redrawing. + + \snippet examples/graphicsview/elasticnodes/node.cpp 11 + + We reimplement \l{QGraphicsItem::itemChange()}{itemChange()} to adjust the + position of all connected edges, and to notify the scene that an item has + moved (i.e., "something has happened"). This will trigger new force + calculations. + + This notification is the only reason why the nodes need to keep a pointer + back to the \c GraphWidget. Another approach could be to provide such + notification using a signal; in such case, \c Node would need to inherit + from QGraphicsObject. + + \snippet examples/graphicsview/elasticnodes/node.cpp 12 + + Because we have set the \l{QGraphicsItem::ItemIsMovable}{ItemIsMovable} + flag, we don't need to implement the logic that moves the node according to + mouse input; this is already provided for us. We still need to reimplement + the mouse press and release handlers, though, to update the nodes' visual + appearance (i.e., sunken or raised). + + \section1 Edge Class Definition + + The \c Edge class represents the arrow-lines between the nodes in this + example. The class is very simple: it maintains a source- and destination + node pointer, and provides an \c adjust() function that makes sure the line + starts at the position of the source, and ends at the position of the + destination. The edges are the only items that change continuously as + forces pull and push on the nodes. + + Let's take a look at the class declaration: + + \snippet examples/graphicsview/elasticnodes/edge.h 0 + + \c Edge inherits from QGraphicsItem, as it's a simple class that has no use + for signals, slots, and properties (compare to QGraphicsObject). + + The constructor takes two node pointers as input. Both pointers are + mandatory in this example. We also provide get-functions for each node. + + The \c adjust() function repositions the edge, and the item also implements + \l{QGraphicsItem::boundingRect()}{boundingRect()} and + \l{QGraphicsItem::paint()}{paint()}. + + We will now review its implementation. + + \snippet examples/graphicsview/elasticnodes/edge.cpp 0 + + The \c Edge constructor initializes its \c arrowSize data member to 10 units; + this determines the size of the arrow which is drawn in + \l{QGraphicsItem::paint()}{paint()}. + + In the constructor body, we call + \l{QGraphicsItem::setAcceptedMouseButtons()}{setAcceptedMouseButtons(0)}. + This ensures that the edge items are not considered for mouse input at all + (i.e., you cannot click the edges). Then, the source and destination + pointers are updated, this edge is registered with each node, and we call + \c adjust() to update this edge's start end end position. + + \snippet examples/graphicsview/elasticnodes/edge.cpp 1 + + The source and destination get-functions simply return the respective + pointers. + + \snippet examples/graphicsview/elasticnodes/edge.cpp 2 + + In \c adjust(), we define two points: \c sourcePoint, and \c destPoint, + pointing at the source and destination nodes' origins respectively. Each + point is calculated using \l{The Graphics View Coordinate System}{local + coordinates}. + + We want the tip of the edge's arrows to point to the exact outline of the + nodes, as opposed to the center of the nodes. To find this point, we first + decompose the vector pointing from the center of the source to the center + of the destination node into X and Y, and then normalize the components by + dividing by the length of the vector. This gives us an X and Y unit delta + that, when multiplied by the radius of the node (which is 10), gives us the + offset that must be added to one point of the edge, and subtracted from the + other. + + If the length of the vector is less than 20 (i.e., if two nodes overlap), + then we fix the source and destination pointer at the center of the source + node. In practise this case is very hard to reproduce manually, as the + forces between the two nodes is then at its maximum. + + It's important to notice that we call + \l{QGraphicsItem::prepareGeometryChange()}{prepareGeometryChange()} in this + function. The reason is that the variables \c sourcePoint and \c destPoint + are used directly when painting, and they are returned from the + \l{QGraphicsItem::boundingRect()}{boundingRect()} reimplementation. We must + always call + \l{QGraphicsItem::prepareGeometryChange()}{prepareGeometryChange()} before + changing what \l{QGraphicsItem::boundingRect()}{boundingRect()} returns, + and before these variables can be used by + \l{QGraphicsItem::paint()}{paint()}, to keep Graphics View's internal + bookkeeping clean. It's safest to call this function once, immediately + before any such variable is modified. + + \snippet examples/graphicsview/elasticnodes/edge.cpp 3 + + The edge's bounding rectangle is defined as the smallest rectangle that + includes both the start and the end point of the edge. Because we draw an + arrow on each edge, we also need to compensate by adjusting with half the + arrow size and half the pen width in all directions. The pen is used to + draw the outline of the arrow, and we can assume that half of the outline + can be drawn outside of the arrow's area, and half will be drawn inside. + + \snippet examples/graphicsview/elasticnodes/edge.cpp 4 + + We start the reimplementation of \l{QGraphicsItem::paint()}{paint()} by + checking a few preconditions. Firstly, if either the source or destination + node is not set, then we return immediately; there is nothing to draw. + + At the same time, we check if the length of the edge is approximately 0, + and if it is, then we also return. + + \snippet examples/graphicsview/elasticnodes/edge.cpp 5 + + We draw the line using a pen that has round joins and caps. If you run the + example, zoom in and study the edge in detail, you will see that there are + no sharp/square edges. + + \snippet examples/graphicsview/elasticnodes/edge.cpp 6 + + We proceed to drawing one arrow at each end of the edge. Each arrow is + drawn as a polygon with a black fill. The coordinates for the arrow are + determined using simple trigonometry. + + \section1 GraphWidget Class Definition + + \c GraphWidget is a subclass of QGraphicsView, which provides the main + window with scrollbars. + + \snippet examples/graphicsview/elasticnodes/graphwidget.h 0 + + The class provides a basic constructor that initializes the scene, an \c + itemMoved() function to notify changes in the scene's node graph, a few + event handlers, a reimplementation of + \l{QGraphicsView::drawBackground()}{drawBackground()}, and a helper + function for scaling the view by using the mouse wheel or keyboard. + + \snippet examples/graphicsview/elasticnodes/graphwidget.cpp 0 + + \c GraphicsWidget's constructor creates the scene, and because most items + move around most of the time, it sets QGraphicsScene::NoIndex. The scene + then gets a fixed \l{QGraphicsScene::sceneRect}{scene rectangle}, and is + assigned to the \c GraphWidget view. + + The view enables QGraphicsView::CacheBackground to cache rendering of its + static, and somewhat complex, background. Because the graph renders a close + collection of small items that all move around, it's unnecessary for + Graphics View to waste time finding accurate update regions, so we set the + QGraphicsView::BoundingRectViewportUpdate viewport update mode. The default + would work fine, but this mode is noticably faster for this example. + + To improve rendering quality, we set QPainter::Antialiasing. + + The transformation anchor decides how the view should scroll when you + transform the view, or in our case, when we zoom in or out. We have chosen + QGraphicsView::AnchorUnderMouse, which centers the view on the point under + the mouse cursor. This makes it easy to zoom towards a point in the scene + by moving the mouse over it, and then rolling the mouse wheel. + + Finally we give the window a minimum size that matches the scene's default + size, and set a suitable window title. + + \snippet examples/graphicsview/elasticnodes/graphwidget.cpp 1 + + The last part of the constructor creates the grid of nodes and edges, and + gives each node an initial position. + + \snippet examples/graphicsview/elasticnodes/graphwidget.cpp 2 + + \c GraphWidget is notified of node movement through this \c itemMoved() + function. Its job is simply to restart the main timer in case it's not + running already. The timer is designed to stop when the graph stabilizes, + and start once it's unstable again. + + \snippet examples/graphicsview/elasticnodes/graphwidget.cpp 3 + + This is \c GraphWidget's key event handler. The arrow keys move the center + node around, the '+' and '-' keys zoom in and out by calling \c + scaleView(), and the enter and space keys randomize the positions of the + nodes. All other key events (e.g., page up and page down) are handled by + QGraphicsView's default implementation. + + \snippet examples/graphicsview/elasticnodes/graphwidget.cpp 4 + + The timer event handler's job is to run the whole force calculation + machinery as a smooth animation. Each time the timer is triggered, the + handler will find all nodes in the scene, and call \c + Node::calculateForces() on each node, one at a time. Then, in a final step + it will call \c Node::advance() to move all nodes to their new positions. + By checking the return value of \c advance(), we can decide if the grid + stabilized (i.e., no nodes moved). If so, we can stop the timer. + + \snippet examples/graphicsview/elasticnodes/graphwidget.cpp 5 + + In the wheel event handler, we convert the mouse wheel delta to a scale + factor, and pass this factor to \c scaleView(). This approach takes into + account the speed that the wheel is rolled. The faster you roll the mouse + wheel, the faster the view will zoom. + + \snippet examples/graphicsview/elasticnodes/graphwidget.cpp 6 + + The view's background is rendered in a reimplementation of + QGraphicsView::drawBackground(). We draw a large rectangle filled with a + linear gradient, add a drop shadow, and then render text on top. The text + is rendered twice for a simple drop-shadow effect. + + This background rendering is quite expensive; this is why the view enables + QGraphicsView::CacheBackground. + + \snippet examples/graphicsview/elasticnodes/graphwidget.cpp 7 + + The \c scaleView() helper function checks that the scale factor stays + within certain limits (i.e., you cannot zoom too far in nor too far out), + and then applies this scale to the view. + + \section1 The main() Function + + In contrast to the complexity of the rest of this example, the \c main() + function is very simple: We create a QApplication instance, seed the + randomizer using qsrand(), and then create and show an instance of \c + GraphWidget. Because all nodes in the grid are moved initially, the \c + GraphWidget timer will start immediately after control has returned to the + event loop. +*/ diff --git a/doc/src/examples/eventtransitions.qdoc b/doc/src/examples/eventtransitions.qdoc new file mode 100644 index 0000000000..be6e814ef8 --- /dev/null +++ b/doc/src/examples/eventtransitions.qdoc @@ -0,0 +1,72 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example statemachine/eventtransitions + \title Event Transitions Example + + The Event Transitions example shows how to use event transitions, a + feature of \l{The State Machine Framework}. + + \snippet examples/statemachine/eventtransitions/main.cpp 0 + + The \c Window class's constructors begins by creating a button. + + \snippet examples/statemachine/eventtransitions/main.cpp 1 + + Two states, \c s1 and \c s2, are created; upon entry they will assign + "Outside" and "Inside" to the button's text, respectively. + + \snippet examples/statemachine/eventtransitions/main.cpp 2 + + When the button receives an event of type QEvent::Enter and the state + machine is in state \c s1, the machine will transition to state \c s2. + + \snippet examples/statemachine/eventtransitions/main.cpp 3 + + When the button receives an event of type QEvent::Leave and the state + machine is in state \c s2, the machine will transition back to state \c + s1. + + \snippet examples/statemachine/eventtransitions/main.cpp 4 + + Next, the state \c s3 is created. \c s3 will be entered when the button + receives an event of type QEvent::MouseButtonPress and the state machine + is in state \c s2. When the button receives an event of type + QEvent::MouseButtonRelease and the state machine is in state \c s3, the + machine will transition back to state \c s2. + + \snippet examples/statemachine/eventtransitions/main.cpp 5 + + Finally, the states are added to the machine as top-level states, the + initial state is set to be \c s1 ("Outside"), and the machine is started. + + \snippet examples/statemachine/eventtransitions/main.cpp 6 + + The main() function constructs a Window object and shows it. + +*/ diff --git a/doc/src/examples/extension.qdoc b/doc/src/examples/extension.qdoc new file mode 100644 index 0000000000..e66c89c893 --- /dev/null +++ b/doc/src/examples/extension.qdoc @@ -0,0 +1,138 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example dialogs/extension + \title Extension Example + + The Extension example shows how to add an extension to a QDialog + using the QAbstractButton::toggled() signal and the + QWidget::setVisible() slot. + + \image extension-example.png Screenshot of the Extension example + + The Extension application is a dialog that allows the user to + perform a simple search as well as a more advanced search. + + The simple search has two options: \gui {Match case} and \gui + {Search from start}. The advanced search options include the + possibilities to search for \gui {Whole words}, \gui {Search + backward} and \gui {Search selection}. Only the simple search is + visible when the application starts. The advanced search options + are located in the application's extension part, and can be made + visible by pressing the \gui More button: + + \image extension_more.png Screenshot of the Extension example + + \section1 FindDialog Class Definition + + The \c FindDialog class inherits QDialog. The QDialog class is the + base class of dialog windows. A dialog window is a top-level + window mostly used for short-term tasks and brief communications + with the user. + + \snippet examples/dialogs/extension/finddialog.h 0 + + The \c FindDialog widget is the main application widget, and + displays the application's search options and controlling + buttons. + + In addition to a constructor, we declare the several child + widgets: We need a QLineEdit with an associated QLabel to let the + user type a word to search for, we need several \l + {QCheckBox}{QCheckBox}es to facilitate the search options, and we + need three \l {QPushButton}{QPushButton}s: the \gui Find button to + start a search and the \gui More button to enable an advanced search. + Finally, we need a QWidget representing the application's extension + part. + + \section1 FindDialog Class Implementation + + In the constructor we first create the standard child widgets for + the simple search: the QLineEdit with the associated QLabel, two + of the \l {QCheckBox}{QCheckBox}es and all the \l + {QPushButton}{QPushButton}s. + + \snippet examples/dialogs/extension/finddialog.cpp 0 + + We give the options and buttons a shortcut key using the & + character. In the \gui {Find what} option's case, we also need to + use the QLabel::setBuddy() function to make the shortcut key work + as expected; then, when the user presses the shortcut key + indicated by the label, the keyboard focus is transferred to the + label's buddy widget, the QLineEdit. + + We set the \gui Find button's default property to true, using the + QPushButton::setDefault() function. Then the push button will be + pressed if the user presses the Enter (or Return) key. Note that a + QDialog can only have one default button. + + \snippet examples/dialogs/extension/finddialog.cpp 2 + + Then we create the extension widget, and the \l + {QCheckBox}{QCheckBox}es associated with the advanced search + options. + + \snippet examples/dialogs/extension/finddialog.cpp 3 + + Now that the extension widget is created, we can connect the \gui + More button's \l{QAbstractButton::toggled()}{toggled()} signal to + the extension widget's \l{QWidget::setVisible()}{setVisible()} slot. + + The QAbstractButton::toggled() signal is emitted whenever a + checkable button changes its state. The signal's argument is true + if the button is checked, or false if the button is unchecked. The + QWidget::setVisible() slot sets the widget's visible status. If + the status is true the widget is shown, otherwise the widget is + hidden. + + Since we made the \gui More button checkable when we created it, + the connection makes sure that the extension widget is shown + depending on the state of \gui More button. + + We also put the check boxes associated with the advanced + search options into a layout we install on the extension widget. + + \snippet examples/dialogs/extension/finddialog.cpp 4 + + Before we create the main layout, we create several child layouts + for the widgets: First we allign the QLabel ans its buddy, the + QLineEdit, using a QHBoxLayout. Then we vertically allign the + QLabel and QLineEdit with the check boxes associated with the + simple search, using a QVBoxLayout. We also create a QVBoxLayout + for the buttons. In the end we lay out the two latter layouts and + the extension widget using a QGridLayout. + + \snippet examples/dialogs/extension/finddialog.cpp 5 + + Finally, we hide the extension widget using the QWidget::hide() + function, making the application only show the simple search + options when it starts. When the user wants to access the advanced + search options, the dialog only needs to change the visibility of + the extension widget. Qt's layout management takes care of the + dialog's appearance. +*/ diff --git a/doc/src/examples/factorial.qdoc b/doc/src/examples/factorial.qdoc new file mode 100644 index 0000000000..bad1a77e1e --- /dev/null +++ b/doc/src/examples/factorial.qdoc @@ -0,0 +1,88 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example statemachine/factorial + \title Factorial States Example + + The Factorial States example shows how to use \l{The State Machine + Framework} to calculate the factorial of an integer. + + The statechart for calculating the factorial looks as follows: + + \img factorial-example.png + \omit + \caption This is a caption + \endomit + + In other words, the state machine calculates the factorial of 6 and prints + the result. + + \snippet examples/statemachine/factorial/main.cpp 0 + + The Factorial class is used to hold the data of the computation, \c x and + \c fac. It also provides a signal that's emitted whenever the value of \c + x changes. + + \snippet examples/statemachine/factorial/main.cpp 1 + + The FactorialLoopTransition class implements the guard (\c x > 1) and + calculations (\c fac = \c x * \c fac; \c x = \c x - 1) of the factorial + loop. + + \snippet examples/statemachine/factorial/main.cpp 2 + + The FactorialDoneTransition class implements the guard (\c x <= 1) that + terminates the factorial computation. It also prints the final result to + standard output. + + \snippet examples/statemachine/factorial/main.cpp 3 + + The application's main() function first creates the application object, a + Factorial object and a state machine. + + \snippet examples/statemachine/factorial/main.cpp 4 + + The \c compute state is created, and the initial values of \c x and \c fac + are defined. A FactorialLoopTransition object is created and added to the + state. + + \snippet examples/statemachine/factorial/main.cpp 5 + + A final state, \c done, is created, and a FactorialDoneTransition object + is created with \c done as its target state. The transition is then added + to the \c compute state. + + \snippet examples/statemachine/factorial/main.cpp 6 + + The machine's initial state is set to be the \c compute state. We connect + the QStateMachine::finished() signal to the QCoreApplication::quit() slot, + so the application will quit when the state machine's work is + done. Finally, the state machine is started, and the application's event + loop is entered. + + */ diff --git a/doc/src/examples/fademessage.qdoc b/doc/src/examples/fademessage.qdoc new file mode 100644 index 0000000000..09c1d947f4 --- /dev/null +++ b/doc/src/examples/fademessage.qdoc @@ -0,0 +1,37 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example effects/fademessage + \title Fade Message Effect Example + + \div { style="text-align: center"} + \inlineimage fademessageeffect-example.png + \inlineimage fademessageeffect-example-faded.png + \enddiv + +*/ diff --git a/doc/src/examples/fetchmore.qdoc b/doc/src/examples/fetchmore.qdoc new file mode 100644 index 0000000000..7aa8b45b52 --- /dev/null +++ b/doc/src/examples/fetchmore.qdoc @@ -0,0 +1,111 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example itemviews/fetchmore + \title Fetch More Example + + The Fetch More example shows how two add items to an item view + model on demand. + + \image fetchmore-example.png + + The user of the example can enter a directory in the \gui + Directory line edit. The contents of the directory will + be listed in the list view below. + + When you have large - or perhaps even infinite - data sets, you + will need to add items to the model in batches, and preferably only + when the items are needed by the view (i.e., when they are visible + in the view). + + In this example, we implement \c FileListModel - an item view + model containing the entries of a directory. We also have \c + Window, which sets up the GUI and feeds the model with + directories. + + Let's take a tour of \c {FileListModel}'s code. + + \section1 FileListModel Class Definition + + The \c FileListModel inherits QAbstractListModel and contains the + contents of a directory. It will add items to itself only when + requested to do so by the view. + + \snippet examples/itemviews/fetchmore/filelistmodel.h 0 + + The secret lies in the reimplementation of + \l{QAbstractItemModel::}{fetchMore()} and + \l{QAbstractItemModel::}{canFetchMore()} from QAbstractItemModel. + These functions are called by the item view when it needs more + items. + + The \c setDirPath() function sets the directory the model will + work on. We emit \c numberPopulated() each time we add a batch of + items to the model. + + We keep all directory entries in \c fileList. \c fileCount is the + number of items that have been added to the model. + + \section1 FileListModel Class Implementation + + We start by checking out the \c setDirPath(). + + \snippet examples/itemviews/fetchmore/filelistmodel.cpp 0 + + We use a QDir to get the contents of the directory. We need to + inform QAbstractItemModel that we want to remove all items - if + any - from the model. + + \snippet examples/itemviews/fetchmore/filelistmodel.cpp 1 + + The \c canFetchMore() function is called by the view when it needs + more items. We return true if there still are entries that we have + not added to the model; otherwise, we return false. + + And now, the \c fetchMore() function itself: + + \snippet examples/itemviews/fetchmore/filelistmodel.cpp 2 + + We first calculate the number of items to fetch. + \l{QAbstractItemModel::}{beginInsertRows()} and + \l{QAbstractItemModel::}{endInsertRows()} are mandatory for + QAbstractItemModel to keep up with the row insertions. Finally, we + emit \c numberPopulated(), which is picked up by \c Window. + + To complete the tour, we also look at \c rowCount() and \c data(). + + \snippet examples/itemviews/fetchmore/filelistmodel.cpp 4 + + Notice that the row count is only the items we have added so far, + i.e., not the number of entries in the directory. + + In \c data(), we return the appropriate entry from the \c + fileList. We also separate the batches with a different background + color. +*/ + diff --git a/doc/src/examples/findfiles.qdoc b/doc/src/examples/findfiles.qdoc new file mode 100644 index 0000000000..2226fe2d0e --- /dev/null +++ b/doc/src/examples/findfiles.qdoc @@ -0,0 +1,249 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example dialogs/findfiles + \title Find Files Example + + The Find Files example shows how to use QProgressDialog to provide + feedback on the progress of a slow operation. The example also + shows how to use QFileDialog to facilitate browsing, how to use + QTextStream's streaming operators to read a file, and how to use + QTableWidget to provide standard table display facilities for + applications. In addition, files can be opened using the + QDesktopServices class. + + \image findfiles-example.png Screenshot of the Find Files example + + With the Find Files application the user can search for files in a + specified directory, matching a specified file name (using wild + cards if appropiate) and containing a specified text. + + The user is provided with a \gui Browse option, and the result of + the search is displayed in a table with the names of the files + found and their sizes. In addition the application provides a + total count of the files found. + + \section1 Window Class Definition + + The \c Window class inherits QWidget, and is the main application + widget. It shows the search options, and displays the search + results. + + \snippet examples/dialogs/findfiles/window.h 0 + + We need two private slots: The \c browse() slot is called whenever + the user wants to browse for a directory to search in, and the \c + find() slot is called whenever the user requests a search to be + performed by pressing the \gui Find button. + + In addition we declare several private functions: We use the \c + findFiles() function to search for files matching the user's + specifications, we call the \c showFiles() function to display the + results, and we use \c createButton(), \c createComboBox() and \c + createFilesTable() when we are constructing the widget. + + \section1 Window Class Implementation + + In the constructor we first create the application's widgets. + + \snippet examples/dialogs/findfiles/window.cpp 0 + + We create the application's buttons using the private \c + createButton() function. Then we create the comboboxes associated + with the search specifications, using the private \c + createComboBox() function. We also create the application's labels + before we use the private \c createFilesTable() function to create + the table displaying the search results. + + \snippet examples/dialogs/findfiles/window.cpp 1 + + Then we add all the widgets to a main layout using QGridLayout. We + have, however, put the \c Find and \c Quit buttons and a + stretchable space in a separate QHBoxLayout first, to make the + buttons appear in the \c Window widget's bottom right corner. + + \snippet examples/dialogs/findfiles/window.cpp 2 + + The \c browse() slot presents a file dialog to the user, using the + QFileDialog class. QFileDialog enables a user to traverse the file + system in order to select one or many files or a directory. The + easiest way to create a QFileDialog is to use the convenience + static functions. + + Here we use the static QFileDialog::getExistingDirectory() + function which returns an existing directory selected by the + user. Then we display the directory in the directory combobox + using the QComboBox::addItem() function, and updates the current + index. + + QComboBox::addItem() adds an item to the combobox with the given + text (if it is not already present in the list), and containing + the specified userData. The item is appended to the list of + existing items. + + \snippet examples/dialogs/findfiles/window.cpp 3 + + The \c find() slot is called whenever the user requests a new + search by pressing the \gui Find button. + + First we eliminate any previous search results by setting the + table widgets row count to zero. Then we retrieve the + specified file name, text and directory path from the respective + comboboxes. + + \snippet examples/dialogs/findfiles/window.cpp 4 + + We use the directory's path to create a QDir; the QDir class + provides access to directory structures and their contents. We + create a list of the files (contained in the newly created QDir) + that match the specified file name. If the file name is empty + the list will contain all the files in the directory. + + Then we search through all the files in the list, using the private + \c findFiles() function, eliminating the ones that don't contain + the specified text. And finally, we display the results using the + private \c showFiles() function. + + If the user didn't specify any text, there is no reason to search + through the files, and we display the results immediately. + + \image findfiles_progress_dialog.png Screenshot of the Progress Dialog + + \snippet examples/dialogs/findfiles/window.cpp 5 + + In the private \c findFiles() function we search through a list of + files, looking for the ones that contain a specified text. This + can be a very slow operation depending on the number of files as + well as their sizes. In case there are a large number of files, or + there exists some large files on the list, we provide a + QProgressDialog. + + The QProgressDialog class provides feedback on the progress of a + slow operation. It is used to give the user an indication of how + long an operation is going to take, and to demonstrate that the + application has not frozen. It can also give the user an + opportunity to abort the operation. + + \snippet examples/dialogs/findfiles/window.cpp 6 + + We run through the files, one at a time, and for each file we + update the QProgressDialog value. This property holds the current + amount of progress made. We also update the progress dialog's + label. + + Then we call the QCoreApplication::processEvents() function using + the QApplication object. In this way we interleave the display of + the progress made with the process of searching through the files + so the application doesn't appear to be frozen. + + The QApplication class manages the GUI application's control flow + and main settings. It contains the main event loop, where all + events from the window system and other sources are processed and + dispatched. QApplication inherits QCoreApplication. The + QCoreApplication::processEvents() function processes all pending + events according to the specified QEventLoop::ProcessEventFlags + until there are no more events to process. The default flags are + QEventLoop::AllEvents. + + \snippet examples/dialogs/findfiles/window.cpp 7 + + After updating the QProgressDialog, we create a QFile using the + QDir::absoluteFilePath() function which returns the absolute path + name of a file in the directory. We open the file in read-only + mode, and read one line at a time using QTextStream. + + The QTextStream class provides a convenient interface for reading + and writing text. Using QTextStream's streaming operators, you can + conveniently read and write words, lines and numbers. + + For each line we read we check if the QProgressDialog has been + canceled. If it has, we abort the operation, otherwise we check if + the line contains the specified text. When we find the text within + one of the files, we add the file's name to a list of found files + that contain the specified text, and start searching a new file. + + Finally, we return the list of the files found. + + \snippet examples/dialogs/findfiles/window.cpp 8 + + Both the \c findFiles() and \c showFiles() functions are called from + the \c find() slot. In the \c showFiles() function we run through + the provided list of file names, adding each file name to the + first column in the table widget and retrieving the file's size using + QFile and QFileInfo for the second column. + + We also update the total number of files found. + + \snippet examples/dialogs/findfiles/window.cpp 9 + + The private \c createButton() function is called from the + constructor. We create a QPushButton with the provided text, + connect it to the provided slot, and return a pointer to the + button. + + \snippet examples/dialogs/findfiles/window.cpp 10 + + The private \c createComboBox() function is also called from the + contructor. We create a QComboBox with the given text, and make it + editable. + + When the user enters a new string in an editable combobox, the + widget may or may not insert it, and it can insert it in several + locations, depending on the QComboBox::InsertPolicy. The default + policy is is QComboBox::InsertAtBottom. + + Then we add the provided text to the combobox, and specify the + widget's size policies, before we return a pointer to the + combobox. + + \snippet examples/dialogs/findfiles/window.cpp 11 + + The private \c createFilesTable() function is called from the + constructor. In this function we create the QTableWidget that + will display the search results. We set its horizontal headers and + their resize mode. + + QTableWidget inherits QTableView which provides a default + model/view implementation of a table view. The + QTableView::horizontalHeader() function returns the table view's + horizontal header as a QHeaderView. The QHeaderView class provides + a header row or header column for item views, and the + QHeaderView::setResizeMode() function sets the constraints on how + the section in the header can be resized. + + Finally, we hide the QTableWidget's vertical headers using the + QWidget::hide() function, and remove the default grid drawn for + the table using the QTableView::setShowGrid() function. + + \snippet examples/dialogs/findfiles/window.cpp 12 + + The \c openFileOfItem() slot is invoked when the user double + clicks on a cell in the table. The QDesktopServices::openUrl() + knows how to open a file given the file name. +*/ + diff --git a/doc/src/examples/fingerpaint.qdoc b/doc/src/examples/fingerpaint.qdoc new file mode 100644 index 0000000000..eaef4ebd6d --- /dev/null +++ b/doc/src/examples/fingerpaint.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example touch/fingerpaint + \title Finger Paint Example + + The Finger Paint example shows the use of touch with a custom widget + to create a simple painting application. + + \image touch-fingerpaint-example.png +*/ diff --git a/doc/src/examples/flowlayout.qdoc b/doc/src/examples/flowlayout.qdoc new file mode 100644 index 0000000000..64a86c33c4 --- /dev/null +++ b/doc/src/examples/flowlayout.qdoc @@ -0,0 +1,145 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example layouts/flowlayout + \title Flow Layout Example + + The Flow Layout example demonstrates a custom layout that arranges child + widgets from left to right and top to bottom in a top-level widget. + + \image flowlayout-example.png Screenshot of the Flow Layout example + + The items are first laid out horizontally and then vertically when each line + in the layout runs out of space. + + The Flowlayout class mainly uses QLayout and QWidgetItem, while the + Window uses QWidget and QLabel. We will only document the definition + and implementation of \c FlowLayout below. + + \section1 FlowLayout Class Definition + + The \c FlowLayout class inherits QLayout. It is a custom layout class + that arranges its child widgets horizontally and vertically. + + \snippet examples/layouts/flowlayout/flowlayout.h 0 + + We reimplement functions inherited from QLayout. These functions add items to + the layout and handle their orientation and geometry. + + We also declare two private methods, \c doLayout() and \c smartSpacing(). + \c doLayout() lays out the layout items, while the \c + smartSpacing() function calculates the spacing between them. + + \section1 FlowLayout Class Implementation + + We start off by looking at the constructor: + + \snippet examples/layouts/flowlayout/flowlayout.cpp 1 + + In the constructor we call \c setContentsMargins() to set the left, top, + right and bottom margin. By default, QLayout uses values provided by + the current style (see QStyle::PixelMetric). + + \snippet examples/layouts/flowlayout/flowlayout.cpp 2 + + In this example we reimplement \c addItem(), which is a pure virtual + function. When using \c addItem() the ownership of the layout items is + transferred to the layout, and it is therefore the layout's + responsibility to delete them. + + \snippet examples/layouts/flowlayout/flowlayout.cpp 3 + + \c addItem() is implemented to add items to the layout. + + \snippet examples/layouts/flowlayout/flowlayout.cpp 4 + + We implement \c horizontalSpacing() and \c verticalSpacing() to get + hold of the spacing between the widgets inside the layout. If the value + is less than or equal to 0, this value will be used. If not, + \c smartSpacing() will be called to calculate the spacing. + + \snippet examples/layouts/flowlayout/flowlayout.cpp 5 + + We then implement \c count() to return the number of items in the + layout. To navigate the list of items we use \c itemAt() and + takeAt() to remove and return items from the list. If an item is + removed, the remaining items will be renumbered. All three + functions are pure virtual functions from QLayout. + + \snippet examples/layouts/flowlayout/flowlayout.cpp 6 + + \c expandingDirections() returns the \l{Qt::Orientation}s in which the + layout can make use of more space than its \c sizeHint(). + + \snippet examples/layouts/flowlayout/flowlayout.cpp 7 + + To adjust to widgets of which height is dependent on width, we implement \c + heightForWidth(). The function \c hasHeightForWidth() is used to test for this + dependency, and \c heightForWidth() passes the width on to \c doLayout() which + in turn uses the width as an argument for the layout rect, i.e., the bounds in + which the items are laid out. This rect does not include the layout margin(). + + \snippet examples/layouts/flowlayout/flowlayout.cpp 8 + + \c setGeometry() is normally used to do the actual layout, i.e., calculate + the geometry of the layout's items. In this example, it calls \c doLayout() + and passes the layout rect. + + \c sizeHint() returns the preferred size of the layout and \c minimumSize() + returns the minimum size of the layout. + + \snippet examples/layouts/flowlayout/flowlayout.cpp 9 + + \c doLayout() handles the layout if \c horizontalSpacing() or \c + verticalSpacing() don't return the default value. It uses + \c getContentsMargins() to calculate the area available to the + layout items. + + \snippet examples/layouts/flowlayout/flowlayout.cpp 10 + + It then sets the proper amount of spacing for each widget in the + layout, based on the current style. + + \snippet examples/layouts/flowlayout/flowlayout.cpp 11 + + The position of each item in the layout is then calculated by + adding the items width and the line height to the initial x and y + coordinates. This in turn lets us find out whether the next item + will fit on the current line or if it must be moved down to the next. + We also find the height of the current line based on the widgets height. + + \snippet examples/layouts/flowlayout/flowlayout.cpp 12 + + \c smartSpacing() is designed to get the default spacing for either + the top-level layouts or the sublayouts. The default spacing for + top-level layouts, when the parent is a QWidget, will be determined + by querying the style. The default spacing for sublayouts, when + the parent is a QLayout, will be determined by querying the spacing + of the parent layout. + +*/ diff --git a/doc/src/examples/fontsampler.qdoc b/doc/src/examples/fontsampler.qdoc new file mode 100644 index 0000000000..d6bd9ba435 --- /dev/null +++ b/doc/src/examples/fontsampler.qdoc @@ -0,0 +1,35 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example painting/fontsampler + \title Font Sampler Example + + The Font Sampler example shows how to preview and print multi-page documents. + + \image fontsampler-example.png +*/ diff --git a/doc/src/examples/fortuneclient.qdoc b/doc/src/examples/fortuneclient.qdoc new file mode 100644 index 0000000000..1c8b504f43 --- /dev/null +++ b/doc/src/examples/fortuneclient.qdoc @@ -0,0 +1,160 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example network/fortuneclient + \title Fortune Client Example + + The Fortune Client example shows how to create a client for a simple + network service using QTcpSocket. It is intended to be run alongside the + \l{network/fortuneserver}{Fortune Server} example or + the \l{network/threadedfortuneserver}{Threaded Fortune Server} example. + + \image fortuneclient-example.png Screenshot of the Fortune Client example + + This example uses a simple QDataStream-based data transfer protocol to + request a line of text from a fortune server (from the + \l{network/fortuneserver}{Fortune Server} example). The client requests a + fortune by simply connecting to the server. The server then responds with + a 16-bit (quint16) integer containing the length of the fortune text, + followed by a QString. + + QTcpSocket supports two general approaches to network programming: + + \list + + \o \e{The asynchronous (non-blocking) approach.} Operations are scheduled + and performed when control returns to Qt's event loop. When the operation + is finished, QTcpSocket emits a signal. For example, + QTcpSocket::connectToHost() returns immediately, and when the connection + has been established, QTcpSocket emits + \l{QTcpSocket::connected()}{connected()}. + + \o \e{The synchronous (blocking) approach.} In non-GUI and multithreaded + applications, you can call the \c waitFor...() functions (e.g., + QTcpSocket::waitForConnected()) to suspend the calling thread until the + operation has completed, instead of connecting to signals. + + \endlist + + In this example, we will demonstrate the asynchronous approach. The + \l{network/blockingfortuneclient}{Blocking Fortune Client} example + illustrates the synchronous approach. + + Our class contains some data and a few private slots: + + \snippet examples/network/fortuneclient/client.h 0 + + Other than the widgets that make up the GUI, the data members include a + QTcpSocket pointer, a copy of the fortune text currently displayed, and + the size of the packet we are currently reading (more on this later). + + The socket is initialized in the Client constructor. We'll pass the main + widget as parent, so that we won't have to worry about deleting the + socket: + + \snippet examples/network/fortuneclient/client.cpp 0 + \dots + \snippet examples/network/fortuneclient/client.cpp 1 + + The only QTcpSocket signals we need in this example are + QTcpSocket::readyRead(), signifying that data has been received, and + QTcpSocket::error(), which we will use to catch any connection errors: + + \dots + \snippet examples/network/fortuneclient/client.cpp 3 + \dots + \snippet examples/network/fortuneclient/client.cpp 5 + + Clicking the \gui{Get Fortune} button will invoke the \c + requestNewFortune() slot: + + \snippet examples/network/fortuneclient/client.cpp 6 + + In this slot, we initialize \c blockSize to 0, preparing to read a new block + of data. Because we allow the user to click \gui{Get Fortune} before the + previous connection finished closing, we start off by aborting the + previous connection by calling QTcpSocket::abort(). (On an unconnected + socket, this function does nothing.) We then proceed to connecting to the + fortune server by calling QTcpSocket::connectToHost(), passing the + hostname and port from the user interface as arguments. + + As a result of calling \l{QTcpSocket::connectToHost()}{connectToHost()}, + one of two things can happen: + + \list + \o \e{The connection is established.} In this case, the server will send us a + fortune. QTcpSocket will emit \l{QTcpSocket::readyRead()}{readyRead()} + every time it receives a block of data. + + \o \e{An error occurs.} We need to inform the user if the connection + failed or was broken. In this case, QTcpSocket will emit + \l{QTcpSocket::error()}{error()}, and \c Client::displayError() will be + called. + \endlist + + Let's go through the \l{QTcpSocket::error()}{error()} case first: + + \snippet examples/network/fortuneclient/client.cpp 13 + + We pop up all errors in a dialog using + QMessageBox::information(). QTcpSocket::RemoteHostClosedError is silently + ignored, because the fortune server protocol ends with the server closing + the connection. + + Now for the \l{QTcpSocket::readyRead()}{readyRead()} alternative. This + signal is connected to \c Client::readFortune(): + + \snippet examples/network/fortuneclient/client.cpp 8 + \codeline + \snippet examples/network/fortuneclient/client.cpp 10 + + The protocol is based on QDataStream, so we start by creating a stream + object, passing the socket to QDataStream's constructor. We then + explicitly set the protocol version of the stream to QDataStream::Qt_4_0 + to ensure that we're using the same version as the fortune server, no + matter which version of Qt the client and server use. + + Now, TCP is based on sending a stream of data, so we cannot expect to get + the entire fortune in one go. Especially on a slow network, the data can + be received in several small fragments. QTcpSocket buffers up all incoming + data and emits \l{QTcpSocket::readyRead()}{readyRead()} for every new + block that arrives, and it is our job to ensure that we have received all + the data we need before we start parsing. The server's response starts + with the size of the packet, so first we need to ensure that we can read + the size, then we will wait until QTcpSocket has received the full packet. + + \snippet examples/network/fortuneclient/client.cpp 11 + \codeline + \snippet examples/network/fortuneclient/client.cpp 12 + + We proceed by using QDataStream's streaming operator to read the fortune + from the socket into a QString. Once read, we can call QLabel::setText() + to display the fortune. + + \sa {Fortune Server Example}, {Blocking Fortune Client Example} +*/ diff --git a/doc/src/examples/fortuneserver.qdoc b/doc/src/examples/fortuneserver.qdoc new file mode 100644 index 0000000000..8007b3dd2c --- /dev/null +++ b/doc/src/examples/fortuneserver.qdoc @@ -0,0 +1,105 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example network/fortuneserver + \title Fortune Server Example + + The Fortune Server example shows how to create a server for a simple + network service. It is intended to be run alongside the + \l{network/fortuneclient}{Fortune Client} example or the + \l{network/blockingfortuneclient}{Blocking Fortune Client} example. + + \image fortuneserver-example.png Screenshot of the Fortune Server example + + This example uses QTcpServer to accept incoming TCP connections, and a + simple QDataStream based data transfer protocol to write a fortune to the + connecting client (from the \l{network/fortuneclient}{Fortune Client} + example), before closing the connection. + + \snippet examples/network/fortuneserver/server.h 0 + + The server is implemented using a simple class with only one slot, for + handling incoming connections. + + \snippet examples/network/fortuneserver/server.cpp 1 + + In its constructor, our Server object calls QTcpServer::listen() to set up + a QTcpServer to listen on all addresses, on an arbitrary port. In then + displays the port QTcpServer picked in a label, so that user knows which + port the fortune client should connect to. + + \snippet examples/network/fortuneserver/server.cpp 2 + + Our server generates a list of random fortunes that is can send to + connecting clients. + + \snippet examples/network/fortuneserver/server.cpp 3 + + When a client connects to our server, QTcpServer will emit + QTcpServer::newConnection(). In turn, this will invoke our + sendFortune() slot: + + \snippet examples/network/fortuneserver/server.cpp 4 + + The purpose of this slot is to select a random line from our list of + fortunes, encode it into a QByteArray using QDataStream, and then write it + to the connecting socket. This is a common way to transfer binary data + using QTcpSocket. First we create a QByteArray and a QDataStream object, + passing the bytearray to QDataStream's constructor. We then explicitly set + the protocol version of QDataStream to QDataStream::Qt_4_0 to ensure that + we can communicate with clients from future versions of Qt. (See + QDataStream::setVersion().) + + \snippet examples/network/fortuneserver/server.cpp 6 + + At the start of our QByteArray, we reserve space for a 16 bit integer that + will contain the total size of the data block we are sending. We continue + by streaming in a random fortune. Then we seek back to the beginning of + the QByteArray, and overwrite the reserved 16 bit integer value with the + total size of the array. By doing this, we provide a way for clients to + verify how much data they can expect before reading the whole packet. + + \snippet examples/network/fortuneserver/server.cpp 7 + + We then call QTcpServer::newPendingConnection(), which returns the + QTcpSocket representing the server side of the connection. By connecting + QTcpSocket::disconnected() to QObject::deleteLater(), we ensure that the + socket will be deleted after disconnecting. + + \snippet examples/network/fortuneserver/server.cpp 8 + + The encoded fortune is written using QTcpSocket::write(), and we finally + call QTcpSocket::disconnectFromHost(), which will close the connection + after QTcpSocket has finished writing the fortune to the network. Because + QTcpSocket works asynchronously, the data will be written after this + function returns, and control goes back to Qt's event loop. The socket + will then close, which in turn will cause QObject::deleteLater() to delete + it. + + \sa {Fortune Client Example}, {Threaded Fortune Server Example} + */ diff --git a/doc/src/examples/framebufferobject2.qdoc b/doc/src/examples/framebufferobject2.qdoc new file mode 100644 index 0000000000..7f5a634325 --- /dev/null +++ b/doc/src/examples/framebufferobject2.qdoc @@ -0,0 +1,37 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example opengl/framebufferobject2 + \title Framebuffer Object 2 Example + + The Framebuffer Object 2 example demonstrates how to use the + QGLFramebufferObject class to render into an off-screen buffer and + use the contents as a texture in a QGLWidget. + + \image framebufferobject2-example.png +*/ diff --git a/doc/src/examples/fridgemagnets.qdoc b/doc/src/examples/fridgemagnets.qdoc new file mode 100644 index 0000000000..98811b847f --- /dev/null +++ b/doc/src/examples/fridgemagnets.qdoc @@ -0,0 +1,360 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example draganddrop/fridgemagnets + \title Fridge Magnets Example + + The Fridge Magnets example shows how to supply more than one type + of MIME-encoded data with a drag and drop operation. + + \image fridgemagnets-example.png + + With this application the user can play around with a collection + of fridge magnets, using drag and drop to form new sentences from + the words on the magnets. The example consists of two classes: + + \list + \o \c DragLabel is a custom widget representing one + single fridge magnet. + \o \c DragWidget provides the main application window. + \endlist + + We will first take a look at the \c DragLabel class, then we will + examine the \c DragWidget class. + + \section1 DragLabel Class Definition + + Each fridge magnet is represented by an instance of the \c + DragLabel class: + + \snippet examples/draganddrop/fridgemagnets/draglabel.h 0 + + Each instance of this QLabel subclass will be used to display an + pixmap generated from a text string. Since we cannot store both + text and a pixmap in a standard label, we declare a private variable + to hold the original text, and we define an additional member + function to allow it to be accessed. + + \section1 DragLabel Class Implementation + + In the \c DragLabel constructor, we first create a QImage object + on which we will draw the fridge magnet's text and frame: + + \snippet examples/draganddrop/fridgemagnets/draglabel.cpp 0 + + Its size depends on the current font size, and its format is + QImage::Format_ARGB32_Premultiplied; i.e., the image is stored + using a premultiplied 32-bit ARGB format (0xAARRGGBB). + + We then construct a font object that uses the application's + default font, and set its style strategy. The style strategy tells + the font matching algorithm what type of fonts should be used to + find an appropriate default family. The QFont::ForceOutline forces + the use of outline fonts. + + To draw the text and frame onto the image, we use the QPainter + class. QPainter provides highly optimized methods to do most of + the drawing GUI programs require. It can draw everything from + simple lines to complex shapes like pies and chords. It can also + draw aligned text and pixmaps. + + \snippet examples/draganddrop/fridgemagnets/draglabel.cpp 1 + + A painter can be activated by passing a paint device to the + constructor, or by using the \l{QPainter::}{begin()} method as we + do in this example. The \l{QPainter::}{end()} method deactivates + it. Note that the latter function is called automatically upon + destruction when the painter is actived by its constructor. The + QPainter::Antialiasing render hint ensures that the paint engine + will antialias the edges of primitives if possible. + + When the painting is done, we convert our image to a pixmap using + QPixmap's \l {QPixmap::}{fromImage()} method. This method also + takes an optional flags argument, and converts the given image to + a pixmap using the specified flags to control the conversion (the + flags argument is a bitwise-OR of the Qt::ImageConversionFlags; + passing 0 for flags sets all the default options). + + \snippet examples/draganddrop/fridgemagnets/draglabel.cpp 2 + + Finally, we set the label's \l{QLabel::pixmap}{pixmap property} + and store the label's text for later use. + + \e{Note that setting the pixmap clears any previous content, including + any text previously set using QLabel::setText(), and disables + the label widget's buddy shortcut, if any.} + + \section1 DragWidget Class Definition + + The \c DragWidget class inherits QWidget, providing support for + drag and drop operations: + + \snippet examples/draganddrop/fridgemagnets/dragwidget.h 0 + + To make the widget responsive to drag and drop operations, we simply + reimplement the \l{QWidget::}{dragEnterEvent()}, + \l{QWidget::}{dragMoveEvent()} and \l{QWidget::}{dropEvent()} event + handlers inherited from QWidget. + + We also reimplement \l{QWidget::}{mousePressEvent()} to make the + widget responsive to mouse clicks. This is where we will write code + to start drag and drop operations. + + \section1 DragWidget Class Implementation + + In the constructor, we first open the file containing the words on + our fridge magnets: + + \snippet examples/draganddrop/fridgemagnets/dragwidget.cpp 0 + + QFile is an I/O device for reading and writing text and binary + files and resources, and may be used by itself or in combination + with QTextStream or QDataStream. We have chosen to read the + contents of the file using the QTextStream class that provides a + convenient interface for reading and writing text. + + We then create the fridge magnets. As long as there is data (the + QTextStream::atEnd() method returns true if there is no more data + to be read from the stream), we read one line at a time using + QTextStream's \l {QTextStream::}{readLine()} method. + + \snippet examples/draganddrop/fridgemagnets/dragwidget.cpp 1 + + For each line, we create a \c DragLabel object using the read line + as text, we calculate its position and ensure that it is visible by + calling the QWidget::show() method. We set the Qt::WA_DeleteOnClose + attribute on each label to ensure that any unused labels will be + deleted; we will need to create new labels and delete old ones when + they are dragged around, and this ensures that the example does not + leak memory. + + We also set the \c FridgeMagnets widget's palette, minimum size + and window title. + + \snippet examples/draganddrop/fridgemagnets/dragwidget.cpp 2 + + Finally, to enable our user to move the fridge magnets around, we + must also set the \c FridgeMagnets widget's + \l{QWidget::acceptDrops}{acceptDrops} property. + + \snippet examples/draganddrop/fridgemagnets/dragwidget.cpp 3 + + Setting this property to true announces to the system that this + widget \e may be able to accept drop events (events that are sent + when drag and drop actions are completed). Later, we will + implement the functions that ensure that the widget accepts the + drop events it is interested in. + + \section2 Dragging + + Let's take a look at the \l{QWidget::}{mousePressEvent()} event + handler, where drag and drop operations begin: + + \snippet examples/draganddrop/fridgemagnets/dragwidget.cpp 13 + \snippet examples/draganddrop/fridgemagnets/dragwidget.cpp 14 + + Mouse events occur when a mouse button is pressed or released + inside a widget, or when the mouse cursor is moved. By + reimplementing the \l{QWidget::}{mousePressEvent()} method we + ensure that we will receive mouse press events for the widget + containing the fridge magnets. + + Whenever we receive such an event, we first check to see if the + position of the click coincides with one of the labels. If not, + we simply return. + + If the user clicked a label, we determine the position of the + \e{hot spot} (the position of the click relative to the top-left + corner of the label). We create a byte array to store the label's + text and the hot spot, and we use a QDataStream object to stream + the data into the byte array. + + With all the information in place, we create a new QMimeData object. + As mentioned above, QMimeData objects associate the data that they + hold with the corresponding MIME types to ensure that information + can be safely transferred between applications. The + \l{QMimeData::}{setData()} method sets the data associated with a + given MIME type. In our case, we associate our item data with the + custom \c application/x-fridgemagnet type. + + \snippet examples/draganddrop/fridgemagnets/dragwidget.cpp 15 + + Note that we also associate the magnet's text with the + \c text/plain MIME type using QMimeData's \l{QMimeData::}{setText()} + method. Below, we will see how our widget detects both these MIME + types with its event handlers. + + Finally, we create a QDrag object. It is the QDrag class that + handles most of the details of a drag and drop operation, + providing support for MIME-based drag and drop data transfer. The + data to be transferred by the drag and drop operation is contained + in a QMimeData object. When we call QDrag's + \l{QDrag::}{setMimeData()} method the ownership of our item data is + transferred to the QDrag object. + + We call the \l{QDrag::}{setPixmap()} function to set the pixmap used + to represent the data during the drag and drop operation. + Typically, this pixmap shows an icon that represents the MIME type + of the data being transferred, but any pixmap can be used. In this + example, we simply use the pixmap used by the label itself to make + it look like the fridge magnet itself is being moved. + + \snippet examples/draganddrop/fridgemagnets/dragwidget.cpp 16 + + We also specify the cursor's hot spot, its position relative to the + top-level corner of the drag pixmap, to be the point we calculated + above. This makes the process of dragging the label feel more natural + because the cursor always points to the same place on the label + during the drag operation. + + We start the drag operation using QDrag's \l{QDrag::}{exec()} function, + requesting that the magnet is copied when the drag is completed. + + \snippet examples/draganddrop/fridgemagnets/dragwidget.cpp 17 + + The function returns the drop action actually performed by the user + (this can be either a copy or a move action in this case); if this + action is equal to Qt::MoveAction we will close the activated + fridge magnet widget because we will create a new one to replace it + (see the \l{drop}{dropEvent()} implementation). Otherwise, if + the drop is outside our main widget, we simply show the widget in + its original position. + + \section2 Dropping + + When a a drag and drop action enters our widget, we will receive a + drag enter \e event. QDragEnterEvent inherits most of its + functionality from QDragMoveEvent, which in turn inherits most of + its functionality from QDropEvent. Note that we must accept this + event in order to receive the drag move events that are sent while + the drag and drop action is in progress. The drag enter event is + always immediately followed by a drag move event. + + In our \c dragEnterEvent() implementation, we first determine + whether we support the event's MIME type or not: + + \snippet examples/draganddrop/fridgemagnets/dragwidget.cpp 4 + \snippet examples/draganddrop/fridgemagnets/dragwidget.cpp 5 + \snippet examples/draganddrop/fridgemagnets/dragwidget.cpp 6 + + If the type is \c application/x-fridgemagnet and the event + origins from any of this application's fridge magnet widgets, we + first set the event's drop action using the + QDropEvent::setDropAction() method. An event's drop action is the + action to be performed on the data by the target. Qt::MoveAction + indicates that the data is moved from the source to the target. + + Then we call the event's \l {QDragMoveEvent::}{accept()} method to + indicate that we have handled the event. In general, unaccepted + events might be propagated to the parent widget. If the event + origins from any other widget, we simply accept the proposed + action. + + \snippet examples/draganddrop/fridgemagnets/dragwidget.cpp 7 + + We also accept the proposed action if the event's MIME type is \c + text/plain, i.e., if QMimeData::hasText() returns true. If the + event has any other type, on the other hand, we call the event's + \l {QDragMoveEvent::}{ignore()} method allowing the event to be + propagated further. + + \snippet examples/draganddrop/fridgemagnets/dragwidget.cpp 8 + + Drag move events occur when the cursor enters a widget, when it + moves within the widget, and when a modifier key is pressed on the + keyboard while the widget has focus. Our widget will receive drag + move events repeatedly while a drag is within its boundaries. We + reimplement the \l {QWidget::}{dragMoveEvent()} method, and + examine the event in the exact same way as we did with drag enter + events. + + Note that the \l{QWidget::}{dropEvent()} event handler behaves + slightly differently: We first get hold of the event's MIME + data. + + \target drop + \snippet examples/draganddrop/fridgemagnets/dragwidget.cpp 9 + + The QMimeData class provides a container for data that + records information about its MIME type. QMimeData objects + associate the data that they hold with the corresponding MIME + types to ensure that information can be safely transferred between + applications, and copied around within the same application. + + We retrieve the data associated with the \c application/x-fridgemagnet + MIME type using a data stream in order to create a new \c DragLabel + object. + + \snippet examples/draganddrop/fridgemagnets/dragwidget.cpp 10 + + The QDataStream class provides serialization of binary data to a + QIODevice (a data stream is a binary stream of encoded information + which is completely independent of the host computer's operating + system, CPU or byte order). + + Finally, we create a label and move it to the event's position: + + \snippet examples/draganddrop/fridgemagnets/dragwidget.cpp 11 + + If the source of the event is also the widget receiving the + drop event, we set the event's drop action to Qt::MoveAction and + call the event's \l{QDragMoveEvent::}{accept()} + method. Otherwise, we simply accept the proposed action. This + means that labels are moved rather than copied in the same + window. However, if we drag a label to a second instance of the + Fridge Magnets example, the default action is to copy it, leaving + the original in the first instance. + + If the event's MIME type is \c text/plain (i.e., if + QMimeData::hasText() returns true) we retrieve its text and split + it into words. For each word we create a new \c DragLabel action, + and show it at the event's position plus an offset depending on + the number of words in the text. In the end we accept the proposed + action. This lets the user drop selected text from a text editor or + Web browser onto the widget to add more fridge magnets. + + \snippet examples/draganddrop/fridgemagnets/dragwidget.cpp 12 + + If the event has any other type, we call the event's + \l{QDragMoveEvent::}{ignore()} method allowing the event to be + propagated further. + + \section1 Summary + + We set our main widget's \l{QWidget::}{acceptDrops} property + and reimplemented QWidget's \l{QWidget::}{dragEnterEvent()}, + \l{QWidget::}{dragMoveEvent()} and \l{QWidget::}{dropEvent()} event + handlers to support content dropped on our widget. + + In addition, we reimplemented the \l{QWidget::}{mousePressEvent()} + function to let the user pick up fridge magnets in the first place. + + Because data is communicated using drag and drop operations and + encoded using MIME types, you can run more than one instance of this + example, and transfer magnets between them. +*/ diff --git a/doc/src/examples/frozencolumn.qdoc b/doc/src/examples/frozencolumn.qdoc new file mode 100644 index 0000000000..5840444c5d --- /dev/null +++ b/doc/src/examples/frozencolumn.qdoc @@ -0,0 +1,133 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example itemviews/frozencolumn + \title Frozen Column Example + + This example demonstrates how to freeze a column within a QTableView. + + \image frozencolumn-example.png "Screenshot of the example" + + We use Qt's model/view framework to implement a table with its first + column frozen. This technique can be aplied to several columns or rows, + as long as they are on the edge of the table. + + The model/view framework allows for one model to be displayed in different + ways using multiple views. For this example, we use two views on the same + model - two \l {QTableView}{table views} sharing one model. The frozen + column is a child of the main tableview, and we provide the desired visual + effect using an overlay technique which will be described step by step in + the coming sections. + + \image frozencolumn-tableview.png + + + \section1 FreezeTableWidget Class Definition + + The \c FreezeTableWidget class has a constructor and a destructor. Also, it + has two private members: the table view that we will use as an overlay, and + the shared model for both table views. Two slots are added to help keep the + section sizes in sync, as well as a function to readjust the frozen + column's geometry. In addition, we reimplement two functions: + \l{QAbstractItemView::}{resizeEvent()} and \l{QTableView::}{moveCursor()}. + + \snippet examples/itemviews/frozencolumn/freezetablewidget.h Widget definition + + \note QAbstractItemView is \l{QTableView}'s ancestor. + + + \section1 FreezeTableWidget Class Implementation + + The constructor takes \a model as an argument and creates a table view that + we will use to display the frozen column. Then, within the constructor, we + invoke the \c init() function to set up the frozen column. Finally, we + connect the \l{QHeaderView::sectionResized()} signals (for horizontal and + vertical headers) to the appropriate slots. This ensures that our frozen + column's sections are in sync with the headers. We also connect the + vertical scrollbars together so that the frozen column scrolls vertically + with the rest of our table. + + \snippet examples/itemviews/frozencolumn/freezetablewidget.cpp constructor + + + In the \c init() function, we ensure that the overlay table view + responsible for displaying the frozen column, is set up properly. This + means that this table view, \c frozenTableView, has to have the same model + as the main table view. However, the difference here is: \c frozenTableView's + only visible column is its first column; we hide the others using + \l{QTableView::}{setColumnHidden()} + + \snippet examples/itemviews/frozencolumn/freezetablewidget.cpp init part1 + + + In terms of the frozen column's z-order, we stack it on top of the + viewport. This is achieved by calling \l{QWidget::}{stackUnder()} on the + viewport. For appearance's sake, we prevent the column from stealing focus + from the main tableview. Also, we make sure that both views share the same + selection model, so only one cell can be selected at a time. A few other + tweaks are done to make our application look good and behave consistently + with the main tableview. Note that we called \c updateFrozenTableGeometry() + to make the column occupy the correct spot. + + \snippet examples/itemviews/frozencolumn/freezetablewidget.cpp init part2 + + When you resize the frozen column, the same column on the main table view + must resize accordingly, to provide seamless integration. This is + accomplished by getting the new size of the column from the \c newSize + value from the \l{QHeaderView::}{sectionResized()} signal, emitted by both + the horizontal and vertical header. + + \snippet examples/itemviews/frozencolumn/freezetablewidget.cpp sections + + Since the width of the frozen column is modified, we adjust the geometry of + the widget accordingly by invoking \c updateFrozenTableGeometry(). This + function is further explained below. + + In our reimplementation of QTableView::resizeEvent(), we call + \c updateFrozenTableGeometry() after invoking the base class + implementation. + + \snippet examples/itemviews/frozencolumn/freezetablewidget.cpp resize + + When navigating around the table with the keyboard, we need to ensure that + the current selection does not disappear behind the frozen column. To + synchronize this, we reimplement QTableView::moveCursor() and adjust the + scrollbar positions if needed, after calling the base class implementation. + + \snippet examples/itemviews/frozencolumn/freezetablewidget.cpp navigate + + The frozen column's geometry calculation is based on the geometry of the + table underneath, so it always appears in the right place. Using the + QFrame::frameWidth() function helps to calculate this geometry correctly, + no matter which style is used. We rely on the geometry of the viewport and + headers to set the boundaries for the frozen column. + + \snippet examples/itemviews/frozencolumn/freezetablewidget.cpp geometry + +*/ + diff --git a/doc/src/examples/googlesuggest.qdoc b/doc/src/examples/googlesuggest.qdoc new file mode 100644 index 0000000000..45d5fbb6ac --- /dev/null +++ b/doc/src/examples/googlesuggest.qdoc @@ -0,0 +1,180 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example network/googlesuggest + \title Google Suggest Example + + The Google Suggest example demonstrates how to use the QNetworkAccessManager + class to obtain a list of suggestions from the Google search engine as the + user types into a QLineEdit. + + \image googlesuggest-example.png + + The application makes use of the \c get function in + QNetworkAccessManager to post a request and obtain the result of the search + query sent to the Google search engine. The results returned are listed as + clickable links appearing below the search box as a drop-down menu. + + The widget is built up by a QLineEdit as the search box, and a QTreeView + used as a popup menu below the search box. + + \section1 GSuggestCompletion Class Declaration + + This class implements an event filter and a number of functions to display + the search results and to determent when and how to perform the search. + + \snippet examples/network/googlesuggest/googlesuggest.h 1 + + The class connects to a QLineEdit and uses a QTreeWidget to display the + results. A QTimer controls the start of the network requests that are + executed using a QNetworkAccessManager. + + \section1 GSuggestCompletion Class Implementation + + We start by defining a constant containing the URL to be used in the Google + queries. This is the basis for the query. The letters typed into the search + box will be added to the query to perform the search itself. + + \snippet examples/network/googlesuggest/googlesuggest.cpp 1 + + In the constructor, we set the parent of this GSuggestCompletion instance + to be the QLineEdit passed in. For simplicity, the QLineEdit is also stored + in the explicit \c editor member variable. + + We then create a QTreeWidget as a toplevel widget and configure the various + properties to give it the look of a popup widget. + + The popup will be populated by the results returned from Google. We set + the number of columns to be two, since we want to display both the + suggested search term and the number of hits it will trigger in the search + engine. + + Furthermore, we install the GSuggestCompletion instance as an event filter + on the QTreeWidget, and connect the \c itemClicked() signal with the \c + doneCompletion() slot. + + A single-shot QTimer is used to start the request when the user has stopped + typing for 500 ms. + + Finally, we connect the networkManagers \c finished() signal with the \c + handleNetworkData() slot to handle the incoming data. + + \snippet examples/network/googlesuggest/googlesuggest.cpp 2 + + Since the QTreeWidget popup has been instantiated as a toplevel widget, the + destructor has to delete it explicitly from memory to avoid a memory leak. + + \snippet examples/network/googlesuggest/googlesuggest.cpp 3 + + The event filter handles mouse press and key press events that are + delivered to the popup. For mouse press events we just hide the popup and + return focus to the editor widget, and then return true to prevent further + event processing. + + Key event handling is implemented so that Enter and Return execute the + selected link, while the Escape key hides the popup. Since we want to be + able to navigate the list of suggestions using the different navigation + keys on the keyboard we let Qt continue regular event processing for those + by returning false from the eventFilter reimplementation. + + For all other keys, the event will be passed on to the editor widget and the + popup is hidden. This way the user's typing will not be interrupted by the + popping up of the completion list. + + \snippet examples/network/googlesuggest/googlesuggest.cpp 4 + + The \c showCompletion() function populates the QTreeWidget with the results + returned from the query. It takes two QStringLists, one with the suggested + search terms and the other with the corresponding number of hits. + + \snippet examples/network/googlesuggest/googlesuggest.cpp 5 + + A QTreeWidgetItem is created for each index in the list and inserted into + the QTreeWidget. Finally, we adjust position and size of the popup to make + sure that it pops up in the correct position below the editor, and show it. + + The \c doneCompletion() function, which is called by the event filter when + either Enter or Return keys are pressed, stops the timer to prevent further + requests and passes the text of the selected item to the editor. We then + make the \c editor QLineEdit emit the returnPressed() signal, to which the + application can connect to open the respective web page. + + \snippet examples/network/googlesuggest/googlesuggest.cpp 6 + + The \c autoSuggest() slot is called when the timer times out, and uses the + text in the editor to build the complete search query. The query is then + passed to the QNetworkAccessManager's \c get() function to start the + request. + + \snippet examples/network/googlesuggest/googlesuggest.cpp 7 + + The function \c preventSuggest() stops the timer to prevent further + requests from being started. + + \snippet examples/network/googlesuggest/googlesuggest.cpp 8 + + When the network request is finished, the QNetworkAccessManager delivers the + data received from the server through the networkReply object. + + \snippet examples/network/googlesuggest/googlesuggest.cpp 9 + + To extract the data from the reply we use the \c readAll() function, which + is inherited from QIODevice and returns a QByteArray. Since this data is + encoded in XML we can use a QXmlStreamReader to traverse the data and + extract the search result as QStrings, which we can stream into two + QStringLists used to populate the popup. + + Finally, we schedule the QNetworkReply object for deletion using the \c + deleteLater function. + + \section1 SearchBox Class Declaration + + The SearchBox class inherits QLineEdit and adds the protected slot \c + doSearch(). + + A \c GSuggestCompletion member provides the SearchBox with the request + functionality and the suggestions returned from the Google search engine. + + \snippet examples/network/googlesuggest/searchbox.h 1 + + \section1 SearchBox Class Implementation + + The search box constructor instantiates the GSuggestCompletion object and + connects the returnPressed() signal to the doSearch() slot. + + \snippet examples/network/googlesuggest/searchbox.cpp 1 + + The function \c doSearch() stops the completer from sending any further + queries to the search engine. + + Further, the function extracts the selected search phrase and opens it + in the default web browser using QDesktopServices. + + \snippet examples/network/googlesuggest/searchbox.cpp 2 + +*/ diff --git a/doc/src/examples/grabber.qdoc b/doc/src/examples/grabber.qdoc new file mode 100644 index 0000000000..d5e2512c49 --- /dev/null +++ b/doc/src/examples/grabber.qdoc @@ -0,0 +1,35 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example opengl/grabber + \title Grabber Example + + The Grabber examples shows how to retrieve the contents of an OpenGL framebuffer. + + \image grabber-example.png +*/ diff --git a/doc/src/examples/groupbox.qdoc b/doc/src/examples/groupbox.qdoc new file mode 100644 index 0000000000..87dd92e63b --- /dev/null +++ b/doc/src/examples/groupbox.qdoc @@ -0,0 +1,140 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example widgets/groupbox + \title Group Box Example + + The Group Box example shows how to use the different kinds of group + boxes in Qt. + + Group boxes are container widgets that organize buttons into groups, + both logically and on screen. They manage the interactions between + the user and the application so that you do not have to enforce + simple constraints. + + Group boxes are usually used to organize check boxes and radio + buttons into exclusive groups. + + \image groupbox-example.png + + The Group Boxes example consists of a single \c Window class that + is used to show four group boxes: an exclusive radio button group, + a non-exclusive checkbox group, an exclusive radio button group + with an enabling checkbox, and a group box with normal push buttons. + + \section1 Window Class Definition + + The \c Window class is a subclass of \c QWidget that is used to + display a number of group boxes. The class definition contains + functions to construct each group box and populate it with different + selections of button widgets: + + \snippet examples/widgets/groupbox/window.h 0 + + In the example, the widget will be used as a top-level window, so + the constructor is defined so that we do not have to specify a parent + widget. + + \section1 Window Class Implementation + + The constructor creates a grid layout and fills it with each of the + group boxes that are to be displayed: + + \snippet examples/widgets/groupbox/window.cpp 0 + + The functions used to create each group box each return a + QGroupBox to be inserted into the grid layout. + + \snippet examples/widgets/groupbox/window.cpp 1 + + The first group box contains and manages three radio buttons. Since + the group box contains only radio buttons, it is exclusive by + default, so only one radio button can be checked at any given time. + We check the first radio button to ensure that the button group + contains one checked button. + + \snippet examples/widgets/groupbox/window.cpp 3 + + We use a vertical layout within the group box to present the + buttons in the form of a vertical list, and return the group + box to the constructor. + + The second group box is itself checkable, providing a convenient + way to disable all the buttons inside it. Initially, it is + unchecked, so the group box itself must be checked before any of + the radio buttons inside can be checked. + + \snippet examples/widgets/groupbox/window.cpp 4 + + The group box contains three exclusive radio buttons, and an + independent checkbox. For consistency, one radio button must be + checked at all times, so we ensure that the first one is initially + checked. + + \snippet examples/widgets/groupbox/window.cpp 5 + + The buttons are arranged in the same way as those in the first + group box. + + \snippet examples/widgets/groupbox/window.cpp 6 + + The third group box is constructed with a "flat" style that is + better suited to certain types of dialog. + + \snippet examples/widgets/groupbox/window.cpp 7 + + This group box contains only checkboxes, so it is non-exclusive by + default. This means that each checkbox can be checked independently + of the others. + + \snippet examples/widgets/groupbox/window.cpp 8 + + Again, we use a vertical layout within the group box to present + the buttons in the form of a vertical list. + + \snippet examples/widgets/groupbox/window.cpp 9 + + The final group box contains only push buttons and, like the + second group box, it is checkable. + + \snippet examples/widgets/groupbox/window.cpp 10 + + We create a normal button, a toggle button, and a flat push button: + + \snippet examples/widgets/groupbox/window.cpp 11 + + Push buttons can be used to display popup menus. We create one, and + attach a simple menu to it: + + \snippet examples/widgets/groupbox/window.cpp 12 + + Finally, we lay out the widgets vertically, and return the group box + that we created: + + \snippet examples/widgets/groupbox/window.cpp 13 +*/ diff --git a/doc/src/examples/hellogl.qdoc b/doc/src/examples/hellogl.qdoc new file mode 100644 index 0000000000..b66eae97d3 --- /dev/null +++ b/doc/src/examples/hellogl.qdoc @@ -0,0 +1,305 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example opengl/hellogl + \title Hello GL Example + + The Hello GL example demonstrates the basic use of the OpenGL-related classes + provided with Qt. + + \image hellogl-example.png + + Qt provides the QGLWidget class to enable OpenGL graphics to be rendered within + a standard application user interface. By subclassing this class, and providing + reimplementations of event handler functions, 3D scenes can be displayed on + widgets that can be placed in layouts, connected to other objects using signals + and slots, and manipulated like any other widget. + + \tableofcontents + + \section1 GLWidget Class Definition + + The \c GLWidget class contains some standard public definitions for the + constructor, destructor, \l{QWidget::sizeHint()}{sizeHint()}, and + \l{QWidget::minimumSizeHint()}{minimumSizeHint()} functions: + + \snippet examples/opengl/hellogl/glwidget.h 0 + + We use a destructor to ensure that any OpenGL-specific data structures + are deleted when the widget is no longer needed (although in this case nothing + needs cleaning up). + + \snippet examples/opengl/hellogl/glwidget.h 1 + + The signals and slots are used to allow other objects to interact with the + 3D scene. + + \snippet examples/opengl/hellogl/glwidget.h 2 + + OpenGL initialization, viewport resizing, and painting are handled by + reimplementing the QGLWidget::initializeGL(), QGLWidget::resizeGL(), and + QGLWidget::paintGL() handler functions. To enable the user to interact + directly with the scene using the mouse, we reimplement + QWidget::mousePressEvent() and QWidget::mouseMoveEvent(). + + \snippet examples/opengl/hellogl/glwidget.h 3 + + The rest of the class contains utility functions and variables that are + used to construct and hold orientation information for the scene. The + \c logo variable will be used to hold a pointer to the QtLogo object which + contains all the geometry. + + \section1 GLWidget Class Implementation + + In this example, we split the class into groups of functions and describe + them separately. This helps to illustrate the differences between subclasses + of native widgets (such as QWidget and QFrame) and QGLWidget subclasses. + + \section2 Widget Construction and Sizing + + The constructor provides default rotation angles for the scene, sets + the pointer to the QtLogo object to null, and sets up some colors for + later use. + + \snippet examples/opengl/hellogl/glwidget.cpp 0 + + We also implement a destructor to release OpenGL-related resources when the + widget is deleted: + + \snippet examples/opengl/hellogl/glwidget.cpp 1 + + In this case nothing requires cleaning up. + + We provide size hint functions to ensure that the widget is shown at a + reasonable size: + + \snippet examples/opengl/hellogl/glwidget.cpp 2 + \codeline + \snippet examples/opengl/hellogl/glwidget.cpp 3 + \snippet examples/opengl/hellogl/glwidget.cpp 4 + + The widget provides three slots that enable other components in the + example to change the orientation of the scene: + + \snippet examples/opengl/hellogl/glwidget.cpp 5 + + In the above slot, the \c xRot variable is updated only if the new angle + is different to the old one, the \c xRotationChanged() signal is emitted to + allow other components to be updated, and the widget's + \l{QGLWidget::updateGL()}{updateGL()} handler function is called. + + The \c setYRotation() and \c setZRotation() slots perform the same task for + rotations measured by the \c yRot and \c zRot variables. + + \section2 OpenGL Initialization + + The \l{QGLWidget::initializeGL()}{initializeGL()} function is used to + perform useful initialization tasks that are needed to render the 3D scene. + These often involve defining colors and materials, enabling and disabling + certain rendering flags, and setting other properties used to customize the + rendering process. + + \snippet examples/opengl/hellogl/glwidget.cpp 6 + + In this example, we reimplement the function to set the background color, + create a QtLogo object instance which will contain all the geometry to + display, and set up the rendering process to use a particular shading model + and rendering flags. + + \section2 Resizing the Viewport + + The \l{QGLWidget::resizeGL()}{resizeGL()} function is used to ensure that + the OpenGL implementation renders the scene onto a viewport that matches the + size of the widget, using the correct transformation from 3D coordinates to + 2D viewport coordinates. + + The function is called whenever the widget's dimensions change, and is + supplied with the new width and height. Here, we define a square viewport + based on the length of the smallest side of the widget to ensure that + the scene is not distorted if the widget has sides of unequal length: + + \snippet examples/opengl/hellogl/glwidget.cpp 8 + + A discussion of the projection transformation used is outside the scope of + this example. Please consult the OpenGL reference documentation for an + explanation of projection matrices. + + \section2 Painting the Scene + + The \l{QGLWidget::paintGL()}{paintGL()} function is used to paint the + contents of the scene onto the widget. For widgets that only need to be + decorated with pure OpenGL content, we reimplement QGLWidget::paintGL() + \e instead of reimplementing QWidget::paintEvent(): + + \snippet examples/opengl/hellogl/glwidget.cpp 7 + + In this example, we clear the widget using the background color that + we defined in the \l{QGLWidget::initializeGL()}{initializeGL()} function, + set up the frame of reference for the geometry we want to display, and + call the draw method of the QtLogo object to render the scene. + + \section2 Mouse Handling + + Just as in subclasses of native widgets, mouse events are handled by + reimplementing functions such as QWidget::mousePressEvent() and + QWidget::mouseMoveEvent(). + + The \l{QWidget::mousePressEvent()}{mousePressEvent()} function simply + records the position of the mouse when a button is initially pressed: + + \snippet examples/opengl/hellogl/glwidget.cpp 9 + + The \l{QWidget::mouseMoveEvent()}{mouseMoveEvent()} function uses the + previous location of the mouse cursor to determine how much the object + in the scene should be rotated, and in which direction: + + \snippet examples/opengl/hellogl/glwidget.cpp 10 + + Since the user is expected to hold down the mouse button and drag the + cursor to rotate the object, the cursor's position is updated every time + a move event is received. + + \section1 QtLogo Class + + This class encapsulates the OpenGL geometry data which will be rendered + in the basic 3D scene. + + \snippet examples/opengl/shared/qtlogo.h 0 + + The geometry is divided into a list of parts which may be rendered in + different ways. The data itself is contained in a Geometry structure that + includes the vertices, their lighting normals and index values which + point into the vertices, grouping them into faces. + + \snippet examples/opengl/shared/qtlogo.cpp 0 + + The data in the Geometry class is stored in QVector<QVector3D> members + which are convenient for use with OpenGL because they expose raw + contiguous floating point values via the constData() method. Methods + are included for adding new vertex data, either with smooth normals, or + facetted normals; and for enabling the geometry ready for rendering. + + \snippet examples/opengl/shared/qtlogo.cpp 1 + + The higher level Patch class has methods for accumulating the geometry + one face at a time, and treating collections of faces or "patches" with + transformations, applying different colors or smoothing. Although faces + may be added as triangles or quads, at the OpenGL level all data is + treated as triangles for compatibility with OpenGL/ES. + + \snippet examples/opengl/shared/qtlogo.cpp 2 + + Drawing a Patch is simply acheived by applying any transformation, + and material effect, then drawing the data using the index range for + the patch. The model-view matrix is saved and then restored so that + any transformation does not affect other parts of the scene. + + \snippet examples/opengl/shared/qtlogo.cpp 3 + + The geometry is built once on construction of the QtLogo, and it is + paramaterized on a number of divisions - which controls how "chunky" the + curved section of the logo looks - and on a scale, so larger and smaller + QtLogo objects can be created without having to use OpenGL scaling + (which would force normal recalculation). + + The building process is done by helper classes (read the source for full + details) which only exist during the build phase, to assemble the parts + of the scene. + + \snippet examples/opengl/shared/qtlogo.cpp 4 + + Finally the complete QtLogo scene is simply drawn by enabling the data arrays + and then iterating over the parts, calling draw() on each one. + + \section1 Window Class Definition + + The \c Window class is used as a container for the \c GLWidget used to + display the scene: + + \snippet examples/opengl/hellogl/window.h 0 + + In addition, it contains sliders that are used to change the orientation + of the object in the scene. + + \section1 Window Class Implementation + + The constructor constructs an instance of the \c GLWidget class and some + sliders to manipulate its contents. + + \snippet examples/opengl/hellogl/window.cpp 0 + + We connect the \l{QAbstractSlider::valueChanged()}{valueChanged()} signal + from each of the sliders to the appropriate slots in \c{glWidget}. + This allows the user to change the orientation of the object by dragging + the sliders. + + We also connect the \c xRotationChanged(), \c yRotationChanged(), and + \c zRotationChanged() signals from \c glWidget to the + \l{QAbstractSlider::setValue()}{setValue()} slots in the + corresponding sliders. + + \snippet examples/opengl/hellogl/window.cpp 1 + + The sliders are placed horizontally in a layout alongside the \c GLWidget, + and initialized with suitable default values. + + The \c createSlider() utility function constructs a QSlider, and ensures + that it is set up with a suitable range, step value, tick interval, and + page step value before returning it to the calling function: + + \snippet examples/opengl/hellogl/window.cpp 2 + + \section1 Summary + + The \c GLWidget class implementation shows how to subclass QGLWidget for + the purposes of rendering a 3D scene using OpenGL calls. Since QGLWidget + is a subclass of QWidget, subclasses of QGLWidget can be placed in layouts + and provided with interactive features just like normal custom widgets. + + We ensure that the widget is able to correctly render the scene using OpenGL + by reimplementing the following functions: + + \list + \o QGLWidget::initializeGL() sets up resources needed by the OpenGL implementation + to render the scene. + \o QGLWidget::resizeGL() resizes the viewport so that the rendered scene fits onto + the widget, and sets up a projection matrix to map 3D coordinates to 2D viewport + coordinates. + \o QGLWidget::paintGL() performs painting operations using OpenGL calls. + \endlist + + Since QGLWidget is a subclass of QWidget, it can also be used + as a normal paint device, allowing 2D graphics to be drawn with QPainter. + This use of QGLWidget is discussed in the \l{2D Painting Example}{2D Painting} + example. + + More advanced users may want to paint over parts of a scene rendered using + OpenGL. QGLWidget allows pure OpenGL rendering to be mixed with QPainter + calls, but care must be taken to maintain the state of the OpenGL implementation. + See the \l{Overpainting Example}{Overpainting} example for more information. +*/ diff --git a/doc/src/examples/hellogl_es.qdoc b/doc/src/examples/hellogl_es.qdoc new file mode 100644 index 0000000000..63ecaddcc6 --- /dev/null +++ b/doc/src/examples/hellogl_es.qdoc @@ -0,0 +1,128 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example opengl/hellogl_es + \title Hello GL ES Example + + The Hello GL ES example is the \l{Hello GL Example} ported to OpenGL ES. + It also included some effects from the OpenGL \l{Overpainting Example}. + + \image hellogl-es-example.png + + A complete introduction to OpenGL ES and a description of all differences + between OpenGL and OpenGL ES is out of the scope of this document; but + we will describe some of the major issues and differences. + + Since Hello GL ES is a direct port of standard OpenGL code, it is a fairly + good example for porting OpenGL code to OpenGL ES. + + \tableofcontents + + \section1 Using QGLWidget + + QGLWidget can be used for OpenGL ES similar to the way it is used with + standard OpenGL; but there are some differences. We use EGL 1.0 to embedd + the OpenGL ES window within the native window manager. In + QGLWidget::initializeGL() we initialize OpenGL ES. + + \section1 Porting OpenGL to OpenGL ES + + Since OpenGL ES is missing the immediate mode and does not support quads, + we have to create triangle arrays. + + We create a quad by adding vertices to a QList of vertices. We create both + sides of the quad and hardcode a distance of 0.05f. We also compute the + correct normal for each face and store them in another QList. + + \snippet examples/opengl/hellogl_es/glwidget.cpp 0 + + And then we convert the complete list of vertexes and the list of normals + into the native OpenGL ES format that we can use with the OpenGL ES API. + + \snippet examples/opengl/hellogl_es/glwidget.cpp 1 + + In \c paintQtLogo() we draw the triangle array using OpenGL ES. We use + q_vertexTypeEnum to abstract the fact that our vertex and normal arrays + are either in float or in fixed point format. + + \snippet examples/opengl/hellogl_es/glwidget.cpp 2 + + \section1 Using QGLPainter + + Since the \c QGLPainter is slower for OpenGL ES we paint the bubbles with + the rasterizer and cache them in a QImage. This happends only once during + the initialiazation. + + \snippet examples/opengl/hellogl_es/bubble.cpp 0 + + For each bubble this QImage is then drawn to the QGLWidget by using the + according QPainter with transparency enabled. + + \snippet examples/opengl/hellogl_es/bubble.cpp 1 + + Another difference beetwen OpenGL and OpenGL ES is that OpenGL ES does not + support glPushAttrib(GL_ALL_ATTRIB_BITS). So we have to restore all the + OpenGL states ourselves, after we created the QPainter in + GLWidget::paintGL(). + + \snippet examples/opengl/hellogl_es/glwidget.cpp 3 + + Setting up up the model view matrix and setting the right OpenGL states is + done in the same way as for standard OpenGL. + + \snippet examples/opengl/hellogl_es/glwidget.cpp 4 + + Now we have to restore the OpenGL state for the QPainter. This is not done + automatically for OpenGL ES. + + \snippet examples/opengl/hellogl_es/glwidget.cpp 5 + + Now we use the QPainter to draw the transparent bubbles. + + \snippet examples/opengl/hellogl_es/glwidget.cpp 6 + + In the end, we calculate the framerate and display it using the QPainter + again. + + \snippet examples/opengl/hellogl_es/glwidget.cpp 7 + + After we finished all the drawing operations we swap the screen buffer. + + \snippet examples/opengl/hellogl_es/glwidget.cpp 8 + + \section1 Summary + + Similar to the \l{Hello GL Example}, we subclass QGLWidget to render + a 3D scene using OpenGL ES calls. QGLWidget is a subclass of QWidget. + Hence, its \l{QGLWidget}'s subclasses can be placed in layouts and + provided with interactive features just like normal custom widgets. + + QGLWidget allows pure OpenGL ES rendering to be mixed with QPainter calls, + but care must be taken to maintain the state of the OpenGL ES + implementation. +*/ diff --git a/doc/src/examples/hellotr.qdoc b/doc/src/examples/hellotr.qdoc new file mode 100644 index 0000000000..384765eb75 --- /dev/null +++ b/doc/src/examples/hellotr.qdoc @@ -0,0 +1,174 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example linguist/hellotr + \title Hello tr() Example + + This example is a small Hello World program with a Latin translation. The + screenshot below shows the English version. + + \image linguist-hellotr_en.png + + See the \l{Qt Linguist manual} for more information about + translating Qt application. + + \section1 Line by Line Walkthrough + + + \snippet examples/linguist/hellotr/main.cpp 0 + + This line includes the definition of the QTranslator class. + Objects of this class provide translations for user-visible text. + + \snippet examples/linguist/hellotr/main.cpp 5 + + Creates a QTranslator object without a parent. + + \snippet examples/linguist/hellotr/main.cpp 6 + + Tries to load a file called \c hellotr_la.qm (the \c .qm file extension is + implicit) that contains Latin translations for the source texts used in + the program. No error will occur if the file is not found. + + \snippet examples/linguist/hellotr/main.cpp 7 + + Adds the translations from \c hellotr_la.qm to the pool of translations used + by the program. + + \snippet examples/linguist/hellotr/main.cpp 8 + + Creates a push button that displays "Hello world!". If \c hellotr_la.qm + was found and contains a translation for "Hello world!", the + translation appears; if not, the source text appears. + + All classes that inherit QObject have a \c tr() function. Inside + a member function of a QObject class, we simply write \c tr("Hello + world!") instead of \c QPushButton::tr("Hello world!") or \c + QObject::tr("Hello world!"). + + \section1 Running the Application in English + + Since we haven't made the translation file \c hellotr_la.qm, the source text + is shown when we run the application: + + \image linguist-hellotr_en.png + + \section1 Creating a Latin Message File + + The first step is to create a project file, \c hellotr.pro, that lists + all the source files for the project. The project file can be a qmake + project file, or even an ordinary makefile. Any file that contains + + \snippet examples/linguist/hellotr/hellotr.pro 0 + \snippet examples/linguist/hellotr/hellotr.pro 1 + + will work. \c TRANSLATIONS specifies the message files we want to + maintain. In this example, we just maintain one set of translations, + namely Latin. + + Note that the file extension is \c .ts, not \c .qm. The \c .ts + translation source format is designed for use during the + application's development. Programmers or release managers run + the \c lupdate program to generate and update TS files with + the source text that is extracted from the source code. + Translators read and update the TS files using \e {Qt + Linguist} adding and editing their translations. + + The TS format is human-readable XML that can be emailed directly + and is easy to put under version control. If you edit this file + manually, be aware that the default encoding for XML is UTF-8, not + Latin1 (ISO 8859-1). One way to type in a Latin1 character such as + '\oslash' (Norwegian o with slash) is to use an XML entity: + "\ø". This will work for any Unicode 4.0 character. + + Once the translations are complete the \c lrelease program is used to + convert the TS files into the QM Qt message file format. The + QM format is a compact binary format designed to deliver very + fast lookup performance. Both \c lupdate and \c lrelease read all the + project's source and header files (as specified in the HEADERS and + SOURCES lines of the project file) and extract the strings that + appear in \c tr() function calls. + + \c lupdate is used to create and update the message files (\c hellotr_la.ts + in this case) to keep them in sync with the source code. It is safe to + run \c lupdate at any time, as \c lupdate does not remove any + information. For example, you can put it in the makefile, so the TS + files are updated whenever the source changes. + + Try running \c lupdate right now, like this: + + \snippet doc/src/snippets/code/doc_src_examples_hellotr.qdoc 0 + + (The \c -verbose option instructs \c lupdate to display messages that + explain what it is doing.) You should now have a file \c hellotr_la.ts in + the current directory, containing this: + + \snippet doc/src/snippets/code/doc_src_examples_hellotr.qdoc 1 + + You don't need to understand the file format since it is read and + updated using tools (\c lupdate, \e {Qt Linguist}, \c lrelease). + + \section1 Translating to Latin with Qt Linguist + + We will use \e {Qt Linguist} to provide the translation, although + you can use any XML or plain text editor to enter a translation into a + TS file. + + To start \e {Qt Linguist}, type + + \snippet doc/src/snippets/code/doc_src_examples_hellotr.qdoc 2 + + You should now see the text "QPushButton" in the top left pane. + Double-click it, then click on "Hello world!" and enter "Orbis, te + saluto!" in the \gui Translation pane (the middle right of the + window). Don't forget the exclamation mark! + + Click the \gui Done checkbox and choose \gui File|Save from the + menu bar. The TS file will no longer contain + + \snippet doc/src/snippets/code/doc_src_examples_hellotr.qdoc 3 + + but instead will have + + \snippet doc/src/snippets/code/doc_src_examples_hellotr.qdoc 4 + + \section1 Running the Application in Latin + + To see the application running in Latin, we have to generate a QM + file from the TS file. Generating a QM file can be achieved + either from within \e {Qt Linguist} (for a single TS file), or + by using the command line program \c lrelease which will produce one + QM file for each of the TS files listed in the project file. + Generate \c hellotr_la.qm from \c hellotr_la.ts by choosing + \gui File|Release from \e {Qt Linguist}'s menu bar and pressing + \gui Save in the file save dialog that pops up. Now run the \c hellotr + program again. This time the button will be labelled "Orbis, te + saluto!". + + \image linguist-hellotr_la.png +*/ diff --git a/doc/src/examples/htmlinfo.qdoc b/doc/src/examples/htmlinfo.qdoc new file mode 100644 index 0000000000..a0d47cb314 --- /dev/null +++ b/doc/src/examples/htmlinfo.qdoc @@ -0,0 +1,75 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example xml/htmlinfo + \title XML HTML Info Example + + The XML HTML Info example provides a simple command line utility that + scans the current directory for HTML files and prints statistics about + them to standard out. + + \note Standard out is redirected on some platforms. On Symbian using Open + C \c stdout is by default directed to the console window, but this window + may not always be visible. To redirect to a file instead, locate the \c + c:\\system\\data\\config.ini file (on either the emulator or the device) + and change \c STDOUT to point to \c MEDIA4. This will redirect the console + to \c c:\\system\\data\\out.txt. + + The files are parsed using a QXmlStreamReader object. If the file does + not contain a well-formed XML document, a description of the error is + printed to the standard error console. + + \section1 Basic Operation + + The main function of the example uses QDir to access files in the current + directory that match either "*.htm" or "*.html". For each file found, + the \c parseHtmlFile() function is called. + + Reading XML is handled by an instance of the QXmlStreamReader class, which + operates on the input file object: + + \snippet examples/xml/htmlinfo/main.cpp 0 + + The work of parsing and the XML and extracting statistics is done in a + while loop, and is driven by input from the reader: + + \snippet examples/xml/htmlinfo/main.cpp 1 + + If more input is available, the next token from the input file is read + and parsed. The program then looks for the specific element types, + "title", "a", and "p", and stores information about them. + + When there is no more input, the loop terminates. If an error occurred, + information is written to the standard out file via a stream, and the + example exits: + + \snippet examples/xml/htmlinfo/main.cpp 2 + + If no error occurred, the example prints some statistics from the data + gathered in the loop, and then exits. +*/ diff --git a/doc/src/examples/http.qdoc b/doc/src/examples/http.qdoc new file mode 100644 index 0000000000..cff42e29a5 --- /dev/null +++ b/doc/src/examples/http.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example network/http + \title HTTP Example + + The HTTP example demonstrates a simple HTTP client that shows how to fetch files + specified by URLs from remote hosts. + + \image http-example.png +*/ diff --git a/doc/src/examples/i18n.qdoc b/doc/src/examples/i18n.qdoc new file mode 100644 index 0000000000..b24b635935 --- /dev/null +++ b/doc/src/examples/i18n.qdoc @@ -0,0 +1,37 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example tools/i18n + \title I18N Example + + The Internationalization (I18N) example demonstrates Qt's support for translated + text. Developers can write the initial application text in one language, and + translations can be provided later without any modifications to the code. + + \image i18n-example.png +*/ diff --git a/doc/src/examples/icons.qdoc b/doc/src/examples/icons.qdoc new file mode 100644 index 0000000000..3966bf4b8d --- /dev/null +++ b/doc/src/examples/icons.qdoc @@ -0,0 +1,780 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example widgets/icons + \title Icons Example + + The Icons example shows how QIcon can generate pixmaps reflecting + an icon's state, mode and size. These pixmaps are generated from + the set of pixmaps made available to the icon, and are used by Qt + widgets to show an icon representing a particular action. + + \image icons-example.png Screenshot of the Icons example + + Contents: + + \tableofcontents + + \section1 QIcon Overview + + The QIcon class provides scalable icons in different modes and + states. An icon's state and mode are depending on the intended use + of the icon. Qt currently defines four modes: + + \table + \header \o Mode \o Description + \row + \o QIcon::Normal + \o Display the pixmap when the user is not interacting with the + icon, but the functionality represented by the icon is + available. + \row + \o QIcon::Active + \o Display the pixmap when the functionality represented by the + icon is available and the user is interacting with the icon, + for example, moving the mouse over it or clicking it. + \row + \o QIcon::Disabled + \o Display the pixmap when the functionality represented by + the icon is not available. + \row + \o QIcon::Selected + \o Display the pixmap when the icon is selected. + \endtable + + QIcon's states are QIcon::On and QIcon::Off, which will display + the pixmap when the widget is in the respective state. The most + common usage of QIcon's states are when displaying checkable tool + buttons or menu entries (see QAbstractButton::setCheckable() and + QAction::setCheckable()). When a tool button or menu entry is + checked, the QIcon's state is \l{QIcon::}{On}, otherwise it's + \l{QIcon::}{Off}. You can, for example, use the QIcon's states to + display differing pixmaps depending on whether the tool button or + menu entry is checked or not. + + A QIcon can generate smaller, larger, active, disabled, and + selected pixmaps from the set of pixmaps it is given. Such + pixmaps are used by Qt widgets to show an icon representing a + particular action. + + \section1 Overview of the Icons Application + + With the Icons application you get a preview of an icon's + generated pixmaps reflecting its different states, modes and size. + + When an image is loaded into the application, it is converted into + a pixmap and becomes a part of the set of pixmaps available to the + icon. An image can be excluded from this set by checking off the + related checkbox. The application provides a sub directory + containing sets of images explicitly designed to illustrate how Qt + renders an icon in different modes and states. + + The application allows you to manipulate the icon size with some + predefined sizes and a spin box. The predefined sizes are style + dependent, but most of the styles have the same values: Only the + Macintosh style differ by using 32 pixels, instead of 16 pixels, + for toolbar buttons. You can navigate between the available styles + using the \gui View menu. + + \image icons-view-menu.png Screenshot of the View menu + + The \gui View menu also provide the option to make the application + guess the icon state and mode from an image's file name. The \gui + File menu provide the options of adding an image and removing all + images. These last options are also available through a context + menu that appears if you press the right mouse button within the + table of image files. In addition, the \gui File menu provide an + \gui Exit option, and the \gui Help menu provide information about + the example and about Qt. + + \image icons_find_normal.png Screenshot of the Find Files + + The screenshot above shows the application with one image file + loaded. The \gui {Guess Image Mode/State} is enabled and the + style is Plastique. + + When QIcon is provided with only one available pixmap, that + pixmap is used for all the states and modes. In this case the + pixmap's icon mode is set to normal, and the generated pixmaps + for the normal and active modes will look the same. But in + disabled and selected mode, Qt will generate a slightly different + pixmap. + + The next screenshot shows the application with an additional file + loaded, providing QIcon with two available pixmaps. Note that the + new image file's mode is set to disabled. When rendering the \gui + Disabled mode pixmaps, Qt will now use the new image. We can see + the difference: The generated disabled pixmap in the first + screenshot is slightly darker than the pixmap with the originally + set disabled mode in the second screenshot. + + \image icons_find_normal_disabled.png Screenshot of the Find Files + + When Qt renders the icon's pixmaps it searches through the set of + available pixmaps following a particular algorithm. The algorithm + is documented in QIcon, but we will describe some particular cases + below. + + \image icons_monkey_active.png Screenshot of the Find Files + + In the screenshot above, we have set \c monkey_on_32x32 to be an + Active/On pixmap and \c monkey_off_64x64 to be Normal/Off. To + render the other six mode/state combinations, QIcon uses the + search algorithm described in the table below: + + \table 100% + \header \o{2,1} Requested Pixmap \o {8,1} Preferred Alternatives (mode/state) + \header \o Mode \o State \o 1 \o 2 \o 3 \o 4 \o 5 \o 6 \o 7 \o 8 + \row \o{1,2} Normal \o Off \o \bold N0 \o A0 \o N1 \o A1 \o D0 \o S0 \o D1 \o S1 + \row \o On \o N1 \o \bold A1 \o N0 \o A0 \o D1 \o S1 \o D0 \o S0 + \row \o{1,2} Active \o Off \o A0 \o \bold N0 \o A1 \o N1 \o D0 \o S0 \o D1 \o S1 + \row \o On \o \bold A1 \o N1 \o A0 \o N0 \o D1 \o S1 \o D0 \o S0 + \row \o{1,2} Disabled \o Off \o D0 \o \bold {N0'} \o A0' \o D1 \o N1' \o A1' \o S0' \o S1' + \row \o On \o D1 \o N1' \o \bold {A1'} \o D0 \o N0' \o A0' \o S1' \o S0' + \row \o{1,2} Selected \o Off \o S0 \o \bold {N0''} \o A0'' \o S1 \o N1'' \o A1'' \o D0'' \o D1'' + \row \o On \o S1 \o N1'' \o \bold {A1''} \o S0 \o N0'' \o A0'' \o D1'' \o D0'' + \endtable + + In the table, "0" and "1" stand for Off" and "On", respectively. + Single quotes indicates that QIcon generates a disabled ("grayed + out") version of the pixmap; similarly, double quuote indicate + that QIcon generates a selected ("blued out") version of the + pixmap. + + The alternatives used in the screenshot above are shown in bold. + For example, the Disabled/Off pixmap is derived by graying out + the Normal/Off pixmap (\c monkey_off_64x64). + + In the next screenshots, we loaded the whole set of monkey + images. By checking or unchecking file names from the image list, + we get different results: + + \table + \row + \o \inlineimage icons_monkey.png Screenshot of the Monkey Files + \o \inlineimage icons_monkey_mess.png Screenshot of the Monkey Files + \endtable + + For any given mode/state combination, it is possible to specify + several images at different resolutions. When rendering an + icon, QIcon will automatically pick the most suitable image + and scale it down if necessary. (QIcon never scales up images, + because this rarely looks good.) + + The screenshots below shows what happens when we provide QIcon + with three images (\c qt_extended_16x16.png, \c qt_extended_32x32.png, \c + qt_extended_48x48.png) and try to render the QIcon at various + resolutions: + + \table + \row + \o + \o \inlineimage icons_qt_extended_8x8.png Qt Extended icon at 8 x 8 + \o \inlineimage icons_qt_extended_16x16.png Qt Extended icon at 16 x 16 + \o \inlineimage icons_qt_extended_17x17.png Qt Extended icon at 17 x 17 + \row + \o + \o 8 x 8 + \o \bold {16 x 16} + \o 17 x 17 + \row + \o \inlineimage icons_qt_extended_32x32.png Qt Extended icon at 32 x 32 + \o \inlineimage icons_qt_extended_33x33.png Qt Extended icon at 33 x 33 + \o \inlineimage icons_qt_extended_48x48.png Qt Extended icon at 48 x 48 + \o \inlineimage icons_qt_extended_64x64.png Qt Extended icon at 64 x 64 + \row + \o \bold {32 x 32} + \o 33 x 33 + \o \bold {48 x 48} + \o 64 x 64 + \endtable + + For sizes up to 16 x 16, QIcon uses \c qt_extended_16x16.png and + scales it down if necessary. For sizes between 17 x 17 and 32 x + 32, it uses \c qt_extended_32x32.png. For sizes above 32 x 32, it uses + \c qt_extended_48x48.png. + + \section1 Line-by-Line Walkthrough + + The Icons example consists of four classes: + + \list + \o \c MainWindow inherits QMainWindow and is the main application + window. + \o \c IconPreviewArea is a custom widget that displays all + combinations of states and modes for a given icon. + \o \c IconSizeSpinBox is a subclass of QSpinBox that lets the + user enter icon sizes (e.g., "48 x 48"). + \o \c ImageDelegate is a subclass of QItemDelegate that provides + comboboxes for letting the user set the mode and state + associated with an image. + \endlist + + We will start by reviewing the \c IconPreviewArea class before we + take a look at the \c MainWindow class. Finally, we will review the + \c IconSizeSpinBox and \c ImageDelegate classes. + + \section2 IconPreviewArea Class Definition + + An \c IconPreviewArea widget consists of a group box containing a grid of + QLabel widgets displaying headers and pixmaps. + + \image icons_preview_area.png Screenshot of IconPreviewArea. + + \snippet examples/widgets/icons/iconpreviewarea.h 0 + + The \c IconPreviewArea class inherits QWidget. It displays the + generated pixmaps corresponding to an icon's possible states and + modes at a given size. + + We need two public functions to set the current icon and the + icon's size. In addition the class has three private functions: We + use the \c createHeaderLabel() and \c createPixmapLabel() + functions when constructing the preview area, and we need the \c + updatePixmapLabels() function to update the preview area when + the icon or the icon's size has changed. + + The \c NumModes and \c NumStates constants reflect \l{QIcon}'s + number of currently defined modes and states. + + \section2 IconPreviewArea Class Implementation + + \snippet examples/widgets/icons/iconpreviewarea.cpp 0 + + In the constructor we create the labels displaying the headers and + the icon's generated pixmaps, and add them to a grid layout. + + When creating the header labels, we make sure the enums \c + NumModes and \c NumStates defined in the \c .h file, correspond + with the number of labels that we create. Then if the enums at + some point are changed, the \c Q_ASSERT() macro will alert that this + part of the \c .cpp file needs to be updated as well. + + If the application is built in debug mode, the \c Q_ASSERT() + macro will expand to + + \snippet doc/src/snippets/code/doc_src_examples_icons.cpp 0 + + In release mode, the macro simply disappear. The mode can be set + in the application's \c .pro file. One way to do so is to add an + option to \c qmake when building the application: + + \snippet doc/src/snippets/code/doc_src_examples_icons.qdoc 1 + + or + + \snippet doc/src/snippets/code/doc_src_examples_icons.qdoc 2 + + Another approach is to add this line directly to the \c .pro + file. + + \snippet examples/widgets/icons/iconpreviewarea.cpp 1 + \codeline + \snippet examples/widgets/icons/iconpreviewarea.cpp 2 + + The public \c setIcon() and \c setSize() functions change the icon + or the icon size, and make sure that the generated pixmaps are + updated. + + \snippet examples/widgets/icons/iconpreviewarea.cpp 3 + \codeline + \snippet examples/widgets/icons/iconpreviewarea.cpp 4 + + We use the \c createHeaderLabel() and \c createPixmapLabel() + functions to create the preview area's labels displaying the + headers and the icon's generated pixmaps. Both functions return + the QLabel that is created. + + \snippet examples/widgets/icons/iconpreviewarea.cpp 5 + + We use the private \c updatePixmapLabel() function to update the + generated pixmaps displayed in the preview area. + + For each mode, and for each state, we retrieve a pixmap using the + QIcon::pixmap() function, which generates a pixmap corresponding + to the given state, mode and size. + + \section2 MainWindow Class Definition + + The \c MainWindow widget consists of three main elements: an + images group box, an icon size group box and a preview area. + + \image icons-example.png Screenshot of the Icons example + + \snippet examples/widgets/icons/mainwindow.h 0 + + The MainWindow class inherits from QMainWindow. We reimplement the + constructor, and declare several private slots: + + \list + \o The \c about() slot simply provides information about the example. + \o The \c changeStyle() slot changes the application's GUI style and + adjust the style dependent size options. + \o The \c changeSize() slot changes the size of the preview area's icon. + \o The \c changeIcon() slot updates the set of pixmaps available to the + icon displayed in the preview area. + \o The \c addImage() slot allows the user to load a new image into the + application. + \endlist + + In addition we declare several private functions to simplify the + constructor. + + \section2 MainWindow Class Implementation + + \snippet examples/widgets/icons/mainwindow.cpp 0 + + In the constructor we first create the main window's central + widget and its child widgets, and put them in a grid layout. Then + we create the menus with their associated entries and actions. + + Before we resize the application window to a suitable size, we set + the window title and determine the current style for the + application. We also enable the icon size spin box by clicking the + associated radio button, making the current value of the spin box + the icon's initial size. + + \snippet examples/widgets/icons/mainwindow.cpp 1 + + The \c about() slot displays a message box using the static + QMessageBox::about() function. In this example it displays a + simple box with information about the example. + + The \c about() function looks for a suitable icon in four + locations: It prefers its parent's icon if that exists. If it + doesn't, the function tries the top-level widget containing + parent, and if that fails, it tries the active window. As a last + resort it uses the QMessageBox's Information icon. + + \snippet examples/widgets/icons/mainwindow.cpp 2 + + In the \c changeStyle() slot we first check the slot's + parameter. If it is false we immediately return, otherwise we find + out which style to change to, i.e. which action that triggered the + slot, using the QObject::sender() function. + + This function returns the sender as a QObject pointer. Since we + know that the sender is a QAction object, we can safely cast the + QObject. We could have used a C-style cast or a C++ \c + static_cast(), but as a defensive programming technique we use a + \l qobject_cast(). The advantage is that if the object has the + wrong type, a null pointer is returned. Crashes due to null + pointers are much easier to diagnose than crashes due to unsafe + casts. + + \snippet examples/widgets/icons/mainwindow.cpp 3 + \snippet examples/widgets/icons/mainwindow.cpp 4 + + Once we have the action, we extract the style name using + QAction::data(). Then we create a QStyle object using the static + QStyleFactory::create() function. + + Although we can assume that the style is supported by the + QStyleFactory: To be on the safe side, we use the \c Q_ASSERT() + macro to check if the created style is valid before we use the + QApplication::setStyle() function to set the application's GUI + style to the new style. QApplication will automatically delete + the style object when a new style is set or when the application + exits. + + The predefined icon size options provided in the application are + style dependent, so we need to update the labels in the icon size + group box and in the end call the \c changeSize() slot to update + the icon's size. + + \snippet examples/widgets/icons/mainwindow.cpp 5 + + The \c changeSize() slot sets the size for the preview area's + icon. + + To determine the new size we first check if the spin box is + enabled. If it is, we extract the extent of the new size from the + box. If it's not, we search through the predefined size options, + extract the QStyle::PixelMetric and use the QStyle::pixelMetric() + function to determine the extent. Then we create a QSize object + based on the extent, and use that object to set the size of the + preview area's icon. + + \snippet examples/widgets/icons/mainwindow.cpp 12 + + The first thing we do when the \c addImage() slot is called, is to + show a file dialog to the user. The easiest way to create a file + dialog is to use QFileDialog's static functions. Here we use the + \l {QFileDialog::getOpenFileNames()}{getOpenFileNames()} function + that will return one or more existing files selected by the user. + + For each of the files the file dialog returns, we add a row to the + table widget. The table widget is listing the images the user has + loaded into the application. + + \snippet examples/widgets/icons/mainwindow.cpp 13 + \snippet examples/widgets/icons/mainwindow.cpp 14 + + We retrieve the image name using the QFileInfo::baseName() + function that returns the base name of the file without the path, + and create the first table widget item in the row. Then we add the + file's complete name to the item's data. Since an item can hold + several information pieces, we need to assign the file name a role + that will distinguish it from other data. This role can be Qt::UserRole + or any value above it. + + We also make sure that the item is not editable by removing the + Qt::ItemIsEditable flag. Table items are editable by default. + + \snippet examples/widgets/icons/mainwindow.cpp 15 + \snippet examples/widgets/icons/mainwindow.cpp 16 + \snippet examples/widgets/icons/mainwindow.cpp 17 + + Then we create the second and third items in the row making the + default mode Normal and the default state Off. But if the \gui + {Guess Image Mode/State} option is checked, and the file name + contains "_act", "_dis", or "_sel", the modes are changed to + Active, Disabled, or Selected. And if the file name contains + "_on", the state is changed to On. The sample files in the + example's \c images subdirectory respect this naming convension. + + \snippet examples/widgets/icons/mainwindow.cpp 18 + \snippet examples/widgets/icons/mainwindow.cpp 19 + + In the end we add the items to the associated row, and use the + QTableWidget::openPersistentEditor() function to create + comboboxes for the mode and state columns of the items. + + Due to the connection between the table widget's \l + {QTableWidget::itemChanged()}{itemChanged()} signal and the \c + changeIcon() slot, the new image is automatically converted into a + pixmap and made part of the set of pixmaps available to the icon + in the preview area. So, corresponding to this fact, we need to + make sure that the new image's check box is enabled. + + \snippet examples/widgets/icons/mainwindow.cpp 6 + \snippet examples/widgets/icons/mainwindow.cpp 7 + + The \c changeIcon() slot is called when the user alters the set + of images listed in the QTableWidget, to update the QIcon object + rendered by the \c IconPreviewArea. + + We first create a QIcon object, and then we run through the + QTableWidget, which lists the images the user has loaded into the + application. + + \snippet examples/widgets/icons/mainwindow.cpp 8 + \snippet examples/widgets/icons/mainwindow.cpp 9 + \snippet examples/widgets/icons/mainwindow.cpp 10 + + We also extract the image file's name using the + QTableWidgetItem::data() function. This function takes a + Qt::DataItemRole as an argument to retrieve the right data + (remember that an item can hold several pieces of information) + and returns it as a QVariant. Then we use the + QVariant::toString() function to get the file name as a QString. + + To create a pixmap from the file, we need to first create an + image and then convert this image into a pixmap using + QPixmap::fromImage(). Once we have the final pixmap, we add it, + with its associated mode and state, to the QIcon's set of + available pixmaps. + + \snippet examples/widgets/icons/mainwindow.cpp 11 + + After running through the entire list of images, we change the + icon of the preview area to the one we just created. + + \snippet examples/widgets/icons/mainwindow.cpp 20 + + In the \c removeAllImages() slot, we simply set the table widget's + row count to zero, automatically removing all the images the user + has loaded into the application. Then we update the set of pixmaps + available to the preview area's icon using the \c changeIcon() + slot. + + \image icons_images_groupbox.png Screenshot of the images group box + + The \c createImagesGroupBox() function is implemented to simplify + the constructor. The main purpose of the function is to create a + QTableWidget that will keep track of the images the user has + loaded into the application. + + \snippet examples/widgets/icons/mainwindow.cpp 21 + + First we create a group box that will contain the table widget. + Then we create a QTableWidget and customize it to suit our + purposes. + + We call QAbstractItemView::setSelectionMode() to prevent the user + from selecting items. + + The QAbstractItemView::setItemDelegate() call sets the item + delegate for the table widget. We create a \c ImageDelegate that + we make the item delegate for our view. + + The QItemDelegate class can be used to provide an editor for an item view + class that is subclassed from QAbstractItemView. Using a delegate + for this purpose allows the editing mechanism to be customized and + developed independently from the model and view. + + In this example we derive \c ImageDelegate from QItemDelegate. + QItemDelegate usually provides line editors, while our subclass + \c ImageDelegate, provides comboboxes for the mode and state + fields. + + \snippet examples/widgets/icons/mainwindow.cpp 22 + \snippet examples/widgets/icons/mainwindow.cpp 23 + + Then we customize the QTableWidget's horizontal header, and hide + the vertical header. + + \snippet examples/widgets/icons/mainwindow.cpp 24 + \snippet examples/widgets/icons/mainwindow.cpp 25 + + At the end, we connect the QTableWidget::itemChanged() signal to + the \c changeIcon() slot to ensuret that the preview area is in + sync with the image table. + + \image icons_size_groupbox.png Screenshot of the icon size group box + + The \c createIconSizeGroupBox() function is called from the + constructor. It creates the widgets controlling the size of the + preview area's icon. + + \snippet examples/widgets/icons/mainwindow.cpp 26 + + First we create a group box that will contain all the widgets; + then we create the radio buttons and the spin box. + + The spin box is not a regular QSpinBox but an \c IconSizeSpinBox. + The \c IconSizeSpinBox class inherits QSpinBox and reimplements + two functions: QSpinBox::textFromValue() and + QSpinBox::valueFromText(). The \c IconSizeSpinBox is designed to + handle icon sizes, e.g., "32 x 32", instead of plain integer + values. + + \snippet examples/widgets/icons/mainwindow.cpp 27 + + Then we connect all of the radio buttons + \l{QRadioButton::toggled()}{toggled()} signals and the spin box's + \l {QSpinBox::valueChanged()}{valueChanged()} signal to the \c + changeSize() slot to make sure that the size of the preview + area's icon is updated whenever the user changes the icon size. + In the end we put the widgets in a layout that we install on the + group box. + + \snippet examples/widgets/icons/mainwindow.cpp 28 + + In the \c createActions() function we create and customize all the + actions needed to implement the functionality associated with the + menu entries in the application. + + In particular we create the \c styleActionGroup based on the + currently available GUI styles using + QStyleFactory. QStyleFactory::keys() returns a list of valid keys, + typically including "windows", "motif", "cde", and + "plastique". Depending on the platform, "windowsxp" and + "macintosh" may be available. + + We create one action for each key, and adds the action to the + action group. Also, for each action, we call QAction::setData() + with the style name. We will retrieve it later using + QAction::data(). + + \snippet examples/widgets/icons/mainwindow.cpp 29 + + In the \c createMenu() function, we add the previously created + actions to the \gui File, \gui View and \gui Help menus. + + The QMenu class provides a menu widget for use in menu bars, + context menus, and other popup menus. We put each menu in the + application's menu bar, which we retrieve using + QMainWindow::menuBar(). + + \snippet examples/widgets/icons/mainwindow.cpp 30 + + QWidgets have a \l{QWidget::contextMenuPolicy}{contextMenuPolicy} + property that controls how the widget should behave when the user + requests a context menu (e.g., by right-clicking). We set the + QTableWidget's context menu policy to Qt::ActionsContextMenu, + meaning that the \l{QAction}s associated with the widget should + appear in its context menu. + + Then we add the \gui{Add Image} and \gui{Remove All Images} + actions to the table widget. They will then appear in the table + widget's context menu. + + \snippet examples/widgets/icons/mainwindow.cpp 31 + + In the \c checkCurrentStyle() function we go through the group of + style actions, looking for the current GUI style. + + For each action, we first extract the style name using + QAction::data(). Since this is only a QStyleFactory key (e.g., + "macintosh"), we cannot compare it directly to the current + style's class name. We need to create a QStyle object using the + static QStyleFactory::create() function and compare the class + name of the created QStyle object with that of the current style. + As soon as we are done with a QStyle candidate, we delete it. + + For all QObject subclasses that use the \c Q_OBJECT macro, the + class name of an object is available through its + \l{QObject::metaObject()}{meta-object}. + + We can assume that the style is supported by + QStyleFactory, but to be on the safe side we use the \c + Q_ASSERT() macro to make sure that QStyleFactory::create() + returned a valid pointer. + + \section2 IconSizeSpinBox Class Definition + + \snippet examples/widgets/icons/iconsizespinbox.h 0 + + The \c IconSizeSpinBox class is a subclass of QSpinBox. A plain + QSpinBox can only handle integers. But since we want to display + the spin box's values in a more sophisticated way, we need to + subclass QSpinBox and reimplement the QSpinBox::textFromValue() + and QSpinBox::valueFromText() functions. + + \image icons_size_spinbox.png Screenshot of the icon size spinbox + + \section2 IconSizeSpinBox Class Implementation + + \snippet examples/widgets/icons/iconsizespinbox.cpp 0 + + The constructor is trivial. + + \snippet examples/widgets/icons/iconsizespinbox.cpp 2 + + QSpinBox::textFromValue() is used by the spin box whenever it + needs to display a value. The default implementation returns a + base 10 representation of the \c value parameter. + + Our reimplementation returns a QString of the form "32 x 32". + + \snippet examples/widgets/icons/iconsizespinbox.cpp 1 + + The QSpinBox::valueFromText() function is used by the spin box + whenever it needs to interpret text typed in by the user. Since + we reimplement the \c textFromValue() function we also need to + reimplement the \c valueFromText() function to interpret the + parameter text and return the associated int value. + + We parse the text using a regular expression (a QRegExp). We + define an expression that matches one or several digits, + optionally followed by whitespace, an "x" or the times symbol, + whitespace and one or several digits again. + + The first digits of the regular expression are captured using + parentheses. This enables us to use the QRegExp::cap() or + QRegExp::capturedTexts() functions to extract the matched + characters. If the first and second numbers of the spin box value + differ (e.g., "16 x 24"), we use the first number. + + When the user presses \key Enter, QSpinBox first calls + QSpinBox::valueFromText() to interpret the text typed by the + user, then QSpinBox::textFromValue() to present it in a canonical + format (e.g., "16 x 16"). + + \section2 ImageDelegate Class Definition + + \snippet examples/widgets/icons/imagedelegate.h 0 + + The \c ImageDelegate class is a subclass of QItemDelegate. The + QItemDelegate class provides display and editing facilities for + data items from a model. A single QItemDelegate object is + responsible for all items displayed in a item view (in our case, + a QTableWidget). + + A QItemDelegate can be used to provide an editor for an item view + class that is subclassed from QAbstractItemView. Using a delegate + for this purpose allows the editing mechanism to be customized and + developed independently from the model and view. + + \snippet examples/widgets/icons/imagedelegate.h 1 + + The default implementation of QItemDelegate creates a QLineEdit. + Since we want the editor to be a QComboBox, we need to subclass + QItemDelegate and reimplement the QItemDelegate::createEditor(), + QItemDelegate::setEditorData() and QItemDelegate::setModelData() + functions. + + \snippet examples/widgets/icons/imagedelegate.h 2 + + The \c emitCommitData() slot is used to emit the + QImageDelegate::commitData() signal with the appropriate + argument. + + \section2 ImageDelegate Class Implementation + + \snippet examples/widgets/icons/imagedelegate.cpp 0 + + The constructor is trivial. + + \snippet examples/widgets/icons/imagedelegate.cpp 1 + + The default QItemDelegate::createEditor() implementation returns + the widget used to edit the item specified by the model and item + index for editing. The parent widget and style option are used to + control the appearance of the editor widget. + + Our reimplementation create and populate a combobox instead of + the default line edit. The contents of the combobox depends on + the column in the table for which the editor is requested. Column + 1 contains the QIcon modes, whereas column 2 contains the QIcon + states. + + In addition, we connect the combobox's \l + {QComboBox::activated()}{activated()} signal to the \c + emitCommitData() slot to emit the + QAbstractItemDelegate::commitData() signal whenever the user + chooses an item using the combobox. This ensures that the rest of + the application notices the change and updates itself. + + \snippet examples/widgets/icons/imagedelegate.cpp 2 + + The QItemDelegate::setEditorData() function is used by + QTableWidget to transfer data from a QTableWidgetItem to the + editor. The data is stored as a string; we use + QComboBox::findText() to locate it in the combobox. + + Delegates work in terms of models, not items. This makes it + possible to use them with any item view class (e.g., QListView, + QListWidget, QTreeView, etc.). The transition between model and + items is done implicitly by QTableWidget; we don't need to worry + about it. + + \snippet examples/widgets/icons/imagedelegate.cpp 3 + + The QItemDelegate::setEditorData() function is used by QTableWidget + to transfer data back from the editor to the \l{QTableWidgetItem}. + + \snippet examples/widgets/icons/imagedelegate.cpp 4 + + The \c emitCommitData() slot simply emit the + QAbstractItemDelegate::commitData() signal for the editor that + triggered the slot. This signal must be emitted when the editor + widget has completed editing the data, and wants to write it back + into the model. +*/ diff --git a/doc/src/examples/imagecomposition.qdoc b/doc/src/examples/imagecomposition.qdoc new file mode 100644 index 0000000000..884ffbed11 --- /dev/null +++ b/doc/src/examples/imagecomposition.qdoc @@ -0,0 +1,165 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example painting/imagecomposition + \title Image Composition Example + + The Image Composition example lets the user combine images + together using any composition mode supported by QPainter, described + in detail in \l{QPainter#Composition Modes}{Composition Modes}. + + \image imagecomposition-example.png + + \section1 Setting Up The Resource File + + The Image Composition example requires two source images, + \e butterfly.png and \e checker.png that are embedded within + \e imagecomposition.qrc. The file contains the following code: + + \quotefile examples/painting/imagecomposition/imagecomposition.qrc + + For more information on resource files, see \l{The Qt Resource System}. + + \section1 ImageComposer Class Definition + + The \c ImageComposer class is a subclass of QWidget that implements three + private slots, \c chooseSource(), \c chooseDestination(), and + \c recalculateResult(). + + \snippet examples/painting/imagecomposition/imagecomposer.h 0 + + In addition, \c ImageComposer consists of five private functions, + \c addOp(), \c chooseImage(), \c loadImage(), \c currentMode(), and + \c imagePos(), as well as private instances of QToolButton, QComboBox, + QLabel, and QImage. + + \snippet examples/painting/imagecomposition/imagecomposer.h 1 + + \section1 ImageComposer Class Implementation + + We declare a QSize object, \c resultSize, as a static constant with width + and height equal to 200. + + \snippet examples/painting/imagecomposition/imagecomposer.cpp 0 + + Within the constructor, we instantiate a QToolButton object, + \c sourceButton and set its \l{QAbstractButton::setIconSize()}{iconSize} + property to \c resultSize. The \c operatorComboBox is instantiated and + then populated using the \c addOp() function. This function accepts a + QPainter::CompositionMode, \a mode, and a QString, \a name, representing + the name of the composition mode. + + \snippet examples/painting/imagecomposition/imagecomposer.cpp 1 + + The \c destinationButton is instantiated and its + \l{QAbstractButton::setIconSize()}{iconSize} property is set to + \c resultSize as well. The \l{QLabel}s \c equalLabel and \c resultLabel + are created and \c{resultLabel}'s \l{QWidget::setMinimumWidth()} + {minimumWidth} is set. + + \snippet examples/painting/imagecomposition/imagecomposer.cpp 2 + + We connect the following signals to their corresponding slots: + \list + \o \c{sourceButton}'s \l{QPushButton::clicked()}{clicked()} signal is + connected to \c chooseSource(), + \o \c{operatorComboBox}'s \l{QComboBox::activated()}{activated()} + signal is connected to \c recalculateResult(), and + \o \c{destinationButton}'s \l{QToolButton::clicked()}{clicked()} signal + is connected to \c chooseDestination(). + \endlist + + \snippet examples/painting/imagecomposition/imagecomposer.cpp 3 + + A QGridLayout, \c mainLayout, is used to place all the widgets. Note + that \c{mainLayout}'s \l{QLayout::setSizeConstraint()}{sizeConstraint} + property is set to QLayout::SetFixedSize, which means that + \c{ImageComposer}'s size cannot be resized at all. + + \snippet examples/painting/imagecomposition/imagecomposer.cpp 4 + + We create a QImage, \c resultImage, and we invoke \c loadImage() twice + to load both the image files in our \e imagecomposition.qrc file. Then, + we set the \l{QWidget::setWindowTitle()}{windowTitle} property to + "Image Composition". + + \snippet examples/painting/imagecomposition/imagecomposer.cpp 5 + + The \c chooseSource() and \c chooseDestination() functions are + convenience functions that invoke \c chooseImage() with specific + parameters. + + \snippet examples/painting/imagecomposition/imagecomposer.cpp 6 + \codeline + \snippet examples/painting/imagecomposition/imagecomposer.cpp 7 + + The \c chooseImage() function loads an image of the user's choice, + depending on the \a title, \a image, and \a button. + + \snippet examples/painting/imagecomposition/imagecomposer.cpp 10 + + The \c recalculateResult() function is used to calculate amd display the + result of combining the two images together with the user's choice of + composition mode. + + \snippet examples/painting/imagecomposition/imagecomposer.cpp 8 + + The \c addOp() function adds an item to the \c operatorComboBox using + \l{QComboBox}'s \l{QComboBox::addItem()}{addItem} function. This function + accepts a QPainter::CompositionMode, \a mode, and a QString, \a name. The + rectangle is filled with Qt::Transparent and both the \c sourceImage and + \c destinationImage are painted, before displaying it on \c resultLabel. + + \snippet examples/painting/imagecomposition/imagecomposer.cpp 9 + + The \c loadImage() function paints a transparent background using + \l{QPainter::fillRect()}{fillRect()} and draws \c image in a + centralized position using \l{QPainter::drawImage()}{drawImage()}. + This \c image is then set as the \c{button}'s icon. + + \snippet examples/painting/imagecomposition/imagecomposer.cpp 11 + + The \c currentMode() function returns the composition mode currently + selected in \c operatorComboBox. + + \snippet examples/painting/imagecomposition/imagecomposer.cpp 12 + + We use the \c imagePos() function to ensure that images loaded onto the + QToolButton objects, \c sourceButton and \c destinationButton, are + centralized. + + \snippet examples/painting/imagecomposition/imagecomposer.cpp 13 + + \section1 The \c main() Function + + The \c main() function instantiates QApplication and \c ImageComposer + and invokes its \l{QWidget::show()}{show()} function. + + \snippet examples/painting/imagecomposition/main.cpp 0 + + */ diff --git a/doc/src/examples/imagegestures.qdoc b/doc/src/examples/imagegestures.qdoc new file mode 100644 index 0000000000..febeaa3793 --- /dev/null +++ b/doc/src/examples/imagegestures.qdoc @@ -0,0 +1,100 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example gestures/imagegestures + \title Image Gestures Example + + This example shows how to enable gestures for a widget and use gesture input + to perform actions. + + We use two classes to create the user interface for the application: \c MainWidget + and \c ImageWidget. The \c MainWidget class is simply used as a container for the + \c ImageWidget class, which we will configure to accept gesture input. Since we + are interested in the way gestures are used, we will concentrate on the + implementation of the \c ImageWidget class. + + \section1 ImageWidget Class Definition + + The \c ImageWidget class is a simple QWidget subclass that reimplements the general + QWidget::event() handler function in addition to several more specific event handlers: + + \snippet examples/gestures/imagegestures/imagewidget.h class definition begin + \dots + \snippet examples/gestures/imagegestures/imagewidget.h class definition end + + We also implement a private helper function, \c gestureEvent(), to help manage + gesture events delivered to the widget, and three functions to perform actions + based on gestures: \c panTriggered(), \c pinchTriggered() and \c swipeTriggered(). + + \section1 ImageWidget Class Implementation + + In the widget's constructor, we begin by setting up various parameters that will + be used to control the way images are displayed. + + \snippet examples/gestures/imagegestures/imagewidget.cpp constructor + + We enable three of the standard gestures for the widget by calling QWidget::grabGesture() + with the types of gesture we need. These will be recognized by the application's + default gesture recognizer, and events will be delivered to our widget. + + Since QWidget does not define a specific event handler for gestures, the widget + needs to reimplement the general QWidget::event() to receive gesture events. + + \snippet examples/gestures/imagegestures/imagewidget.cpp event handler + + We implement the event handler to delegate gesture events to a private function + specifically written for the task, and pass all other events to QWidget's + implementation. + + The \c gestureHandler() function examines the gestures supplied by the + newly-delivered QGestureEvent. Since only one gesture of a given type can be + used on a widget at any particular time, we can check for each gesture type + using the QGestureEvent::gesture() function: + + \snippet examples/gestures/imagegestures/imagewidget.cpp gesture event handler + + If a QGesture object is supplied for a certain type of gesture, we call a special + purpose function to deal with it, casting the gesture object to the appropriate + QGesture subclass. + + To illustrate how a standard gesture can be interpreted by an application, we + show the implementation of the \c swipeTriggered() function, which handles the + gesture associated with a brushing or swiping motion on the user's display or + input device: + + \snippet examples/gestures/imagegestures/imagewidget.cpp swipe function + + The QSwipeGesture class provides specialized functions and defines a enum + to make it more convenient for developers to discover which direction, if + any, the user swiped the display. Here, we simply navigate to the previous + image in the collection if the user swiped upwards or to the left; otherwise + we navigate to the next image in the collection. + + The other gestures are also handled by special purpose functions, but use + the values of properties held by the QGesture object passed to them. +*/ diff --git a/doc/src/examples/imageviewer.qdoc b/doc/src/examples/imageviewer.qdoc new file mode 100644 index 0000000000..f1d02c3abc --- /dev/null +++ b/doc/src/examples/imageviewer.qdoc @@ -0,0 +1,326 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example widgets/imageviewer + \title Image Viewer Example + + The example shows how to combine QLabel and QScrollArea to + display an image. QLabel is typically used for displaying text, + but it can also display an image. QScrollArea provides a + scrolling view around another widget. If the child widget exceeds + the size of the frame, QScrollArea automatically provides scroll + bars. + + The example demonstrates how QLabel's ability to scale its + contents (QLabel::scaledContents), and QScrollArea's ability to + automatically resize its contents (QScrollArea::widgetResizable), + can be used to implement zooming and scaling features. In + addition the example shows how to use QPainter to print an image. + + \image imageviewer-example.png Screenshot of the Image Viewer example + + With the Image Viewer application, the users can view an image of + their choice. The \gui File menu gives the user the possibility + to: + + \list + \o \gui{Open...} - Open an image file + \o \gui{Print...} - Print an image + \o \gui{Exit} - Exit the application + \endlist + + Once an image is loaded, the \gui View menu allows the users to: + + \list + \o \gui{Zoom In} - Scale the image up by 25% + \o \gui{Zoom Out} - Scale the image down by 25% + \o \gui{Normal Size} - Show the image at its original size + \o \gui{Fit to Window} - Stretch the image to occupy the entire window + \endlist + + In addition the \gui Help menu provides the users with information + about the Image Viewer example in particular, and about Qt in + general. + + \section1 ImageViewer Class Definition + + \snippet examples/widgets/imageviewer/imageviewer.h 0 + + The \c ImageViewer class inherits from QMainWindow. We reimplement + the constructor, and create several private slots to facilitate + the menu entries. In addition we create four private functions. + + We use \c createActions() and \c createMenus() when constructing + the \c ImageViewer widget. We use the \c updateActions() function + to update the menu entries when a new image is loaded, or when + the \gui {Fit to Window} option is toggled. The zoom slots use \c + scaleImage() to perform the zooming. In turn, \c + scaleImage() uses \c adjustScrollBar() to preserve the focal point after + scaling an image. + + \section1 ImageViewer Class Implementation + + \snippet examples/widgets/imageviewer/imageviewer.cpp 0 + + In the constructor we first create the label and the scroll area. + + We set \c {imageLabel}'s size policy to \l + {QSizePolicy::Ignored}{ignored}, making the users able to scale + the image to whatever size they want when the \gui {Fit to Window} + option is turned on. Otherwise, the default size polizy (\l + {QSizePolicy::Preferred}{preferred}) will make scroll bars appear + when the scroll area becomes smaller than the label's minimum size + hint. + + We ensure that the label will scale its contents to fill all + available space, to enable the image to scale properly when + zooming. If we omitted to set the \c {imageLabel}'s \l + {QLabel::scaledContents}{scaledContents} property, zooming in + would enlarge the QLabel, but leave the pixmap at + its original size, exposing the QLabel's background. + + We make \c imageLabel the scroll area's child widget, and we make + \c scrollArea the central widget of the QMainWindow. At the end + we create the associated actions and menus, and customize the \c + {ImageViewer}'s appearance. + + \snippet examples/widgets/imageviewer/imageviewer.cpp 1 + \snippet examples/widgets/imageviewer/imageviewer.cpp 2 + + In the \c open() slot, we show a file dialog to the user. The + easiest way to create a QFileDialog is to use the static + convenience functions. QFileDialog::getOpenFileName() returns an + existing file selected by the user. If the user presses \gui + Cancel, QFileDialog returns an empty string. + + Unless the file name is a empty string, we check if the file's + format is an image format by constructing a QImage which tries to + load the image from the file. If the constructor returns a null + image, we use a QMessageBox to alert the user. + + The QMessageBox class provides a modal dialog with a short + message, an icon, and some buttons. As with QFileDialog the + easiest way to create a QMessageBox is to use its static + convenience functions. QMessageBox provides a range of different + messages arranged along two axes: severity (question, + information, warning and critical) and complexity (the number of + necessary response buttons). In this particular example an + information message with an \gui OK button (the default) is + sufficient, since the message is part of a normal operation. + + \snippet examples/widgets/imageviewer/imageviewer.cpp 3 + \snippet examples/widgets/imageviewer/imageviewer.cpp 4 + + If the format is supported, we display the image in \c imageLabel + by setting the label's \l {QLabel::pixmap}{pixmap}. Then we enable + the \gui Print and \gui {Fit to Window} menu entries and update + the rest of the view menu entries. The \gui Open and \gui Exit + entries are enabled by default. + + If the \gui {Fit to Window} option is turned off, the + QScrollArea::widgetResizable property is \c false and it is + our responsibility (not QScrollArea's) to give the QLabel a + reasonable size based on its contents. We call + \{QWidget::adjustSize()}{adjustSize()} to achieve this, which is + essentially the same as + + \snippet doc/src/snippets/code/doc_src_examples_imageviewer.cpp 0 + + In the \c print() slot, we first make sure that an image has been + loaded into the application: + + \snippet examples/widgets/imageviewer/imageviewer.cpp 5 + \snippet examples/widgets/imageviewer/imageviewer.cpp 6 + + If the application is built in debug mode, the \c Q_ASSERT() macro + will expand to + + \snippet doc/src/snippets/code/doc_src_examples_imageviewer.cpp 1 + + In release mode, the macro simply disappear. The mode can be set + in the application's \c .pro file. One way to do so is to add an + option to \gui qmake when building the appliction: + + \snippet doc/src/snippets/code/doc_src_examples_imageviewer.qdoc 2 + + or + + \snippet doc/src/snippets/code/doc_src_examples_imageviewer.qdoc 3 + + Another approach is to add this line directly to the \c .pro + file. + + \snippet examples/widgets/imageviewer/imageviewer.cpp 7 + \snippet examples/widgets/imageviewer/imageviewer.cpp 8 + + Then we present a print dialog allowing the user to choose a + printer and to set a few options. We construct a painter with a + QPrinter as the paint device. We set the painter's window + and viewport in such a way that the image is as large as possible + on the paper, but without altering its + \l{Qt::KeepAspectRatio}{aspect ratio}. + + In the end we draw the pixmap at position (0, 0). + + \snippet examples/widgets/imageviewer/imageviewer.cpp 9 + \snippet examples/widgets/imageviewer/imageviewer.cpp 10 + + We implement the zooming slots using the private \c scaleImage() + function. We set the scaling factors to 1.25 and 0.8, + respectively. These factor values ensure that a \gui {Zoom In} + action and a \gui {Zoom Out} action will cancel each other (since + 1.25 * 0.8 == 1), and in that way the normal image size can be + restored using the zooming features. + + The screenshots below show an image in its normal size, and the + same image after zooming in: + + \table + \row + \o \inlineimage imageviewer-original_size.png + \o \inlineimage imageviewer-zoom_in_1.png + \o \inlineimage imageviewer-zoom_in_2.png + \endtable + + \snippet examples/widgets/imageviewer/imageviewer.cpp 11 + \snippet examples/widgets/imageviewer/imageviewer.cpp 12 + + When zooming, we use the QLabel's ability to scale its contents. + Such scaling doesn't change the actual size hint of the contents. + And since the \l {QLabel::adjustSize()}{adjustSize()} function + use those size hint, the only thing we need to do to restore the + normal size of the currently displayed image is to call \c + adjustSize() and reset the scale factor to 1.0. + + \snippet examples/widgets/imageviewer/imageviewer.cpp 13 + \snippet examples/widgets/imageviewer/imageviewer.cpp 14 + + The \c fitToWindow() slot is called each time the user toggled + the \gui {Fit to Window} option. If the slot is called to turn on + the option, we tell the scroll area to resize its child widget + with the QScrollArea::setWidgetResizable() function. Then we + disable the \gui {Zoom In}, \gui {Zoom Out} and \gui {Normal + Size} menu entries using the private \c updateActions() function. + + If the \l {QScrollArea::widgetResizable} property is set to \c + false (the default), the scroll area honors the size of its child + widget. If this property is set to \c true, the scroll area will + automatically resize the widget in order to avoid scroll bars + where they can be avoided, or to take advantage of extra space. + But the scroll area will honor the minimum size hint of its child + widget independent of the widget resizable property. So in this + example we set \c {imageLabel}'s size policy to \l + {QSizePolicy::Ignored}{ignored} in the constructor, to avoid that + scroll bars appear when the scroll area becomes smaller than the + label's minimum size hint. + + The screenshots below shows an image in its normal size, and the + same image with the \gui {Fit to window} option turned on. + Enlarging the window will stretch the image further, as shown in + the third screenshot. + + \table + \row + \o \inlineimage imageviewer-original_size.png + \o \inlineimage imageviewer-fit_to_window_1.png + \o \inlineimage imageviewer-fit_to_window_2.png + \endtable + + If the slot is called to turn off the option, the + {QScrollArea::setWidgetResizable} property is set to \c false. We + also restore the image pixmap to its normal size by adjusting the + label's size to its content. And in the end we update the view + menu entries. + + \snippet examples/widgets/imageviewer/imageviewer.cpp 15 + \snippet examples/widgets/imageviewer/imageviewer.cpp 16 + + We implement the \c about() slot to create a message box + describing what the example is designed to show. + + \snippet examples/widgets/imageviewer/imageviewer.cpp 17 + \snippet examples/widgets/imageviewer/imageviewer.cpp 18 + + In the private \c createAction() function, we create the + actions providing the application features. + + We assign a short-cut key to each action and connect them to the + appropiate slots. We only enable the \c openAct and \c exitAxt at + the time of creation, the others are updated once an image has + been loaded into the application. In addition we make the \c + fitToWindowAct \l {QAction::checkable}{checkable}. + + \snippet examples/widgets/imageviewer/imageviewer.cpp 19 + \snippet examples/widgets/imageviewer/imageviewer.cpp 20 + + In the private \c createMenu() function, we add the previously + created actions to the \gui File, \gui View and \gui Help menus. + + The QMenu class provides a menu widget for use in menu bars, + context menus, and other popup menus. The QMenuBar class provides + a horizontal menu bar that consists of a list of pull-down menu + items. So at the end we put the menus in the \c {ImageViewer}'s + menu bar which we retrieve with the QMainWindow::menuBar() + function. + + \snippet examples/widgets/imageviewer/imageviewer.cpp 21 + \snippet examples/widgets/imageviewer/imageviewer.cpp 22 + + The private \c updateActions() function enables or disables the + \gui {Zoom In}, \gui {Zoom Out} and \gui {Normal Size} menu + entries depending on whether the \gui {Fit to Window} option is + turned on or off. + + \snippet examples/widgets/imageviewer/imageviewer.cpp 23 + \snippet examples/widgets/imageviewer/imageviewer.cpp 24 + + In \c scaleImage(), we use the \c factor parameter to calculate + the new scaling factor for the displayed image, and resize \c + imageLabel. Since we set the + \l{QLabel::scaledContents}{scaledContents} property to \c true in + the constructor, the call to QWidget::resize() will scale the + image displayed in the label. We also adjust the scroll bars to + preserve the focal point of the image. + + At the end, if the scale factor is less than 33.3% or greater + than 300%, we disable the respective menu entry to prevent the + image pixmap from becoming too large, consuming too much + resources in the window system. + + \snippet examples/widgets/imageviewer/imageviewer.cpp 25 + \snippet examples/widgets/imageviewer/imageviewer.cpp 26 + + Whenever we zoom in or out, we need to adjust the scroll bars in + consequence. It would have been tempting to simply call + + \snippet doc/src/snippets/code/doc_src_examples_imageviewer.cpp 4 + + but this would make the top-left corner the focal point, not the + center. Therefore we need to take into account the scroll bar + handle's size (the \l{QScrollBar::pageStep}{page step}). +*/ diff --git a/doc/src/examples/inputpanel.qdoc b/doc/src/examples/inputpanel.qdoc new file mode 100644 index 0000000000..53051085cb --- /dev/null +++ b/doc/src/examples/inputpanel.qdoc @@ -0,0 +1,224 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example tools/inputpanel + \title Input Panel Example + + The Input Panel example shows how to create an input panel that + can be used to input text into widgets using only the pointer and + no keyboard. + + \image inputpanel-example.png + + The input fields in the main window have no function other than + to accept input. The main focus is on how the extra input panel + can be used to input text without the need for a real keyboard or + keypad. + + \section1 Main Form Class Definition + + Because the main window has no other function than to accept + input, it has no class definition. Instead, its whole layout is + made in Qt Designer. This emphasizes the point that no widget + specific code is needed to use input panels with Qt. + + \section1 MyInputPanelContext Class Definition + + \snippet examples/tools/inputpanel/myinputpanelcontext.h 0 + + The \c MyInputPanelContext class inherits QInputContext, which is + Qt's base class for handling input methods. + \c MyInputPanelContext is responsible for managing the state of + the input panel and sending input method events to the receiving + widgets. + + The \c inputPanel member is a pointer to the input panel widget + itself; in other words, the window that will display the buttons + used for input. + + The \c identifierName(), \c language(), \c isComposing() and + \c reset() functions are there mainly to fill in the pure virtual + functions in the base class, QInputContext, but they can be + useful in other scenarios. The important functions and slots are + the following: + + \list + \o \c filterEvent() is where we receive events telling us to open + or close the input panel. + \o \c sendCharacter() is a slot which is called when we want to + send a character to the focused widget. + \o \c updatePosition() is used to position the input panel + relative to the focused widget, and will be used when opening + the input panel. + \endlist + + \section1 MyInputPanelContext Class Implementation + + In the constructor we connect to the \c characterGenerated() + signal of the input panel, in order to receive key presses. We'll + see how it works in detail later on. + + \snippet examples/tools/inputpanel/myinputpanelcontext.cpp 0 + + In the \c filterEvent() function, we must look for the two event + types: \c RequestSoftwareInputPanel and \c CloseSoftwareInputPanel. + + \snippet examples/tools/inputpanel/myinputpanelcontext.cpp 1 + + The first type will be sent whenever + an input capable widget wants to ask for an input panel. Qt's + input widgets do this automatically. If we receive that type of + event, we call \c updatePosition() \mdash we'll see later on what it + does \mdash then show the actual input panel widget. If we receive + the \c CloseSoftwareInputPanel event, we do the opposite, and + hide the input panel. + + \snippet examples/tools/inputpanel/myinputpanelcontext.cpp 2 + + We implement the \c sendCharacter() function so that it sends the + supplied character to the focused widget. All QInputContext based + classes are always supposed to send events to the widget returned + by QInputContext::focusWidget(). Note the QPointer guards to make + sure that the widget does not get destroyed in between events. + + Also note that we chose to use key press events in this example. + For more complex use cases with composed text it might be more + appropriate to send QInputMethodEvent events. + + The \c updatePosition() function is implemented to position the + actual input panel window directly below the focused widget. + + \snippet examples/tools/inputpanel/myinputpanelcontext.cpp 3 + + It performs the positioning by obtaining the coordinates of the + focused widget and translating them to global coordinates. + + \section1 MyInputPanel Class Definition + + The \c MyInputPanel class inherits QWidget and is used to display + the input panel widget and its buttons. + + \snippet examples/tools/inputpanel/myinputpanel.h 0 + + If we look at the member variables first, we see that there is + \c form, which is made with Qt Designer, that contains the layout + of buttons to click. Note that all the buttons in the layout have + been declared with the \c NoFocus focus policy so that we can + maintain focus on the window receiving input instead of the + window containing buttons. + + The \c lastFocusedWidget is a helper variable, which also aids in + maintaining focus. + + \c signalMapper is an instance of the QSignalMapper class and is + there to help us tell which button was clicked. Since they are + all very similar this is a better solution than creating a separate + slot for each one. + + The functions that we implement in \c MyInputPanel are the + following: + + \list + \o \c event() is used to intercept and manipulate focus events, + so we can maintain focus in the main window. + \o \c saveFocusWidget() is a slot which will be called whenever + focus changes, and allows us to store the newly focused widget + in \c lastFocusedWidget, so that its focus can be restored + if it loses it to the input panel. + \o \c buttonClicked() is a slot which will be called by the + \c signalMapper whenever it receives a \c clicked() signal + from any of the buttons. + \endlist + + \section1 MyInputPanel Class Implementation + + If we look at the constructor first, we have a lot of signals to + connect to! + + We connect the QApplication::focusChanged() signal + to the \c saveFocusWidget() signal in order to get focus updates. + Then comes the interesting part with the signal mapper: the + series of \c setMapping() calls sets the mapper up so that each + signal from one of the buttons will result in a + QSignalMapper::mapped() signal, with the given widget as a + parameter. This allows us to do general processing of clicks. + + \snippet examples/tools/inputpanel/myinputpanel.cpp 0 + + The next series of connections then connect each button's + \c clicked() signal to the signal mapper. Finally, we create + a connection from the \c mapped() signal to the + \c buttonClicked() slot, where we will handle it. + + \snippet examples/tools/inputpanel/myinputpanel.cpp 3 + + In the \c buttonClicked() slot, we extract the value of the + "buttonValue" property. This is a custom property which was + created in Qt Designer and set to the character that we wish the + button to produce. Then we emit the \c characterGenerated() + signal, which \c MyInputPanelContext is connected to. This will + in turn cause it to send the input to the focused widget. + + In the \c saveFocusWidget() slot, we test whether the newly + focused widget is a child of the input panel or not, using the + QWidget::isAncestorOf() call. + + \snippet examples/tools/inputpanel/myinputpanel.cpp 2 + + If it isn't, it means that the widget is outside the input panel, + and we store a pointer to that widget for later. + + In the \c event() function we handle QEvent::WindowActivate + event, which occurs if the focus switches to the input panel. + + \snippet examples/tools/inputpanel/myinputpanel.cpp 1 + + Since we want avoid focus on the input panel, we immediately call + QWidget::activateWindow() on the widget that last had focus, so + that input into that widget can continue. We ignore any other events + that we receive. + + \section1 Setting the Input Context + + The main function for the example is very similar to those for other + examples. The only real difference is that it creates a + \c MyInputPanelContext and sets it as the application-wide input + context. + + \snippet examples/tools/inputpanel/main.cpp main + + With the input context in place, we set up and show the user interface + made in Qt Designer before running the event loop. + + \section1 Further Reading + + This example shows a specific kind of input context that uses interaction + with a widget to provide input for another. Qt's input context system can + also be used to create other kinds of input methods. We recommend starting + with the QInputContext documentation if you want to explore further. +*/ diff --git a/doc/src/examples/licensewizard.qdoc b/doc/src/examples/licensewizard.qdoc new file mode 100644 index 0000000000..0b335349fd --- /dev/null +++ b/doc/src/examples/licensewizard.qdoc @@ -0,0 +1,218 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example dialogs/licensewizard + \title License Wizard Example + + The License Wizard example shows how to implement complex wizards in + Qt. + + \image licensewizard-example.png Screenshot of the License Wizard example + + Most wizards have a linear structure, with page 1 followed by + page 2 and so on until the last page. The + \l{dialogs/classwizard}{Class Wizard} example shows how to create + such wizards. + + Some wizards are more complex in that they allow different + traversal paths based on the information provided by the user. + The License Wizard example illustrates this. It provides five + wizard pages; depending on which options are selected, the user + can reach different pages. + + \image licensewizard-flow.png The License Wizard pages + + The example consists of the following classes: + + \list + \o \c LicenseWizard inherits QWizard and implements a non-linear + five-page wizard that leads the user through the process of + choosing a license agreement. + \o \c IntroPage, \c EvaluatePage, \c RegisterPage, \c + DetailsPage, and \c ConclusionPage are QWizardPage subclasses + that implement the wizard pages. + \endlist + + \section1 The LicenseWizard Class + + The \c LicenseWizard class derives from QWizard and provides a + five-page wizard that guides the user through the process of + registering their copy of a fictitious software product. Here's + the class definition: + + \snippet examples/dialogs/licensewizard/licensewizard.h 1 + + The class's public API is limited to a constructor and an enum. + The enum defines the IDs associated with the various pages: + + \table + \header \o Class name \o Enum value \o Page ID + \row \o \c IntroPage \o \c Page_Intro \o 0 + \row \o \c EvaluatePage \o \c Page_Evaluate \o 1 + \row \o \c RegisterPage \o \c Page_Register \o 2 + \row \o \c DetailsPage \o \c Page_Details \o 3 + \row \o \c ConclusionPage \o \c Page_Conclusion \o 4 + \endtable + + For this example, the IDs are arbitrary. The only constraints are + that they must be unique and different from -1. IDs allow us to + refer to pages. + + \snippet examples/dialogs/licensewizard/licensewizard.cpp 2 + + In the constructor, we create the five pages, insert them into + the wizard using QWizard::setPage(), and set \c Page_Intro to be + the first page. + + \snippet examples/dialogs/licensewizard/licensewizard.cpp 3 + \snippet examples/dialogs/licensewizard/licensewizard.cpp 4 + + We set the style to \l{QWizard::}{ModernStyle} on all platforms + except Mac OS X, + + \snippet examples/dialogs/licensewizard/licensewizard.cpp 5 + \snippet examples/dialogs/licensewizard/licensewizard.cpp 6 + + We configure the QWizard to show a \gui Help button, which is + connected to our \c showHelp() slot. We also set the + \l{QWizard::}{LogoPixmap} for all pages that have a header (i.e., + \c EvaluatePage, \c RegisterPage, and \c DetailsPage). + + \snippet examples/dialogs/licensewizard/licensewizard.cpp 9 + \snippet examples/dialogs/licensewizard/licensewizard.cpp 11 + \dots + \snippet examples/dialogs/licensewizard/licensewizard.cpp 13 + + In \c showHelp(), we display help texts that are appropiate for + the current page. If the user clicks \gui Help twice for the same + page, we say, "Sorry, I already gave what help I could. Maybe you + should try asking a human?" + + \section1 The IntroPage Class + + The pages are defined in \c licensewizard.h and implemented in \c + licensewizard.cpp, together with \c LicenseWizard. + + Here's the definition and implementation of \c{IntroPage}: + + \snippet examples/dialogs/licensewizard/licensewizard.h 4 + \codeline + \snippet examples/dialogs/licensewizard/licensewizard.cpp 16 + + A page inherits from QWizardPage. We set a + \l{QWizardPage::}{title} and a + \l{QWizard::WatermarkPixmap}{watermark pixmap}. By not setting + any \l{QWizardPage::}{subTitle}, we ensure that no header is + displayed for this page. (On Windows, it is customary for wizards + to display a watermark pixmap on the first and last pages, and to + have a header on the other pages.) + + \snippet examples/dialogs/licensewizard/licensewizard.cpp 17 + \snippet examples/dialogs/licensewizard/licensewizard.cpp 19 + + The \c nextId() function returns the ID for \c EvaluatePage if + the \gui{Evaluate the product for 30 days} option is checked; + otherwise it returns the ID for \c RegisterPage. + + \section1 The EvaluatePage Class + + The \c EvaluatePage is slightly more involved: + + \snippet examples/dialogs/licensewizard/licensewizard.h 5 + \codeline + \snippet examples/dialogs/licensewizard/licensewizard.cpp 20 + \dots + \snippet examples/dialogs/licensewizard/licensewizard.cpp 21 + \dots + \snippet examples/dialogs/licensewizard/licensewizard.cpp 22 + + First, we set the page's \l{QWizardPage::}{title} + and \l{QWizardPage::}{subTitle}. + + Then we create the child widgets, create \l{Registering and Using + Fields}{wizard fields} associated with them, and put them into + layouts. The fields are created with an asterisk (\c + *) next to their name. This makes them \l{mandatory fields}, that + is, fields that must be filled before the user can press the + \gui Next button (\gui Continue on Mac OS X). The fields' values + can be accessed from any other page using QWizardPage::field(). + + Resetting the page amounts to clearing the two text fields. + + \snippet examples/dialogs/licensewizard/licensewizard.cpp 23 + + The next page is always the \c ConclusionPage. + + \section1 The ConclusionPage Class + + The \c RegisterPage and \c DetailsPage are very similar to \c + EvaluatePage. Let's go directly to the \c ConclusionPage: + + \snippet examples/dialogs/licensewizard/licensewizard.h 6 + + This time, we reimplement QWizardPage::initializePage() and + QWidget::setVisible(), in addition to + \l{QWizardPage::}{nextId()}. We also declare a private slot: + \c printButtonClicked(). + + \snippet examples/dialogs/licensewizard/licensewizard.cpp 18 + + The default implementation of QWizardPage::nextId() returns + the page with the next ID, or -1 if the current page has the + highest ID. This behavior would work here, because \c + Page_Conclusion equals 5 and there is no page with a higher ID, + but to avoid relying on such subtle behavior, we reimplement + \l{QWizardPage::}{nextId()} to return -1. + + \snippet examples/dialogs/licensewizard/licensewizard.cpp 27 + + We use QWizard::hasVisitedPage() to determine the type of + license agreement the user has chosen. If the user filled the \c + EvaluatePage, the license text refers to an Evaluation License + Agreement. If the user filled the \c DetailsPage, the license + text is a First-Time License Agreement. If the user provided an + upgrade key and skipped the \c DetailsPage, the license text is + an Update License Agreement. + + \snippet examples/dialogs/licensewizard/licensewizard.cpp 28 + + We want to display a \gui Print button in the wizard when the \c + ConclusionPage is up. One way to accomplish this is to reimplement + QWidget::setVisible(): + + \list + \o If the page is shown, we set the \l{QWizard::}{CustomButton1} button's + text to \gui{\underline{P}rint}, we enable the \l{QWizard::}{HaveCustomButton1} + option, and we connect the QWizard's \l{QWizard::}{customButtonClicked()} + signal to our \c printButtonClicked() slot. + \o If the page is hidden, we disable the \l{QWizard::}{HaveCustomButton1} + option and disconnect the \c printButtonClicked() slot. + \endlist + + \sa QWizard, {Class Wizard Example}, {Trivial Wizard Example} +*/ diff --git a/doc/src/examples/lighting.qdoc b/doc/src/examples/lighting.qdoc new file mode 100644 index 0000000000..f50a4135d8 --- /dev/null +++ b/doc/src/examples/lighting.qdoc @@ -0,0 +1,33 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example effects/lighting + \title Lighting Effect Example + + \image lightingeffect-example.png +*/ diff --git a/doc/src/examples/lineedits.qdoc b/doc/src/examples/lineedits.qdoc new file mode 100644 index 0000000000..9b4abdc333 --- /dev/null +++ b/doc/src/examples/lineedits.qdoc @@ -0,0 +1,161 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example widgets/lineedits + \title Line Edits Example + + The Line Edits example demonstrates the many ways that QLineEdit can be used, and + shows the effects of various properties and validators on the input and output + supplied by the user. + + \image lineedits-example.png + + The example consists of a single \c Window class, containing a selection of + line edits with different input constraints and display properties that can be + changed by selecting items from comboboxes. Presenting these together helps + developers choose suitable properties to use with line edits, and makes it easy + to compare the effects of each validator on user input. + + \section1 Window Class Definition + + The \c Window class inherits QWidget and contains a constructor and several + slots: + + \snippet examples/widgets/lineedits/window.h 0 + + The slots are used to update the type of validator used for a given line edit when + a new validator has been selected in the associated combobox. The line edits + are stored in the window for use in these slots. + + \section1 Window Class Implementation + + The \c Window constructor is used to set up the line edits, validators, + and comboboxes, connect signals from the comboboxes to slots in the \c Window + class, and arrange the child widgets in layouts. + + We begin by constructing a \l{QGroupBox}{group box} to hold a label, combobox, + and line edit so that we can demonstrate the QLineEdit::echoMode property: + + \snippet examples/widgets/lineedits/window.cpp 0 + + At this point, none of these widgets have been arranged in layouts. Eventually, + the \c echoLabel, \c echoComboBox, and \c echoLineEdit will be placed in a + vertical layout inside the \c echoGroup group box. + + Similarly, we construct group boxes and collections of widgets to show the + effects of QIntValidator and QDoubleValidator on a line edit's contents: + + \snippet examples/widgets/lineedits/window.cpp 1 + + Text alignment is demonstrated by another group of widgets: + + \snippet examples/widgets/lineedits/window.cpp 2 + + QLineEdit supports the use of \l{QLineEdit::inputMask}{input masks}. + These only allow the user to type characters into the line edit that + follow a simple specification. We construct a group of widgets to + demonstrate a selection of predefined masks: + + \snippet examples/widgets/lineedits/window.cpp 3 + + Another useful feature of QLineEdit is its ability to make its contents + read-only. This property is used to control access to a line edit in the + following group of widgets: + + \snippet examples/widgets/lineedits/window.cpp 4 + + Now that all the child widgets have been constructed, we connect signals + from the comboboxes to slots in the \c Window object: + + \snippet examples/widgets/lineedits/window.cpp 5 + + Each of these connections use the QComboBox::activated() signal that + supplies an integer to the slot. This will be used to efficiently + make changes to the appropriate line edit in each slot. + + We place each combobox, line edit, and label in a layout for each group + box, beginning with the layout for the \c echoGroup group box: + + \snippet examples/widgets/lineedits/window.cpp 6 + + The other layouts are constructed in the same way: + + \snippet examples/widgets/lineedits/window.cpp 7 + + Finally, we place each group box in a grid layout for the \c Window object + and set the window title: + + \snippet examples/widgets/lineedits/window.cpp 8 + + The slots respond to signals emitted when the comboboxes are changed by the + user. + + When the combobox for the \gui{Echo} group box is changed, the \c echoChanged() + slot is called: + + \snippet examples/widgets/lineedits/window.cpp 9 + + The slot updates the line edit in the same group box to use an echo mode that + corresponds to the entry described in the combobox. + + When the combobox for the \gui{Validator} group box is changed, the + \c validatorChanged() slot is called: + + \snippet examples/widgets/lineedits/window.cpp 10 + + The slot either creates a new validator for the line edit to use, or it removes + the validator in use by calling QLineEdit::setValidator() with a zero pointer. + We clear the line edit in this case to ensure that the new validator is + initially given valid input to work with. + + When the combobox for the \gui{Alignment} group box is changed, the + \c alignmentChanged() slot is called: + + \snippet examples/widgets/lineedits/window.cpp 11 + + This changes the way that text is displayed in the line edit to correspond with + the description selected in the combobox. + + The \c inputMaskChanged() slot handles changes to the combobox in the + \gui{Input Mask} group box: + + \snippet examples/widgets/lineedits/window.cpp 12 + + Each entry in the relevant combobox is associated with an input mask. We set + a new mask by calling the QLineEdit::setMask() function with a suitable string; + the mask is disabled if an empty string is used. + + The \c accessChanged() slot handles changes to the combobox in the + \gui{Access} group box: + + \snippet examples/widgets/lineedits/window.cpp 13 + + Here, we simply associate the \gui{False} and \gui{True} entries in the combobox + with \c false and \c true values to be passed to QLineEdit::setReadOnly(). This + allows the user to enable and disable input to the line edit. +*/ diff --git a/doc/src/examples/localfortuneclient.qdoc b/doc/src/examples/localfortuneclient.qdoc new file mode 100644 index 0000000000..0a659667f8 --- /dev/null +++ b/doc/src/examples/localfortuneclient.qdoc @@ -0,0 +1,38 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example ipc/localfortuneclient + \title Local Fortune Client Example + + The Local Fortune Client example shows how to create a client for a simple + local service using QLocalSocket. It is intended to be run alongside the + \l{ipc/localfortuneserver}{Local Fortune Server} example. + + \image localfortuneclient-example.png Screenshot of the Local Fortune Client example + +*/ diff --git a/doc/src/examples/localfortuneserver.qdoc b/doc/src/examples/localfortuneserver.qdoc new file mode 100644 index 0000000000..ca25e96f3d --- /dev/null +++ b/doc/src/examples/localfortuneserver.qdoc @@ -0,0 +1,37 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example ipc/localfortuneserver + \title Local Fortune Server Example + + The Local Fortune Server example shows how to create a server for a simple + local service. It is intended to be run alongside the + \l{ipc/localfortuneclient}{Local Fortune Client} example + + \image localfortuneserver-example.png Screenshot of the Local Fortune Server example + */ diff --git a/doc/src/examples/loopback.qdoc b/doc/src/examples/loopback.qdoc new file mode 100644 index 0000000000..06916b3820 --- /dev/null +++ b/doc/src/examples/loopback.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example network/loopback + \title Loopback Example + + The Loopback example shows how to communicate between simple clients and servers on a local + host. + + \image loopback-example.png +*/ diff --git a/doc/src/examples/mandelbrot.qdoc b/doc/src/examples/mandelbrot.qdoc new file mode 100644 index 0000000000..7a1ea37c18 --- /dev/null +++ b/doc/src/examples/mandelbrot.qdoc @@ -0,0 +1,368 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example threads/mandelbrot + \title Mandelbrot Example + + The Mandelbrot example shows how to use a worker thread to + perform heavy computations without blocking the main thread's + event loop. + + The heavy computation here is the Mandelbrot set, probably the + world's most famous fractal. These days, while sophisticated + programs such as \l{XaoS} that provide real-time zooming in the + Mandelbrot set, the standard Mandelbrot algorithm is just slow + enough for our purposes. + + \image mandelbrot-example.png Screenshot of the Mandelbrot example + + In real life, the approach described here is applicable to a + large set of problems, including synchronous network I/O and + database access, where the user interface must remain responsive + while some heavy operation is taking place. The \l + network/blockingfortuneclient example shows the same principle at + work in a TCP client. + + The Mandelbrot application supports zooming and scrolling using + the mouse or the keyboard. To avoid freezing the main thread's + event loop (and, as a consequence, the application's user + interface), we put all the fractal computation in a separate + worker thread. The thread emits a signal when it is done + rendering the fractal. + + During the time where the worker thread is recomputing the + fractal to reflect the new zoom factor position, the main thread + simply scales the previously rendered pixmap to provide immediate + feedback. The result doesn't look as good as what the worker + thread eventually ends up providing, but at least it makes the + application more responsive. The sequence of screenshots below + shows the original image, the scaled image, and the rerendered + image. + + \table + \row + \o \inlineimage mandelbrot_zoom1.png + \o \inlineimage mandelbrot_zoom2.png + \o \inlineimage mandelbrot_zoom3.png + \endtable + + Similarly, when the user scrolls, the previous pixmap is scrolled + immediately, revealing unpainted areas beyond the edge of the + pixmap, while the image is rendered by the worker thread. + + \table + \row + \o \inlineimage mandelbrot_scroll1.png + \o \inlineimage mandelbrot_scroll2.png + \o \inlineimage mandelbrot_scroll3.png + \endtable + + The application consists of two classes: + + \list + \o \c RenderThread is a QThread subclass that renders + the Mandelbrot set. + \o \c MandelbrotWidget is a QWidget subclass that shows the + Mandelbrot set on screen and lets the user zoom and scroll. + \endlist + + If you are not already familiar with Qt's thread support, we + recommend that you start by reading the \l{Thread Support in Qt} + overview. + + \section1 RenderThread Class Definition + + We'll start with the definition of the \c RenderThread class: + + \snippet examples/threads/mandelbrot/renderthread.h 0 + + The class inherits QThread so that it gains the ability to run in + a separate thread. Apart from the constructor and destructor, \c + render() is the only public function. Whenever the thread is done + rendering an image, it emits the \c renderedImage() signal. + + The protected \c run() function is reimplemented from QThread. It + is automatically called when the thread is started. + + In the \c private section, we have a QMutex, a QWaitCondition, + and a few other data members. The mutex protects the other data + member. + + \section1 RenderThread Class Implementation + + \snippet examples/threads/mandelbrot/renderthread.cpp 0 + + In the constructor, we initialize the \c restart and \c abort + variables to \c false. These variables control the flow of the \c + run() function. + + We also initialize the \c colormap array, which contains a series + of RGB colors. + + \snippet examples/threads/mandelbrot/renderthread.cpp 1 + + The destructor can be called at any point while the thread is + active. We set \c abort to \c true to tell \c run() to stop + running as soon as possible. We also call + QWaitCondition::wakeOne() to wake up the thread if it's sleeping. + (As we will see when we review \c run(), the thread is put to + sleep when it has nothing to do.) + + The important thing to notice here is that \c run() is executed + in its own thread (the worker thread), whereas the \c + RenderThread constructor and destructor (as well as the \c + render() function) are called by the thread that created the + worker thread. Therefore, we need a mutex to protect accesses to + the \c abort and \c condition variables, which might be accessed + at any time by \c run(). + + At the end of the destructor, we call QThread::wait() to wait + until \c run() has exited before the base class destructor is + invoked. + + \snippet examples/threads/mandelbrot/renderthread.cpp 2 + + The \c render() function is called by the \c MandelbrotWidget + whenever it needs to generate a new image of the Mandelbrot set. + The \c centerX, \c centerY, and \c scaleFactor parameters specify + the portion of the fractal to render; \c resultSize specifies the + size of the resulting QImage. + + The function stores the parameters in member variables. If the + thread isn't already running, it starts it; otherwise, it sets \c + restart to \c true (telling \c run() to stop any unfinished + computation and start again with the new parameters) and wakes up + the thread, which might be sleeping. + + \snippet examples/threads/mandelbrot/renderthread.cpp 3 + + \c run() is quite a big function, so we'll break it down into + parts. + + The function body is an infinite loop which starts by storing the + rendering parameters in local variables. As usual, we protect + accesses to the member variables using the class's mutex. Storing + the member variables in local variables allows us to minimize the + amout of code that needs to be protected by a mutex. This ensures + that the main thread will never have to block for too long when + it needs to access \c{RenderThread}'s member variables (e.g., in + \c render()). + + The \c forever keyword is, like \c foreach, a Qt pseudo-keyword. + + \snippet examples/threads/mandelbrot/renderthread.cpp 4 + \snippet examples/threads/mandelbrot/renderthread.cpp 5 + \snippet examples/threads/mandelbrot/renderthread.cpp 6 + \snippet examples/threads/mandelbrot/renderthread.cpp 7 + + Then comes the core of the algorithm. Instead of trying to create + a perfect Mandelbrot set image, we do multiple passes and + generate more and more precise (and computationally expensive) + approximations of the fractal. + + If we discover inside the loop that \c restart has been set to \c + true (by \c render()), we break out of the loop immediately, so + that the control quickly returns to the very top of the outer + loop (the \c forever loop) and we fetch the new rendering + parameters. Similarly, if we discover that \c abort has been set + to \c true (by the \c RenderThread destructor), we return from + the function immediately, terminating the thread. + + The core algorithm is beyond the scope of this tutorial. + + \snippet examples/threads/mandelbrot/renderthread.cpp 8 + \snippet examples/threads/mandelbrot/renderthread.cpp 9 + + Once we're done with all the iterations, we call + QWaitCondition::wait() to put the thread to sleep by calling, + unless \c restart is \c true. There's no use in keeping a worker + thread looping indefinitely while there's nothing to do. + + \snippet examples/threads/mandelbrot/renderthread.cpp 10 + + The \c rgbFromWaveLength() function is a helper function that + converts a wave length to a RGB value compatible with 32-bit + \l{QImage}s. It is called from the constructor to initialize the + \c colormap array with pleasing colors. + + \section1 MandelbrotWidget Class Defintion + + The \c MandelbrotWidget class uses \c RenderThread to draw the + Mandelbrot set on screen. Here's the class definition: + + \snippet examples/threads/mandelbrot/mandelbrotwidget.h 0 + + The widget reimplements many event handlers from QWidget. In + addition, it has an \c updatePixmap() slot that we'll connect to + the worker thread's \c renderedImage() signal to update the + display whenever we receive new data from the thread. + + Among the private variables, we have \c thread of type \c + RenderThread and \c pixmap, which contains the last rendered + image. + + \section1 MandelbrotWidget Class Implementation + + \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 0 + + The implementation starts with a few contants that we'll need + later on. + + \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 1 + + The interesting part of the constructor is the + qRegisterMetaType() and QObject::connect() calls. Let's start + with the \l{QObject::connect()}{connect()} call. + + Although it looks like a standard signal-slot connection between + two \l{QObject}s, because the signal is emitted in a different + thread than the receiver lives in, the connection is effectively a + \l{Qt::QueuedConnection}{queued connection}. These connections are + asynchronous (i.e., non-blocking), meaning that the slot will be + called at some point after the \c emit statement. What's more, the + slot will be invoked in the thread in which the receiver lives. + Here, the signal is emitted in the worker thread, and the slot is + executed in the GUI thread when control returns to the event loop. + + With queued connections, Qt must store a copy of the arguments + that were passed to the signal so that it can pass them to the + slot later on. Qt knows how to take of copy of many C++ and Qt + types, but QImage isn't one of them. We must therefore call the + template function qRegisterMetaType() before we can use QImage + as parameter in queued connections. + + \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 2 + \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 3 + \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 4 + + In \l{QWidget::paintEvent()}{paintEvent()}, we start by filling + the background with black. If we have nothing yet to paint (\c + pixmap is null), we print a message on the widget asking the user + to be patient and return from the function immediately. + + \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 5 + \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 6 + \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 7 + \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 8 + + If the pixmap has the right scale factor, we draw the pixmap directly onto + the widget. Otherwise, we scale and translate the \l{Coordinate + System}{coordinate system} before we draw the pixmap. By reverse mapping + the widget's rectangle using the scaled painter matrix, we also make sure + that only the exposed areas of the pixmap are drawn. The calls to + QPainter::save() and QPainter::restore() make sure that any painting + performed afterwards uses the standard coordinate system. + + \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 9 + + At the end of the paint event handler, we draw a text string and + a semi-transparent rectangle on top of the fractal. + + \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 10 + + Whenever the user resizes the widget, we call \c render() to + start generating a new image, with the same \c centerX, \c + centerY, and \c curScale parameters but with the new widget size. + + Notice that we rely on \c resizeEvent() being automatically + called by Qt when the widget is shown the first time to generate + the image the very first time. + + \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 11 + + The key press event handler provides a few keyboard bindings for + the benefit of users who don't have a mouse. The \c zoom() and \c + scroll() functions will be covered later. + + \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 12 + + The wheel event handler is reimplemented to make the mouse wheel + control the zoom level. QWheelEvent::delta() returns the angle of + the wheel mouse movement, in eights of a degree. For most mice, + one wheel step corresponds to 15 degrees. We find out how many + mouse steps we have and determine the zoom factor in consequence. + For example, if we have two wheel steps in the positive direction + (i.e., +30 degrees), the zoom factor becomes \c ZoomInFactor + to the second power, i.e. 0.8 * 0.8 = 0.64. + + \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 13 + + When the user presses the left mouse button, we store the mouse + pointer position in \c lastDragPos. + + \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 14 + + When the user moves the mouse pointer while the left mouse button + is pressed, we adjust \c pixmapOffset to paint the pixmap at a + shifted position and call QWidget::update() to force a repaint. + + \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 15 + + When the left mouse button is released, we update \c pixmapOffset + just like we did on a mouse move and we reset \c lastDragPos to a + default value. Then, we call \c scroll() to render a new image + for the new position. (Adjusting \c pixmapOffset isn't sufficient + because areas revealed when dragging the pixmap are drawn in + black.) + + \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 16 + + The \c updatePixmap() slot is invoked when the worker thread has + finished rendering an image. We start by checking whether a drag + is in effect and do nothing in that case. In the normal case, we + store the image in \c pixmap and reinitialize some of the other + members. At the end, we call QWidget::update() to refresh the + display. + + At this point, you might wonder why we use a QImage for the + parameter and a QPixmap for the data member. Why not stick to one + type? The reason is that QImage is the only class that supports + direct pixel manipulation, which we need in the worker thread. On + the other hand, before an image can be drawn on screen, it must + be converted into a pixmap. It's better to do the conversion once + and for all here, rather than in \c paintEvent(). + + \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 17 + + In \c zoom(), we recompute \c curScale. Then we call + QWidget::update() to draw a scaled pixmap, and we ask the worker + thread to render a new image corresponding to the new \c curScale + value. + + \snippet examples/threads/mandelbrot/mandelbrotwidget.cpp 18 + + \c scroll() is similar to \c zoom(), except that the affected + parameters are \c centerX and \c centerY. + + \section1 The main() Function + + The application's multithreaded nature has no impact on its \c + main() function, which is as simple as usual: + + \snippet examples/threads/mandelbrot/main.cpp 0 +*/ diff --git a/doc/src/examples/masterdetail.qdoc b/doc/src/examples/masterdetail.qdoc new file mode 100644 index 0000000000..1a8519ea33 --- /dev/null +++ b/doc/src/examples/masterdetail.qdoc @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example sql/masterdetail + \title Master Detail Example + + The Master Detail Example shows how to present data from different + data sources in the same application. The album titles, and the + corresponding artists and release dates, are kept in a + database, while each album's tracks are stored in an XML + file. + + The example also shows how to add as well as remove data from both + the database and the associated XML file using the API provided by + the QtSql and QtXml modules, respectively. + + \image masterdetail-example.png +*/ diff --git a/doc/src/examples/mdi.qdoc b/doc/src/examples/mdi.qdoc new file mode 100644 index 0000000000..f4a22244d7 --- /dev/null +++ b/doc/src/examples/mdi.qdoc @@ -0,0 +1,37 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example mainwindows/mdi + \title MDI Example + + The MDI example shows how to implement a Multiple Document Interface using Qt's + QMdiArea class. + + \image mdi-example.png + +*/ diff --git a/doc/src/examples/menus.qdoc b/doc/src/examples/menus.qdoc new file mode 100644 index 0000000000..7868d6d261 --- /dev/null +++ b/doc/src/examples/menus.qdoc @@ -0,0 +1,218 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example mainwindows/menus + \title Menus Example + + The Menus example demonstrates how menus can be used in a main + window application. + + A menu widget can be either a pull-down menu in a menu bar or a + standalone context menu. Pull-down menus are shown by the menu bar + when the user clicks on the respective item or presses the + specified shortcut key. Context menus are usually invoked by some + special keyboard key or by right-clicking. + + \image menus-example.png + + A menu consists of a list of \e action items. In applications, + many common commands can be invoked via menus, toolbar buttons as + well as keyboard shortcuts. Since the user expects the commands to + be performed in the same way, regardless of the user interface + used, it is useful to represent each command as an action. + + The Menus example consists of one single class, \c MainWindow, derived + from the QMainWindow class. When choosing one of the + action items in our application, it will display the item's path + in its central widget. + + \section1 MainWindow Class Definition + + QMainWindow provides a main application window, with a menu bar, + tool bars, dock widgets and a status bar around a large central + widget. + + \snippet examples/mainwindows/menus/mainwindow.h 0 + + In this example, we will see how to implement pull-down menus as + well as a context menu. In order to implement a custom context + menu we must reimplement QWidget's \l + {QWidget::}{contextMenuEvent()} function to receive the context + menu events for our main window. + + \snippet examples/mainwindows/menus/mainwindow.h 1 + + We must also implement a collection of private slots to respond to + the user activating any of our menu entries. Note that these + slots are left out of this documentation since they are trivial, + i.e., most of them are only displaying the action's path in the + main window's central widget. + + \snippet examples/mainwindows/menus/mainwindow.h 2 + + We have chosen to simplify the constructor by implementing two + private convenience functions to create the various actions, to + add them to menus and to insert the menus into our main window's + menu bar. + + \snippet examples/mainwindows/menus/mainwindow.h 3 + + Finally, we declare the various menus and actions as well as a + simple information label in the application wide scope. + + The QMenu class provides a menu widget for use in menu bars, + context menus, and other popup menus while the QAction class + provides an abstract user interface action that can be inserted + into widgets. + + In some situations it is useful to group actions together, e.g., + we have a \gui {Left Align} action, a \gui {Right Align} action, a + \gui {Justify} action, and a \gui {Center} action, and we want + only one of these actions to be active at any one time. One simple + way of achieving this is to group the actions together in an + action group using the QActionGroup class. + + \section1 MainWindow Class Implementation + + In the constructor, we start off by creating a regular QWidget and + make it our main window's central widget. Note that the main + window takes ownership of the widget pointer and deletes it at the + appropriate time. + + \snippet examples/mainwindows/menus/mainwindow.cpp 0 + \codeline + \snippet examples/mainwindows/menus/mainwindow.cpp 1 + + Then we create the information label as well as a top and bottom + filler that we add to a layout which we install on the central + widget. QMainWindow objects come with their own customized layout + and setting a layout on a the actual main window, or creating a + layout with a main window as a parent, is considered an error. You + should always set your own layout on the central widget instead. + + \snippet examples/mainwindows/menus/mainwindow.cpp 2 + + To create the actions and menus we call our two convenience + functions: \c createActions() and \c createMenus(). We will get + back to these shortly. + + QMainWindow's \l {QMainWindow::statusBar()}{statusBar()} function + returns the status bar for the main window (if the status bar does + not exist, this function will create and return an empty status + bar). We initialize the status bar and window title, resize the + window to an appropriate size as well as ensure that the main + window cannot be resized to a smaller size than the given + one. + + Now, let's take a closer look at the \c createActions() convenience + function that creates the various actions: + + \snippet examples/mainwindows/menus/mainwindow.cpp 4 + \dots + + A QAction object may contain an icon, a text, a shortcut, a status + tip, a "What's This?" text, and a tooltip. Most of these can be + set in the constructor, but they can also be set independently + using the provided convenience functions. + + In the \c createActions() function, we first create a \c newAct + action. We make \gui Ctrl+N its shortcut using the + QAction::setShortcut() function, and we set its status tip using the + QAction::setStatusTip() function (the status tip is displayed on all + status bars provided by the action's top-level parent widget). We + also connect its \l {QAction::}{triggered()} signal to the \c + newFile() slot. + + The rest of the actions are created in a similar manner. Please + see the source code for details. + + \snippet examples/mainwindows/menus/mainwindow.cpp 7 + + + Once we have created the \gui {Left Align}, \gui {Right Align}, + \gui {Justify}, and a \gui {Center} actions, we can also create + the previously mentioned action group. + + Each action is added to the group using QActionGroup's \l + {QActionGroup::}{addAction()} function. Note that an action also + can be added to a group by creating it with the group as its + parent. Since an action group is exclusive by default, only one of + the actions in the group is checked at any one time (this can be + altered using the QActionGroup::setExclusive() function). + + When all the actions are created, we use the \c createMenus() + function to add the actions to the menus and to insert the menus + into the menu bar: + + \snippet examples/mainwindows/menus/mainwindow.cpp 8 + + QMenuBar's \l {QMenuBar::addMenu()}{addMenu()} function appends a + new QMenu with the given title, to the menu bar (note that the + menu bar takes ownership of the menu). We use QWidget's \l + {QWidget::addAction()}{addAction()} function to add each action to + the corresponding menu. + + Alternatively, the QMenu class provides several \l + {QMenu::addAction()}{addAction()} convenience functions that create + and add new actions from given texts and/or icons. You can also + provide a member that will automatically connect to the new + action's \l {QAction::triggered()}{triggered()} signal, and a + shortcut represented by a QKeySequence instance. + + The QMenu::addSeparator() function creates and returns a new + separator action, i.e. an action for which QAction::isSeparator() + returns true, and adds the new action to the menu's list of + actions. + + \snippet examples/mainwindows/menus/mainwindow.cpp 12 + + Note the \gui Format menu. First of all, it is added as a submenu + to the \gui Edit Menu using QMenu's \l + {QMenu::addMenu()}{addMenu()} function. Secondly, take a look at the + alignment actions: In the \c createActions() function we added the + \c leftAlignAct, \c rightAlignAct, \c justifyAct and \c centerAct + actions to an action group. Nevertheless, we must add each action + to the menu separately while the action group does its magic + behind the scene. + + \snippet examples/mainwindows/menus/mainwindow.cpp 3 + + To provide a custom context menu, we must reimplement QWidget's \l + {QWidget::}{contextMenuEvent()} function to receive the widget's + context menu events (note that the default implementation simply + ignores these events). + + Whenever we receive such an event, we create a menu containing the + \gui Cut, \gui Copy and \gui Paste actions. Context menus can be + executed either asynchronously using the \l {QMenu::}{popup()} + function or synchronously using the \l {QMenu::}{exec()} + function. In this example, we have chosen to show the menu using + its \l {QMenu::}{exec()} function. By passing the event's position + as argument we ensure that the context menu appears at the + expected position. +*/ diff --git a/doc/src/examples/mousecalibration.qdoc b/doc/src/examples/mousecalibration.qdoc new file mode 100644 index 0000000000..9edc11b823 --- /dev/null +++ b/doc/src/examples/mousecalibration.qdoc @@ -0,0 +1,193 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example qws/mousecalibration + \title Mouse Calibration Example + + The Mouse Calibration example demonstrates how to write a simple + program using the mechanisms provided by the QWSMouseHandler class + to calibrate the mouse handler in \l{Qt for Embedded Linux}. + + Calibration is the process of mapping between physical + (i.e. device) coordinates and logical coordinates. + + The example consists of two classes in addition to the main program: + + \list + \o \c Calibration is a dialog widget that retrieves the device coordinates. + \o \c ScribbleWidget is a minimal drawing program used to let the user + test the new mouse settings. + \endlist + + First we will review the main program, then we will take a look at + the \c Calibration class. The \c ScribbleWidget class is only a + help tool in this context, and will not be covered here. + + \section1 The Main Program + + The program starts by presenting a message box informing the user + of what is going to happen: + + \snippet examples/qws/mousecalibration/main.cpp 0 + + The QMessageBox class provides a modal dialog with a range of + different messages, roughly arranged along two axes: severity and + complexity. The message box has a different icon for each of the + severity levels, but the icon must be specified explicitly. In our + case we use the default QMessageBox::NoIcon value. In addition we + use the default complexity, i.e. a message box showing the given + text and an \gui OK button. + + At this stage in the program, the mouse could be completely + uncalibrated, making the user unable to press the \gui OK button. For + that reason we use the static QTimer::singleShot() function to + make the message box disappear after 10 seconds. The QTimer class + provides repetitive and single-shot timers: The single shot + function calls the given slot after the specified interval. + + \snippet examples/qws/mousecalibration/main.cpp 1 + + Next, we create an instance of the \c Calibration class which is a + dialog widget retrieving the required sample coordinates: The + dialog sequentially presents five marks for the user to press, + storing the device coordinates for the mouse press events. + + \snippet examples/qws/mousecalibration/main.cpp 2 + + When the calibration dialog returns, we let the user test the new + mouse settings by drawing onto a \c ScribbleWidget object. Since + the mouse still can be uncalibrated, we continue to use the + QMessageBox and QTimer classes to inform the user about the + program's progress. + + An improved calibration tool would let the user choose between + accepting the new calibration, reverting to the old one, and + restarting the calibration. + + \section1 Calibration Class Definition + + The \c Calibration class inherits from QDialog and is responsible + for retrieving the device coordinates from the user. + + \snippet examples/qws/mousecalibration/calibration.h 0 + + We reimplement QDialog's \l {QDialog::exec()}{exec()} and \l + {QDialog::accept()}{accept()} slots, and QWidget's \l + {QWidget::paintEvent()}{paintEvent()} and \l + {QWidget::mouseReleaseEvent()}{mouseReleaseEvent()} functions. + + In addition, we declare a couple of private variables, \c data and + \c pressCount, holding the \c Calibration object's number of mouse + press events and current calibration data. The \c pressCount + variable is a convenience variable, while the \c data is a + QWSPointerCalibrationData object (storing the physical and logical + coordinates) that is passed to the mouse handler. The + QWSPointerCalibrationData class is simply a container for + calibration data. + + \section1 Calibration Class Implementation + + In the constructor we first ensure that the \c Calibration dialog + fills up the entire screen, has focus and will receive mouse + events (the latter by making the dialog modal): + + \snippet examples/qws/mousecalibration/calibration.cpp 0 + + Then we initialize the \l{QWSPointerCalibrationData::}{screenPoints} + array: + + \snippet examples/qws/mousecalibration/calibration.cpp 1 + + In order to specify the calibration, the + \l{QWSPointerCalibrationData::screenPoints}{screenPoints} array must + contain the screen coordinates for the logical positions + represented by the QWSPointerCalibrationData::Location enum + (e.g. QWSPointerCalibrationData::TopLeft). Since non-linearity is + expected to increase on the edge of the screen, all points are + kept 10 percent within the screen. The \c qt_screen pointer is a + reference to the screen device. There can only be one screen + device per application. + + \snippet examples/qws/mousecalibration/calibration.cpp 2 + + Finally, we initialize the variable which keeps track of the number of + mouse press events we have received. + + \snippet examples/qws/mousecalibration/calibration.cpp 3 + + The destructor is trivial. + + \snippet examples/qws/mousecalibration/calibration.cpp 4 + + The reimplementation of the QDialog::exec() slot is called from + the main program. + + First we clear the current calibration making the following mouse + event delivered in raw device coordinates. Then we call the + QWidget::grabMouse() function to make sure no mouse events are + lost, and the QWidget::activateWindow() function to make the + top-level widget containing this dialog, the active window. When + the call to the QDialog::exec() base function returns, we call + QWidget::releaseMouse() to release the mouse grab before the + function returns. + + \snippet examples/qws/mousecalibration/calibration.cpp 5 + + The QWidget::paintEvent() function is reimplemented to receive the + widget's paint events. A paint event is a request to repaint all + or parts of the widget. It can happen as a result of + QWidget::repaint() or QWidget::update(), or because the widget was + obscured and has now been uncovered, or for many other reasons. + In our reimplementation of the function we simply draw a cross at + the next point the user should press. + + \snippet examples/qws/mousecalibration/calibration.cpp 6 + + We then reimplement the QWidget::mouseReleaseEvent() function to + receive the widget's move events, using the QMouseEvent object + passed as parameter to find the coordinates the user pressed, and + update the QWSPointerCalibrationData::devPoints array. + + In order to complete the mapping between logical and physical + coordinates, the \l + {QWSPointerCalibrationData::devPoints}{devPoints} array must + contain the raw device coordinates for the logical positions + represented by the QWSPointerCalibrationData::Location enum + (e.g. QWSPointerCalibrationData::TopLeft) + + We continue by drawing the next cross, or close the dialog by + calling the QDialog::accept() slot if we have collected all the + required coordinate samples. + + \snippet examples/qws/mousecalibration/calibration.cpp 7 + + Our reimplementation of the QDialog::accept() slot simply activate + the new calibration data using the QWSMouseHandler::calibrate() + function. We also use the Q_ASSERT() macro to ensure that the number + of required samples are present. +*/ diff --git a/doc/src/examples/moveblocks.qdoc b/doc/src/examples/moveblocks.qdoc new file mode 100644 index 0000000000..7377ae0906 --- /dev/null +++ b/doc/src/examples/moveblocks.qdoc @@ -0,0 +1,214 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example animation/moveblocks + \title Move Blocks Example + + The Move Blocks example shows how to animate items in a + QGraphicsScene using a QStateMachine with a custom transition. + + \image moveblocks-example.png + + The example animates the blue blocks that you can see in the image + above. The animation moves the blocks between four preset positions. + + The example consists of the following classes: + + \list + \o \c StateSwitcher inherits QState and can add + \c {StateSwitchTransition}s to other states. + When entered, it will randomly transition to one of these + states. + \o \c StateSwitchTransition is a custom transition that + triggers on \c{StateSwitchEvent}s. + \o \c StateSwitchEvent is a QEvent that triggers \c{StateSwitchTransition}s. + \o \c QGraphicsRectWidget is a QGraphicsWidget that simply + paints its background in a solid \l{Qt::}{blue} color. + \endlist + + The blocks are instances of \c QGraphicsRectWidget and are + animated in a QGraphicsScene. We do this by building a state + graph, which we insert animations into. The graph is then executed + in a QStateMachine. All this is done in \c main(). + Let's look at the \c main() function first. + + \section1 The \c main() Function + + After QApplication has been initialized, we set up the + QGraphicsScene with its \c{QGraphicsRectWidget}s. + + \snippet examples/animation/moveblocks/main.cpp 1 + + After adding the scene to a QGraphicsView, it is time to build the + state graph. Let's first look at a statechart of what we are + trying to build. + + \image move-blocks-chart.png + + Note that the \c group has seven sub states, but we have only + included three of them in the diagram. The code that builds this + graph will be examined line-by-line, and will show how the graph + works. First off, we construct the \c group state: + + \snippet examples/animation/moveblocks/main.cpp 2 + + The timer is used to add a delay between each time the blocks are + moved. The timer is started when \c group is entered. As we will + see later, \c group has a transition back to the \c StateSwitcher + when the timer times out. \c group is the initial state in the + machine, so an animation will be scheduled when the example is + started. + + \snippet examples/animation/moveblocks/main.cpp 3 + \dots + \snippet examples/animation/moveblocks/main.cpp 4 + + \c createGeometryState() returns a QState that will set the + geometry of our items upon entry. It also assigns \c group as the + parent of this state. + + A QPropertyAnimation inserted into a transition will use the + values assigned to a QState (with QState::assignProperty()), i.e., + the animation will interpolate between the current values of the + properties and the values in the target state. We add animated + transitions to the state graph later. + + \snippet examples/animation/moveblocks/main.cpp 5 + + We move the items in parallel. Each item is added to \c + animationGroup, which is the animation that is inserted into the + transitions. + + \snippet examples/animation/moveblocks/main.cpp 6 + + The sequential animation group, \c subGroup, helps us insert a + delay between the animation of each item. + + \snippet examples/animation/moveblocks/main.cpp 7 + \dots + \snippet examples/animation/moveblocks/main.cpp 8 + + A StateSwitchTransition is added to the state switcher + in \c StateSwitcher::addState(). We also add the animation in this + function. Since QPropertyAnimation uses the values from the + states, we can insert the same QPropertyAnimation instance in all + \c {StateSwitchTransition}s. + + As mentioned previously, we add a transition to the state switcher + that triggers when the timer times out. + + \snippet examples/animation/moveblocks/main.cpp 9 + + Finally, we can create the state machine, add our initial state, + and start execution of the state graph. + + \section2 The \c createGeometryState() Function + + In \c createGeometryState(), we set up the geometry for each + graphics item. + + \snippet examples/animation/moveblocks/main.cpp 13 + + As mentioned before, QAbstractTransition will set up an animation + added with \l{QAbstractTransition::}{addAnimation()} using + property values set with \l{QState::}{assignProperty()}. + + \section1 The StateSwitcher Class + + \c StateSwitcher has state switch transitions to each \l{QState}s + we created with \c createGeometryState(). Its job is to transition + to one of these states at random when it is entered. + + All functions in \c StateSwitcher are inlined. We'll step through + its definition. + + \snippet examples/animation/moveblocks/main.cpp 10 + + \c StateSwitcher is a state designed for a particular purpose and + will always be a top-level state. We use \c m_stateCount to keep + track of how many states we are managing, and \c m_lastIndex to + remember which state was the last state to which we transitioned. + + \snippet examples/animation/moveblocks/main.cpp 11 + + We select the next state we are going to transition to, and post a + \c StateSwitchEvent, which we know will trigger the \c + StateSwitchTransition to the selected state. + + \snippet examples/animation/moveblocks/main.cpp 12 + + This is where the magic happens. We assign a number to each state + added. This number is given to both a StateSwitchTransition and to + StateSwitchEvents. As we have seen, state switch events will + trigger a transition with the same number. + + \section1 The StateSwitchTransition Class + + \c StateSwitchTransition inherits QAbstractTransition and triggers + on \c{StateSwitchEvent}s. It contains only inline functions, so + let's take a look at its \l{QAbstractTransition::}{eventTest()} + function, which is the only function that we define.. + + \snippet examples/animation/moveblocks/main.cpp 14 + + \c eventTest is called by QStateMachine when it checks whether a + transition should be triggered--a return value of true means that + it will. We simply check if our assigned number is equal to the + event's number (in which case we fire away). + + \section1 The StateSwitchEvent Class + + \c StateSwitchEvent inherits QEvent, and holds a number that has + been assigned to a state and state switch transition by + \c StateSwitcher. We have already seen how it is used to trigger + \c{StateSwitchTransition}s in \c StateSwitcher. + + \snippet examples/animation/moveblocks/main.cpp 15 + + We only have inlined functions in this class, so a look at its + definition will do. + + \section1 The QGraphicsRectWidget Class + + QGraphicsRectWidget inherits QGraphicsWidget and simply paints its + \l{QWidget::}{rect()} blue. We inline \l{QWidget::}{paintEvent()}, + which is the only function we define. Here is the + QGraphicsRectWidget class definition: + + \snippet examples/animation/moveblocks/main.cpp 16 + + \section1 Moving On + + The technique shown in this example works equally well for all + \l{QPropertyAnimation}s. As long as the value to be animated is a + Qt property, you can insert an animation of it into a state graph. + + QState::addAnimation() takes a QAbstractAnimation, so any type + of animation can be inserted into the graph. +*/ + diff --git a/doc/src/examples/movie.qdoc b/doc/src/examples/movie.qdoc new file mode 100644 index 0000000000..bbf3411ee7 --- /dev/null +++ b/doc/src/examples/movie.qdoc @@ -0,0 +1,39 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example widgets/movie + \title Movie Example + + The Movie example demonstrates how to use QMovie and QLabel to + display animations. Now that Qt comes with the \l{Phonon multimedia + framework} {Phonon multimedia framework}, QMovie is mostly + useful if one wants to play a simple animation without the added + complexity of a multimedia framework to install and deploy. + + \image movie-example.png +*/ diff --git a/doc/src/examples/multicastreceiver.qdoc b/doc/src/examples/multicastreceiver.qdoc new file mode 100644 index 0000000000..776c5fa5f8 --- /dev/null +++ b/doc/src/examples/multicastreceiver.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example network/multicastreceiver + \title Multicast Receiver Example + + The Multicast Receiever example shows how to receive information that is + sent to a multicast group. + + \image multicastreceiver-example.png +*/ diff --git a/doc/src/examples/multicastsender.qdoc b/doc/src/examples/multicastsender.qdoc new file mode 100644 index 0000000000..bfb91a677e --- /dev/null +++ b/doc/src/examples/multicastsender.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example network/multicastsender + \title Multicast Sender Example + + The Multicast Sender example shows how to send information to multiple + clients in a multicast group. + + \image multicastsender-example.png +*/ diff --git a/doc/src/examples/multipleinheritance.qdoc b/doc/src/examples/multipleinheritance.qdoc new file mode 100644 index 0000000000..aff80b7b85 --- /dev/null +++ b/doc/src/examples/multipleinheritance.qdoc @@ -0,0 +1,94 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example uitools/multipleinheritance + \title Multiple Inheritance Example + + The Multiple Inheritance Example shows how to use a form created with \QD + in an application by subclassing both QWidget and the user interface + class, which is \c{Ui::CalculatorForm}. + + \image multipleinheritance-example.png + + To subclass the \c calculatorform.ui file and ensure that \c qmake + processes it with the \c uic, we have to include \c calculatorform.ui + in the \c .pro file, as shown below: + + \snippet examples/uitools/multipleinheritance/multipleinheritance.pro 0 + + When the project is compiled, the \c uic will generate a corresponding + \c ui_calculatorform.h. + + \section1 CalculatorForm Definition + + In the \c CalculatorForm definition, we include the \c ui_calculatorform.h + that was generated earlier. + + \snippet examples/uitools/multipleinheritance/calculatorform.h 0 + + As mentioned earlier, the class is a subclass of both QWidget and + \c{Ui::CalculatorForm}. + + \snippet examples/uitools/multipleinheritance/calculatorform.h 1 + + Two slots are defined according to the \l{Automatic Connections} + {automatic connection} naming convention required by \c uic. This is + to ensure that \l{QMetaObject}'s auto-connection facilities connect + all the signals and slots involved automatically. + + \section1 CalculatorForm Implementation + + In the constructor, we call \c setupUi() to load the user interface file. + Note that we do not need the \c{ui} prefix as \c CalculatorForm is a + subclass of the user interface class. + + \snippet examples/uitools/multipleinheritance/calculatorform.cpp 0 + + We include two slots, \c{on_inputSpinBox1_valueChanged()} and + \c{on_inputSpinBox2_valueChanged()}. These slots respond to the + \l{QSpinBox::valueChanged()}{valueChanged()} signal that both spin boxes + emit. Whenever there is a change in one spin box's value, we take that + value and add it to whatever value the other spin box has. + + \snippet examples/uitools/multipleinheritance/calculatorform.cpp 1 + \codeline + \snippet examples/uitools/multipleinheritance/calculatorform.cpp 2 + + \section1 \c main() Function + + The \c main() function instantiates QApplication and \c CalculatorForm. + The \c calculator object is displayed by invoking the \l{QWidget::show()} + {show()} function. + + \snippet examples/uitools/multipleinheritance/main.cpp 0 + + There are various approaches to include forms into applications. The + Multiple Inheritance approach is just one of them. See + \l{Using a Designer UI File in Your Application} for more information on + the other approaches available. +*/ diff --git a/doc/src/examples/network-chat.qdoc b/doc/src/examples/network-chat.qdoc new file mode 100644 index 0000000000..42fbe74ad5 --- /dev/null +++ b/doc/src/examples/network-chat.qdoc @@ -0,0 +1,37 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example network/network-chat + \title Network Chat Example + + The Network Chat example demonstrates a stateful peer-to-peer Chat client + that uses broadcasting with QUdpSocket and QNetworkInterface to discover + its peers. + + \image network-chat-example.png +*/ diff --git a/doc/src/examples/orderform.qdoc b/doc/src/examples/orderform.qdoc new file mode 100644 index 0000000000..d6b421d62e --- /dev/null +++ b/doc/src/examples/orderform.qdoc @@ -0,0 +1,364 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example richtext/orderform + \title Order Form Example + + The Order Form example shows how to generate rich text documents by + combining a simple template with data input by the user in a dialog. Data + is extracted from a \c DetailsDialog object and displayed on a QTextEdit + with a QTextCursor, using various formats. Each form generated is added + to a QTabWidget for easy access. + + \image orderform-example.png + + \section1 DetailsDialog Definition + + The \c DetailsDialog class is a subclass of QDialog, implementing a slot + \c verify() to allow contents of the \c DetailsDialog to be verified later. + This is further explained in \c DetailsDialog Implementation. + + \snippet examples/richtext/orderform/detailsdialog.h 0 + + The constructor of \c DetailsDialog accepts parameters \a title and + \a parent. The class defines four \e{getter} functions: \c orderItems(), + \c senderName(), \c senderAddress(), and \c sendOffers() to allow data + to be accessed externally. + + The class definition includes input widgets for the required + fields, \c nameEdit and \c addressEdit. Also, a QCheckBox and a + QDialogButtonBox are defined; the former to provide the user with the + option to receive information on products and offers, and the latter + to ensure that buttons used are arranged according to the user's native + platform. In addition, a QTableWidget, \c itemsTable, is used to hold + order details. + + The screenshot below shows the \c DetailsDialog we intend to create. + + \image orderform-example-detailsdialog.png + + \section1 DetailsDialog Implementation + + The constructor of \c DetailsDialog instantiates the earlier defined fields + and their respective labels. The label for \c offersCheckBox is set and the + \c setupItemsTable() function is invoked to setup and populate + \c itemsTable. The QDialogButtonBox object, \c buttonBox, is instantiated + with \gui OK and \gui Cancel buttons. This \c buttonBox's \c accepted() and + \c rejected() signals are connected to the \c verify() and \c reject() + slots in \c DetailsDialog. + + \snippet examples/richtext/orderform/detailsdialog.cpp 0 + + A QGridLayout is used to place all the objects on the \c DetailsDialog. + + \snippet examples/richtext/orderform/detailsdialog.cpp 1 + + The \c setupItemsTable() function instantiates the QTableWidget object, + \c itemsTable, and sets the number of rows based on the QStringList + object, \c items, which holds the type of items ordered. The number of + columns is set to 2, providing a "name" and "quantity" layout. A \c for + loop is used to populate the \c itemsTable and the \c name item's flag + is set to Qt::ItemIsEnabled or Qt::ItemIsSelectable. For demonstration + purposes, the \c quantity item is set to a 1 and all items in the + \c itemsTable have this value for quantity; but this can be modified by + editing the contents of the cells at run time. + + \snippet examples/richtext/orderform/detailsdialog.cpp 2 + + The \c orderItems() function extracts data from the \c itemsTable and + returns it in the form of a QList<QPair<QString,int>> where each QPair + corresponds to an item and the quantity ordered. + + \snippet examples/richtext/orderform/detailsdialog.cpp 3 + + The \c senderName() function is used to return the value of the QLineEdit + used to store the name field for the order form. + + \snippet examples/richtext/orderform/detailsdialog.cpp 4 + + The \c senderAddress() function is used to return the value of the + QTextEdit containing the address for the order form. + + \snippet examples/richtext/orderform/detailsdialog.cpp 5 + + The \c sendOffers() function is used to return a \c true or \c false + value that is used to determine if the customer in the order form + wishes to receive more information on the company's offers and promotions. + + \snippet examples/richtext/orderform/detailsdialog.cpp 6 + + The \c verify() function is an additionally implemented slot used to + verify the details entered by the user into the \c DetailsDialog. If + the details entered are incomplete, a QMessageBox is displayed + providing the user the option to discard the \c DetailsDialog. Otherwise, + the details are accepted and the \c accept() function is invoked. + + \snippet examples/richtext/orderform/detailsdialog.cpp 7 + + \section1 MainWindow Definition + + The \c MainWindow class is a subclass of QMainWindow, implementing two + slots - \c openDialog() and \c printFile(). It also contains a private + instance of QTabWidget, \c letters. + + \snippet examples/richtext/orderform/mainwindow.h 0 + + \section1 MainWindow Implementation + + The \c MainWindow constructor sets up the \c fileMenu and the required + actions, \c newAction and \c printAction. These actions' \c triggered() + signals are connected to the additionally implemented openDialog() slot + and the default close() slot. The QTabWidget, \c letters, is + instantiated and set as the window's central widget. + + \snippet examples/richtext/orderform/mainwindow.cpp 0 + + The \c createLetter() function creates a new QTabWidget with a QTextEdit, + \c editor, as the parent. This function accepts four parameters that + correspond to we obtained through \c DetailsDialog, in order to "fill" + the \c editor. + + \snippet examples/richtext/orderform/mainwindow.cpp 1 + + We then obtain the cursor for the \c editor using QTextEdit::textCursor(). + The \c cursor is then moved to the start of the document using + QTextCursor::Start. + + \snippet examples/richtext/orderform/mainwindow.cpp 2 + + Recall the structure of a \l{Rich Text Document Structure} + {Rich Text Document}, where sequences of frames and + tables are always separated by text blocks, some of which may contain no + information. + + In the case of the Order Form Example, the document structure for this portion + is described by the table below: + + \table + \row + \o {1, 8} frame with \e{referenceFrameFormat} + \row + \o block \o \c{A company} + \row + \o block + \row + \o block \o \c{321 City Street} + \row + \o block + \row + \o block \o \c{Industry Park} + \row + \o block + \row + \o block \o \c{Another country} + \endtable + + This is accomplished with the following code: + + \snippet examples/richtext/orderform/mainwindow.cpp 3 + + Note that \c topFrame is the \c {editor}'s top-level frame and is not shown + in the document structure. + + We then set the \c{cursor}'s position back to its last position in + \c topFrame and fill in the customer's name (provided by the constructor) + and address - using a \c foreach loop to traverse the QString, \c address. + + \snippet examples/richtext/orderform/mainwindow.cpp 4 + + The \c cursor is now back in \c topFrame and the document structure for + the above portion of code is: + + \table + \row + \o block \o \c{Donald} + \row + \o block \o \c{47338 Park Avenue} + \row + \o block \o \c{Big City} + \endtable + + For spacing purposes, we invoke \l{QTextCursor::insertBlock()} + {insertBlock()} twice. The \l{QDate::currentDate()}{currentDate()} is + obtained and displayed. We use \l{QTextFrameFormat::setWidth()} + {setWidth()} to increase the width of \c bodyFrameFormat and we insert + a new frame with that width. + + \snippet examples/richtext/orderform/mainwindow.cpp 5 + + The following code inserts standard text into the order form. + + \snippet examples/richtext/orderform/mainwindow.cpp 6 + \snippet examples/richtext/orderform/mainwindow.cpp 7 + + This part of the document structure now contains the date, a frame with + \c bodyFrameFormat, as well as the standard text. + + \table + \row + \o block + \row + \o block + \row + \o block \o \c{Date: 25 May 2007} + \row + \o block + \row + \o {1, 4} frame with \e{bodyFrameFormat} + \row + \o block \o \c{I would like to place an order for the following items:} + \row + \o block + \row + \o block + \endtable + + A QTextTableFormat object, \c orderTableFormat, is used to hold the type + of item and the quantity ordered. + + \snippet examples/richtext/orderform/mainwindow.cpp 8 + + We use \l{QTextTable::cellAt()}{cellAt()} to set the headers for the + \c orderTable. + + \snippet examples/richtext/orderform/mainwindow.cpp 9 + + Then, we iterate through the QList of QPair objects to populate + \c orderTable. + + \snippet examples/richtext/orderform/mainwindow.cpp 10 + + The resulting document structure for this section is: + + \table + \row + \o {1, 11} \c{orderTable} with \e{orderTableFormat} + \row + \o block \o \c{Product} + \row + \o block \o \c{Quantity} + \row + \o block \o \c{T-shirt} + \row + \o block \o \c{4} + \row + \o block \o \c{Badge} + \row + \o block \o \c{3} + \row + \o block \o \c{Reference book} + \row + \o block \o \c{2} + \row + \o block \o \c{Coffee cup} + \row + \o block \o \c{5} + \endtable + + The \c cursor is then moved back to \c{topFrame}'s + \l{QTextFrame::lastPosition()}{lastPosition()} and more standard text + is inserted. + + \snippet examples/richtext/orderform/mainwindow.cpp 11 + \snippet examples/richtext/orderform/mainwindow.cpp 12 + + Another QTextTable is inserted, to display the customer's + preference regarding offers. + + \snippet examples/richtext/orderform/mainwindow.cpp 13 + + The document structure for this portion is: + + \table + \row + \o block + \row + \o block\o \c{Please update my...} + \row + \o {1, 5} block + \row + \o {1, 4} \c{offersTable} + \row + \o block \o \c{I want to receive...} + \row + \o block \o \c{I do not want to recieve...} + \row + \o block \o \c{X} + \endtable + + The \c cursor is moved to insert "Sincerely" along with the customer's + name. More blocks are inserted for spacing purposes. The \c printAction + is enabled to indicate that an order form can now be printed. + + \snippet examples/richtext/orderform/mainwindow.cpp 14 + + The bottom portion of the document structure is: + + \table + \row + \o block + \row + \o {1, 5} block\o \c{Sincerely,} + \row + \o block + \row + \o block + \row + \o block + \row + \o block \o \c{Donald} + \endtable + + The \c createSample() function is used for illustration purposes, to create + a sample order form. + + \snippet examples/richtext/orderform/mainwindow.cpp 15 + + The \c openDialog() function opens a \c DetailsDialog object. If the + details in \c dialog are accepted, the \c createLetter() function is + invoked using the parameters extracted from \c dialog. + + \snippet examples/richtext/orderform/mainwindow.cpp 16 + + In order to print out the order form, a \c printFile() function is + included, as shown below: + + \snippet examples/richtext/orderform/mainwindow.cpp 17 + + This function also allows the user to print a selected area with + QTextCursor::hasSelection(), instead of printing the entire document. + + \section1 \c main() Function + + The \c main() function instantiates \c MainWindow and sets its size to + 640x480 pixels before invoking the \c show() function and + \c createSample() function. + + \snippet examples/richtext/orderform/main.cpp 0 + +*/ diff --git a/doc/src/examples/overpainting.qdoc b/doc/src/examples/overpainting.qdoc new file mode 100644 index 0000000000..6b7be8c27c --- /dev/null +++ b/doc/src/examples/overpainting.qdoc @@ -0,0 +1,243 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example opengl/overpainting + \title Overpainting Example + + The Overpainting example shows how QPainter can be used + to overpaint a scene rendered using OpenGL in a QGLWidget. + + \image overpainting-example.png + + QGLWidget provides a widget with integrated OpenGL graphics support + that enables 3D graphics to be displayed using normal OpenGL calls, + yet also behaves like any other standard Qt widget with support for + signals and slots, properties, and Qt's action system. + + Usually, QGLWidget is subclassed to display a pure 3D scene. The + developer reimplements \l{QGLWidget::initializeGL()}{initializeGL()} + to initialize any required resources, \l{QGLWidget::resizeGL()}{resizeGL()} + to set up the projection and viewport, and + \l{QGLWidget::paintGL()}{paintGL()} to perform the OpenGL calls needed + to render the scene. However, it is possible to subclass QGLWidget + differently to allow 2D graphics, drawn using QPainter, to be + painted over a scene rendered using OpenGL. + + In this example, we demonstrate how this is done by reusing the code + from the \l{Hello GL Example}{Hello GL} example to provide a 3D scene, + and painting over it with some translucent 2D graphics. Instead of + examining each class in detail, we only cover the parts of the + \c GLWidget class that enable overpainting, and provide more detailed + discussion in the final section of this document. + + \section1 GLWidget Class Definition + + The \c GLWidget class is a subclass of QGLWidget, based on the one used + in the \l{Hello GL Example}{Hello GL} example. Rather than describe the + class as a whole, we show the first few lines of the class and only + discuss the changes we have made to the rest of it: + + \snippet examples/opengl/overpainting/glwidget.h 0 + \dots + \snippet examples/opengl/overpainting/glwidget.h 1 + \dots + \snippet examples/opengl/overpainting/glwidget.h 4 + + As usual, the widget uses \l{QGLWidget::initializeGL()}{initializeGL()} + to set up geometry for our scene and perform OpenGL initialization tasks. + The \l{QGLWidget::resizeGL()}{resizeGL()} function is used to ensure that + the 3D graphics in the scene are transformed correctly to the 2D viewport + displayed in the widget. + + Instead of implementing \l{QGLWidget::paintGL()}{paintGL()} to handle updates + to the widget, we implement a normal QWidget::paintEvent(). This + allows us to mix OpenGL calls and QPainter operations in a controlled way. + + In this example, we also implement QWidget::showEvent() to help with the + initialization of the 2D graphics used. + + The new private member functions and variables relate exclusively to the + 2D graphics and animation. The \c animate() slot is called periodically by the + \c animationTimer to update the widget; the \c createBubbles() function + initializes the \c bubbles list with instances of a helper class used to + draw the animation; the \c drawInstructions() function is responsible for + a semi-transparent message that is also overpainted onto the OpenGL scene. + + \section1 GLWidget Class Implementation + + Again, we only show the parts of the \c GLWidget implementation that are + relevant to this example. In the constructor, we initialize a QTimer to + control the animation: + + \snippet examples/opengl/overpainting/glwidget.cpp 0 + + We turn off the widget's \l{QWidget::autoFillBackground}{autoFillBackground} property to + instruct OpenGL not to paint a background for the widget when + \l{QPainter::begin()}{QPainter::begin()} is called. + + As in the \l{Hello GL Example}{Hello GL} example, the destructor is responsible + for freeing any OpenGL-related resources: + + \snippet examples/opengl/overpainting/glwidget.cpp 1 + + The \c initializeGL() function is fairly minimal, only setting up the QtLogo + object used in the scene. See the \l{Hello GL Example}{Hello GL} example + for details of the QtLogo class. + + \snippet examples/opengl/overpainting/glwidget.cpp 2 + + To cooperate fully with QPainter, we defer matrix stack operations and attribute + initialization until the widget needs to be updated. + + In this example, we implement \l{QWidget::paintEvent()}{paintEvent()} rather + than \l{QGLWidget::paintGL()}{paintGL()} to render + our scene. When drawing on a QGLWidget, the paint engine used by QPainter + performs certain operations that change the states of the OpenGL + implementation's matrix and property stacks. Therefore, it is necessary to + make all the OpenGL calls to display the 3D graphics before we construct + a QPainter to draw the 2D overlay. + + We render a 3D scene by setting up model and projection transformations + and other attributes. We use an OpenGL stack operation to preserve the + original matrix state, allowing us to recover it later: + + \snippet examples/opengl/overpainting/glwidget.cpp 4 + + We define a color to use for the widget's background, and set up various + attributes that define how the scene will be rendered. + + \snippet examples/opengl/overpainting/glwidget.cpp 6 + + We call the \c setupViewport() private function to set up the + projection used for the scene. This is unnecessary in OpenGL + examples that implement the \l{QGLWidget::paintGL()}{paintGL()} + function because the matrix stacks are usually unmodified between + calls to \l{QGLWidget::resizeGL()}{resizeGL()} and + \l{QGLWidget::paintGL()}{paintGL()}. + + Since the widget's background is not drawn by the system or by Qt, we use + an OpenGL call to paint it before positioning the object defined earlier + in the scene: + + \snippet examples/opengl/overpainting/glwidget.cpp 7 + + Once the QtLogo object's draw method has been executed, the GL + states we changed and the matrix stack needs to be restored to its + original state at the start of this function before we can begin + overpainting: + + \snippet examples/opengl/overpainting/glwidget.cpp 8 + + With the 3D graphics done, we construct a QPainter for use on the widget + and simply overpaint the widget with 2D graphics; in this case, using a + helper class to draw a number of translucent bubbles onto the widget, + and calling \c drawInstructions() to overlay some instructions: + + \snippet examples/opengl/overpainting/glwidget.cpp 10 + + When QPainter::end() is called, suitable OpenGL-specific calls are made to + write the scene, and its additional contents, onto the widget. + + With \l{QGLWidget::paintGL()}{paintGL()} the + \l{QGLWidget::swapBuffers()}{swapBuffers()} call is done for us. But an explicit + call to swapBuffers() is still not required because in the + \l{QWidget::paintEvent()}{paintEvent()} method the QPainter on the OpenGL + widget takes care of this for us. + + The implementation of the \l{QGLWidget::resizeGL()}{resizeGL()} function + sets up the dimensions of the viewport and defines a projection + transformation: + + \snippet examples/opengl/overpainting/glwidget.cpp 11 + + Ideally, we want to arrange the 2D graphics to suit the widget's dimensions. + To achieve this, we implement the \l{QWidget::showEvent()}{showEvent()} handler, + creating new graphic elements (bubbles) if necessary at appropriate positions + in the widget. + + \snippet examples/opengl/overpainting/glwidget.cpp 12 + + This function only has an effect if less than 20 bubbles have already been + created. + + The \c animate() slot is called every time the widget's \c animationTimer emits + the \l{QTimer::timeout()}{timeout()} signal. This keeps the bubbles moving + around. + + \snippet examples/opengl/overpainting/glwidget.cpp 13 + + We simply iterate over the bubbles in the \c bubbles list, updating the + widget before and after each of them is moved. + + The \c setupViewport() function is called from \c paintEvent() + and \c resizeGL(). + + \snippet examples/opengl/overpainting/glwidget.cpp 14 + + The \c drawInstructions() function is used to prepare some basic + instructions that will be painted with the other 2D graphics over + the 3D scene. + + \snippet examples/opengl/overpainting/glwidget.cpp 15 + + \section1 Summary + + When overpainting 2D content onto 3D content, we need to use a QPainter + \e and make OpenGL calls to achieve the desired effect. Since QPainter + itself uses OpenGL calls when used on a QGLWidget subclass, we need to + preserve the state of various OpenGL stacks when we perform our own + calls, using the following approach: + + \list + \o Reimplement QGLWidget::initializeGL(), but only perform minimal + initialization. QPainter will perform its own initialization + routines, modifying the matrix and property stacks, so it is better + to defer certain initialization tasks until just before you render + the 3D scene. + \o Reimplement QGLWidget::resizeGL() as in the pure 3D case. + \o Reimplement QWidget::paintEvent() to draw both 2D and 3D graphics. + \endlist + + The \l{QWidget::paintEvent()}{paintEvent()} implementation performs the + following tasks: + + \list + \o Push the current OpenGL modelview matrix onto a stack. + \o Perform initialization tasks usually done in the + \l{QGLWidget::initializeGL()}{initializeGL()} function. + \o Perform code that would normally be located in the widget's + \l{QGLWidget::resizeGL()}{resizeGL()} function to set the correct + perspective transformation and set up the viewport. + \o Render the scene using OpenGL calls. + \o Pop the OpenGL modelview matrix off the stack. + \o Construct a QPainter object. + \o Initialize it for use on the widget with the QPainter::begin() function. + \o Draw primitives using QPainter's member functions. + \o Call QPainter::end() to finish painting. + \endlist +*/ diff --git a/doc/src/examples/padnavigator.qdoc b/doc/src/examples/padnavigator.qdoc new file mode 100644 index 0000000000..76c1596440 --- /dev/null +++ b/doc/src/examples/padnavigator.qdoc @@ -0,0 +1,583 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example graphicsview/padnavigator + \title Pad Navigator Example + + The Pad Navigator Example shows how you can use Graphics View together with + embedded widgets and Qt's \l{State Machine Framework} to create a simple + but useful, dynamic, animated user interface. + + \image padnavigator-example.png + + The interface consists of a flippable, rotating pad with icons that can be + selected using the arrow keys on your keyboard or keypad. Pressing enter + will flip the pad around and reveal its back side, which has a form + embedded into a QGraphicsProxyWidget. You can interact with the form, and + press the enter key to flip back to the front side of the pad at any time. + + Graphics View provides the QGraphicsScene class for managing and + interacting with a large number of custom-made 2D graphical items derived + from the QGraphicsItem class, and a QGraphicsView widget for visualizing + the items, with support for zooming and rotation. + + This example consists of a \c RoundRectItem class, a \c FlippablePad class, + a \c PadNavigator class, a \c SplashItem class, and a \c main() function. + + \section1 RoundRectItem Class Definition + + The \c RoundRectItem class is used by itself to diplay the icons on the + pad, and as a base class for \c FlippablePad, the class for the pad itself. + The role of the class is to paint a round rectangle of a specified size and + gradient color, and optionally to paint a pixmap icon on top. To support \c + FlippablePad it also allows filling its contents with a plain window + background color. + + Let's start by reviewing the \c RoundRectItem class declaration. + + \snippet examples/graphicsview/padnavigator/roundrectitem.h 0 + + \c RoundRectItem inherits QGraphicsObject, which makes it easy to control + its properties using QPropertyAnimation. Its constructor takes a rectangle + to determine its bounds, and a color. + + Besides implementing the mandatory \l{QGraphicsItem::paint()}{paint()} and + \l{QGraphicsItem::boundingRect()}{boundingRect()} pure virtual functions, + it also provides the \c pixmap and \c fill properties. + + The \c pixmap property sets an optional pixmap that is drawn on top of the + round rectangle. The \c fill property will, when true, fill the round + rectangle contents with a fixed QPalette::Window background color. + Otherwise the contents are filled using a gradient based on the color + passed to \c RoundRectItem's constructor. + + \snippet examples/graphicsview/padnavigator/roundrectitem.h 1 + + The private data members are: + + \list + \o \c pix: The optional pixmap that is drawn on top of the rectangle. + \o \c fillRect: Corresponds to the \c fill property. + \o \c color: The configurable gradient color fill of the rectangle. + \o \c bounds: The bounds of the rectangle. + \o \c gradient: A precalculated gradient used to fill the rectangle. + \endlist + + We will now review the \c RoundRectItem implementation. Let's start by + looking at its constructor: + + \snippet examples/graphicsview/padnavigator/roundrectitem.cpp 0 + + The constructor initializes its member variables and forwards the \c parent + argument to QGraphicsObject's constructor. It then constructs the linear + gradient that is used in \l{QGraphicsItem::paint()}{paint()} to draw the + round rectangle's gradient background. The linear gradient's starting point + is at the top-left corner of the bounds, and the end is at the bottom-left + corner. The start color is identical to the color passed as an argument, + and a slightly darker color is chosen for the final stop. + + We store this gradient as a member variable to avoid having to recreate the + gradient every time the item is repainted. + + Finally we set the cache mode + \l{QGraphicsItem::ItemCoordinateCache}{ItemCoordinateCache}. This mode + causes the item's rendering to be cached into an off-screen pixmap that + remains persistent as we move and transform the item. This mode is ideal + for this example, and works particularily well with OpenGL and OpenGL ES. + + \snippet examples/graphicsview/padnavigator/roundrectitem.cpp 1 + + The \c pixmap property implementation simple returns the member pixmap, or + sets it and then calls \l{QGraphicsItem::update()}{update()}. + + \snippet examples/graphicsview/padnavigator/roundrectitem.cpp 2 + + As the \l{QGraphicsItem::paint()}{paint()} implementation below draws a + simple drop shadow down and to the right of the item, we return a slightly + adjusted rectangle from \l{QGraphicsItem::boundingRect()}{boundingRect()}. + + \snippet examples/graphicsview/padnavigator/roundrectitem.cpp 3 + + The \l{QGraphicsItem::paint()}{paint()} implementation starts by rendering + a semi transparent black round rectangle drop shadow, two units down and to + the right of the main item. + + \snippet examples/graphicsview/padnavigator/roundrectitem.cpp 4 + + We then draw the "foreground" round rectangle itself. The fill depends on + the \c fill property; if true, we will with a plain QPalette::Window color. + We get the corrent brush from QApplication::palette(). We assign a single + unit wide pen for the stroke, assign the brush, and then draw the + rectangle. + + \snippet examples/graphicsview/padnavigator/roundrectitem.cpp 5 + + If a pixmap has been assigned to the \e pixmap property, we draw this + pixmap in the center of the rectangle item. The pixmaps are scaled to match + the size of the icons; in arguably a better approach would have been to + store the icons with the right size in the first places. + + \snippet examples/graphicsview/padnavigator/roundrectitem.cpp 6 + + Finally, for completeness we include the \c fill property implementation. + It returns the \c fill member variable's value, and when assigned to, it + calls \l{QGraphicsItem::update()}{update()}. + + As mentioned already, \c RoundRectItem is the base class for \c + FlippablePad, which is the class representing the tilting pad itself. We + will proceed to reviewing \c FlippablePad. + + \section1 FlippablePad Class Definition + + \c FlippablePad is, in addition to its inherited \c RoundRectItem + responsibilities, responsible for creating and managing a grid of icons. + + \snippet examples/graphicsview/padnavigator/flippablepad.h 0 + + Its declaration is very simple: It inherits \c RoundRectItem and does not + need any special polymorphic behavior. It's suitable to declare its own + constructor, and a getter-function that allows \c PadNavigator to access + the icons in the grid by (row, column). + + The example has no "real" behavior or logic of any kind, and because of + that, the icons do not need to provide any \e behavior or special + interactions management. In a real application, however, it would be + natural for the \c FlippablePad and its icons to handle more of the + navigation logic. In this example, we have chosen to leave this to + the \c PadNavigator class, which we will get back to below. + + We will now review the \c FlippablePad implementation. This implementation + starts with two helper functions: \c boundsFromSize() and \c + posForLocation(): + + \snippet examples/graphicsview/padnavigator/flippablepad.cpp 0 + + \c boundsForSize() takes a QSize argument, and returns the bounding + rectangle of the flippable pad item. The QSize determines how many rows and + columns the icon grid should have. Each icon is given 150x150 units of + space, and this determines the bounds. + + \snippet examples/graphicsview/padnavigator/flippablepad.cpp 1 + + \c posForLocation() returns the position of an icon given its row and + column position. Like \c boundsForSize(), the function assumes each icon is + given 150x150 units of space, and that all icons are centered around the + flippable pad item's origin (0, 0). + + \snippet examples/graphicsview/padnavigator/flippablepad.cpp 2 + + The \c FlippablePad constructor passes suitable bounds (using \c + boundsForSize()) and specific color to \c RoundRectItem's constructor. + + \snippet examples/graphicsview/padnavigator/flippablepad.cpp 3 + + It then loads pixmaps from compiled-in resources to use for its icons. + QDirIterator is very useful in this context, as it allows us to fetch all + resource "*.png" files inside the \c :/images directory without explicitly + naming the files. + + We also make sure not to load more pixmaps than we need. + + \snippet examples/graphicsview/padnavigator/flippablepad.cpp 4 + + Now that we have the pixmaps, we can create icons, position then and assign + pixmaps. We start by finding a suitable size and color for the icons, and + initializing a convenient grid structure for storing the icons. This \c + iconGrid is also used later to find the icon for a specific (column, row) + location. + + For each row and column in our grid, we proceed to constructing each icon + as an instance of \c RoundRectItem. The item is placed by using the \c + posForLocation() helper function. To make room for the slip-behind + selection item, we give each icon a \l{QGraphicsItem::zValue()}{Z-value} of + 1. The pixmaps are distributed to the icons in round-robin fasion. + + Again, this approach is only suitable for example purposes. In a real-life + application where each icon represents a specific action, it would be more + natural to assign the pixmaps directly, or that the icons themselves + provide suitable pixmaps. + + \snippet examples/graphicsview/padnavigator/flippablepad.cpp 5 + + Finally, the \c iconAt() function returns a pointer to the icon at a + specific row and column. It makes a somewhat bold assumption that the input + is valid, which is fair because the \c PadNavigator class only calls this + function with correct input. + + We will now review the \c SplashItem class. + + \section1 SplashItem Class Definition + + The \c SplashItem class represents the "splash window", a semitransparent + white overlay with text that appears immediately after the application has + started, and disappears after pressing any key. The animation is controlled + by \c PadNavigator; this class is very simple by itself. + + \snippet examples/graphicsview/padnavigator/splashitem.h 0 + + The class declaration shows that \c SplashItem inherits QGraphicsObject to + allow it to be controlled by QPropertyAnimation. It reimplements the + mandatory \l{QGraphicsItem::paint()}{paint()} and + \l{QGraphicsItem::boundingRect()}{boundingRect()} pure virtual functions, + and keeps a \c text member variable which will contain the information text + displayed on this splash item. + + Let's look at its implementation. + + \snippet examples/graphicsview/padnavigator/splashitem.cpp 0 + + The constructor forwards to QGraphicsObject as expected, assigns a text + message to the \c text member variable, and enables + \l{QGraphicsItem::DeviceCoordinateCache}{DeviceCoordinateCache}. This cache + mode is suitable because the splash item only moves and is never + transformed, and because it contains text, it's important that it has a + pixel perfect visual appearance (in constrast to + \l{QGraphicsItem::ItemCoordinateCache}{ItemCoordinateCache}, where the + visual appearance is not as good). + + We use caching to avoid having to relayout and rerender the text for each + frame. An alterative approach would be to use the new QStaticText class. + + \snippet examples/graphicsview/padnavigator/splashitem.cpp 1 + + \c SplashItem's bounding rectangle is fixed at (400x175). + + \snippet examples/graphicsview/padnavigator/splashitem.cpp 2 + + The \l{QGraphicsItem::paint()}{paint()} implementation draws a clipped + round rectangle with a thick 2-unit border and a semi-transparent white + background. It proceeds to finding a suitable text area by adjusting the + splash item's bounding rectangle with 10 units in each side. The text is + rendered inside this rectangle, with top-left alignment, and with word + wrapping enabled. + + The main class now remains. We will proceed to reviewing \c PadNavigator. + + \section1 PadNavigator Class Definition + + \c PadNavigator represents the main window of our Pad Navigator Example + application. It creates and controls a somewhat complex state machine, and + several animations. Its class declaration is very simple: + + \snippet examples/graphicsview/padnavigator/padnavigator.h 0 + + It inherits QGraphicsView and reimplements only one function: + \l{QGraphicsView::resizeEvent()}{resizeEvent()}, to ensure the scene is + scaled to fit inside the view when resizing the main window. + + The \c PadNavigator constructor takes a QSize argument that determines the + number or rows and columns in the grid. + + It also keeps a private member instance, \c form, which is the generated + code for the pad's back side item's QGraphicsProxyWidget-embedded form. + + \snippet examples/graphicsview/padnavigator/padnavigator.cpp 0 + + \c PadNavigator's constructor is a bit long. In short, its job is to create + all items, including the \c FlippablePad, the \c SplashItem and the + QGraphicsProxyWidget \c backItem, and then to set up all animations, states + and transitions that control the behavior of the application. + + It starts out simple, by forwarding to QGraphicsView's constructor. + + \snippet examples/graphicsview/padnavigator/padnavigator.cpp 1 + + The first item to be created is \c SplashItem. This is going to be a top-level + item in the scene, next to \c FlippablePad, and stacked on top of it, so we + assign it a \l{QGraphicsItem::zValue()}{Z-value} of 1. + + \snippet examples/graphicsview/padnavigator/padnavigator.cpp 2 + + Now we construct the \c FlippablePad item, passing its column-row count to + its constructor. + + The pad is constrolled by three transformations, and we create one + QGraphicsRotation object for each of these. + + \list + \o \c flipRotation: Rotates the grid around its Qt::YAxis. This rotation is + animated from 0 to 180, and eventually back, when enter is pressed on the + keyboard, flipping the pad around. + \o \c xRotation: Rotates the grid around its Qt::XAxis. This is used to + tilt the pad vertically corresponding to which item is currently selected. + This way, the selected item is always kept in front. + \o \c yRotation: Rotates the grid around its Qt::YAxis. This is used to + tilt the pad horizontally corresponding to which item is selected. This + way, the selected item is always kept in front. + \endlist + + The combination of all three rotations is assigned via + QGraphicsItem::setTransformations(). + + \snippet examples/graphicsview/padnavigator/padnavigator.cpp 3 + + Now we construct the QGraphicsProxyWidget-embedded \c backItem. The proxy + widget is created as a child of the pad. We create a new QWidget and + populate it with the \c form member. To ensure the \c hostName line edit is + the first to receive input focus when this item is shown, we call + \l{QWidget::setFocus()}{setFocus()} immediately. This will not give the + widget focus right away; it will only prepare the item to automatically + receive focus once it is shown. + + The QWidget based form is embedded into the proxy widget. The proxy is + hidden initially; we only want to show it when the pad is rotated at least + 90 degrees, and we also rotate the proxy itself by 180 degrees. This way we + give the impression that the proxy widget is "behind" the flipped pad, when + in fact, it's actually \e{on top of it}. + + We enable \l{QGraphicsItem::ItemCoordinateCache}{ItemCoordinateCache} to + ensure the flip animation can run smoothly. + + \snippet examples/graphicsview/padnavigator/padnavigator.cpp 4 + + We now create the selection item. This is simply another instance of \c + RoundRectItem that is slightly larger than the icons on the pad. We create + it as an immediate child of the \c FlippablePad, so the selection item is a + sibling to all the icons. By giving it a + \l{QGraphicsItem::zValue()}{Z-value} of 0.5 we ensure it will slide beteen + the pad and its icons. + + What follows now is a series of animation initializations. + + \snippet examples/graphicsview/padnavigator/padnavigator.cpp 5 + + We begin with the animations that apply to the splash item. The first + animation, \c smoothSplashMove, ensures that the "y" property of \c splash + will be animated with a 250-millisecond duration + \l{QEasingCurve::InQuad}{InQuad} easing function. \c smoothSplashOpacity + ensures the opacity of \c splash eases in and out in 250 milliseconds. + + The values are assigned by \c PadNavigator's state machine, which is + created later. + + \snippet examples/graphicsview/padnavigator/padnavigator.cpp 6 + + These are the animations that control the selection item's movement and the + \c xRotation and \c yRotation QGraphicsRotation objects that tilt the pad. + All animations have a duration of 125 milliseconds, and they all use the + \l{QEasingCurve::InOutQuad}{InOutQuad} easing function. + + \snippet examples/graphicsview/padnavigator/padnavigator.cpp 7 + + We now create the animations that control the flip-effect when you press + the enter key. The main goal is to rotate the pad by 180 degrees or back, + but we also need to make sure the selection item's tilt rotations are reset + back to 0 when the pad is flipped, and restored back to their original + values when flipped back: + + \list + \o \c smoothFlipRotation: Animates the main 180 degree rotation of the pad. + \o \c smoothFlipScale: Scales the pad out and then in again while the pad is rotating. + \o \c smoothFlipXRotation: Animates the selection item's X-tilt to 0 and back. + \o \c smoothFlipYRotation: Animates the selection item's Y-tilt to 0 and back. + \o \c flipAnimation: A parallel animation group that ensures all the above animations are run in parallel. + \endlist + + All animations are given a 500 millisecond duration and an + \l{QEasingCurve::InOutQuad}{InOutQuad} easing function. + + It's worth taking a close look at \c smoothFlipScale. This animation's + start and end values are both 1.0, but at animation step 0.5 the + animation's value is 0.7. This means that after 50% of the animation's + duration, or 250 milliseconds, the pad will be scaled down to 0.7x of its + original size, which gives a great visual effect while flipping. + + \snippet examples/graphicsview/padnavigator/padnavigator.cpp 8 + + This section uses a trick to ensure that certain properties are assigned + precisely when the flip animation passes 50%, or 90 degrees, rotation. In + short, the pad's icons and selection item are all hidden, the pad's \c fill + property is enabled, and \c backItem is shown when flipping over. When + flipping back, the reverse properties are applied. + + The way this is achieved is by running a sequential animation in parallel + to the other animations. This sequence, dubbed \c setVariablesSequence, + starts with a 250 millisecond pause, and then executes several animations + with a duration of 0. Each animation will ensure that properties are set + immediate at this point. + + This approach can also be used to call functions or set any other + properties at a specific time while an animation is running. + + \snippet examples/graphicsview/padnavigator/padnavigator.cpp 9 + + We will now create the state machine. The whole \c PadNavigator state + machinery is controlled by one single state machine that has a + straight-forward state structure. The state engine itself is created + as a child of the \c PadNavigator itself. We then create three top level + states: + + \list + \o \c splashState: The initial state where the splash item is visible. + \o \c frontState: The base state where the splash is gone and we can see + the front side of the pad, and navigate the selection item. + \o \c backState: The flipped state where the \c backItem is visible, and we + can interact with the QGraphicsProxyWidget-embedded form. + \endlist + + \snippet examples/graphicsview/padnavigator/padnavigator.cpp 10 + + Each state assigns specific properties to objects on entry. Most + interesting perhaps is the assignment of the value 0.0 to the pad's \c + flipRotation angle property when in \c frontState, and 180.0 when in \c + backState. At the end of this section we register default animations with + the state engine; these animations will apply to their respective objects + and properties for any state transition. Otherwise it's common to assign + animations to specific transitions. + + The \c splashState state is set as the initial state. This is required + before we start the state engine. We proceed with creating some + transitions. + + \snippet examples/graphicsview/padnavigator/padnavigator.cpp 11 + + QEventTransition defines a very flexible transition type. You can use this + class to trigger a transition based on an object receiving an event of a + specific type. In this case, we would like to transition from \c + splashState into \c frontState if \c PadNavigator receives any key press + event (QEvent::KeyPress). + + We register the \c splashItem's animations to this transition to ensure they + are used to animate the item's movement and opacity. + + \snippet examples/graphicsview/padnavigator/padnavigator.cpp 12 + + We use QKeyEventTransition to capture specific key events. In this case, we + detect that the user presses Qt::Key_Return or Qt::Key_Enter, and use this + to trigger transitions between \c frontState and backState. We register \c + flipAnimation, our complex parallel animation group, with these + transitions. + + We continue by defining the states for each of the icons in the grid. + + \snippet examples/graphicsview/padnavigator/padnavigator.cpp 13 + + We will use state groups to control transitions between icons. Each icon + represents a \e substate of \c frontState. We will then define transitions + between the states by detecting key presses, using QKeyEventTransition. + + We start by creating all the substates, and at the same time we create a + temporary grid structure for the states to make it easier to find which + states represents icons that are up, down, left and to the right each + other. + + Once the first substate is known, we set this up as the initial substate of + \c frontState. We will use the (0, 0), or top-left, icon for the initial + substate. We initialze the selection item's position to be exactly where + the top-left icon is. + + \snippet examples/graphicsview/padnavigator/padnavigator.cpp 14 + + We can now create four transitions for each icon. Each transition ensures + that we move to the state corresponding to which arrow key has been + pressed. It's clear from this techinique that we could design any other + specific transitions to and from each of the sub states depending on these + and other keys. + + \snippet examples/graphicsview/padnavigator/padnavigator.cpp 15 + + Also, for each of the icons, we assign suitable values to the \c xRotation + and \c yRotation objects' "angle"-properties. If you recall, these + properties "tilt" the pad corresponding to which item is currently + selected. We ensure each icon is invisible when the pad is flipped, and + visible when the pad is not flipped. To ensure the visible property is + assigned at the right time, we add property-controlling animations to the + \c setVariableSequence animation defined earlier. + + \snippet examples/graphicsview/padnavigator/padnavigator.cpp 16 + + We are now finished with all states, transitions, and animations. We now + create the scene that will contain all our items. The scene gets a defined + background pixmap, and we disable item indexing (as most items in this + scene are animated). We add our \c pad item to the scene, and use its + bounding rectangle to fixate the scene rectangle. This rectangle is used by + the view to find a suitable size for the application window. + + Then the scene is assigned to the view, or in our case, \c PadNavigator + itself. + + \snippet examples/graphicsview/padnavigator/padnavigator.cpp 17 + + Now that the scene has received its final size, we can position the splash + item at the very top, find its fade-out position, and add it to the scene. + + \snippet examples/graphicsview/padnavigator/padnavigator.cpp 18 + + The view toggles a few necessary properties: + + \list + \o It disables its scroll bars - this application has no use for scroll bars. + \o It assigns a minimum size. This is necessary to avoid numerical errors + in our fit-in-view \c resizeEvent() implementation. + \o It sets \l{QGraphicsView::FullViewportUpdate}{FullViewportUpdate}, to + ensure QGraphicsView doesn't spend time figuring out precisely what needs + to be redrawn. This application is very simple - if anything changes, + everything is updated. + \o It enables background caching - this makes no performance difference + with OpenGL, but without OpenGL it avoids unnecessary re-scaling of the + background pixmap. + \o It sets render hints that increase rendering quality. + \o If OpenGL is supported, a QGLWidget viewport is assigned to the view. + \endlist + + Finally, we start the state engine. + + \snippet examples/graphicsview/padnavigator/padnavigator.cpp 19 + + The \l{QGraphicsView::resizeEvent()}{resizeEvent()} implementation calls + the base implementation, and then calls QGraphicsView::fitInView() to scale + the scene so that it fits perfectly inside the view. + + By resizing the main application window, you can see this effect yourself. + The scene contents grow when you make the window larger, and shrink when + you make it smaller, while keeping the aspect ratio intact. + + \section1 The main() Function + + \snippet examples/graphicsview/padnavigator/main.cpp 0 + + The \c main function creates the QApplication instance, uses + Q_INIT_RESOURCE to ensure our compiled-in resources aren't removed by the + linker, and then creates a 3x3 \c PadNavigator instance and shows it. + + Our flippable pad shows up with a suitable splash item once control returns + to the event loop. + + \section1 Performance Notes + + The example uses OpenGL if this is available, to achieve optimal + performance; otherwise perspective tranformations can be quite costly. + + Although this example does use QGraphicsProxyWidget to demonstrate + integration of Qt widget components integrated into Graphics View, using + QGraphicsProxyWidget comes with a performance penalty, and is therefore not + recommended for embedded development. + + This example uses extensive item caching to avoid rerendering of static + elements, at the expense of graphics memory. +*/ diff --git a/doc/src/examples/painterpaths.qdoc b/doc/src/examples/painterpaths.qdoc new file mode 100644 index 0000000000..076437c1ec --- /dev/null +++ b/doc/src/examples/painterpaths.qdoc @@ -0,0 +1,418 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example painting/painterpaths + \title Painter Paths Example + + The Painter Paths example shows how painter paths can be used to + build complex shapes for rendering. + + \image painterpaths-example.png + + The QPainterPath class provides a container for painting + operations, enabling graphical shapes to be constructed and + reused. + + A painter path is an object composed of a number of graphical + building blocks (such as rectangles, ellipses, lines, and curves), + and can be used for filling, outlining, and clipping. The main + advantage of painter paths over normal drawing operations is that + complex shapes only need to be created once, but they can be drawn + many times using only calls to QPainter::drawPath(). + + The example consists of two classes: + + \list + \o The \c RenderArea class which is a custom widget displaying + a single painter path. + \o The \c Window class which is the applications main window + displaying several \c RenderArea widgets, and allowing the user + to manipulate the painter paths' filling, pen, color + and rotation angle. + \endlist + + First we will review the \c Window class, then we will take a look + at the \c RenderArea class. + + \section1 Window Class Definition + + The \c Window class inherits QWidget, and is the applications main + window displaying several \c RenderArea widgets, and allowing the + user to manipulate the painter paths' filling, pen, color and + rotation angle. + + \snippet examples/painting/painterpaths/window.h 0 + + We declare three private slots to respond to user input regarding + filling and color: \c fillRuleChanged(), \c fillGradientChanged() + and \c penColorChanged(). + + When the user changes the pen width and the rotation angle, the + new value is passed directly on to the \c RenderArea widgets using + the QSpinBox::valueChanged() signal. The reason why we must + implement slots to update the filling and color, is that QComboBox + doesn't provide a similar signal passing the new value as + argument; so we need to retrieve the new value, or values, before + we can update the \c RenderArea widgets. + + \snippet examples/painting/painterpaths/window.h 1 + + We also declare a couple of private convenience functions: \c + populateWithColors() populates a given QComboBox with items + corresponding to the color names Qt knows about, and \c + currentItemData() returns the current item for a given QComboBox. + + \snippet examples/painting/painterpaths/window.h 2 + + Then we declare the various components of the main window + widget. We also declare a convenience constant specifying the + number of \c RenderArea widgets. + + \section1 Window Class Implementation + + In the implementation of the \c Window class we first declare the + constant \c Pi with six significant figures: + + \snippet examples/painting/painterpaths/window.cpp 0 + + In the constructor, we then define the various painter paths and + create corresponding \c RenderArea widgets which will render the + graphical shapes: + + \snippet examples/painting/painterpaths/window.cpp 1 + + We construct a rectangle with sharp corners using the + QPainterPath::moveTo() and QPainterPath::lineTo() + functions. + + QPainterPath::moveTo() moves the current point to the point passed + as argument. A painter path is an object composed of a number of + graphical building blocks, i.e. subpaths. Moving the current point + will also start a new subpath (implicitly closing the previously + current path when the new one is started). The + QPainterPath::lineTo() function adds a straight line from the + current point to the given end point. After the line is drawn, the + current point is updated to be at the end point of the line. + + We first move the current point starting a new subpath, and we + draw three of the rectangle's sides. Then we call the + QPainterPath::closeSubpath() function which draws a line to the + beginning of the current subpath. A new subpath is automatically + begun when the current subpath is closed. The current point of the + new path is (0, 0). We could also have called + QPainterPath::lineTo() to draw the last line as well, and then + explicitly start a new subpath using the QPainterPath::moveTo() + function. + + QPainterPath also provide the QPainterPath::addRect() convenience + function, which adds a given rectangle to the path as a closed + subpath. The rectangle is added as a clockwise set of lines. The + painter path's current position after the rect has been added is + at the top-left corner of the rectangle. + + \snippet examples/painting/painterpaths/window.cpp 2 + + Then we construct a rectangle with rounded corners. As before, we + use the QPainterPath::moveTo() and QPainterPath::lineTo() + functions to draw the rectangle's sides. To create the rounded + corners we use the QPainterPath::arcTo() function. + + QPainterPath::arcTo() creates an arc that occupies the given + rectangle (specified by a QRect or the rectangle's coordinates), + beginning at the given start angle and extending the given degrees + counter-clockwise. Angles are specified in degrees. Clockwise arcs + can be specified using negative angles. The function connects the + current point to the starting point of the arc if they are not + already connected. + + \snippet examples/painting/painterpaths/window.cpp 3 + + We also use the QPainterPath::arcTo() function to construct the + ellipse path. First we move the current point starting a new + path. Then we call QPainterPath::arcTo() with starting angle 0.0 + and 360.0 degrees as the last argument, creating an ellipse. + + Again, QPainterPath provides a convenience function ( + QPainterPath::addEllipse()) which creates an ellipse within a + given bounding rectangle and adds it to the painter path. If the + current subpath is closed, a new subpath is started. The ellipse + is composed of a clockwise curve, starting and finishing at zero + degrees (the 3 o'clock position). + + \snippet examples/painting/painterpaths/window.cpp 4 + + When constructing the pie chart path we continue to use a + combination of the mentioned functions: First we move the current + point, starting a new subpath. Then we create a line from the + center of the chart to the arc, and the arc itself. When we close + the subpath, we implicitly construct the last line back to the + center of the chart. + + \snippet examples/painting/painterpaths/window.cpp 5 + + Constructing a polygon is equivalent to constructing a rectangle. + + QPainterPath also provide the QPainterPath::addPolygon() + convenience function which adds the given polygon to the path as a + new subpath. Current position after the polygon has been added is + the last point in polygon. + + \snippet examples/painting/painterpaths/window.cpp 6 + + Then we create a path consisting of a group of subpaths: First we + move the current point, and create a circle using the + QPainterPath::arcTo() function with starting angle 0.0, and 360 + degrees as the last argument, as we did when we created the + ellipse path. Then we move the current point again, starting a + new subpath, and construct three sides of a square using the + QPainterPath::lineTo() function. + + Now, when we call the QPainterPath::closeSubpath() fucntion the + last side is created. Remember that the + QPainterPath::closeSubpath() function draws a line to the + beginning of the \e current subpath, i.e the square. + + QPainterPath provide a convenience function, + QPainterPath::addPath() which adds a given path to the path that + calls the function. + + \snippet examples/painting/painterpaths/window.cpp 7 + + When creating the text path, we first create the font. Then we set + the font's style strategy which tells the font matching algorithm + what type of fonts should be used to find an appropriate default + family. QFont::ForceOutline forces the use of outline fonts. + + To construct the text, we use the QPainterPath::addText() function + which adds the given text to the path as a set of closed subpaths + created from the supplied font. The subpaths are positioned so + that the left end of the text's baseline lies at the specified + point. + + \snippet examples/painting/painterpaths/window.cpp 8 + + To create the Bezier path, we use the QPainterPath::cubicTo() + function which adds a Bezier curve between the current point and + the given end point with the given control point. After the curve + is added, the current point is updated to be at the end point of + the curve. + + In this case we omit to close the subpath so that we only have a + simple curve. But there is still a logical line from the curve's + endpoint back to the beginning of the subpath; it becomes visible + when filling the path as can be seen in the applications main + window. + + \snippet examples/painting/painterpaths/window.cpp 9 + + The final path that we construct shows that you can use + QPainterPath to construct rather complex shapes using only the + previous mentioned QPainterPath::moveTo(), QPainterPath::lineTo() + and QPainterPath::closeSubpath() functions. + + \snippet examples/painting/painterpaths/window.cpp 10 + + Now that we have created all the painter paths that we need, we + create a corresponding \c RenderArea widget for each. In the end, + we make sure that the number of render areas is correct using the + Q_ASSERT() macro. + + \snippet examples/painting/painterpaths/window.cpp 11 + + Then we create the widgets associated with the painter paths' fill + rule. + + There are two available fill rules in Qt: The Qt::OddEvenFill rule + determine whether a point is inside the shape by drawing a + horizontal line from the point to a location outside the shape, + and count the number of intersections. If the number of + intersections is an odd number, the point is inside the + shape. This rule is the default. + + The Qt::WindingFill rule determine whether a point is inside the + shape by drawing a horizontal line from the point to a location + outside the shape. Then it determines whether the direction of the + line at each intersection point is up or down. The winding number + is determined by summing the direction of each intersection. If + the number is non zero, the point is inside the shape. + + The Qt::WindingFill rule can in most cases be considered as the + intersection of closed shapes. + + \snippet examples/painting/painterpaths/window.cpp 12 + + We also create the other widgets associated with the filling, the + pen and the rotation angle. + + \snippet examples/painting/painterpaths/window.cpp 16 + + We connect the comboboxes \l {QComboBox::activated()}{activated()} + signals to the associated slots in the \c Window class, while we + connect the spin boxes \l + {QSpinBox::valueChanged()}{valueChanged()} signal directly to the + \c RenderArea widget's respective slots. + + \snippet examples/painting/painterpaths/window.cpp 17 + + We add the \c RenderArea widgets to a separate layout which we + then add to the main layout along with the rest of the widgets. + + \snippet examples/painting/painterpaths/window.cpp 18 + + Finally, we initialize the \c RenderArea widgets by calling the \c + fillRuleChanged(), \c fillGradientChanged() and \c + penColorChanged() slots, and we set the inital pen width and + window title. + + \snippet examples/painting/painterpaths/window.cpp 19 + \codeline + \snippet examples/painting/painterpaths/window.cpp 20 + \codeline + \snippet examples/painting/painterpaths/window.cpp 21 + + The private slots are implemented to retrieve the new value, or + values, from the associated comboboxes and update the RenderArea + widgets. + + First we determine the new value, or values, using the private \c + currentItemData() function and the qvariant_cast() template + function. Then we call the associated slot for each of the \c + RenderArea widgets to update the painter paths. + + \snippet examples/painting/painterpaths/window.cpp 22 + + The \c populateWithColors() function populates the given combobox + with items corresponding to the color names Qt knows about + provided by the static QColor::colorNames() function. + + \snippet examples/painting/painterpaths/window.cpp 23 + + The \c currentItemData() function simply return the current item + of the given combobox. + + \section1 RenderArea Class Definition + + The \c RenderArea class inherits QWidget, and is a custom widget + displaying a single painter path. + + \snippet examples/painting/painterpaths/renderarea.h 0 + + We declare several public slots updating the \c RenderArea + widget's associated painter path. In addition we reimplement the + QWidget::minimumSizeHint() and QWidget::sizeHint() functions to + give the \c RenderArea widget a reasonable size within our + application, and we reimplement the QWidget::paintEvent() event + handler to draw its painter path. + + \snippet examples/painting/painterpaths/renderarea.h 1 + + Each instance of the \c RenderArea class has a QPainterPath, a + couple of fill colors, a pen width, a pen color and a rotation + angle. + + \section1 RenderArea Class Implementation + + The constructor takes a QPainterPath as argument (in addition to + the optional QWidget parent): + + \snippet examples/painting/painterpaths/renderarea.cpp 0 + + In the constructor we initialize the \c RenderArea widget with the + QPainterPath parameter as well as initializing the pen width and + rotation angle. We also set the widgets \l + {QWidget::backgroundRole()}{background role}; QPalette::Base is + typically white. + + \snippet examples/painting/painterpaths/renderarea.cpp 1 + \codeline + \snippet examples/painting/painterpaths/renderarea.cpp 2 + + Then we reimplement the QWidget::minimumSizeHint() and + QWidget::sizeHint() functions to give the \c RenderArea widget a + reasonable size within our application. + + \snippet examples/painting/painterpaths/renderarea.cpp 3 + \codeline + \snippet examples/painting/painterpaths/renderarea.cpp 4 + \codeline + \snippet examples/painting/painterpaths/renderarea.cpp 5 + \codeline + \snippet examples/painting/painterpaths/renderarea.cpp 6 + \codeline + \snippet examples/painting/painterpaths/renderarea.cpp 7 + + The various public slots updates the \c RenderArea widget's + painter path by setting the associated property and make a call to + the QWidget::update() function, forcing a repaint of the widget + with the new rendering preferences. + + The QWidget::update() slot does not cause an immediate repaint; + instead it schedules a paint event for processing when Qt returns + to the main event loop. + + \snippet examples/painting/painterpaths/renderarea.cpp 8 + + A paint event is a request to repaint all or parts of the + widget. The paintEvent() function is an event handler that can be + reimplemented to receive the widget's paint events. We reimplement + the event handler to render the \c RenderArea widget's painter + path. + + First, we create a QPainter for the \c RenderArea instance, and + set the painter's render hints. The QPainter::RenderHints are used + to specify flags to QPainter that may, or may not, be respected by + any given engine. QPainter::Antialiasing indicates that the engine + should anti-alias the edges of primitives if possible, i.e. put + additional pixels around the original ones to smooth the edges. + + \snippet examples/painting/painterpaths/renderarea.cpp 9 + + Then we scale the QPainter's coordinate system to ensure that the + painter path is rendered in the right size, i.e that it grows with + the \c RenderArea widget when the application is resized. When we + constructed the various painter paths, they were all rnedered + within a square with a 100 pixel width wich is equivalent to \c + RenderArea::sizeHint(). The QPainter::scale() function scales the + coordinate system by the \c RenderArea widget's \e current width + and height divided by 100. + + Now, when we are sure that the painter path has the right size, we + can translate the coordinate system to make the painter path + rotate around the \c RenderArea widget's center. After we have + performed the rotation, we must remember to translate the + coordinate system back again. + + \snippet examples/painting/painterpaths/renderarea.cpp 10 + + Then we set the QPainter's pen with the instance's rendering + preferences. We create a QLinearGradient and set its colors + corresponding to the \c RenderArea widget's fill colors. Finally, + we set the QPainter's brush (the gradient is automatically + converted into a QBrush), and draw the \c RenderArea widget's + painter path using the QPainter::drawPath() function. +*/ diff --git a/doc/src/examples/pbuffers.qdoc b/doc/src/examples/pbuffers.qdoc new file mode 100644 index 0000000000..6390bde28a --- /dev/null +++ b/doc/src/examples/pbuffers.qdoc @@ -0,0 +1,37 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example opengl/pbuffers + \title Pixel Buffers Example + + The Pixel Buffers example demonstrates how to use the + QGLPixelBuffer class to render into an off-screen buffer and use + the contents as a dynamic texture in a QGLWidget. + + \image pbuffers-example.png +*/ diff --git a/doc/src/examples/pbuffers2.qdoc b/doc/src/examples/pbuffers2.qdoc new file mode 100644 index 0000000000..de82c304f3 --- /dev/null +++ b/doc/src/examples/pbuffers2.qdoc @@ -0,0 +1,37 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example opengl/pbuffers2 + \title Pixel Buffers 2 Example + + The Pixel Buffers 2 example demonstrates how to use the + QGLPixelBuffer class to render into an off-screen buffer and use + the contents as a dynamic texture in a QGLWidget. + + \image pbuffers2-example.png +*/ diff --git a/doc/src/examples/pinchzoom.qdoc b/doc/src/examples/pinchzoom.qdoc new file mode 100644 index 0000000000..3cca892a27 --- /dev/null +++ b/doc/src/examples/pinchzoom.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example touch/pinchzoom + \title Pinch Zoom Example + + The Pinch Zoom example shows how to use low-level touch information + to recognize a gesture. + + \image touch-pinchzoom-example.png +*/ diff --git a/doc/src/examples/pingpong.qdoc b/doc/src/examples/pingpong.qdoc new file mode 100644 index 0000000000..5fc8009879 --- /dev/null +++ b/doc/src/examples/pingpong.qdoc @@ -0,0 +1,93 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example statemachine/pingpong + \title Ping Pong States Example + + The Ping Pong States example shows how to use parallel states together + with custom events and transitions in \l{The State Machine Framework}. + + This example implements a statechart where two states communicate by + posting events to the state machine. The state chart looks as follows: + + \img pingpong-example.png + \omit + \caption This is a caption + \endomit + + The \c pinger and \c ponger states are parallel states, i.e. they are + entered simultaneously and will take transitions independently of + eachother. + + The \c pinger state will post the first \c ping event upon entry; the \c + ponger state will respond by posting a \c pong event; this will cause the + \c pinger state to post a new \c ping event; and so on. + + \snippet examples/statemachine/pingpong/main.cpp 0 + + Two custom events are defined, \c PingEvent and \c PongEvent. + + \snippet examples/statemachine/pingpong/main.cpp 1 + + The \c Pinger class defines a state that posts a \c PingEvent to the state + machine when the state is entered. + + \snippet examples/statemachine/pingpong/main.cpp 2 + + The \c PingTransition class defines a transition that is triggered by + events of type \c PingEvent, and that posts a \c PongEvent (with a delay + of 500 milliseconds) to the state machine when the transition is + triggered. + + \snippet examples/statemachine/pingpong/main.cpp 3 + + The \c PongTransition class defines a transition that is triggered by + events of type \c PongEvent, and that posts a \c PingEvent (with a delay + of 500 milliseconds) to the state machine when the transition is + triggered. + + \snippet examples/statemachine/pingpong/main.cpp 4 + + The main() function begins by creating a state machine and a parallel + state group. + + \snippet examples/statemachine/pingpong/main.cpp 5 + + Next, the \c pinger and \c ponger states are created, with the parallel + state group as their parent state. Note that the transitions are \e + targetless. When such a transition is triggered, the source state won't be + exited and re-entered; only the transition's onTransition() function will + be called, and the state machine's configuration will remain the same, + which is precisely what we want in this case. + + \snippet examples/statemachine/pingpong/main.cpp 6 + + Finally, the group is added to the state machine, the machine is started, + and the application event loop is entered. + + */ diff --git a/doc/src/examples/pixelator.qdoc b/doc/src/examples/pixelator.qdoc new file mode 100644 index 0000000000..809231465b --- /dev/null +++ b/doc/src/examples/pixelator.qdoc @@ -0,0 +1,255 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example itemviews/pixelator + \title Pixelator Example + + The Pixelator example shows how delegates can be used to customize the way that + items are rendered in standard item views. + + \image pixelator-example.png + + By default, QTreeView, QTableView, and QListView use a standard item delegate + to display and edit a set of common data types that are sufficient for many + applications. However, an application may need to represent items of data in a + particular way, or provide support for rendering more specialized data types, + and this often requires the use of a custom delegate. + + In this example, we show how to use custom delegates to modify the appearance + of standard views. To do this, we implement the following components: + + \list + \i A model which represents each pixel in an image as an item of data, where each + item contains a value for the brightness of the corresponding pixel. + \i A custom delegate that uses the information supplied by the model to represent + each pixel as a black circle on a white background, where the radius of the + circle corresponds to the darkness of the pixel. + \endlist + + This example may be useful for developers who want to implement their own table + models or custom delegates. The process of creating custom delegates for editing + item data is covered in the \l{Spin Box Delegate Example}{Spin Box Delegate} + example. + + \section1 ImageModel Class Definition + + The \c ImageModel class is defined as follows: + + \snippet examples/itemviews/pixelator/imagemodel.h 0 + + Since we only require a simple, read-only table model, we only need to implement + functions to indicate the dimensions of the image and supply data to other + components. + + \section1 ImageModel Class Implementation + + The constructor is trivial: + + \snippet examples/itemviews/pixelator/imagemodel.cpp 0 + + The \c setImage() function sets the image that will be used by the model: + + \snippet examples/itemviews/pixelator/imagemodel.cpp 1 + + The QAbstractItemModel::reset() call tells the view(s) that the model + has changed. + + The \c rowCount() and \c columnCount() functions return the height and width of + the image respectively: + + \snippet examples/itemviews/pixelator/imagemodel.cpp 2 + \snippet examples/itemviews/pixelator/imagemodel.cpp 3 + + Since the image is a simple two-dimensional structure, the \c parent arguments + to these functions are unused. They both simply return the relevant size from + the underlying image object. + + The \c data() function returns data for the item that corresponds to a given + model index in a format that is suitable for a particular role: + + \snippet examples/itemviews/pixelator/imagemodel.cpp 4 + + In this implementation, we only check that the model index is valid, and that + the role requested is the \l{Qt::ItemDataRole}{DisplayRole}. If so, the function + returns the grayscale value of the relevant pixel in the image; otherwise, a null + model index is returned. + + This model can be used with QTableView to display the integer brightness values + for the pixels in the image. However, we will implement a custom delegate to + display this information in a more artistic way. + + The \c headerData() function is also reimplemented: + + \snippet examples/itemviews/pixelator/imagemodel.cpp 5 + + We return (1, 1) as the size hint for a header item. If we + didn't, the headers would default to a larger size, preventing + us from displaying really small items (which can be specified + using the \gui{Pixel size} combobox). + + \section1 PixelDelegate Class Definition + + The \c PixelDelegate class is defined as follows: + + \snippet examples/itemviews/pixelator/pixeldelegate.h 0 + + This class provides only basic features for a delegate so, unlike the + \l{Spin Box Delegate Example}{Spin Box Delegate} example, we subclass + QAbstractItemDelegate instead of QItemDelegate. + + We only need to reimplement \l{QAbstractItemDelegate::paint()}{paint()} and + \l{QAbstractItemDelegate::sizeHint()}{sizeHint()} in this class. + However, we also provide a delegate-specific \c setPixelSize() function so + that we can change the delegate's behavior via the signals and slots mechanism. + + \section1 PixelDelegate Class Implementation + + The \c PixelDelegate constructor is used to set up a default value for + the size of each "pixel" that it renders. The base class constructor is + also called to ensure that the delegate is set up with a parent object, + if one is supplied: + + \snippet examples/itemviews/pixelator/pixeldelegate.cpp 0 + + Each item is rendered by the delegate's + \l{QAbstractItemDelegate::paint()}{paint()} function. The view calls this + function with a ready-to-use QPainter object, style information that the + delegate should use to correctly draw the item, and an index to the item in + the model: + + \snippet examples/itemviews/pixelator/pixeldelegate.cpp 1 + + The first task the delegate has to perform is to draw the item's background + correctly. Usually, selected items appear differently to non-selected items, + so we begin by testing the state passed in the style option and filling the + background if necessary. + + The radius of each circle is calculated in the following lines of code: + + \snippet examples/itemviews/pixelator/pixeldelegate.cpp 3 + \snippet examples/itemviews/pixelator/pixeldelegate.cpp 4 + + First, the largest possible radius of the circle is determined by taking the + smallest dimension of the style option's \c rect attribute. + Using the model index supplied, we obtain a value for the brightness of the + relevant pixel in the image. The radius of the circle is calculated by + scaling the brightness to fit within the item and subtracting it from the + largest possible radius. + + \snippet examples/itemviews/pixelator/pixeldelegate.cpp 5 + \snippet examples/itemviews/pixelator/pixeldelegate.cpp 6 + \snippet examples/itemviews/pixelator/pixeldelegate.cpp 7 + + We save the painter's state, turn on antialiasing (to obtain smoother + curves), and turn off the pen. + + \snippet examples/itemviews/pixelator/pixeldelegate.cpp 8 + \snippet examples/itemviews/pixelator/pixeldelegate.cpp 9 + + The foreground of the item (the circle representing a pixel) must be + rendered using an appropriate brush. For unselected items, we will use a + solid black brush; selected items are drawn using a predefined brush from + the style option's palette. + + \snippet examples/itemviews/pixelator/pixeldelegate.cpp 10 + + Finally, we paint the circle within the rectangle specified by the style + option and we call \l{QPainter::}{restore()} on the painter. + + The \c paint() function does not have to be particularly complicated; it is + only necessary to ensure that the state of the painter when the function + returns is the same as it was when it was called. This usually + means that any transformations applied to the painter must be preceded by + a call to QPainter::save() and followed by a call to QPainter::restore(). + + The delegate's \l{QAbstractItemDelegate::}{sizeHint()} function + returns a size for the item based on the predefined pixel size, initially set + up in the constructor: + + \snippet examples/itemviews/pixelator/pixeldelegate.cpp 11 + + The delegate's size is updated whenever the pixel size is changed. + We provide a custom slot to do this: + + \snippet examples/itemviews/pixelator/pixeldelegate.cpp 12 + + \section1 Using The Custom Delegate + + In this example, we use a main window to display a table of data, using the + custom delegate to render each cell in a particular way. Much of the + \c MainWindow class performs tasks that are not related to item views. Here, + we only quote the parts that are relevant. You can look at the rest of the + implementation by following the links to the code at the top of this + document. + + In the constructor, we set up a table view, turn off its grid, and hide its + headers: + + \snippet examples/itemviews/pixelator/mainwindow.cpp 0 + \dots + \snippet examples/itemviews/pixelator/mainwindow.cpp 1 + + This enables the items to be drawn without any gaps between them. Removing + the headers also prevents the user from adjusting the sizes of individual + rows and columns. + + We also set the minimum section size to 1 on the headers. If we + didn't, the headers would default to a larger size, preventing + us from displaying really small items (which can be specified + using the \gui{Pixel size} combobox). + + The custom delegate is constructed with the main window as its parent, so + that it will be deleted correctly later, and we set it on the table view. + + \snippet examples/itemviews/pixelator/mainwindow.cpp 2 + + Each item in the table view will be rendered by the \c PixelDelegate + instance. + + We construct a spin box to allow the user to change the size of each "pixel" + drawn by the delegate: + + \snippet examples/itemviews/pixelator/mainwindow.cpp 3 + + This spin box is connected to the custom slot we implemented in the + \c PixelDelegate class. This ensures that the delegate always draws each + pixel at the currently specified size: + + \snippet examples/itemviews/pixelator/mainwindow.cpp 4 + \dots + \snippet examples/itemviews/pixelator/mainwindow.cpp 5 + + We also connect the spin box to a slot in the \c MainWindow class. This + forces the view to take into account the new size hints for each item; + these are provided by the delegate in its \c sizeHint() function. + + \snippet examples/itemviews/pixelator/mainwindow.cpp 6 + + We explicitly resize the columns and rows to match the + \gui{Pixel size} combobox. +*/ diff --git a/doc/src/examples/plugandpaint.qdoc b/doc/src/examples/plugandpaint.qdoc new file mode 100644 index 0000000000..d685d0c880 --- /dev/null +++ b/doc/src/examples/plugandpaint.qdoc @@ -0,0 +1,540 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example tools/plugandpaint + \title Plug & Paint Example + + The Plug & Paint example demonstrates how to write Qt + applications that can be extended through plugins. + + \image plugandpaint.png Screenshot of the Plug & Paint example + + A plugin is a dynamic library that can be loaded at run-time to + extend an application. Qt makes it possible to create custom + plugins and to load them using QPluginLoader. To ensure that + plugins don't get lost, it is also possible to link them + statically to the executable. The Plug & Paint example uses + plugins to support custom brushes, shapes, and image filters. A + single plugin can provide multiple brushes, shapes, and/or + filters. + + If you want to learn how to make your own application extensible + through plugins, we recommend that you start by reading this + overview, which explains how to make an application use plugins. + Afterward, you can read the + \l{tools/plugandpaintplugins/basictools}{Basic Tools} and + \l{tools/plugandpaintplugins/extrafilters}{Extra Filters} + overviews, which show how to implement static and dynamic + plugins, respectively. + + Plug & Paint consists of the following classes: + + \list + \o \c MainWindow is a QMainWindow subclass that provides the menu + system and that contains a \c PaintArea as the central widget. + \o \c PaintArea is a QWidget that allows the user to draw using a + brush and to insert shapes. + \o \c PluginDialog is a dialog that shows information about the + plugins detected by the application. + \o \c BrushInterface, \c ShapeInterface, and \c FilterInterface are + abstract base classes that can be implemented by plugins to + provide custom brushes, shapes, and image filters. + \endlist + + \section1 The Plugin Interfaces + + We will start by reviewing the interfaces defined in \c + interfaces.h. These interfaces are used by the Plug & Paint + application to access extra functionality. They are implemented + in the plugins. + + + \snippet examples/tools/plugandpaint/interfaces.h 0 + + The \c BrushInterface class declares four pure virtual functions. + The first pure virtual function, \c brushes(), returns a list of + strings that identify the brushes provided by the plugin. By + returning a QStringList instead of a QString, we make it possible + for a single plugin to provide multiple brushes. The other + functions have a \c brush parameter to identify which brush + (among those returned by \c brushes()) is used. + + \c mousePress(), \c mouseMove(), and \c mouseRelease() take a + QPainter and one or two \l{QPoint}s, and return a QRect + identifying which portion of the image was altered by the brush. + + The class also has a virtual destructor. Interface classes + usually don't need such a destructor (because it would make + little sense to \c delete the object that implements the + interface through a pointer to the interface), but some compilers + emit a warning for classes that declare virtual functions but no + virtual destructor. We provide the destructor to keep these + compilers happy. + + \snippet examples/tools/plugandpaint/interfaces.h 1 + + The \c ShapeInterface class declares a \c shapes() function that + works the same as \c{BrushInterface}'s \c brushes() function, and + a \c generateShape() function that has a \c shape parameter. + Shapes are represented by a QPainterPath, a data type that can + represent arbitrary 2D shapes or combinations of shapes. The \c + parent parameter can be used by the plugin to pop up a dialog + asking the user to specify more information. + + \snippet examples/tools/plugandpaint/interfaces.h 2 + + The \c FilterInterface class declares a \c filters() function + that returns a list of filter names, and a \c filterImage() + function that applies a filter to an image. + + \snippet examples/tools/plugandpaint/interfaces.h 4 + + To make it possible to query at run-time whether a plugin + implements a given interface, we must use the \c + Q_DECLARE_INTERFACE() macro. The first argument is the name of + the interface. The second argument is a string identifying the + interface in a unique way. By convention, we use a "Java package + name" syntax to identify interfaces. If we later change the + interfaces, we must use a different string to identify the new + interface; otherwise, the application might crash. It is therefore + a good idea to include a version number in the string, as we did + above. + + The \l{tools/plugandpaintplugins/basictools}{Basic Tools} plugin + and the \l{tools/plugandpaintplugins/extrafilters}{Extra Filters} + plugin shows how to derive from \c BrushInterface, \c + ShapeInterface, and \c FilterInterface. + + A note on naming: It might have been tempting to give the \c + brushes(), \c shapes(), and \c filters() functions a more generic + name, such as \c keys() or \c features(). However, that would + have made multiple inheritance impractical. When creating + interfaces, we should always try to give unique names to the pure + virtual functions. + + \section1 The MainWindow Class + + The \c MainWindow class is a standard QMainWindow subclass, as + found in many of the other examples (e.g., + \l{mainwindows/application}{Application}). Here, we'll + concentrate on the parts of the code that are related to plugins. + + \snippet examples/tools/plugandpaint/mainwindow.cpp 4 + + The \c loadPlugins() function is called from the \c MainWindow + constructor to detect plugins and update the \gui{Brush}, + \gui{Shapes}, and \gui{Filters} menus. We start by handling static + plugins (available through QPluginLoader::staticInstances()) + + To the application that uses the plugin, a Qt plugin is simply a + QObject. That QObject implements plugin interfaces using multiple + inheritance. + + \snippet examples/tools/plugandpaint/mainwindow.cpp 5 + + The next step is to load dynamic plugins. We initialize the \c + pluginsDir member variable to refer to the \c plugins + subdirectory of the Plug & Paint example. On Unix, this is just a + matter of initializing the QDir variable with + QApplication::applicationDirPath(), the path of the executable + file, and to do a \l{QDir::cd()}{cd()}. On Windows and Mac OS X, + this file is usually located in a subdirectory, so we need to + take this into account. + + \snippet examples/tools/plugandpaint/mainwindow.cpp 6 + \snippet examples/tools/plugandpaint/mainwindow.cpp 7 + \snippet examples/tools/plugandpaint/mainwindow.cpp 8 + + We use QDir::entryList() to get a list of all files in that + directory. Then we iterate over the result using \l foreach and + try to load the plugin using QPluginLoader. + + The QObject provided by the plugin is accessible through + QPluginLoader::instance(). If the dynamic library isn't a Qt + plugin, or if it was compiled against an incompatible version of + the Qt library, QPluginLoader::instance() returns a null pointer. + + If QPluginLoader::instance() is non-null, we add it to the menus. + + \snippet examples/tools/plugandpaint/mainwindow.cpp 9 + + At the end, we enable or disable the \gui{Brush}, \gui{Shapes}, + and \gui{Filters} menus based on whether they contain any items. + + \snippet examples/tools/plugandpaint/mainwindow.cpp 10 + + For each plugin (static or dynamic), we check which interfaces it + implements using \l qobject_cast(). First, we try to cast the + plugin instance to a \c BrushInterface; if it works, we call the + private function \c addToMenu() with the list of brushes returned + by \c brushes(). Then we do the same with the \c ShapeInterface + and the \c FilterInterface. + + \snippet examples/tools/plugandpaint/mainwindow.cpp 3 + + The \c aboutPlugins() slot is called on startup and can be + invoked at any time through the \gui{About Plugins} action. It + pops up a \c PluginDialog, providing information about the loaded + plugins. + + \image plugandpaint-plugindialog.png Screenshot of the Plugin dialog + + + The \c addToMenu() function is called from \c loadPlugin() to + create \l{QAction}s for custom brushes, shapes, or filters and + add them to the relevant menu. The QAction is created with the + plugin from which it comes from as the parent; this makes it + convenient to get access to the plugin later. + + \snippet examples/tools/plugandpaint/mainwindow.cpp 0 + + The \c changeBrush() slot is invoked when the user chooses one of + the brushes from the \gui{Brush} menu. We start by finding out + which action invoked the slot using QObject::sender(). Then we + get the \c BrushInterface out of the plugin (which we + conveniently passed as the QAction's parent) and we call \c + PaintArea::setBrush() with the \c BrushInterface and the string + identifying the brush. Next time the user draws on the paint + area, \c PaintArea will use this brush. + + \snippet examples/tools/plugandpaint/mainwindow.cpp 1 + + The \c insertShape() is invoked when the use chooses one of the + shapes from the \gui{Shapes} menu. We retrieve the QAction that + invoked the slot, then the \c ShapeInterface associated with that + QAction, and finally we call \c ShapeInterface::generateShape() + to obtain a QPainterPath. + + \snippet examples/tools/plugandpaint/mainwindow.cpp 2 + + The \c applyFilter() slot is similar: We retrieve the QAction + that invoked the slot, then the \c FilterInterface associated to + that QAction, and finally we call \c + FilterInterface::filterImage() to apply the filter onto the + current image. + + \section1 The PaintArea Class + + The \c PaintArea class contains some code that deals with \c + BrushInterface, so we'll review it briefly. + + \snippet examples/tools/plugandpaint/paintarea.cpp 0 + + In \c setBrush(), we simply store the \c BrushInterface and the + brush that are given to us by \c MainWindow. + + \snippet examples/tools/plugandpaint/paintarea.cpp 1 + + In the \l{QWidget::mouseMoveEvent()}{mouse move event handler}, + we call the \c BrushInterface::mouseMove() function on the + current \c BrushInterface, with the current brush. The mouse + press and mouse release handlers are very similar. + + \section1 The PluginDialog Class + + The \c PluginDialog class provides information about the loaded + plugins to the user. Its constructor takes a path to the plugins + and a list of plugin file names. It calls \c findPlugins() + to fill the QTreeWdiget with information about the plugins: + + \snippet examples/tools/plugandpaint/plugindialog.cpp 0 + + The \c findPlugins() is very similar to \c + MainWindow::loadPlugins(). It uses QPluginLoader to access the + static and dynamic plugins. Its helper function \c + populateTreeWidget() uses \l qobject_cast() to find out which + interfaces are implemented by the plugins: + + \snippet examples/tools/plugandpaint/plugindialog.cpp 1 + + \section1 Importing Static Plugins + + The \l{tools/plugandpaintplugins/basictools}{Basic Tools} plugin + is built as a static plugin, to ensure that it is always + available to the application. This requires using the + Q_IMPORT_PLUGIN() macro somewhere in the application (in a \c + .cpp file) and specifying the plugin in the \c .pro file. + + For Plug & Paint, we have chosen to put Q_IMPORT_PLUGIN() in \c + main.cpp: + + \snippet examples/tools/plugandpaint/main.cpp 0 + + The argument to Q_IMPORT_PLUGIN() is the plugin's name, as + specified with Q_EXPORT_PLUGIN2() in the \l{Exporting the + Plugin}{plugin}. + + In the \c .pro file, we need to specify the static library. + Here's the project file for building Plug & Paint: + + \snippet examples/tools/plugandpaint/plugandpaint.pro 0 + + The \c LIBS line variable specifies the library \c pnp_basictools + located in the \c ../plugandpaintplugins/basictools directory. + (Although the \c LIBS syntax has a distinct Unix flavor, \c qmake + supports it on all platforms.) + + The \c CONFIG() code at the end is necessary for this example + because the example is part of the Qt distribution and Qt can be + configured to be built simultaneously in debug and in release + modes. You don't need to for your own plugin applications. + + This completes our review of the Plug & Paint application. At + this point, you might want to take a look at the + \l{tools/plugandpaintplugins/basictools}{Basic Tools} example + plugin. +*/ + +/*! + \example tools/plugandpaintplugins/basictools + \title Plug & Paint Basic Tools Example + + The Basic Tools example is a static plugin for the + \l{tools/plugandpaint}{Plug & Paint} example. It provides a set + of basic brushes, shapes, and filters. Through the Basic Tools + example, we will review the four steps involved in writing a Qt + plugin: + + \list 1 + \o Declare a plugin class. + \o Implement the interfaces provided by the plugin. + \o Export the plugin using the Q_EXPORT_PLUGIN2() macro. + \o Build the plugin using an adequate \c .pro file. + \endlist + + \section1 Declaration of the Plugin Class + + \snippet examples/tools/plugandpaintplugins/basictools/basictoolsplugin.h 0 + + We start by including \c interfaces.h, which defines the plugin + interfaces for the \l{tools/plugandpaint}{Plug & Paint} + application. For the \c #include to work, we need to add an \c + INCLUDEPATH entry to the \c .pro file with the path to Qt's \c + examples/tools directory. + + The \c BasicToolsPlugin class is a QObject subclass that + implements the \c BrushInterface, the \c ShapeInterface, and the + \c FilterInterface. This is done through multiple inheritance. + The \c Q_INTERFACES() macro is necessary to tell \l{moc}, Qt's + meta-object compiler, that the base classes are plugin + interfaces. Without the \c Q_INTERFACES() macro, we couldn't use + \l qobject_cast() in the \l{tools/plugandpaint}{Plug & Paint} + application to detect interfaces. + + \snippet examples/tools/plugandpaintplugins/basictools/basictoolsplugin.h 2 + + In the \c public section of the class, we declare all the + functions from the three interfaces. + + \section1 Implementation of the Brush Interface + + Let's now review the implementation of the \c BasicToolsPlugin + member functions inherited from \c BrushInterface. + + \snippet examples/tools/plugandpaintplugins/basictools/basictoolsplugin.cpp 0 + + The \c brushes() function returns a list of brushes provided by + this plugin. We provide three brushes: \gui{Pencil}, \gui{Air + Brush}, and \gui{Random Letters}. + + \snippet examples/tools/plugandpaintplugins/basictools/basictoolsplugin.cpp 1 + + On a mouse press event, we just call \c mouseMove() to draw the + spot where the event occurred. + + \snippet examples/tools/plugandpaintplugins/basictools/basictoolsplugin.cpp 2 + + In \c mouseMove(), we start by saving the state of the QPainter + and we compute a few variables that we'll need later. + + \snippet examples/tools/plugandpaintplugins/basictools/basictoolsplugin.cpp 3 + + Then comes the brush-dependent part of the code: + + \list + \o If the brush is \gui{Pencil}, we just call + QPainter::drawLine() with the current QPen. + + \o If the brush is \gui{Air Brush}, we start by setting the + painter's QBrush to Qt::Dense6Pattern to obtain a dotted + pattern. Then we draw a circle filled with that QBrush several + times, resulting in a thick line. + + \o If the brush is \gui{Random Letters}, we draw a random letter + at the new cursor position. Most of the code is for setting + the font to be bold and larger than the default font and for + computing an appropriate bounding rect. + \endlist + + At the end, we restore the painter state to what it was upon + entering the function and we return the bounding rectangle. + + \snippet examples/tools/plugandpaintplugins/basictools/basictoolsplugin.cpp 4 + + When the user releases the mouse, we do nothing and return an + empty QRect. + + \section1 Implementation of the Shape Interface + + \snippet examples/tools/plugandpaintplugins/basictools/basictoolsplugin.cpp 5 + + The plugin provides three shapes: \gui{Circle}, \gui{Star}, and + \gui{Text...}. The three dots after \gui{Text} are there because + the shape pops up a dialog asking for more information. We know + that the shape names will end up in a menu, so we include the + three dots in the shape name. + + A cleaner but more complicated design would have been to + distinguish between the internal shape name and the name used in + the user interface. + + \snippet examples/tools/plugandpaintplugins/basictools/basictoolsplugin.cpp 6 + + The \c generateShape() creates a QPainterPath for the specified + shape. If the shape is \gui{Text}, we pop up a QInputDialog to + let the user enter some text. + + \section1 Implementation of the Filter Interface + + \snippet examples/tools/plugandpaintplugins/basictools/basictoolsplugin.cpp 7 + + The plugin provides three filters: \gui{Invert Pixels}, \gui{Swap + RGB}, and \gui{Grayscale}. + + \snippet examples/tools/plugandpaintplugins/basictools/basictoolsplugin.cpp 8 + + The \c filterImage() function takes a filter name and a QImage as + parameters and returns an altered QImage. The first thing we do + is to convert the image to a 32-bit RGB format, to ensure that + the algorithms will work as expected. For example, + QImage::invertPixels(), which is used to implement the + \gui{Invert Pixels} filter, gives counterintuitive results for + 8-bit images, because they invert the indices into the color + table instead of inverting the color table's entries. + + \section1 Exporting the Plugin + + Whereas applications have a \c main() function as their entry + point, plugins need to contain exactly one occurrence of the + Q_EXPORT_PLUGIN2() macro to specify which class provides the + plugin: + + \snippet examples/tools/plugandpaintplugins/basictools/basictoolsplugin.cpp 9 + + This line may appear in any \c .cpp file that is part of the + plugin's source code. + + \section1 The .pro File + + Here's the project file for building the Basic Tools plugin: + + \snippet examples/tools/plugandpaintplugins/basictools/basictools.pro 0 + + The \c .pro file differs from typical \c .pro files in many + respects. First, it starts with a \c TEMPLATE entry specifying \c + lib. (The default template is \c app.) It also adds \c plugin to + the \c CONFIG variable. This is necessary on some platforms to + avoid generating symbolic links with version numbers in the file + name, which is appropriate for most dynamic libraries but not for + plugins. + + To make the plugin a static plugin, all that is required is to + specify \c static in addition to \c plugin. The + \l{tools/plugandpaintplugins/extrafilters}{Extra Filters} plugin, + which is compiled as a dynamic plugin, doesn't specify \c static + in its \c .pro file. + + The \c INCLUDEPATH variable sets the search paths for global + headers (i.e., header files included using \c{#include <...>}). + We add Qt's \c examples/tools directory (strictly speaking, + \c{examples/tools/plugandpaintplugins/basictools/../..}) to the + list, so that we can include \c <plugandpaint/interfaces.h>. + + The \c TARGET variable specifies which name we want to give the + target library. We use \c pnp_ as the prefix to show that the + plugin is designed to work with Plug & Paint. On Unix, \c lib is + also prepended to that name. On all platforms, a + platform-specific suffix is appended (e.g., \c .dll on Windows, + \c .a on Linux). + + The \c CONFIG() code at the end is necessary for this example + because the example is part of the Qt distribution and Qt can be + configured to be built simultaneously in debug and in release + modes. You don't need to for your own plugins. +*/ + +/*! + \example tools/plugandpaintplugins/extrafilters + \title Plug & Paint Extra Filters Example + + The Extra Filters example is a plugin for the + \l{tools/plugandpaint}{Plug & Paint} example. It provides a set + of filters in addition to those provided by the + \l{tools/plugandpaintplugins/basictools}{Basic Tools} plugin. + + Since the approach is identical to + \l{tools/plugandpaintplugins/basictools}{Basic Tools}, we won't + review the code here. The only part of interest is the + \c .pro file, since Extra Filters is a dynamic plugin + (\l{tools/plugandpaintplugins/basictools}{Basic Tools} is + linked statically into the Plug & Paint executable). + + Here's the project file for building the Extra Filters plugin: + + \snippet examples/tools/plugandpaintplugins/extrafilters/extrafilters.pro 0 + + The \c .pro file differs from typical \c .pro files in many + respects. First, it starts with a \c TEMPLATE entry specifying \c + lib. (The default template is \c app.) It also adds \c plugin to + the \c CONFIG variable. This is necessary on some platforms to + avoid generating symbolic links with version numbers in the file + name, which is appropriate for most dynamic libraries but not for + plugins. + + The \c INCLUDEPATH variable sets the search paths for global + headers (i.e., header files included using \c{#include <...>}). + We add Qt's \c examples/tools directory (strictly speaking, + \c{examples/tools/plugandpaintplugins/basictools/../..}) to the + list, so that we can include \c <plugandpaint/interfaces.h>. + + The \c TARGET variable specifies which name we want to give the + target library. We use \c pnp_ as the prefix to show that the + plugin is designed to work with Plug & Paint. On Unix, \c lib is + also prepended to that name. On all platforms, a + platform-specific suffix is appended (e.g., \c .dll on Windows, + \c .so on Linux). + + The \c DESTDIR variable specifies where we want to install the + plugin. We put it in Plug & Paint's \c plugins subdirectory, + since that's where the application looks for dynamic plugins. + + The \c CONFIG() code at the end is necessary for this example + because the example is part of the Qt distribution and Qt can be + configured to be built simultaneously in debug and in release + modes. You don't need to for your own plugins. +*/ diff --git a/doc/src/examples/querymodel.qdoc b/doc/src/examples/querymodel.qdoc new file mode 100644 index 0000000000..384eb3b6c0 --- /dev/null +++ b/doc/src/examples/querymodel.qdoc @@ -0,0 +1,37 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example sql/querymodel + \title Query Model Example + + The Query Model example shows how to make customized versions of + data obtained from a SQL query, using a model that encapsulates + the query and table views to display the results. + + \image querymodel-example.png +*/ diff --git a/doc/src/examples/queuedcustomtype.qdoc b/doc/src/examples/queuedcustomtype.qdoc new file mode 100644 index 0000000000..3df7e4d6aa --- /dev/null +++ b/doc/src/examples/queuedcustomtype.qdoc @@ -0,0 +1,163 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example threads/queuedcustomtype + \title Queued Custom Type Example + + The Queued Custom Type example shows how to send custom types between + threads with queued signals and slots. + + \image queuedcustomtype-example.png + + Contents: + + \tableofcontents + + \section1 Overview + + In the \l{Custom Type Sending Example}, we showed how to use a custom type + with signal-slot communication within the same thread. + + In this example, we create a new value class, \c Block, and register it + with the meta-object system to enable us to send instances of it between + threads using queued signals and slots. + + \section1 The Block Class + + The \c Block class is similar to the \c Message class described in the + \l{Custom Type Example}. It provides the default constructor, copy + constructor and destructor in the public section of the class that the + meta-object system requires. It describes a colored rectangle. + + \snippet examples/threads/queuedcustomtype/block.h custom type definition and meta-type declaration + + We will still need to register it with the meta-object system at + run-time by calling the qRegisterMetaType() template function before + we make any signal-slot connections that use this type. + Even though we do not intend to use the type with QVariant in this example, + it is good practice to also declare the new type with Q_DECLARE_METATYPE(). + + The implementation of the \c Block class is trivial, so we avoid quoting + it here. + + \section1 The Window Class + + We define a simple \c Window class with a public slot that accepts a + \c Block object. The rest of the class is concerned with managing the + user interface and handling images. + + \snippet examples/threads/queuedcustomtype/window.h Window class definition + + The \c Window class also contains a worker thread, provided by a + \c RenderThread object. This will emit signals to send \c Block objects + to the window's \c addBlock(Block) slot. + + The parts of the \c Window class that are most relevant are the constructor + and the \c addBlock(Block) slot. + + The constructor creates a thread for rendering images, sets up a user + interface containing a label and two push buttons that are connected to + slots in the same class. + + \snippet examples/threads/queuedcustomtype/window.cpp Window constructor start + \snippet examples/threads/queuedcustomtype/window.cpp set up widgets and connections + \snippet examples/threads/queuedcustomtype/window.cpp connecting signal with custom type + + In the last of these connections, we connect a signal in the + \c RenderThread object to the \c addBlock(Block) slot in the window. + + \dots + \snippet examples/threads/queuedcustomtype/window.cpp Window constructor finish + + The rest of the constructor simply sets up the layout of the window. + + The \c addBlock(Block) slot receives blocks from the rendering thread via + the signal-slot connection set up in the constructor: + + \snippet examples/threads/queuedcustomtype/window.cpp Adding blocks to the display + + We simply paint these onto the label as they arrive. + + \section1 The RenderThread Class + + The \c RenderThread class processes an image, creating \c Block objects + and using the \c sendBlock(Block) signal to send them to other components + in the example. + + \snippet examples/threads/queuedcustomtype/renderthread.h RenderThread class definition + + The constructor and destructor are not quoted here. These take care of + setting up the thread's internal state and cleaning up when it is destroyed. + + Processing is started with the \c processImage() function, which calls the + \c RenderThread class's reimplementation of the QThread::run() function: + + \snippet examples/threads/queuedcustomtype/renderthread.cpp processing the image (start) + + Ignoring the details of the way the image is processed, we see that the + signal containing a block is emitted in the usual way: + + \dots + \snippet examples/threads/queuedcustomtype/renderthread.cpp processing the image (finish) + + Each signal that is emitted will be queued and delivered later to the + window's \c addBlock(Block) slot. + + \section1 Registering the Type + + In the example's \c{main()} function, we perform the registration of the + \c Block class as a custom type with the meta-object system by calling the + qRegisterMetaType() template function: + + \snippet examples/threads/queuedcustomtype/main.cpp main function + + This call is placed here to ensure that the type is registered before any + signal-slot connections are made that use it. + + The rest of the \c{main()} function is concerned with setting a seed for + the pseudo-random number generator, creating and showing the window, and + setting a default image. See the source code for the implementation of the + \c createImage() function. + + \section1 Further Reading + + This example showed how a custom type can be registered with the + meta-object system so that it can be used with signal-slot connections + between threads. For ordinary communication involving direct signals and + slots, it is enough to simply declare the type in the way described in the + \l{Custom Type Sending Example}. + + In practice, both the Q_DECLARE_METATYPE() macro and the qRegisterMetaType() + template function can be used to register custom types, but + qRegisterMetaType() is only required if you need to perform signal-slot + communication or need to create and destroy objects of the custom type + at run-time. + + More information on using custom types with Qt can be found in the + \l{Creating Custom Qt Types} document. +*/ diff --git a/doc/src/examples/recentfiles.qdoc b/doc/src/examples/recentfiles.qdoc new file mode 100644 index 0000000000..2df0f46987 --- /dev/null +++ b/doc/src/examples/recentfiles.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example mainwindows/recentfiles + \title Recent Files Example + + The Recent Files example shows how a standard File menu can be extended to show + the most recent files loaded by a main window application. + + \image recentfiles-example.png +*/ diff --git a/doc/src/examples/regexp.qdoc b/doc/src/examples/regexp.qdoc new file mode 100644 index 0000000000..30610c087a --- /dev/null +++ b/doc/src/examples/regexp.qdoc @@ -0,0 +1,37 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example tools/regexp + \title Regular Expressions Example + + The Regular Expressions (RegExp) example shows how regular expressions in Qt are + applied to text by providing an environment in which new regular expressions can be + created and tested on custom text strings. + + \image regexp-example.png +*/ diff --git a/doc/src/examples/relationaltablemodel.qdoc b/doc/src/examples/relationaltablemodel.qdoc new file mode 100644 index 0000000000..37c319a908 --- /dev/null +++ b/doc/src/examples/relationaltablemodel.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example sql/relationaltablemodel + \title Relational Table Model Example + + The Relational Table Model example shows how to use table views with a relational + model to visualize the relations between items in a database. + + \image relationaltablemodel-example.png +*/ diff --git a/doc/src/examples/rogue.qdoc b/doc/src/examples/rogue.qdoc new file mode 100644 index 0000000000..4df0910f60 --- /dev/null +++ b/doc/src/examples/rogue.qdoc @@ -0,0 +1,208 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example statemachine/rogue + \title Rogue Example + + The Rogue example shows how to use the Qt state machine for event + handling. + + \image rogue-example.png + + This example implements a simple text based game. Do you see the + \c{@} in the screenshot? That's you, the rogue. The \c{#} + characters are walls, and the dots represent floor. In a real + game, other ASCII characters would represent all kinds of objects + and creatures, for instance, ancient dragons (\c{D}s) or food + rations (\c{%}s). But let's not get carried away. In this game, + the rogue is simply running around in an empty room. + + The rogue is moved with the keypad (2, 4, 8, 6). That aside, we + have implemented a \c quit command that triggers if the player + types \c {q}. The player is then asked if he/she really wants to + quit. + + Most games have commands that need more than one key press (we + think of consecutive presses, i.e., not of several keys being + pressed at the same time). In this game, only the \c quit command + falls under this category, but for the sake of argument, let's + imagine a fully-fledged game with a rich set of commands. If we + were to implement these by catching key events in + \l{QWidget::}{keyPressEvent()}, we would have to keep a lot of + class member variables to track the sequence of keys already typed + (or find some other way of deducing the current state of a + command). This can easily lead to spaghetti, which is--as we all + well know, I'm sure--unpleasant. With a state machine, on the + other hand, separate states can wait for a single key press, and + that makes our lives a lot simpler. + + The example consists of two classes: + + \list + \o \c Window draws the text display of the game and sets + up the state machine. The window also has a status bar + above the area in which the rouge moves. + \o \c MovementTransition is a transition that carries out + a single move of the rogue. + \endlist + + Before we embark on a code walkthrough, it is necessary to take a + closer look at the design of the machine. Here is a state chart + that shows what we want to achieve: + + \image rogue-statechart.png + + The input state waits for a key press to start a new command. + When receiving a key it recognizes, it transitions to one of the + two commands of the game; though, as we will see, movement is + handled by the transition itself. The quit state waits for the + player to answer yes or no (by typing \c y or \c n) when asked + whether he/she really wants to quit the game. + + The chart demonstrates how we use one state to wait for a single + key press. The press received may trigger one of the transitions + connected to the state. + + \section1 Window Class Definition + + The \c Window class is a widget that draws the text display of the + game. It also sets up the state machine, i.e., creates and + connects the states in the machine. It is the key events from this + widget that are used by the machine. + + \snippet examples/statemachine/rogue/window.h 0 + + \c Direction specifies the direction in which the rogue is to + move. We use this in \c movePlayer(), which moves the rogue and + repaints the window. The game has a status line above the area in + which the rogue moves. The \c status property contains the text of + this line. We use a property because the QState class allows + setting any Qt \l{Qt's Property System}{property} when entered. + More on this later. + + \snippet examples/statemachine/rogue/window.h 1 + + The \c map is an array with the characters that are currently + displayed. We set up the array in \c setupMap(), and update it + when the rogue is moved. \c pX and \c pY is the current position + of the rogue. \c WIDTH and \c HEIGHT are macros specifying the + dimensions of the map. + + The \c paintEvent() function is left out of this walkthrough. We + also do not discuss other code that does not concern the state + machine (the \c setupMap(), \c status(), \c setStatus(), \c + movePlayer(), and \c sizeHint() functions). If you wish to take a + look at the code, click on the link for the \c window.cpp file at + the top of this page. + + \section1 Window Class Implementation + + Here is the constructor of \c Window: + + \snippet examples/statemachine/rogue/window.cpp 0 + \dots + \snippet examples/statemachine/rogue/window.cpp 1 + + The player starts off at position (5, 5). We then set up the map + and statemachine. Let's proceed with the \c buildMachine() + function: + + \snippet examples/statemachine/rogue/window.cpp 2 + + We enter \c inputState when the machine is started and from the \c + quitState if the user wants to continue playing. We then set the + status to a helpful reminder of how to play the game. + + First, the \c Movement transition is added to the input state. + This will enable the rogue to be moved with the keypad. Notice + that we don't set a target state for the movement transition. This + will cause the transition to be triggered (and the + \l{QAbstractTransition::}{onTransition()} function to be invoked), + but the machine will not leave the \c inputState. If we had set \c + inputState as the target state, we would first have left and then + entered the \c inputState again. + + \snippet examples/statemachine/rogue/window.cpp 3 + + When we enter \c quitState, we update the status bar of the + window. + + \c QKeyEventTransition is a utility class that removes the hassle + of implementing transitions for \l{QKeyEvent}s. We simply need to + specify the key on which the transition should trigger and the + target state of the transition. + + \snippet examples/statemachine/rogue/window.cpp 4 + + The transition from \c inputState allows triggering the quit state + when the player types \c {q}. + + \snippet examples/statemachine/rogue/window.cpp 5 + + The machine is set up, so it's time to start it. + + \section1 The MovementTransition Class + + \c MovementTransition is triggered when the player request the + rogue to be moved (by typing 2, 4, 6, or 8) when the machine is in + the \c inputState. + + \snippet examples/statemachine/rogue/movementtransition.h 0 + + In the constructor, we tell QEventTransition to only send + \l{QEvent::}{KeyPress} events to the + \l{QAbstractTransition::}{eventTest()} function: + + \snippet examples/statemachine/rogue/movementtransition.h 1 + + The KeyPress events come wrapped in \l{QStateMachine::WrappedEvent}s. \c event + must be confirmed to be a wrapped event because Qt uses other + events internally. After that, it is simply a matter of checking + which key has been pressed. + + Let's move on to the \c onTransition() function: + + \snippet examples/statemachine/rogue/movementtransition.h 2 + + When \c onTransition() is invoked, we know that we have a + \l{QEvent::}{KeyPress} event with 2, 4, 6, or 8, and can ask \c + Window to move the player. + + \section1 The Roguelike Tradition + + You might have been wondering why the game features a rogue. Well, + these kinds of text based dungeon exploration games date back to a + game called, yes, "Rogue". Although outflanked by the technology + of modern 3D computer games, roguelikes have a solid community of + hard-core, devoted followers. + + Playing these games can be surprisingly addictive (despite the + lack of graphics). Angband, the perhaps most well-known rougelike, + is found here: \l{http://rephial.org/}. +*/ + diff --git a/doc/src/examples/rsslisting.qdoc b/doc/src/examples/rsslisting.qdoc new file mode 100644 index 0000000000..ca29c04bed --- /dev/null +++ b/doc/src/examples/rsslisting.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example xml/rsslisting + \title RSS-Listing Example + + This example shows how to create a widget that displays news items + from RDF news sources. + + \image rsslistingexample.png +*/ diff --git a/doc/src/examples/samplebuffers.qdoc b/doc/src/examples/samplebuffers.qdoc new file mode 100644 index 0000000000..59891ae893 --- /dev/null +++ b/doc/src/examples/samplebuffers.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example opengl/samplebuffers + \title Sample Buffers Example + + The Sample Buffers example demonstrates how to use and enable + sample buffers in a QGLWidget. + + \image samplebuffers-example.png +*/ diff --git a/doc/src/examples/saxbookmarks.qdoc b/doc/src/examples/saxbookmarks.qdoc new file mode 100644 index 0000000000..de4f386771 --- /dev/null +++ b/doc/src/examples/saxbookmarks.qdoc @@ -0,0 +1,40 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example xml/saxbookmarks + \title SAX Bookmarks Example + + The SAX Bookmarks example provides a reader for XML Bookmark Exchange Language (XBEL) + files that uses Qt's SAX-based API to read and parse the files. The DOM Bookmarks + example provides an alternative way to read this type of file. + + \image saxbookmarks-example.png + + See the \l{XML Bookmark Exchange Language Resource Page} for more + information about XBEL files. +*/ diff --git a/doc/src/examples/screenshot.qdoc b/doc/src/examples/screenshot.qdoc new file mode 100644 index 0000000000..3875f04b18 --- /dev/null +++ b/doc/src/examples/screenshot.qdoc @@ -0,0 +1,248 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example desktop/screenshot + \title Screenshot Example + + The Screenshot example shows how to take a screenshot of the + desktop using QApplication and QDesktopWidget. It also shows how + to use QTimer to provide a single-shot timer, and how to + reimplement the QWidget::resizeEvent() event handler to make sure + that an application resizes smoothly and without data loss. + + \image screenshot-example.png + + With the application the users can take a screenshot of their + desktop. They are provided with a couple of options: + + \list + \o Delaying the screenshot, giving them time to rearrange + their desktop. + \o Hiding the application's window while the screenshot is taken. + \endlist + + In addition the application allows the users to save their + screenshot if they want to. + + \section1 Screenshot Class Definition + + \snippet examples/desktop/screenshot/screenshot.h 0 + + The \c Screenshot class inherits QWidget and is the application's + main widget. It displays the application options and a preview of + the screenshot. + + We reimplement the QWidget::resizeEvent() function to make sure + that the preview of the screenshot scales properly when the user + resizes the application widget. We also need several private slots + to facilitate the options: + + \list + \o The \c newScreenshot() slot prepares a new screenshot. + \o The \c saveScreenshot() slot saves the last screenshot. + \o The \c shootScreen() slot takes the screenshot. + \o The \c updateCheckBox() slot enables or disables the + \gui {Hide This Window} option. + \endlist + + We also declare some private functions: We use the \c + createOptionsGroupBox(), \c createButtonsLayout() and \c + createButton() functions when we construct the widget. And we call + the private \c updateScreenshotLabel() function whenever a new + screenshot is taken or when a resize event changes the size of the + screenshot preview label. + + In addition we need to store the screenshot's original pixmap. The + reason is that when we display the preview of the screenshot, we + need to scale its pixmap, storing the original we make sure that + no data are lost in that process. + + \section1 Screenshot Class Implementation + + \snippet examples/desktop/screenshot/screenshot.cpp 0 + + In the constructor we first create the QLabel displaying the + screenshot preview. + + We set the QLabel's size policy to be QSizePolicy::Expanding both + horizontally and vertically. This means that the QLabel's size + hint is a sensible size, but the widget can be shrunk and still be + useful. Also, the widget can make use of extra space, so it should + get as much space as possible. Then we make sure the QLabel is + aligned in the center of the \c Screenshot widget, and set its + minimum size. + + We create the applications's buttons and the group box containing + the application's options, and put it all into a main + layout. Finally we take the initial screenshot, and set the inital + delay and the window title, before we resize the widget to a + suitable size. + + \snippet examples/desktop/screenshot/screenshot.cpp 1 + + The \c resizeEvent() function is reimplemented to receive the + resize events dispatched to the widget. The purpose is to scale + the preview screenshot pixmap without deformation of its content, + and also make sure that the application can be resized smoothly. + + To achieve the first goal, we scale the screenshot pixmap using + Qt::KeepAspectRatio. We scale the pixmap to a rectangle as large + as possible inside the current size of the screenshot preview + label, preserving the aspect ratio. This means that if the user + resizes the application window in only one direction, the preview + screenshot keeps the same size. + + To reach our second goal, we make sure that the preview screenshot + only is repainted (using the private \c updateScreenshotLabel() + function) when it actually changes its size. + + \snippet examples/desktop/screenshot/screenshot.cpp 2 + + The private \c newScreenshot() slot is called when the user + requests a new screenshot; but the slot only prepares a new + screenshot. + + First we see if the \gui {Hide This Window} option is checked, if + it is we hide the \c Screenshot widget. Then we disable the \gui + {New Screenshot} button, to make sure the user only can request + one screenshot at a time. + + We create a timer using the QTimer class which provides repetitive + and single-shot timers. We set the timer to time out only once, + using the static QTimer::singleShot() function. This function + calls the private \c shootScreen() slot after the time interval + specified by the \gui {Screenshot Delay} option. It is \c + shootScreen() that actually performs the screenshot. + + \snippet examples/desktop/screenshot/screenshot.cpp 3 + + The \c saveScreenshot() slot is called when the user push the \gui + Save button, and it presents a file dialog using the QFileDialog + class. + + QFileDialog enables a user to traverse the file system in order to + select one or many files or a directory. The easiest way to create + a QFileDialog is to use the convenience static + functions. + + We define the default file format to be png, and we make the file + dialog's initial path the path the application is run from. We + create the file dialog using the static + QFileDialog::getSaveFileName() function which returns a file name + selected by the user. The file does not have to exist. If the file + name is valid, we use the QPixmap::save() function to save the + screenshot's original pixmap in that file. + + \snippet examples/desktop/screenshot/screenshot.cpp 4 + + The \c shootScreen() slot is called to take the screenshot. If the + user has chosen to delay the screenshot, we make the application + beep when the screenshot is taken using the static + QApplication::beep() function. + + The QApplication class manages the GUI application's control flow + and main settings. It contains the main event loop, where all + events from the window system and other sources are processed and + dispatched. + + \snippet examples/desktop/screenshot/screenshot.cpp 5 + + We take the screenshot using the static QPixmap::grabWindow() + function. The function grabs the contents of the window passed as + an argument, makes a pixmap out of it and returns that pixmap. + + We identify the argument window using the QWidget::winID() + function which returns the window system identifier. Here it + returns the identifier of the current QDesktopWidget retrieved by + the QApplication::desktop() function. The QDesktopWidget class + provides access to screen information, and inherits + QWidget::winID(). + + We update the screenshot preview label using the private \c + updateScreenshotLabel() function. Then we enable the \gui {New + Screenshot} button, and finally we make the \c Screenshot widget + visible if it was hidden during the screenshot. + + \snippet examples/desktop/screenshot/screenshot.cpp 6 + + The \gui {Hide This Window} option is enabled or disabled + depending on the delay of the screenshot. If there is no delay, + the application window cannot be hidden and the option's checkbox + is disabled. + + The \c updateCheckBox() slot is called whenever the user changes + the delay using the \gui {Screenshot Delay} option. + + \snippet examples/desktop/screenshot/screenshot.cpp 7 + + The private \c createOptionsGroupBox() function is called from the + constructor. + + First we create a group box that will contain all of the options' + widgets. Then we create a QSpinBox and a QLabel for the \gui + {Screenshot Delay} option, and connect the spinbox to the \c + updateCheckBox() slot. Finally, we create a QCheckBox for the \gui + {Hide This Window} option, add all the options' widgets to a + QGridLayout and install the layout on the group box. + + Note that we don't have to specify any parents for the widgets + when we create them. The reason is that when we add a widget to a + layout and install the layout on another widget, the layout's + widgets are automatically reparented to the widget the layout is + installed on. + + \snippet examples/desktop/screenshot/screenshot.cpp 8 + + The private \c createButtonsLayout() function is called from the + constructor. We create the application's buttons using the private + \c createButton() function, and add them to a QHBoxLayout. + + \snippet examples/desktop/screenshot/screenshot.cpp 9 + + The private \c createButton() function is called from the \c + createButtonsLayout() function. It simply creates a QPushButton + with the provided text, connects it to the provided receiver and + slot, and returns a pointer to the button. + + \snippet examples/desktop/screenshot/screenshot.cpp 10 + + The private \c updateScreenshotLabel() function is called whenever + the screenshot changes, or when a resize event changes the size of + the screenshot preview label. It updates the screenshot preview's + label using the QLabel::setPixmap() and QPixmap::scaled() + functions. + + QPixmap::scaled() returns a copy of the given pixmap scaled to a + rectangle of the given size according to the given + Qt::AspectRatioMode and Qt::TransformationMode. + + We scale the original pixmap to fit the current screenshot label's + size, preserving the aspect ratio and giving the resulting pixmap + smoothed edges. +*/ + diff --git a/doc/src/examples/scribble.qdoc b/doc/src/examples/scribble.qdoc new file mode 100644 index 0000000000..de60eab670 --- /dev/null +++ b/doc/src/examples/scribble.qdoc @@ -0,0 +1,417 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example widgets/scribble + \title Scribble Example + + The Scribble example shows how to reimplement some of QWidget's + event handlers to receive the events generated for the + application's widgets. + + We reimplement the mouse event handlers to implement drawing, the + paint event handler to update the application and the resize event + handler to optimize the application's appearance. In addition we + reimplement the close event handler to intercept the close events + before terminating the application. + + The example also demonstrates how to use QPainter to draw an image + in real time, as well as to repaint widgets. + + \image scribble-example.png Screenshot of the Scribble example + + With the Scribble application the users can draw an image. The + \gui File menu gives the users the possibility to open and edit an + existing image file, save an image and exit the application. While + drawing, the \gui Options menu allows the users to to choose the + pen color and pen width, as well as clear the screen. In addition + the \gui Help menu provides the users with information about the + Scribble example in particular, and about Qt in general. + + The example consists of two classes: + + \list + \o \c ScribbleArea is a custom widget that displays a QImage and + allows to the user to draw on it. + \o \c MainWindow provides a menu above the \c ScribbleArea. + \endlist + + We will start by reviewing the \c ScribbleArea class. Then we will + review the \c MainWindow class, which uses \c ScribbleArea. + + \section1 ScribbleArea Class Definition + + \snippet examples/widgets/scribble/scribblearea.h 0 + + The \c ScribbleArea class inherits from QWidget. We reimplement + the \c mousePressEvent(), \c mouseMoveEvent() and \c + mouseReleaseEvent() functions to implement the drawing. We + reimplement the \c paintEvent() function to update the scribble + area, and the \c resizeEvent() function to ensure that the QImage + on which we draw is at least as large as the widget at any time. + + We need several public functions: \c openImage() loads an image + from a file into the scribble area, allowing the user to edit the + image; \c save() writes the currently displayed image to file; \c + clearImage() slot clears the image displayed in the scribble + area. We need the private \c drawLineTo() function to actually do + the drawing, and \c resizeImage() to change the size of a + QImage. The \c print() slot handles printing. + + We also need the following private variables: + + \list + \o \c modified is \c true if there are unsaved + changes to the image displayed in the scribble area. + \o \c scribbling is \c true while the user is pressing + the left mouse button within the scribble area. + \o \c penWidth and \c penColor hold the currently + set width and color for the pen used in the application. + \o \c image stores the image drawn by the user. + \o \c lastPoint holds the position of the cursor at the last + mouse press or mouse move event. + \endlist + + \section1 ScribbleArea Class Implementation + + \snippet examples/widgets/scribble/scribblearea.cpp 0 + + In the constructor, we set the Qt::WA_StaticContents + attribute for the widget, indicating that the widget contents are + rooted to the top-left corner and don't change when the widget is + resized. Qt uses this attribute to optimize paint events on + resizes. This is purely an optimization and should only be used + for widgets whose contents are static and rooted to the top-left + corner. + + \snippet examples/widgets/scribble/scribblearea.cpp 1 + \snippet examples/widgets/scribble/scribblearea.cpp 2 + + In the \c openImage() function, we load the given image. Then we + resize the loaded QImage to be at least as large as the widget in + both directions using the private \c resizeImage() function and + we set the \c image member variable to be the loaded image. At + the end, we call QWidget::update() to schedule a repaint. + + \snippet examples/widgets/scribble/scribblearea.cpp 3 + \snippet examples/widgets/scribble/scribblearea.cpp 4 + + The \c saveImage() function creates a QImage object that covers + only the visible section of the actual \c image and saves it using + QImage::save(). If the image is successfully saved, we set the + scribble area's \c modified variable to \c false, because there is + no unsaved data. + + \snippet examples/widgets/scribble/scribblearea.cpp 5 + \snippet examples/widgets/scribble/scribblearea.cpp 6 + \codeline + \snippet examples/widgets/scribble/scribblearea.cpp 7 + \snippet examples/widgets/scribble/scribblearea.cpp 8 + + The \c setPenColor() and \c setPenWidth() functions set the + current pen color and width. These values will be used for future + drawing operations. + + \snippet examples/widgets/scribble/scribblearea.cpp 9 + \snippet examples/widgets/scribble/scribblearea.cpp 10 + + The public \c clearImage() slot clears the image displayed in the + scribble area. We simply fill the entire image with white, which + corresponds to RGB value (255, 255, 255). As usual when we modify + the image, we set \c modified to \c true and schedule a repaint. + + \snippet examples/widgets/scribble/scribblearea.cpp 11 + \snippet examples/widgets/scribble/scribblearea.cpp 12 + + For mouse press and mouse release events, we use the + QMouseEvent::button() function to find out which button caused + the event. For mose move events, we use QMouseEvent::buttons() + to find which buttons are currently held down (as an OR-combination). + + If the users press the left mouse button, we store the position + of the mouse cursor in \c lastPoint. We also make a note that the + user is currently scribbling. (The \c scribbling variable is + necessary because we can't assume that a mouse move and mouse + release event is always preceded by a mouse press event on the + same widget.) + + If the user moves the mouse with the left button pressed down or + releases the button, we call the private \c drawLineTo() function + to draw. + + \snippet examples/widgets/scribble/scribblearea.cpp 13 + \snippet examples/widgets/scribble/scribblearea.cpp 14 + + In the reimplementation of the \l + {QWidget::paintEvent()}{paintEvent()} function, we simply create + a QPainter for the scribble area, and draw the image. + + At this point, you might wonder why we don't just draw directly + onto the widget instead of drawing in a QImage and copying the + QImage onto screen in \c paintEvent(). There are at least three + good reasons for this: + + \list + \o The window system requires us to be able to redraw the widget + \e{at any time}. For example, if the window is minimized and + restored, the window system might have forgotten the contents + of the widget and send us a paint event. In other words, we + can't rely on the window system to remember our image. + + \o Qt normally doesn't allow us to paint outside of \c + paintEvent(). In particular, we can't paint from the mouse + event handlers. (This behavior can be changed using the + Qt::WA_PaintOnScreen widget attribute, though.) + + \o If initialized properly, a QImage is guaranteed to use 8-bit + for each color channel (red, green, blue, and alpha), whereas + a QWidget might have a lower color depth, depending on the + monitor configuration. This means that if we load a 24-bit or + 32-bit image and paint it onto a QWidget, then copy the + QWidget into a QImage again, we might lose some information. + \endlist + + \snippet examples/widgets/scribble/scribblearea.cpp 15 + \snippet examples/widgets/scribble/scribblearea.cpp 16 + + When the user starts the Scribble application, a resize event is + generated and an image is created and displayed in the scribble + area. We make this initial image slightly larger than the + application's main window and scribble area, to avoid always + resizing the image when the user resizes the main window (which + would be very inefficient). But when the main window becomes + larger than this initial size, the image needs to be resized. + + \snippet examples/widgets/scribble/scribblearea.cpp 17 + \snippet examples/widgets/scribble/scribblearea.cpp 18 + + In \c drawLineTo(), we draw a line from the point where the mouse + was located when the last mouse press or mouse move occurred, we + set \c modified to true, we generate a repaint event, and we + update \c lastPoint so that next time \c drawLineTo() is called, + we continue drawing from where we left. + + We could call the \c update() function with no parameter, but as + an easy optimization we pass a QRect that specifies the rectangle + inside the scribble are needs updating, to avoid a complete + repaint of the widget. + + \snippet examples/widgets/scribble/scribblearea.cpp 19 + \snippet examples/widgets/scribble/scribblearea.cpp 20 + + QImage has no nice API for resizing an image. There's a + QImage::copy() function that could do the trick, but when used to + expand an image, it fills the new areas with black, whereas we + want white. + + So the trick is to create a brand new QImage with the right size, + to fill it with white, and to draw the old image onto it using + QPainter. The new image is given the QImage::Format_RGB32 + format, which means that each pixel is stored as 0xffRRGGBB + (where RR, GG, and BB are the red, green and blue + color channels, ff is the hexadecimal value 255). + + Printing is handled by the \c print() slot: + + \snippet examples/widgets/scribble/scribblearea.cpp 21 + + We construct a high resolution QPrinter object for the required + output format, using a QPrintDialog to ask the user to specify a + page size and indicate how the output should be formatted on the page. + + If the dialog is accepted, we perform the task of printing to the paint + device: + + \snippet examples/widgets/scribble/scribblearea.cpp 22 + + Printing an image to a file in this way is simply a matter of + painting onto the QPrinter. We scale the image to fit within the + available space on the page before painting it onto the paint + device. + + \section1 MainWindow Class Definition + + \snippet examples/widgets/scribble/mainwindow.h 0 + + The \c MainWindow class inherits from QMainWindow. We reimplement + the \l{QWidget::closeEvent()}{closeEvent()} handler from QWidget. + The \c open(), \c save(), \c penColor() and \c penWidth() + slots correspond to menu entries. In addition we create four + private functions. + + We use the boolean \c maybeSave() function to check if there are + any unsaved changes. If there are unsaved changes, we give the + user the opportunity to save these changes. The function returns + \c false if the user clicks \gui Cancel. We use the \c saveFile() + function to let the user save the image currently displayed in + the scribble area. + + \section1 MainWindow Class Implementation + + \snippet examples/widgets/scribble/mainwindow.cpp 0 + + In the constructor, we create a scribble area which we make the + central widget of the \c MainWindow widget. Then we create the + associated actions and menus. + + \snippet examples/widgets/scribble/mainwindow.cpp 1 + \snippet examples/widgets/scribble/mainwindow.cpp 2 + + Close events are sent to widgets that the users want to close, + usually by clicking \gui{File|Exit} or by clicking the \gui X + title bar button. By reimplementing the event handler, we can + intercept attempts to close the application. + + In this example, we use the close event to ask the user to save + any unsaved changes. The logic for that is located in the \c + maybeSave() function. If \c maybeSave() returns true, there are + no modifications or the users successfully saved them, and we + accept the event. The application can then terminate normally. If + \c maybeSave() returns false, the user clicked \gui Cancel, so we + "ignore" the event, leaving the application unaffected by it. + + \snippet examples/widgets/scribble/mainwindow.cpp 3 + \snippet examples/widgets/scribble/mainwindow.cpp 4 + + In the \c open() slot we first give the user the opportunity to + save any modifications to the currently displayed image, before a + new image is loaded into the scribble area. Then we ask the user + to choose a file and we load the file in the \c ScribbleArea. + + \snippet examples/widgets/scribble/mainwindow.cpp 5 + \snippet examples/widgets/scribble/mainwindow.cpp 6 + + The \c save() slot is called when the users choose the \gui {Save + As} menu entry, and then choose an entry from the format menu. The + first thing we need to do is to find out which action sent the + signal using QObject::sender(). This function returns the sender + as a QObject pointer. Since we know that the sender is an action + object, we can safely cast the QObject. We could have used a + C-style cast or a C++ \c static_cast<>(), but as a defensive + programming technique we use a qobject_cast(). The advantage is + that if the object has the wrong type, a null pointer is + returned. Crashes due to null pointers are much easier to diagnose + than crashes due to unsafe casts. + + Once we have the action, we extract the chosen format using + QAction::data(). (When the actions are created, we use + QAction::setData() to set our own custom data attached to the + action, as a QVariant. More on this when we review \c + createActions().) + + Now that we know the format, we call the private \c saveFile() + function to save the currently displayed image. + + \snippet examples/widgets/scribble/mainwindow.cpp 7 + \snippet examples/widgets/scribble/mainwindow.cpp 8 + + We use the \c penColor() slot to retrieve a new color from the + user with a QColorDialog. If the user chooses a new color, we + make it the scribble area's color. + + \snippet examples/widgets/scribble/mainwindow.cpp 9 + \snippet examples/widgets/scribble/mainwindow.cpp 10 + + To retrieve a new pen width in the \c penWidth() slot, we use + QInputDialog. The QInputDialog class provides a simple + convenience dialog to get a single value from the user. We use + the static QInputDialog::getInt() function, which combines a + QLabel and a QSpinBox. The QSpinBox is initialized with the + scribble area's pen width, allows a range from 1 to 50, a step of + 1 (meaning that the up and down arrow increment or decrement the + value by 1). + + The boolean \c ok variable will be set to \c true if the user + clicked \gui OK and to \c false if the user pressed \gui Cancel. + + \snippet examples/widgets/scribble/mainwindow.cpp 11 + \snippet examples/widgets/scribble/mainwindow.cpp 12 + + We implement the \c about() slot to create a message box + describing what the example is designed to show. + + \snippet examples/widgets/scribble/mainwindow.cpp 13 + \snippet examples/widgets/scribble/mainwindow.cpp 14 + + In the \c createAction() function we create the actions + representing the menu entries and connect them to the appropiate + slots. In particular we create the actions found in the \gui + {Save As} sub-menu. We use QImageWriter::supportedImageFormats() + to get a list of the supported formats (as a QList<QByteArray>). + + Then we iterate through the list, creating an action for each + format. We call QAction::setData() with the file format, so we + can retrieve it later as QAction::data(). We could also have + deduced the file format from the action's text, by truncating the + "...", but that would have been inelegant. + + \snippet examples/widgets/scribble/mainwindow.cpp 15 + \snippet examples/widgets/scribble/mainwindow.cpp 16 + + In the \c createMenu() function, we add the previously created + format actions to the \c saveAsMenu. Then we add the rest of the + actions as well as the \c saveAsMenu sub-menu to the \gui File, + \gui Options and \gui Help menus. + + The QMenu class provides a menu widget for use in menu bars, + context menus, and other popup menus. The QMenuBar class provides + a horizontal menu bar with a list of pull-down \l{QMenu}s. At the + end we put the \gui File and \gui Options menus in the \c + {MainWindow}'s menu bar, which we retrieve using the + QMainWindow::menuBar() function. + + \snippet examples/widgets/scribble/mainwindow.cpp 17 + \snippet examples/widgets/scribble/mainwindow.cpp 18 + + In \c mayBeSave(), we check if there are any unsaved changes. If + there are any, we use QMessageBox to give the user a warning that + the image has been modified and the opportunity to save the + modifications. + + As with QColorDialog and QFileDialog, the easiest way to create a + QMessageBox is to use its static functions. QMessageBox provides + a range of different messages arranged along two axes: severity + (question, information, warning and critical) and complexity (the + number of necessary response buttons). Here we use the \c + warning() function sice the message is rather important. + + If the user chooses to save, we call the private \c saveFile() + function. For simplicitly, we use PNG as the file format; the + user can always press \gui Cancel and save the file using another + format. + + The \c maybeSave() function returns \c false if the user clicks + \gui Cancel; otherwise it returns \c true. + + \snippet examples/widgets/scribble/mainwindow.cpp 19 + \snippet examples/widgets/scribble/mainwindow.cpp 20 + + In \c saveFile(), we pop up a file dialog with a file name + suggestion. The static QFileDialog::getSaveFileName() function + returns a file name selected by the user. The file does not have + to exist. +*/ diff --git a/doc/src/examples/sdi.qdoc b/doc/src/examples/sdi.qdoc new file mode 100644 index 0000000000..247a21697d --- /dev/null +++ b/doc/src/examples/sdi.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example mainwindows/sdi + \title SDI Example + + The SDI example shows how to create a Single Document Interface. It uses a number of + top-level windows to display the contents of different text files. + + \image sdi-example.png +*/ diff --git a/doc/src/examples/securesocketclient.qdoc b/doc/src/examples/securesocketclient.qdoc new file mode 100644 index 0000000000..0482bdab58 --- /dev/null +++ b/doc/src/examples/securesocketclient.qdoc @@ -0,0 +1,39 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example network/securesocketclient + \title Secure Socket Client Example + + The Secure Socket Client example shows how to use QSslSocket to + communicate over an encrypted (SSL) connection. It also demonstrates how + to deal with authenticity problems, and how to display security and + certificate information. + + \image securesocketclient.png + \image securesocketclient2.png +*/ diff --git a/doc/src/examples/semaphores.qdoc b/doc/src/examples/semaphores.qdoc new file mode 100644 index 0000000000..1610b8c615 --- /dev/null +++ b/doc/src/examples/semaphores.qdoc @@ -0,0 +1,145 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example threads/semaphores + \title Semaphores Example + + The Semaphores example shows how to use QSemaphore to control + access to a circular buffer shared by a producer thread and a + consumer thread. + + The producer writes data to the buffer until it reaches the end + of the buffer, at which point it restarts from the beginning, + overwriting existing data. The consumer thread reads the data as + it is produced and writes it to standard error. + + Semaphores make it possible to have a higher level of concurrency + than mutexes. If accesses to the buffer were guarded by a QMutex, + the consumer thread couldn't access the buffer at the same time + as the producer thread. Yet, there is no harm in having both + threads working on \e{different parts} of the buffer at the same + time. + + The example comprises two classes: \c Producer and \c Consumer. + Both inherit from QThread. The circular buffer used for + communicating between these two classes and the semaphores that + protect it are global variables. + + An alternative to using QSemaphore to solve the producer-consumer + problem is to use QWaitCondition and QMutex. This is what the + \l{threads/waitconditions}{Wait Conditions} example does. + + \section1 Global Variables + + Let's start by reviewing the circular buffer and the associated + semaphores: + + \snippet examples/threads/semaphores/semaphores.cpp 0 + + \c DataSize is the amout of data that the producer will generate. + To keep the example as simple as possible, we make it a constant. + \c BufferSize is the size of the circular buffer. It is less than + \c DataSize, meaning that at some point the producer will reach + the end of the buffer and restart from the beginning. + + To synchronize the producer and the consumer, we need two + semaphores. The \c freeBytes semaphore controls the "free" area + of the buffer (the area that the producer hasn't filled with data + yet or that the consumer has already read). The \c usedBytes + semaphore controls the "used" area of the buffer (the area that + the producer has filled but that the consumer hasn't read yet). + + Together, the semaphores ensure that the producer is never more + than \c BufferSize bytes ahead of the consumer, and that the + consumer never reads data that the producer hasn't generated yet. + + The \c freeBytes semaphore is initialized with \c BufferSize, + because initially the entire buffer is empty. The \c usedBytes + semaphore is initialized to 0 (the default value if none is + specified). + + \section1 Producer Class + + Let's review the code for the \c Producer class: + + \snippet examples/threads/semaphores/semaphores.cpp 1 + \snippet examples/threads/semaphores/semaphores.cpp 2 + + The producer generates \c DataSize bytes of data. Before it + writes a byte to the circular buffer, it must acquire a "free" + byte using the \c freeBytes semaphore. The QSemaphore::acquire() + call might block if the consumer hasn't kept up the pace with the + producer. + + At the end, the producer releases a byte using the \c usedBytes + semaphore. The "free" byte has successfully been transformed into + a "used" byte, ready to be read by the consumer. + + \section1 Consumer Class + + Let's now turn to the \c Consumer class: + + \snippet examples/threads/semaphores/semaphores.cpp 3 + \snippet examples/threads/semaphores/semaphores.cpp 4 + + The code is very similar to the producer, except that this time + we acquire a "used" byte and release a "free" byte, instead of + the opposite. + + \section1 The main() Function + + In \c main(), we create the two threads and call QThread::wait() + to ensure that both threads get time to finish before we exit: + + \snippet examples/threads/semaphores/semaphores.cpp 5 + \snippet examples/threads/semaphores/semaphores.cpp 6 + + So what happens when we run the program? Initially, the producer + thread is the only one that can do anything; the consumer is + blocked waiting for the \c usedBytes semaphore to be released (its + initial \l{QSemaphore::available()}{available()} count is 0). + Once the producer has put one byte in the buffer, + \c{freeBytes.available()} is \c BufferSize - 1 and + \c{usedBytes.available()} is 1. At that point, two things can + happen: Either the consumer thread takes over and reads that + byte, or the consumer gets to produce a second byte. + + The producer-consumer model presented in this example makes it + possible to write highly concurrent multithreaded applications. + On a multiprocessor machine, the program is potentially up to + twice as fast as the equivalent mutex-based program, since the + two threads can be active at the same time on different parts of + the buffer. + + Be aware though that these benefits aren't always realized. + Acquiring and releasing a QSemaphore has a cost. In practice, it + would probably be worthwhile to divide the buffer into chunks and + to operate on chunks instead of individual bytes. The buffer size + is also a parameter that must be selected carefully, based on + experimentation. +*/ diff --git a/doc/src/examples/settingseditor.qdoc b/doc/src/examples/settingseditor.qdoc new file mode 100644 index 0000000000..3a3099c261 --- /dev/null +++ b/doc/src/examples/settingseditor.qdoc @@ -0,0 +1,37 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example tools/settingseditor + \title Settings Editor Example + + The Settings Editor example shows how Qt's standard settings support is used in an + application by providing an editor that enables the user to view the settings for + installed applications, and modify those that can be edited. + + \image settingseditor-example.png +*/ diff --git a/doc/src/examples/shapedclock.qdoc b/doc/src/examples/shapedclock.qdoc new file mode 100644 index 0000000000..58a3575d16 --- /dev/null +++ b/doc/src/examples/shapedclock.qdoc @@ -0,0 +1,131 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example widgets/shapedclock + \title Shaped Clock Example + + The Shaped Clock example shows how to apply a widget mask to a top-level + widget to produce a shaped window. + + \image shapedclock-example.png + + Widget masks are used to customize the shapes of top-level widgets by restricting + the available area for painting. On some window systems, setting certain window flags + will cause the window decoration (title bar, window frame, buttons) to be disabled, + allowing specially-shaped windows to be created. In this example, we use this feature + to create a circular window containing an analog clock. + + Since this example's window does not provide a \gui File menu or a close + button, we provide a context menu with an \gui Exit entry so that the example + can be closed. Click the right mouse button over the window to open this menu. + + \section1 ShapedClock Class Definition + + The \c ShapedClock class is based on the \c AnalogClock class defined in the + \l{Analog Clock Example}{Analog Clock} example. The whole class definition is + presented below: + + \snippet examples/widgets/shapedclock/shapedclock.h 0 + + The \l{QWidget::paintEvent()}{paintEvent()} implementation is the same as that found + in the \c AnalogClock class. We implement \l{QWidget::sizeHint()}{sizeHint()} + so that we don't have to resize the widget explicitly. We also provide an event + handler for resize events. This allows us to update the mask if the clock is resized. + + Since the window containing the clock widget will have no title bar, we provide + implementations for \l{QWidget::mouseMoveEvent()}{mouseMoveEvent()} and + \l{QWidget::mousePressEvent()}{mousePressEvent()} to allow the clock to be dragged + around the screen. The \c dragPosition variable lets us keep track of where the user + last clicked on the widget. + + \section1 ShapedClock Class Implementation + + The \c ShapedClock constructor performs many of the same tasks as the \c AnalogClock + constructor. We set up a timer and connect it to the widget's update() slot: + + \snippet examples/widgets/shapedclock/shapedclock.cpp 0 + + We inform the window manager that the widget is not to be decorated with a window + frame by setting the Qt::FramelessWindowHint flag on the widget. As a result, we need + to provide a way for the user to move the clock around the screen. + + Mouse button events are delivered to the \c mousePressEvent() handler: + + \snippet examples/widgets/shapedclock/shapedclock.cpp 1 + + If the left mouse button is pressed over the widget, we record the displacement in + global (screen) coordinates between the top-left position of the widget's frame (even + when hidden) and the point where the mouse click occurred. This displacement will be + used if the user moves the mouse while holding down the left button. Since we acted + on the event, we accept it by calling its \l{QEvent::accept()}{accept()} function. + + \image shapedclock-dragging.png + + The \c mouseMoveEvent() handler is called if the mouse is moved over the widget. + + \snippet examples/widgets/shapedclock/shapedclock.cpp 2 + + If the left button is held down while the mouse is moved, the top-left corner of the + widget is moved to the point given by subtracting the \c dragPosition from the current + cursor position in global coordinates. If we drag the widget, we also accept the event. + + The \c paintEvent() function is given for completeness. See the + \l{Analog Clock Example}{Analog Clock} example for a description of the process used + to render the clock. + + \snippet examples/widgets/shapedclock/shapedclock.cpp 3 + + In the \c resizeEvent() handler, we re-use some of the code from the \c paintEvent() + to determine the region of the widget that is visible to the user: + + \snippet examples/widgets/shapedclock/shapedclock.cpp 4 + + Since the clock face is a circle drawn in the center of the widget, this is the region + we use as the mask. + + Although the lack of a window frame may make it difficult for the user to resize the + widget on some platforms, it will not necessarily be impossible. The \c resizeEvent() + function ensures that the widget mask will always be updated if the widget's dimensions + change, and additionally ensures that it will be set up correctly when the widget is + first displayed. + + Finally, we implement the \c sizeHint() for the widget so that it is given a reasonable + default size when it is first shown: + + \snippet examples/widgets/shapedclock/shapedclock.cpp 5 + + \section1 Notes on Widget Masks + + Since QRegion allows arbitrarily complex regions to be created, widget masks can be + made to suit the most unconventionally-shaped windows, and even allow widgets to be + displayed with holes in them. + + Widget masks can also be constructed by using the contents of pixmap to define the + opaque part of the widget. For a pixmap with an alpha channel, a suitable mask can be + obtained with QPixmap::mask(). +*/ diff --git a/doc/src/examples/sharedmemory.qdoc b/doc/src/examples/sharedmemory.qdoc new file mode 100644 index 0000000000..6ceed147a5 --- /dev/null +++ b/doc/src/examples/sharedmemory.qdoc @@ -0,0 +1,128 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example ipc/sharedmemory + \title Shared Memory Example + + The Shared Memory example shows how to use the QSharedMemory class + to implement inter-process communication using shared memory. To + build the example, run make. To run the example, start two instances + of the executable. The main() function creates an \l {QApplication} + {application} and an instance of our example's Dialog class. The + dialog is displayed and then control is passed to the application in + the standard way. + + \snippet examples/ipc/sharedmemory/main.cpp 0 + + Two instances of class Dialog appear. + + \image sharedmemory-example_1.png Screenshot of the Shared Memory example + + Class Dialog inherits QDialog. It encapsulates the user interface + and an instance of QSharedMemory. It also has two public slots, + loadFromFile() and loadFromMemory() that correspond to the two + buttons on the dialog. + + \snippet examples/ipc/sharedmemory/dialog.h 0 + + The constructor builds the user interface widgets and connects the + clicked() signal of each button to the corresponding slot function. + + \snippet examples/ipc/sharedmemory/dialog.cpp 0 + + Note that "QSharedMemoryExample" is passed to the \l {QSharedMemory} + {QSharedMemory()} constructor to be used as the key. This will be + used by the system as the identifier of the underlying shared memory + segment. + + Click the \tt {Load Image From File...} button on one of the + dialogs. The loadFromFile() slot is invoked. First, it tests whether + a shared memory segment is already attached to the process. If so, + that segment is detached from the process, so we can be assured of + starting off the example correctly. + + \snippet examples/ipc/sharedmemory/dialog.cpp 1 + + The user is then asked to select an image file using + QFileDialog::getOpenFileName(). The selected file is loaded into a + QImage. Using a QImage lets us ensure that the selected file is a + valid image, and it also allows us to immediately display the image + in the dialog using setPixmap(). + + Next the image is streamed into a QBuffer using a QDataStream. This + gives us the size, which we then use to \l {QSharedMemory::} + {create()} our shared memory segment. Creating a shared memory + segment automatically \l {QSharedMemory::attach()} {attaches} the + segment to the process. Using a QBuffer here lets us get a pointer + to the image data, which we then use to do a memcopy() from the + QBuffer into the shared memory segment. + + \snippet examples/ipc/sharedmemory/dialog.cpp 2 + + Note that we \l {QSharedMemory::} {lock()} the shared memory segment + before we copy into it, and we \l {QSharedMemory::} {unlock()} it + again immediately after the copy. This ensures we have exclusive + access to the shared memory segment to do our memcopy(). If some + other process has the segment lock, then our process will block + until the lock becomes available. + + Note also that the function does not \l {QSharedMemory::} {detach()} + from the shared memory segment after the memcopy() and + unlock(). Recall that when the last process detaches from a shared + memory segment, the segment is released by the operating + system. Since this process only one that is attached to the shared + memory segment at the moment, if loadFromFile() detached from the + shared memory segment, the segment would be destroyed before we get + to the next step. + + When the function returns, if the file you selected was qt.png, your + first dialog looks like this. + + \image sharedmemory-example_2.png Screenshot of the Shared Memory example + + In the second dialog, click the \tt {Display Image From Shared + Memory} button. The loadFromMemory() slot is invoked. It first \l + {QSharedMemory::attach()} {attaches} the process to the same shared + memory segment created by the first process. Then it \l + {QSharedMemory::lock()} {locks} the segment for exclusive access and + links a QBuffer to the image data in the shared memory segment. It + then streams the data into a QImage and \l {QSharedMemory::unlock()} + {unlocks} the segment. + + \snippet examples/ipc/sharedmemory/dialog.cpp 3 + + In this case, the function does \l {QSharedMemory::} {detach()} from + the segment, because now we are effectively finished using + it. Finally, the QImage is displayed. At this point, both dialogs + should be showing the same image. When you close the first dialog, + the Dialog destructor calls the QSharedMemory destructor, which + detaches from the shared memory segment. Since this is the last + process to be detached from the segment, the operating system will + now release the shared memory. + + */ diff --git a/doc/src/examples/simpledecoration.qdoc b/doc/src/examples/simpledecoration.qdoc new file mode 100644 index 0000000000..d379fd3c7f --- /dev/null +++ b/doc/src/examples/simpledecoration.qdoc @@ -0,0 +1,252 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** 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. +*/ diff --git a/doc/src/examples/simpledommodel.qdoc b/doc/src/examples/simpledommodel.qdoc new file mode 100644 index 0000000000..9b4d80ec8a --- /dev/null +++ b/doc/src/examples/simpledommodel.qdoc @@ -0,0 +1,280 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example itemviews/simpledommodel + \title Simple DOM Model Example + + The Simple DOM Model example shows how an existing class can be adapted for use with + the model/view framework. + + \image simpledommodel-example.png + + Qt provides two complementary sets of classes for reading XML files: The classes based + around QXmlReader provide a SAX-style API for incremental reading of large files, and + the classes based around QDomDocument enable developers to access the contents of XML + files using a Document Object Model (DOM) API. + + In this example, we create a model that uses the DOM API to expose the structure and + contents of XML documents to views via the standard QAbstractModel interface. + + \section1 Design and Concepts + + Reading an XML document with Qt's DOM classes is a straightforward process. Typically, + the contents of a file are supplied to QDomDocument, and nodes are accessed using the + functions provided by QDomNode and its subclasses. + + \omit + For example, the following code + snippet reads the contents of a file into a QDomDocument object and traverses the + document, reading all the plain text that can be found: + + \snippet doc/src/snippets/code/doc_src_examples_simpledommodel.cpp 0 + + In principle, the functions provided by QDomNode can be used to navigate from any + given starting point in a document to the piece of data requested by another component. + Since QDomDocument maintains information about the structure of a document, we can + use this to implement the required virtual functions in a QAbstractItemModel subclass. + \endomit + + The aim is to use the structure provided by QDomDocument by wrapping QDomNode objects + in item objects similar to the \c TreeItem objects used in the + \l{Simple Tree Model Example}{Simple Tree Model} example. + + \section1 DomModel Class Definition + + Let us begin by examining the \c DomModel class: + + \snippet examples/itemviews/simpledommodel/dommodel.h 0 + + The class definition contains all the basic functions that are needed for a + read-only model. Only the constructor and \c document() function are specific to + this model. The private \c domDocument variable is used to hold the document + that is exposed by the model; the \c rootItem variable contains a pointer to + the root item in the model. + + \section1 DomItem Class Definition + + The \c DomItem class is used to hold information about a specific QDomNode in + the document: + + \snippet examples/itemviews/simpledommodel/domitem.h 0 + + Each \c DomItem provides a wrapper for a QDomNode obtained from the underlying + document which contains a reference to the node, it's location in the parent node's + list of child nodes, and a pointer to a parent wrapper item. + + The \c parent(), \c child(), and \c row() functions are convenience functions for + the \c DomModel to use that provide basic information about the item to be discovered + quickly. The node() function provides access to the underlying QDomNode object. + + As well as the information supplied in the constructor, the class maintains a cache + of information about any child items. This is used to provide a collection of + persistent item objects that the model can identify consistently and improve the + performance of the model when accessing child items. + + \section1 DomItem Class Implementation + + Since the \c DomItem class is only a thin wrapper around QDomNode objects, with a + few additional features to help improve performance and memory usage, we can provide + a brief outline of the class before discussing the model itself. + + The constructor simply records details of the QDomNode that needs to be wrapped: + + \snippet examples/itemviews/simpledommodel/domitem.cpp 0 + \snippet examples/itemviews/simpledommodel/domitem.cpp 1 + + As a result, functions to provide the parent wrapper, the row number occupied by + the item in its parent's list of children, and the underlying QDomNode for each item + are straightforward to write: + + \snippet examples/itemviews/simpledommodel/domitem.cpp 4 + \codeline + \snippet examples/itemviews/simpledommodel/domitem.cpp 6 + \codeline + \snippet examples/itemviews/simpledommodel/domitem.cpp 3 + + It is necessary to maintain a collection of items which can be consistently identified + by the model. For that reason, we maintain a hash of child wrapper items that, to + minimize memory usage, is initially empty. The model uses the item's \c child() + function to help create model indexes, and this constructs wrappers for the children + of the item's QDomNode, relating the row number of each child to the newly-constructed + wrapper: + + \snippet examples/itemviews/simpledommodel/domitem.cpp 5 + + If a QDomNode was previously wrapped, the cached wrapper is returned; otherwise, a + new wrapper is constructed and stored for valid children, and zero is returned for + invalid ones. + + The class's destructor deletes all the child items of the wrapper: + + \snippet examples/itemviews/simpledommodel/domitem.cpp 2 + + These, in turn, will delete their children and free any QDomNode objects in use. + + \section1 DomModel Class Implementation + + The structure provided by the \c DomItem class makes the implementation of \c DomModel + similar to the \c TreeModel shown in the + \l{Simple Tree Model Example}{Simple Tree Model} example. + + The constructor accepts an existing document and a parent object for the model: + + \snippet examples/itemviews/simpledommodel/dommodel.cpp 0 + + A shallow copy of the document is stored for future reference, and a root item is + created to provide a wrapper around the document. We assign the root item a row + number of zero only to be consistent since the root item will have no siblings. + + Since the model only contains information about the root item, the destructor only + needs to delete this one item: + + \snippet examples/itemviews/simpledommodel/dommodel.cpp 1 + + All of the child items in the tree will be deleted by the \c DomItem destructor as + their parent items are deleted. + + \section2 Basic Properties of The Model + + Some aspects of the model do not depend on the structure of the underlying document, + and these are simple to implement. + + The number of columns exposed by the model is returned by the \c columnCount() + function: + + \snippet examples/itemviews/simpledommodel/dommodel.cpp 2 + + This value is fixed, and does not depend on the location or type of the underlying + node in the document. We will use these three columns to display different kinds of + data from the underlying document. + + Since we only implement a read-only model, the \c flags() function is straightforward + to write: + + \snippet examples/itemviews/simpledommodel/dommodel.cpp 5 + + Since the model is intended for use in a tree view, the \c headerData() function only + provides a horizontal header: + + \snippet examples/itemviews/simpledommodel/dommodel.cpp 6 + + The model presents the names of nodes in the first column, element attributes in the + second, and any node values in the third. + + \section2 Navigating The Document + + The index() function creates a model index for the item with the given row, column, + and parent in the model: + + \snippet examples/itemviews/simpledommodel/dommodel.cpp 7 + + The function first has to relate the parent index to an item that contains a node + from the underlying document. If the parent index is invalid, it refers to the root + node in the document, so we retrieve the root item that wraps it; otherwise, we + obtain a pointer to the relevant item using the QModelIndex::internalPointer() + function. We are able to extract a pointer in this way because any valid model index + will have been created by this function, and we store pointers to item objects in + any new indexes that we create with QAbstractItemModel::createIndex(): + + \snippet examples/itemviews/simpledommodel/dommodel.cpp 8 + + A child item for the given row is provided by the parent item's \c child() function. + If a suitable child item was found then we call + \l{QAbstractItemModel::createIndex()}{createIndex()} to produce a model index for the + requested row and column, passing a pointer to the child item for it to store + internally. If no suitable child item is found, an invalid model index is returned. + + Note that the items themselves maintain ownership of their child items. This means + that the model does not need to keep track of the child items that have been created, + and can let the items themselves tidy up when they are deleted. + + The number of rows beneath a given item in the model is returned by the \c rowCount() + function, and is the number of child nodes contained by the node that corresponds to + the specified model index: + + \snippet examples/itemviews/simpledommodel/dommodel.cpp 10 + + To obtain the relevant node in the underlying document, we access the item via the + internal pointer stored in the model index. If an invalid index is supplied, the + root item is used instead. We use the item's \c node() function to access the node + itself, and simply count the number of child nodes it contains. + + Since the model is used to represent a hierarchical data structure, it needs to + provide an implementation for the \c parent() function. This returns a model index + that corresponds to the parent of a child model index supplied as its argument: + + \snippet examples/itemviews/simpledommodel/dommodel.cpp 9 + + For valid indexes other than the index corresponding to the root item, we obtain + a pointer to the relevant item using the method described in the \c index() function, + and use the item's \c parent() function to obtain a pointer to the parent item. + + If no valid parent item exists, or if the parent item is the root item, we can simply + follow convention and return an invalid model index. For all other parent items, we + create a model index containing the appropriate row and column numbers, and a pointer + to the parent item we just obtained. + + Data is provided by the \c data() function. For simplicity, we only provide data for + the \l{Qt::DisplayRole}{display role}, returning an invalid variant for all other + requests: + + \snippet examples/itemviews/simpledommodel/dommodel.cpp 3 + + As before, we obtain an item pointer for the index supplied, and use it to obtain + the underlying document node. Depending on the column specified, the data we return + is obtained in different ways: + + \snippet examples/itemviews/simpledommodel/dommodel.cpp 4 + + For the first column, we return the node's name. For the second column, we read any + attributes that the node may have, and return a string that contains a space-separated + list of attribute-value assignments. For the third column, we return any value that + the node may have; this allows the contents of text nodes to be displayed in a view. + + If data from any other column is requested, an invalid variant is returned. + + \section1 Implementation Notes + + Ideally, we would rely on the structure provided by QDomDocument to help us write + the \l{QAbstractItemModel::parent()}{parent()} and + \l{QAbstractItemModel::index()}{index()} functions that are required when subclassing + QAbstractItemModel. However, since Qt's DOM classes use their own system for + dynamically allocating memory for DOM nodes, we cannot guarantee that the QDomNode + objects returned for a given piece of information will be the same for subsequent + accesses to the document. + + We use item wrappers for each QDomNode to provide consistent pointers that the model + can use to navigate the document structure. + \omit + Since these items contain value references to the QDomNode objects themselves, this + has the side effect that the DOM nodes themselves can be used to reliably navigate + the document [not sure about this - QDom* may return different QDomNode objects for + the same piece of information]. However, this advantage is redundant since we need to + use wrapper items to obtain it. [Possible use of QDomNode cache in the model itself.] + \endomit +*/ diff --git a/doc/src/examples/simpletreemodel.qdoc b/doc/src/examples/simpletreemodel.qdoc new file mode 100644 index 0000000000..3b842f00a8 --- /dev/null +++ b/doc/src/examples/simpletreemodel.qdoc @@ -0,0 +1,333 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example itemviews/simpletreemodel + \title Simple Tree Model Example + + The Simple Tree Model example shows how to create a basic, read-only + hierarchical model to use with Qt's standard view classes. For a + description of simple non-hierarchical list and table models, see the + \l{Model/View Programming} overview. + + \image simpletreemodel-example.png + + Qt's model/view architecture provides a standard way for views to + manipulate information in a data source, using an abstract model + of the data to simplify and standardize the way it is accessed. + Simple models represent data as a table of items, and allow views + to access this data via an + \l{Model/View Programming#Models}{index-based} system. More generally, + models can be used to represent data in the form of a tree structure + by allowing each item to act as a parent to a table of child items. + + Before attempting to implement a tree model, it is worth considering whether + the data is supplied by an external source, or whether it is going to be + maintained within the model itself. In this example, we will implement an + internal structure to hold data rather than discuss how to package data from + an external source. + + \section1 Design and Concepts + + The data structure that we use to represent the structure of the data takes + the form of a tree built from \c TreeItem objects. Each \c TreeItem + represents an item in a tree view, and contains several columns of data. + + \target SimpleTreeModelStructure + \table + \row \i \inlineimage treemodel-structure.png + \i \bold{Simple Tree Model Structure} + + The data is stored internally in the model using \c TreeItem objects that + are linked together in a pointer-based tree structure. Generally, each + \c TreeItem has a parent item, and can have a number of child items. + However, the root item in the tree structure has no parent item and it + is never referenced outside the model. + + Each \c TreeItem contains information about its place in the tree + structure; it can return its parent item and its row number. Having + this information readily available makes implementing the model easier. + + Since each item in a tree view usually contains several columns of data + (a title and a summary in this example), it is natural to store this + information in each item. For simplicity, we will use a list of QVariant + objects to store the data for each column in the item. + \endtable + + The use of a pointer-based tree structure means that, when passing a + model index to a view, we can record the address of the corresponding + item in the index (see QAbstractItemModel::createIndex()) and retrieve + it later with QModelIndex::internalPointer(). This makes writing the + model easier and ensures that all model indexes that refer to the same + item have the same internal data pointer. + + With the appropriate data structure in place, we can create a tree model + with a minimal amount of extra code to supply model indexes and data to + other components. + + \section1 TreeItem Class Definition + + The \c TreeItem class is defined as follows: + + \snippet examples/itemviews/simpletreemodel/treeitem.h 0 + + The class is a basic C++ class. It does not inherit from QObject or + provide signals and slots. It is used to hold a list of QVariants, + containing column data, and information about its position in the tree + structure. The functions provide the following features: + + \list + \o The \c appendChildItem() is used to add data when the model is first + constructed and is not used during normal use. + \o The \c child() and \c childCount() functions allow the model to obtain + information about any child items. + \o Information about the number of columns associated with the item is + provided by \c columnCount(), and the data in each column can be + obtained with the data() function. + \o The \c row() and \c parent() functions are used to obtain the item's + row number and parent item. + \endlist + + The parent item and column data are stored in the \c parentItem and + \c itemData private member variables. The \c childItems variable contains + a list of pointers to the item's own child items. + + \section1 TreeItem Class Implementation + + The constructor is only used to record the item's parent and the data + associated with each column. + + \snippet examples/itemviews/simpletreemodel/treeitem.cpp 0 + + A pointer to each of the child items belonging to this item will be + stored in the \c childItems private member variable. When the class's + destructor is called, it must delete each of these to ensure that + their memory is reused: + + \snippet examples/itemviews/simpletreemodel/treeitem.cpp 1 + + Since each of the child items are constructed when the model is initially + populated with data, the function to add child items is straightforward: + + \snippet examples/itemviews/simpletreemodel/treeitem.cpp 2 + + Each item is able to return any of its child items when given a suitable + row number. For example, in the \l{#SimpleTreeModelStructure}{above diagram}, + the item marked with the letter "A" corresponds to the child of the root item + with \c{row = 0}, the "B" item is a child of the "A" item with \c{row = 1}, + and the "C" item is a child of the root item with \c{row = 1}. + + The \c child() function returns the child that corresponds to + the specified row number in the item's list of child items: + + \snippet examples/itemviews/simpletreemodel/treeitem.cpp 3 + + The number of child items held can be found with \c childCount(): + + \snippet examples/itemviews/simpletreemodel/treeitem.cpp 4 + + The \c TreeModel uses this function to determine the number of rows that + exist for a given parent item. + + The \c row() function reports the item's location within its parent's + list of items: + + \snippet examples/itemviews/simpletreemodel/treeitem.cpp 8 + + Note that, although the root item (with no parent item) is automatically + assigned a row number of 0, this information is never used by the model. + + The number of columns of data in the item is trivially returned by the + \c columnCount() function. + + \snippet examples/itemviews/simpletreemodel/treeitem.cpp 5 + + Column data is returned by the \c data() function, taking advantage of + QList's ability to provide sensible default values if the column number + is out of range: + + \snippet examples/itemviews/simpletreemodel/treeitem.cpp 6 + + The item's parent is found with \c parent(): + + \snippet examples/itemviews/simpletreemodel/treeitem.cpp 7 + + Note that, since the root item in the model will not have a parent, this + function will return zero in that case. We need to ensure that the model + handles this case correctly when we implement the \c TreeModel::parent() + function. + + \section1 TreeModel Class Definition + + The \c TreeModel class is defined as follows: + + \snippet examples/itemviews/simpletreemodel/treemodel.h 0 + + This class is similar to most other subclasses of QAbstractItemModel that + provide read-only models. Only the form of the constructor and the + \c setupModelData() function are specific to this model. In addition, we + provide a destructor to clean up when the model is destroyed. + + \section1 TreeModel Class Implementation + + For simplicity, the model does not allow its data to be edited. As a + result, the constructor takes an argument containing the data that the + model will share with views and delegates: + + \snippet examples/itemviews/simpletreemodel/treemodel.cpp 0 + + It is up to the constructor to create a root item for the model. This + item only contains vertical header data for convenience. We also use it + to reference the internal data structure that contains the model data, + and it is used to represent an imaginary parent of top-level items in + the model. + + The model's internal data structure is populated with items by the + \c setupModelData() function. We will examine this function separately + at the end of this document. + + The destructor ensures that the root item and all of its descendants + are deleted when the model is destroyed: + + \snippet examples/itemviews/simpletreemodel/treemodel.cpp 1 + + Since we cannot add data to the model after it is constructed and set + up, this simplifies the way that the internal tree of items is managed. + + Models must implement an \c index() function to provide indexes for + views and delegates to use when accessing data. Indexes are created + for other components when they are referenced by their row and column + numbers, and their parent model index. If an invalid model + index is specified as the parent, it is up to the model to return an + index that corresponds to a top-level item in the model. + + When supplied with a model index, we first check whether it is valid. + If it is not, we assume that a top-level item is being referred to; + otherwise, we obtain the data pointer from the model index with its + \l{QModelIndex::internalPointer()}{internalPointer()} function and use + it to reference a \c TreeItem object. Note that all the model indexes + that we construct will contain a pointer to an existing \c TreeItem, + so we can guarantee that any valid model indexes that we receive will + contain a valid data pointer. + + \snippet examples/itemviews/simpletreemodel/treemodel.cpp 6 + + Since the row and column arguments to this function refer to a + child item of the corresponding parent item, we obtain the item using + the \c TreeItem::child() function. The + \l{QAbstractItemModel::createIndex()}{createIndex()} function is used + to create a model index to be returned. We specify the row and column + numbers, and a pointer to the item itself. The model index can be used + later to obtain the item's data. + + The way that the \c TreeItem objects are defined makes writing the + \c parent() function easy: + + \snippet examples/itemviews/simpletreemodel/treemodel.cpp 7 + + We only need to ensure that we never return a model index corresponding + to the root item. To be consistent with the way that the \c index() + function is implemented, we return an invalid model index for the + parent of any top-level items in the model. + + When creating a model index to return, we must specify the row and + column numbers of the parent item within its own parent. We can + easily discover the row number with the \c TreeItem::row() function, + but we follow a convention of specifying 0 as the column number of + the parent. The model index is created with + \l{QAbstractItemModel::createIndex()}{createIndex()} in the same way + as in the \c index() function. + + The \c rowCount() function simply returns the number of child items + for the \c TreeItem that corresponds to a given model index, or the + number of top-level items if an invalid index is specified: + + \snippet examples/itemviews/simpletreemodel/treemodel.cpp 8 + + Since each item manages its own column data, the \c columnCount() + function has to call the item's own \c columnCount() function to + determine how many columns are present for a given model index. + As with the \c rowCount() function, if an invalid model index is + specified, the number of columns returned is determined from the + root item: + + \snippet examples/itemviews/simpletreemodel/treemodel.cpp 2 + + Data is obtained from the model via \c data(). Since the item manages + its own columns, we need to use the column number to retrieve the data + with the \c TreeItem::data() function: + + \snippet examples/itemviews/simpletreemodel/treemodel.cpp 3 + + Note that we only support the \l{Qt::ItemDataRole}{DisplayRole} + in this implementation, and we also return invalid QVariant objects for + invalid model indexes. + + We use the \c flags() function to ensure that views know that the + model is read-only: + + \snippet examples/itemviews/simpletreemodel/treemodel.cpp 4 + + The \c headerData() function returns data that we conveniently stored + in the root item: + + \snippet examples/itemviews/simpletreemodel/treemodel.cpp 5 + + This information could have been supplied in a different way: either + specified in the constructor, or hard coded into the \c headerData() + function. + + \section1 Setting Up the Data in the Model + + We use the \c setupModelData() function to set up the initial data in + the model. This function parses a text file, extracting strings of + text to use in the model, and creates item objects that record both + the data and the overall model structure. + Naturally, this function works in a way that is very specific to + this model. We provide the following description of its behavior, + and refer the reader to the example code itself for more information. + + We begin with a text file in the following format: + + \snippet doc/src/snippets/code/doc_src_examples_simpletreemodel.qdoc 0 + \dots + \snippet doc/src/snippets/code/doc_src_examples_simpletreemodel.qdoc 1 + + We process the text file with the following two rules: + + \list + \o For each pair of strings on each line, create an item (or node) + in a tree structure, and place each string in a column of data + in the item. + \o When the first string on a line is indented with respect to the + first string on the previous line, make the item a child of the + previous item created. + \endlist + + To ensure that the model works correctly, it is only necessary to + create instances of \c TreeItem with the correct data and parent item. +*/ diff --git a/doc/src/examples/simplewidgetmapper.qdoc b/doc/src/examples/simplewidgetmapper.qdoc new file mode 100644 index 0000000000..22ca9e7a30 --- /dev/null +++ b/doc/src/examples/simplewidgetmapper.qdoc @@ -0,0 +1,125 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example itemviews/simplewidgetmapper + \title Simple Widget Mapper Example + + The Simple Widget Mapper example shows how to use a widget mapper to display + data from a model in a collection of widgets. + + \image simplewidgetmapper-example.png + + The QDataWidgetMapper class allows information obtained from a + \l{Model Classes}{model} to be viewed and edited in a collection of + widgets instead of in an \l{View Classes}{item view}. + Any model derived from QAbstractItemModel can be used as the source of + data and almost any input widget can be used to display it. + + The example itself is very simple: we create \c Window, a QWidget subclass + that we use to hold the widgets used to present the data, and show it. The + \c Window class will provide buttons that the user can click to show + different records from the model. + + \section1 Window Class Definition + + The class provides a constructor, a slot to keep the buttons up to date, + and a private function to set up the model: + + \snippet examples/itemviews/simplewidgetmapper/window.h Window definition + + In addition to the QDataWidgetMapper object and the controls used to make + up the user interface, we use a QStandardItemModel to hold our data. + We could use a custom model, but this standard implementation is sufficient + for our purposes. + + \section1 Window Class Implementation + + The constructor of the \c Window class can be explained in three parts. + In the first part, we set up the widgets used for the user interface: + + \snippet examples/itemviews/simplewidgetmapper/window.cpp Set up widgets + + We also set up the buddy relationships between various labels and the + corresponding input widgets. + + Next, we set up the widget mapper, relating each input widget to a column + in the model specified by the call to \l{QDataWidgetMapper::}{setModel()}: + + \snippet examples/itemviews/simplewidgetmapper/window.cpp Set up the mapper + + We also connect the mapper to the \gui{Next} and \gui{Previous} buttons + via its \l{QDataWidgetMapper::}{toNext()} and + \l{QDataWidgetMapper::}{toPrevious()} slots. The mapper's + \l{QDataWidgetMapper::}{currentIndexChanged()} signal is connected to the + \c{updateButtons()} slot in the window which we'll show later. + + In the final part of the constructor, we set up the layout, placing each + of the widgets in a grid (we could also use a QFormLayout for this): + + \snippet examples/itemviews/simplewidgetmapper/window.cpp Set up the layout + + Lastly, we set the window title and initialize the mapper by setting it to + refer to the first row in the model. + + The model is initialized in the window's \c{setupModel()} function. Here, + we create a standard model with 5 rows and 3 columns, and we insert some + sample names, addresses and ages into each row: + + \snippet examples/itemviews/simplewidgetmapper/window.cpp Set up the model + + As a result, each row can be treated like a record in a database, and the + widget mapper will read the data from each row, using the column numbers + specified earlier to access the correct data for each widget. This is + shown in the following diagram: + + \image widgetmapper-simple-mapping.png + + Since the user can navigate using the buttons in the user interface, the + example is fully-functional at this point, but to make it a bit more + user-friendly, we implement the \c{updateButtons()} slot to show when the + user is viewing the first or last records: + + \snippet examples/itemviews/simplewidgetmapper/window.cpp Slot for updating the buttons + + If the mapper is referring to the first row in the model, the \gui{Previous} + button is disabled. Similarly, the \gui{Next} button is disabled if the + mapper reaches the last row in the model. + + \section1 More Complex Mappings + + The QDataWidgetMapper class makes it easy to relate information from a + model to widgets in a user interface. However, it is sometimes necessary + to use input widgets which offer choices to the user, such as QComboBox, + in conjunction with a widget mapper. + + In these situations, although the mapping to input widgets remains simple, + more work needs to be done to expose additional data to the widget mapper. + This is covered by the \l{Combo Widget Mapper Example}{Combo Widget Mapper} + and \l{SQL Widget Mapper Example}{SQL Widget Mapper} + examples. +*/ diff --git a/doc/src/examples/sipdialog.qdoc b/doc/src/examples/sipdialog.qdoc new file mode 100644 index 0000000000..7c2a3eece6 --- /dev/null +++ b/doc/src/examples/sipdialog.qdoc @@ -0,0 +1,127 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example dialogs/sipdialog + \title SIP Dialog Example + \ingroup qtce + + The SIP Dialog example shows how to create a dialog that is aware of + the Windows Mobile SIP (Software Input Panel) and reacts to it. + + \table + \row \o \inlineimage sipdialog-closed.png + \o \inlineimage sipdialog-opened.png + \endtable + + Sometimes it is necessary for a dialog to take the SIP into account, + as the SIP may hide important input widgets. The SIP Dialog Example + shows how a \c Dialog object, \c dialog, can be resized accordingly + if the SIP is opened, by embedding the contents of \c dialog in a + QScrollArea. + + \section1 Dialog Class Definition + + The \c Dialog class is a subclass of QDialog that implements a public + slot, \c desktopResized(), and a public function, \c reactToSIP(). Also, + it holds a private instance of QRect, \c desktopGeometry. + + \snippet dialogs/sipdialog/dialog.h Dialog header + + \section1 Dialog Class Implementation + + In the constructor of \c Dialog, we start by obtaining the + available geometry of the screen with + \l{QDesktopWidget::availableGeometry()}{availableGeometry()}. The + parameter used is \c 0 to indicate that we require the primary screen. + + \snippet dialogs/sipdialog/dialog.cpp Dialog constructor part1 + + We set the window's title to "SIP Dialog Example" and declare a QScrollArea + object, \c scrollArea. Next we instantiate a QGroupBox, \c groupBox, with + \c scrollArea as its parent. The title of \c groupBox is also set to + "SIP Dialog Example". A QGridLayout object, \c gridLayout, is then used + as \c{groupBox}'s layout. + + We create a QLineEdit, a QLabel and a QPushButton and we set the + \l{QWidget::setMinimumWidth()}{minimumWidth} property to 220 pixels, + respectively. + + \snippet dialogs/sipdialog/dialog.cpp Dialog constructor part2 + + Also, all three widgets' text are set accordingly. The + \l{QGridLayout::setVerticalSpacing()}{verticalSpacing} property of + \c gridLayout is set based on the height of \c desktopGeometry. This + is to adapt to the different form factors of Windows Mobile. Then, we + add our widgets to the layout. + + \snippet dialogs/sipdialog/dialog.cpp Dialog constructor part3 + + The \c{scrollArea}'s widget is set to \c groupBox. We use a QHBoxLayout + object, \c layout, to contain \c scrollArea. The \c{Dialog}'s layout + is set to \c layout and the scroll area's horizontal scroll bar is turned + off. + + \snippet dialogs/sipdialog/dialog.cpp Dialog constructor part4 + + The following signals are connected to their respective slots: + \list + \o \c{button}'s \l{QPushButton::pressed()}{pressed()} signal to + \l{QApplication}'s \l{QApplication::closeAllWindows()} + {closeAllWindows()} slot, + \o \l{QDesktopWidget}'s \l{QDesktopWidget::workAreaResized()} + {workAreaResized()} signal to \c{dialog}'s \c desktopResized() slot. + \endlist + + \snippet dialogs/sipdialog/dialog.cpp Dialog constructor part5 + + The \c desktopResized() function accepts an integer, \a screen, + corresponding to the screen's index. We only invoke \c reactToSIP() + if \a screen is the primary screen (e.g. index = 0). + + \snippet dialogs/sipdialog/dialog.cpp desktopResized() function + + The \c reactToSIP() function resizes \c dialog accordingly if the + desktop's available geometry changed vertically, as this change signifies + that the SIP may have been opened or closed. + + \snippet dialogs/sipdialog/dialog.cpp reactToSIP() function + + If the height has decreased, we unset the maximized window state. + Otherwise, we set the maximized window state. Lastly, we update + \c desktopGeometry to the desktop's available geometry. + + \section1 The \c main() function + + The \c main() function for the SIP Dialog example instantiates \c Dialog + and invokes its \l{QDialog::exec()}{exec()} function. + + \snippet dialogs/sipdialog/main.cpp main() function + + \note Although this example uses a dialog, the techniques used here apply to + all top-level widgets respectively. +*/ diff --git a/doc/src/examples/sliders.qdoc b/doc/src/examples/sliders.qdoc new file mode 100644 index 0000000000..c202ccba0d --- /dev/null +++ b/doc/src/examples/sliders.qdoc @@ -0,0 +1,255 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example widgets/sliders + \title Sliders Example + + Qt provides three types of slider-like widgets: QSlider, + QScrollBar and QDial. They all inherit most of their + functionality from QAbstractSlider, and can in theory replace + each other in an application since the differences only concern + their look and feel. This example shows what they look like, how + they work and how their behavior and appearance can be + manipulated through their properties. + + The example also demonstrates how signals and slots can be used to + synchronize the behavior of two or more widgets. + + \image sliders-example.png Screenshot of the Sliders example + + The Sliders example consists of two classes: + + \list + + \o \c SlidersGroup is a custom widget. It combines a QSlider, a + QScrollBar and a QDial. + + \o \c Window is the main widget combining a QGroupBox and a + QStackedWidget. In this example, the QStackedWidget provides a + stack of two \c SlidersGroup widgets. The QGroupBox contain + several widgets that control the behavior of the slider-like + widgets. + + \endlist + + First we will review the \c Window class, then we + will take a look at the \c SlidersGroup class. + + \section1 Window Class Definition + + \snippet examples/widgets/sliders/window.h 0 + + The \c Window class inherits from QWidget. It displays the slider + widgets and allows the user to set their minimum, maximum and + current values and to customize their appearance, key bindings + and orientation. We use a private \c createControls() function to + create the widgets that provide these controlling mechanisms and + to connect them to the slider widgets. + + \section1 Window Class Implementation + + \snippet examples/widgets/sliders/window.cpp 0 + + In the constructor we first create the two \c SlidersGroup + widgets that display the slider widgets horizontally and + vertically, and add them to the QStackedWidget. QStackedWidget + provides a stack of widgets where only the top widget is visible. + With \c createControls() we create a connection from a + controlling widget to the QStackedWidget, making the user able to + choose between horizontal and vertical orientation of the slider + widgets. The rest of the controlling mechanisms is implemented by + the same function call. + + \snippet examples/widgets/sliders/window.cpp 1 + \snippet examples/widgets/sliders/window.cpp 2 + + Then we connect the \c horizontalSliders, \c verticalSliders and + \c valueSpinBox to each other, so that the slider widgets and the + control widget will behave synchronized when the current value of + one of them changes. The \c valueChanged() signal is emitted with + the new value as argument. The \c setValue() slot sets the + current value of the widget to the new value, and emits \c + valueChanged() if the new value is different from the old one. + + We put the group of control widgets and the stacked widget in a + horizontal layout before we initialize the minimum, maximum and + current values. The initialization of the current value will + propagate to the slider widgets through the connection we made + between \c valueSpinBox and the \c SlidersGroup widgets. The + minimum and maximum values propagate through the connections we + created with \c createControls(). + + \snippet examples/widgets/sliders/window.cpp 3 + \snippet examples/widgets/sliders/window.cpp 4 + + In the private \c createControls() function, we let a QGroupBox + (\c controlsGroup) display the control widgets. A group box can + provide a frame, a title and a keyboard shortcut, and displays + various other widgets inside itself. The group of control widgets + is composed by two checkboxes, three spin boxes (with labels) and + one combobox. + + After creating the labels, we create the two checkboxes. + Checkboxes are typically used to represent features in an + application that can be enabled or disabled. When \c + invertedAppearance is enabled, the slider values are inverted. + The table below shows the appearance for the different + slider-like widgets: + + \table + \header \o \o{2,1} QSlider \o{2,1} QScrollBar \o{2,1} QDial + \header \o \o Normal \o Inverted \o Normal \o Inverted \o Normal \o Inverted + \row \o Qt::Horizontal \o Left to right \o Right to left \o Left to right \o Right to left \o Clockwise \o Counterclockwise + \row \o Qt::Vertical \o Bottom to top \o Top to bottom \o Top to bottom \o Bottom to top \o Clockwise \o Counterclockwise + \endtable + + It is common to invert the appearance of a vertical QSlider. A + vertical slider that controls volume, for example, will typically + go from bottom to top (the non-inverted appearance), whereas a + vertical slider that controls the position of an object on screen + might go from top to bottom, because screen coordinates go from + top to bottom. + + When the \c invertedKeyBindings option is enabled (corresponding + to the QAbstractSlider::invertedControls property), the slider's + wheel and key events are inverted. The normal key bindings mean + that scrolling the mouse wheel "up" or using keys like page up + will increase the slider's current value towards its maximum. + Inverted, the same wheel and key events will move the value + toward the slider's minimum. This can be useful if the \e + appearance of a slider is inverted: Some users might expect the + keys to still work the same way on the value, whereas others + might expect \key PageUp to mean "up" on the screen. + + Note that for horizontal and vertical scroll bars, the key + bindings are inverted by default: \key PageDown increases the + current value, and \key PageUp decreases it. + + \snippet examples/widgets/sliders/window.cpp 5 + \snippet examples/widgets/sliders/window.cpp 6 + + Then we create the spin boxes. QSpinBox allows the user to choose + a value by clicking the up and down buttons or pressing the \key + Up and \key Down keys on the keyboard to modify the value + currently displayed. The user can also type in the value + manually. The spin boxes control the minimum, maximum and current + values for the QSlider, QScrollBar, and QDial widgets. + + We create a QComboBox that allows the user to choose the + orientation of the slider widgets. The QComboBox widget is a + combined button and popup list. It provides a means of presenting + a list of options to the user in a way that takes up the minimum + amount of screen space. + + \snippet examples/widgets/sliders/window.cpp 7 + \snippet examples/widgets/sliders/window.cpp 8 + + We synchronize the behavior of the control widgets and the slider + widgets through their signals and slots. We connect each control + widget to both the horizontal and vertical group of slider + widgets. We also connect \c orientationCombo to the + QStackedWidget, so that the correct "page" is shown. Finally, we + lay out the control widgets in a QGridLayout within the \c + controlsGroup group box. + + \section1 SlidersGroup Class Definition + + \snippet examples/widgets/sliders/slidersgroup.h 0 + + The \c SlidersGroup class inherits from QGroupBox. It provides a + frame and a title, and contains a QSlider, a QScrollBar and a + QDial. + + We provide a \c valueChanged() signal and a public \c setValue() + slot with equivalent functionality to the ones in QAbstractSlider + and QSpinBox. In addition, we implement several other public + slots to set the minimum and maximum value, and invert the slider + widgets' appearance as well as key bindings. + + \section1 SlidersGroup Class Implementation + + \snippet examples/widgets/sliders/slidersgroup.cpp 0 + + First we create the slider-like widgets with the appropiate + properties. In particular we set the focus policy for each + widget. Qt::FocusPolicy is an enum type that defines the various + policies a widget can have with respect to acquiring keyboard + focus. The Qt::StrongFocus policy means that the widget accepts + focus by both tabbing and clicking. + + Then we connect the widgets with each other, so that they will + stay synchronized when the current value of one of them changes. + + \snippet examples/widgets/sliders/slidersgroup.cpp 1 + \snippet examples/widgets/sliders/slidersgroup.cpp 2 + + We connect \c {dial}'s \c valueChanged() signal to the + \c{SlidersGroup}'s \c valueChanged() signal, to notify the other + widgets in the application (i.e., the control widgets) of the + changed value. + + \snippet examples/widgets/sliders/slidersgroup.cpp 3 + \codeline + \snippet examples/widgets/sliders/slidersgroup.cpp 4 + + Finally, depending on the \l {Qt::Orientation}{orientation} given + at the time of construction, we choose and create the layout for + the slider widgets within the group box. + + \snippet examples/widgets/sliders/slidersgroup.cpp 5 + \snippet examples/widgets/sliders/slidersgroup.cpp 6 + + The \c setValue() slot sets the value of the QSlider. We don't + need to explicitly call + \l{QAbstractSlider::setValue()}{setValue()} on the QScrollBar and + QDial widgets, since QSlider will emit the + \l{QAbstractSlider::valueChanged()}{valueChanged()} signal when + its value changes, triggering a domino effect. + + \snippet examples/widgets/sliders/slidersgroup.cpp 7 + \snippet examples/widgets/sliders/slidersgroup.cpp 8 + \codeline + \snippet examples/widgets/sliders/slidersgroup.cpp 9 + \snippet examples/widgets/sliders/slidersgroup.cpp 10 + + The \c setMinimum() and \c setMaximum() slots are used by the \c + Window class to set the range of the QSlider, QScrollBar, and + QDial widgets. + + \snippet examples/widgets/sliders/slidersgroup.cpp 11 + \snippet examples/widgets/sliders/slidersgroup.cpp 12 + \codeline + \snippet examples/widgets/sliders/slidersgroup.cpp 13 + \snippet examples/widgets/sliders/slidersgroup.cpp 14 + + The \c invertAppearance() and \c invertKeyBindings() slots + control the child widgets' + \l{QAbstractSlider::invertedAppearance}{invertedAppearance} and + \l{QAbstractSlider::invertedControls}{invertedControls} + properties. +*/ diff --git a/doc/src/examples/spinboxdelegate.qdoc b/doc/src/examples/spinboxdelegate.qdoc new file mode 100644 index 0000000000..bb62dd277e --- /dev/null +++ b/doc/src/examples/spinboxdelegate.qdoc @@ -0,0 +1,137 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example itemviews/spinboxdelegate + \title Spin Box Delegate Example + + The Spin Box Delegate example shows how to create an editor for a custom delegate in + the model/view framework by reusing a standard Qt editor widget. + + The model/view framework provides a standard delegate that is used by default + with the standard view classes. For most purposes, the selection of editor + widgets available through this delegate is sufficient for editing text, boolean + values, and other simple data types. However, for specific data types, it is + sometimes necessary to use a custom delegate to either display the data in a + specific way, or allow the user to edit it with a custom control. + + \image spinboxdelegate-example.png + + This concepts behind this example are covered in the + \l{Model/View Programming#Delegate Classes}{Delegate Classes} chapter + of the \l{Model/View Programming} overview. + + \section1 SpinBoxDelegate Class Definition + + The definition of the delegate is as follows: + + \snippet examples/itemviews/spinboxdelegate/delegate.h 0 + + The delegate class declares only those functions that are needed to + create an editor widget, display it at the correct location in a view, + and communicate with a model. Custom delegates can also provide their + own painting code by reimplementing the \c paintEvent() function. + + \section1 SpinBoxDelegate Class Implementation + + Since the delegate is stateless, the constructor only needs to + call the base class's constructor with the parent QObject as its + argument: + + \snippet examples/itemviews/spinboxdelegate/delegate.cpp 0 + + Since the delegate is a subclass of QItemDelegate, the data it retrieves + from the model is displayed in a default style, and we do not need to + provide a custom \c paintEvent(). + + The \c createEditor() function returns an editor widget, in this case a + spin box that restricts values from the model to integers from 0 to 100 + inclusive. + + \snippet examples/itemviews/spinboxdelegate/delegate.cpp 1 + + We install an event filter on the spin box to ensure that it behaves in + a way that is consistent with other delegates. The implementation for + the event filter is provided by the base class. + + The \c setEditorData() function reads data from the model, converts it + to an integer value, and writes it to the editor widget. + + \snippet examples/itemviews/spinboxdelegate/delegate.cpp 2 + + Since the view treats delegates as ordinary QWidget instances, we have + to use a static cast before we can set the value in the spin box. + + The \c setModelData() function reads the contents of the spin box, and + writes it to the model. + + \snippet examples/itemviews/spinboxdelegate/delegate.cpp 3 + + We call \l{QSpinBox::interpretText()}{interpretText()} to make sure that + we obtain the most up-to-date value in the spin box. + + The \c updateEditorGeometry() function updates the editor widget's + geometry using the information supplied in the style option. This is the + minimum that the delegate must do in this case. + + \snippet examples/itemviews/spinboxdelegate/delegate.cpp 4 + + More complex editor widgets may divide the rectangle available in + \c{option.rect} between different child widgets if required. + + \section1 The Main Function + + This example is written in a slightly different way to many of the + other examples supplied with Qt. To demonstrate the use of a custom + editor widget in a standard view, it is necessary to set up a model + containing some arbitrary data and a view to display it. + + We set up the application in the normal way, construct a standard item + model to hold some data, set up a table view to use the data in the + model, and construct a custom delegate to use for editing: + + \snippet examples/itemviews/spinboxdelegate/main.cpp 0 + + The table view is informed about the delegate, and will use it to + display each of the items. Since the delegate is a subclass of + QItemDelegate, each cell in the table will be rendered using standard + painting operations. + + We insert some arbitrary data into the model for demonstration purposes: + + \snippet examples/itemviews/spinboxdelegate/main.cpp 1 + \snippet examples/itemviews/spinboxdelegate/main.cpp 2 + + Finally, the table view is displayed with a window title, and we start + the application's event loop: + + \snippet examples/itemviews/spinboxdelegate/main.cpp 3 + + Each of the cells in the table can now be edited in the usual way, but + the spin box ensures that the data returned to the model is always + constrained by the values allowed by the spin box delegate. +*/ diff --git a/doc/src/examples/spinboxes.qdoc b/doc/src/examples/spinboxes.qdoc new file mode 100644 index 0000000000..fde9e3759a --- /dev/null +++ b/doc/src/examples/spinboxes.qdoc @@ -0,0 +1,191 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example widgets/spinboxes + \title Spin Boxes Example + + The Spin Boxes example shows how to use the many different types of spin boxes + available in Qt, from a simple QSpinBox widget to more complex editors like + the QDateTimeEdit widget. + + \image spinboxes-example.png + + The example consists of a single \c Window class that is used to display the + different spin box-based widgets available with Qt. + + \section1 Window Class Definition + + The \c Window class inherits QWidget and contains two slots that are used + to provide interactive features: + + \snippet examples/widgets/spinboxes/window.h 0 + + The private functions are used to set up each type of spin box in the window. + We use member variables to keep track of various widgets so that they can + be reconfigured when required. + + \section1 Window Class Implementation + + The constructor simply calls private functions to set up the different types + of spin box used in the example, and places each group in a layout: + + \snippet examples/widgets/spinboxes/window.cpp 0 + + We use the layout to manage the arrangement of the window's child widgets, + and change the window title. + + The \c createSpinBoxes() function constructs a QGroupBox and places three + QSpinBox widgets inside it with descriptive labels to indicate the types of + input they expect. + + \snippet examples/widgets/spinboxes/window.cpp 1 + + The first spin box shows the simplest way to use QSpinBox. It accepts values + from -20 to 20, the current value can be increased or decreased by 1 with + either the arrow buttons or \key{Up} and \key{Down} keys, and the default + value is 0. + + The second spin box uses a larger step size and displays a suffix to + provide more information about the type of data the number represents: + + \snippet examples/widgets/spinboxes/window.cpp 2 + + This spin box also displays a + \l{QAbstractSpinBox::specialValueText}{special value} instead of the minimum + value defined for it. This means that it will never show \gui{0%}, but will + display \gui{Automatic} when the minimum value is selected. + + The third spin box shows how a prefix can be used: + + \snippet examples/widgets/spinboxes/window.cpp 4 + + For simplicity, we show a spin box with a prefix and no suffix. It is also + possible to use both at the same time. + + \snippet examples/widgets/spinboxes/window.cpp 5 + + The rest of the function sets up a layout for the group box and places each + of the widgets inside it. + + The \c createDateTimeEdits() function constructs another group box with a + selection of spin boxes used for editing dates and times. + + \snippet examples/widgets/spinboxes/window.cpp 6 + + The first spin box is a QDateEdit widget that is able to accept dates + within a given range specified using QDate values. The arrow buttons and + \key{Up} and \key{Down} keys can be used to increase and decrease the + values for year, month, and day when the cursor is in the relevant section. + + The second spin box is a QTimeEdit widget: + + \snippet examples/widgets/spinboxes/window.cpp 7 + + Acceptable values for the time are defined using QTime values. + + The third spin box is a QDateTimeEdit widget that can display both date and + time values, and we place a label above it to indicate the range of allowed + times for a meeting. These widgets will be updated when the user changes a + format string. + + \snippet examples/widgets/spinboxes/window.cpp 8 + + The format string used for the date time editor, which is also shown in the + string displayed by the label, is chosen from a set of strings in a combobox: + + \snippet examples/widgets/spinboxes/window.cpp 9 + \codeline + \snippet examples/widgets/spinboxes/window.cpp 10 + + A signal from this combobox is connected to a slot in the \c Window class + (shown later). + + \snippet examples/widgets/spinboxes/window.cpp 11 + + Each child widget of the group box in placed in a layout. + + The \c setFormatString() slot is called whenever the user selects a new + format string in the combobox. The display format for the QDateTimeEdit + widget is set using the raw string passed by the signal: + + \snippet examples/widgets/spinboxes/window.cpp 12 + + Depending on the visible sections in the widget, we set a new date or time + range, and update the associated label to provide relevant information for + the user: + + \snippet examples/widgets/spinboxes/window.cpp 13 + + When the format string is changed, there will be an appropriate label and + entry widget for dates, times, or both types of input. + + The \c createDoubleSpinBoxes() function constructs three spin boxes that are + used to input double-precision floating point numbers: + + \snippet examples/widgets/spinboxes/window.cpp 14 + + Before the QDoubleSpinBox widgets are constructed, we create a spin box to + control how many decimal places they show. By default, only two decimal places + are shown in the following spin boxes, each of which is the equivalent of a + spin box in the group created by the \c createSpinBoxes() function. + + The first double spin box shows a basic double-precision spin box with the + same range, step size, and default value as the first spin box in the + \c createSpinBoxes() function: + + \snippet examples/widgets/spinboxes/window.cpp 15 + + However, this spin box also allows non-integer values to be entered. + + The second spin box displays a suffix and shows a special value instead + of the minimum value: + + \snippet examples/widgets/spinboxes/window.cpp 16 + + The third spin box displays a prefix instead of a suffix: + + \snippet examples/widgets/spinboxes/window.cpp 17 + + We connect the QSpinBox widget that specifies the precision to a slot in + the \c Window class. + + \snippet examples/widgets/spinboxes/window.cpp 18 + + The rest of the function places each of the widgets into a layout for the + group box. + + The \c changePrecision() slot is called when the user changes the value in + the precision spin box: + + \snippet examples/widgets/spinboxes/window.cpp 19 + + This function simply uses the integer supplied by the signal to specify the + number of decimal places in each of the QDoubleSpinBox widgets. Each one + of these will be updated automatically when their + \l{QDoubleSpinBox::decimals}{decimals} property is changed. +*/ diff --git a/doc/src/examples/sqlwidgetmapper.qdoc b/doc/src/examples/sqlwidgetmapper.qdoc new file mode 100644 index 0000000000..af978c5ac8 --- /dev/null +++ b/doc/src/examples/sqlwidgetmapper.qdoc @@ -0,0 +1,185 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example sql/sqlwidgetmapper + \title SQL Widget Mapper Example + + The SQL Widget Mapper example shows how to use a map information from a + database to widgets on a form. + + \image sql-widget-mapper.png + + In the \l{Combo Widget Mapper Example}, we showed how to use a named + mapping between a widget mapper and a QComboBox widget with a special + purpose model to relate values in the model to a list of choices. + + Again, we create a \c Window class with an almost identical user interface, + providing a combo box to allow their addresses to be classified as "Home", + "Work" or "Other". However, instead of using a separate model to hold these + address types, we use one database table to hold the example data and + another to hold the address types. In this way, we store all the + information in the same place. + + \section1 Window Class Definition + + The class provides a constructor, a slot to keep the buttons up to date, + and a private function to set up the model: + + \snippet examples/sql/sqlwidgetmapper/window.h Window definition + + In addition to the QDataWidgetMapper object and the controls used to make + up the user interface, we use a QStandardItemModel to hold our data and + a QStringListModel to hold information about the types of address that + can be applied to each person's data. + + \section1 Window Class Implementation + + The first act performed by the \c Window class constructor is to set up + the model used to hold the example data. Since this is a key part of the + example, we will look at this first. + + The model is initialized in the window's \c{setupModel()} function. Here, + we create a SQLite database containing a "person" table with primary key, + name, address and type fields. + + \snippet examples/sql/sqlwidgetmapper/window.cpp Set up the main table + + On each row of the table, we insert default values for these fields, + including values for the address types that correspond to the address + types are stored in a separate table. + + \image widgetmapper-sql-mapping-table.png + + We create an "addresstype" table containing the identifiers used in the + "person" table and the corresponding strings: + + \snippet examples/sql/sqlwidgetmapper/window.cpp Set up the address type table + + The "typeid" field in the "person" table is related to the contents of + the "addresstype" table via a relation in a QSqlRelationalTableModel. + This kind of model performs all the necessary work to store the data in + a database and also allows any relations to be used as models in their + own right. + + In this case, we have defined a relation for the "typeid" field in the + "person" table that relates it to the "id" field in the "addresstype" + table and which causes the contents of the "description" field to be + used wherever the "typeid" is presented to the user. (See the + QSqlRelationalTableModel::setRelation() documentation for details.) + + \image widgetmapper-sql-mapping.png + + The constructor of the \c Window class can be explained in three parts. + In the first part, we set up the model used to hold the data, then we set + up the widgets used for the user interface: + + \snippet examples/sql/sqlwidgetmapper/window.cpp Set up widgets + + We obtain a model for the combo box from the main model, based on the + relation we set up for the "typeid" field. The call to the combo box's + \l{QComboBox::}{setModelColumn()} selects the field in the field in the + model to display. + + Note that this approach is similar to the one used in the + \l{Combo Widget Mapper Example} in that we set up a model for the + combo box. However, in this case, we obtain a model based on a relation + in the QSqlRelationalTableModel rather than create a separate one. + + Next, we set up the widget mapper, relating each input widget to a field + in the model: + + \snippet examples/sql/sqlwidgetmapper/window.cpp Set up the mapper + + For the combo box, we already know the index of the field in the model + from the \c{setupModel()} function. We use a QSqlRelationalDelegate as + a proxy between the mapper and the input widgets to match up the "typeid" + values in the model with those in the combo box's model and populate the + combo box with descriptions rather than integer values. + + As a result, the user is able to select an item from the combo box, + and the associated value is written back to the model. + + The rest of the constructor is very similar to that of the + \l{Simple Widget Mapper Example}: + + \snippet examples/sql/sqlwidgetmapper/window.cpp Set up connections and layouts + + We show the implementation of the \c{updateButtons()} slot for + completeness: + + \snippet examples/sql/sqlwidgetmapper/window.cpp Slot for updating the buttons + + \omit + \section1 Delegate Class Definition and Implementation + + The delegate we use to mediate interaction between the widget mapper and + the input widgets is a small QItemDelegate subclass: + + \snippet examples/sql/sqlwidgetmapper/delegate.h Delegate class definition + + This provides implementations of the two standard functions used to pass + data between editor widgets and the model (see the \l{Delegate Classes} + documentation for a more general description of these functions). + + Since we only provide an empty implementation of the constructor, we + concentrate on the other two functions. + + The \l{QItemDelegate::}{setEditorData()} implementation takes the data + referred to by the model index supplied and processes it according to + the presence of a \c currentIndex property in the editor widget: + + \snippet examples/sql/sqlwidgetmapper/delegate.cpp setEditorData implementation + + If, like QComboBox, the editor widget has this property, it is set using + the value from the model. Since we are passing around QVariant values, + the strings stored in the model are automatically converted to the integer + values needed for the \c currentIndex property. + + As a result, instead of showing "0", "1" or "2" in the combo box, one of + its predefined set of items is shown. We call QItemDelegate::setEditorData() + for widgets without the \c currentIndex property. + + The \l{QItemDelegate::}{setModelData()} implementation performs the reverse + process, taking the value stored in the widget's \c currentIndex property + and storing it back in the model: + + \snippet examples/sql/sqlwidgetmapper/delegate.cpp setModelData implementation + \endomit + + \section1 Summary and Further Reading + + The use of a separate model for the combo box and a special delegate for the + widget mapper allows us to present a menu of choices to the user. Although + the choices are stored in the same database as the user's data, they are held + in a separate table. Using this approach, we can reconstructed complete records + at a later time while using database features appropriately. + + If SQL models are not being used, it is still possible to use more than + one model to present choices to the user. This is covered by the + \l{Combo Widget Mapper Example}. +*/ diff --git a/doc/src/examples/standarddialogs.qdoc b/doc/src/examples/standarddialogs.qdoc new file mode 100644 index 0000000000..540e4c5c04 --- /dev/null +++ b/doc/src/examples/standarddialogs.qdoc @@ -0,0 +1,35 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example dialogs/standarddialogs + \title Standard Dialogs Example + + The Standard Dialogs example shows the standard dialogs that are provided by Qt. + + \image standarddialogs-example.png +*/ diff --git a/doc/src/examples/stardelegate.qdoc b/doc/src/examples/stardelegate.qdoc new file mode 100644 index 0000000000..3514a6f22d --- /dev/null +++ b/doc/src/examples/stardelegate.qdoc @@ -0,0 +1,296 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example itemviews/stardelegate + \title Star Delegate Example + + The Star Delegate example shows how to create a delegate that + can paint itself and that supports editing. + + \image stardelegate.png The Star Delegate Example + + When displaying data in a QListView, QTableView, or QTreeView, + the individual items are drawn by a + \l{Delegate Classes}{delegate}. Also, when the user starts + editing an item (e.g., by double-clicking the item), the delegate + provides an editor widget that is placed on top of the item while + editing takes place. + + Delegates are subclasses of QAbstractItemDelegate. Qt provides + QItemDelegate, which inherits QAbstractItemDelegate and handles + the most common data types (notably \c int and QString). If we + need to support custom data types, or want to customize the + rendering or the editing for existing data types, we can subclass + QAbstractItemDelegate or QItemDelegate. See \l{Delegate Classes} + for more information about delegates, and \l{Model/View + Programming} if you need a high-level introduction to Qt's + model/view architecture (including delegates). + + In this example, we will see how to implement a custom delegate + to render and edit a "star rating" data type, which can store + values such as "1 out of 5 stars". + + The example consists of the following classes: + + \list + \o \c StarRating is the custom data type. It stores a rating + expressed as stars, such as "2 out of 5 stars" or "5 out of + 6 stars". + + \o \c StarDelegate inherits QItemDelegate and provides support + for \c StarRating (in addition to the data types already + handled by QItemDelegate). + + \o \c StarEditor inherits QWidget and is used by \c StarDelegate + to let the user edit a star rating using the mouse. + \endlist + + To show the \c StarDelegate in action, we will fill a + QTableWidget with some data and install the delegate on it. + + \section1 StarDelegate Class Definition + + Here's the definition of the \c StarDelegate class: + + \snippet examples/itemviews/stardelegate/stardelegate.h 0 + + All public functions are reimplemented virtual functions from + QItemDelegate to provide custom rendering and editing. + + \section1 StarDelegate Class Implementation + + The \l{QAbstractItemDelegate::}{paint()} function is + reimplemented from QItemDelegate and is called whenever the view + needs to repaint an item: + + \snippet examples/itemviews/stardelegate/stardelegate.cpp 0 + + The function is invoked once for each item, represented by a + QModelIndex object from the model. If the data stored in the item + is a \c StarRating, we paint it ourselves; otherwise, we let + QItemDelegate paint it for us. This ensures that the \c + StarDelegate can handle the most common data types. + + In the case where the item is a \c StarRating, we draw the + background if the item is selected, and we draw the item using \c + StarRating::paint(), which we will review later. + + \c{StartRating}s can be stored in a QVariant thanks to the + Q_DECLARE_METATYPE() macro appearing in \c starrating.h. More on + this later. + + The \l{QAbstractItemDelegate::}{createEditor()} function is + called when the user starts editing an item: + + \snippet examples/itemviews/stardelegate/stardelegate.cpp 2 + + If the item is a \c StarRating, we create a \c StarEditor and + connect its \c editingFinished() signal to our \c + commitAndCloseEditor() slot, so we can update the model when the + editor closes. + + Here's the implementation of \c commitAndCloseEditor(): + + \snippet examples/itemviews/stardelegate/stardelegate.cpp 5 + + When the user is done editing, we emit + \l{QAbstractItemDelegate::}{commitData()} and + \l{QAbstractItemDelegate::}{closeEditor()} (both declared in + QAbstractItemDelegate), to tell the model that there is edited + data and to inform the view that the editor is no longer needed. + + The \l{QAbstractItemDelegate::}{setEditorData()} function is + called when an editor is created to initialize it with data + from the model: + + \snippet examples/itemviews/stardelegate/stardelegate.cpp 3 + + We simply call \c setStarRating() on the editor. + + The \l{QAbstractItemDelegate::}{setModelData()} function is + called when editing is finished, to commit data from the editor + to the model: + + \snippet examples/itemviews/stardelegate/stardelegate.cpp 4 + + The \c sizeHint() function returns an item's preferred size: + + \snippet examples/itemviews/stardelegate/stardelegate.cpp 1 + + We simply forward the call to \c StarRating. + + \section1 StarEditor Class Definition + + The \c StarEditor class was used when implementing \c + StarDelegate. Here's the class definition: + + \snippet examples/itemviews/stardelegate/stareditor.h 0 + + The class lets the user edit a \c StarRating by moving the mouse + over the editor. It emits the \c editingFinished() signal when + the user clicks on the editor. + + The protected functions are reimplemented from QWidget to handle + mouse and paint events. The private function \c starAtPosition() + is a helper function that returns the number of the star under + the mouse pointer. + + \section1 StarEditor Class Implementation + + Let's start with the constructor: + + \snippet examples/itemviews/stardelegate/stareditor.cpp 0 + + We enable \l{QWidget::setMouseTracking()}{mouse tracking} on the + widget so we can follow the cursor even when the user doesn't + hold down any mouse button. We also turn on QWidget's + \l{QWidget::autoFillBackground}{auto-fill background} feature to + obtain an opaque background. (Without the call, the view's + background would shine through the editor.) + + The \l{QWidget::}{paintEvent()} function is reimplemented from + QWidget: + + \snippet examples/itemviews/stardelegate/stareditor.cpp 1 + + We simply call \c StarRating::paint() to draw the stars, just + like we did when implementing \c StarDelegate. + + \snippet examples/itemviews/stardelegate/stareditor.cpp 2 + + In the mouse event handler, we call \c setStarCount() on the + private data member \c myStarRating to reflect the current cursor + position, and we call QWidget::update() to force a repaint. + + \snippet examples/itemviews/stardelegate/stareditor.cpp 3 + + When the user releases a mouse button, we simply emit the \c + editingFinished() signal. + + \snippet examples/itemviews/stardelegate/stareditor.cpp 4 + + The \c starAtPosition() function uses basic linear algebra to + find out which star is under the cursor. + + \section1 StarRating Class Definition + + \snippet examples/itemviews/stardelegate/starrating.h 0 + \codeline + \snippet examples/itemviews/stardelegate/starrating.h 1 + + The \c StarRating class represents a rating as a number of stars. + In addition to holding the data, it is also capable of painting + the stars on a QPaintDevice, which in this example is either a + view or an editor. The \c myStarCount member variable stores the + current rating, and \c myMaxStarCount stores the highest possible + rating (typically 5). + + The Q_DECLARE_METATYPE() macro makes the type \c StarRating known + to QVariant, making it possible to store \c StarRating values in + QVariant. + + \section1 StarRating Class Implementation + + The constructor initializes \c myStarCount and \c myMaxStarCount, + and sets up the polygons used to draw stars and diamonds: + + \snippet examples/itemviews/stardelegate/starrating.cpp 0 + + The \c paint() function paints the stars in this \c StarRating + object on a paint device: + + \snippet examples/itemviews/stardelegate/starrating.cpp 2 + + We first set the pen and brush we will use for painting. The \c + mode parameter can be either \c Editable or \c ReadOnly. If \c + mode is editable, we use the \l{QPalette::}{Highlight} color + instead of the \l{QPalette::}{Foreground} color to draw the + stars. + + Then we draw the stars. If we are in \c Edit mode, we paint + diamonds in place of stars if the rating is less than the highest + rating. + + The \c sizeHint() function returns the preferred size for an area + to paint the stars on: + + \snippet examples/itemviews/stardelegate/starrating.cpp 1 + + The preferred size is just enough to paint the maximum number of + stars. The function is called by both \c StarDelegate::sizeHint() + and \c StarEditor::sizeHint(). + + \section1 The \c main() Function + + Here's the program's \c main() function: + + \snippet examples/itemviews/stardelegate/main.cpp 5 + + The \c main() function creates a QTableWidget and sets a \c + StarDelegate on it. \l{QAbstractItemView::}{DoubleClicked} and + \l{QAbstractItemView::}{SelectedClicked} are set as + \l{QAbstractItemView::editTriggers()}{edit triggers}, so that the + editor is opened with a single click when the star rating item is + selected. + + The \c populateTableWidget() function fills the QTableWidget with + data: + + \snippet examples/itemviews/stardelegate/main.cpp 0 + \snippet examples/itemviews/stardelegate/main.cpp 1 + \dots + \snippet examples/itemviews/stardelegate/main.cpp 2 + \snippet examples/itemviews/stardelegate/main.cpp 3 + \codeline + \snippet examples/itemviews/stardelegate/main.cpp 4 + + Notice the call to qVariantFromValue to convert a \c + StarRating to a QVariant. + + \section1 Possible Extensions and Suggestions + + There are many ways to customize Qt's \l{Model/View + Programming}{model/view framework}. The approach used in this + example is appropriate for most custom delegates and editors. + Examples of possibilities not used by the star delegate and star + editor are: + + \list + \o It is possible to open editors programmatically by calling + QAbstractItemView::edit(), instead of relying on edit + triggers. This could be use to support other edit triggers + than those offered by the QAbstractItemView::EditTrigger enum. + For example, in the Star Delegate example, hovering over an + item with the mouse might make sense as a way to pop up an + editor. + + \o By reimplementing QAbstractItemDelegate::editorEvent(), it is + possible to implement the editor directly in the delegate, + instead of creating a separate QWidget subclass. + \endlist +*/ diff --git a/doc/src/examples/states.qdoc b/doc/src/examples/states.qdoc new file mode 100644 index 0000000000..d83f2319ee --- /dev/null +++ b/doc/src/examples/states.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example animation/states + \title States Example + + The States example shows how to use the Qt state machine to play + animations. + + \image states-example.png +*/ diff --git a/doc/src/examples/stickman.qdoc b/doc/src/examples/stickman.qdoc new file mode 100644 index 0000000000..a2c1255485 --- /dev/null +++ b/doc/src/examples/stickman.qdoc @@ -0,0 +1,102 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example animation/stickman + \title Stickman Example + + The Stickman example shows how to animate transitions in a state machine to implement key frame + animations. + + \image stickman-example.png + + In this example, we will write a small application which animates the joints in a skeleton and + projects a stickman figure on top. The stickman can be either "alive" or "dead", and when in the + "alive" state, he can be performing different actions defined by key frame animations. + + Animations are implemented as composite states. Each child state of the animation state + represents a frame in the animation by setting the position of each joint in the stickman's + skeleton to the positions defined for the particular frame. The frames are then bound together + with animated transitions that trigger on the source state's propertiesAssigned() signal. Thus, + the machine will enter the state representing the next frame in the animation immediately after + it has finished animating into the previous frame. + + \image stickman-example1.png + + The states for an animation is constructed by reading a custom animation file format and + creating states that assign values to the the "position" properties of each of the nodes in the + skeleton graph. + + \snippet examples/animation/stickman/lifecycle.cpp 1 + + The states are then bound together with signal transitions that listen to the + propertiesAssigned() signal. + + \snippet examples/animation/stickman/lifecycle.cpp 2 + + The last frame state is given a transition to the first one, so that the animation will loop + until it is interrupted when a transition out from the animation state is taken. To get smooth + animations between the different key frames, we set a default animation on the state machine. + This is a parallel animation group which contains animations for all the "position" properties + and will be selected by default when taking any transition that leads into a state that assigns + values to these properties. + + \snippet examples/animation/stickman/lifecycle.cpp 3 + + Several such animation states are constructed, and are placed together as children of a top + level "alive" state which represents the stickman life cycle. Transitions go from the parent + state to the child state to ensure that each of the child states inherit them. + + \image stickman-example2.png + + This saves us the effort of connect every state to every state with identical transitions. The + state machine makes sure that transitions between the key frame animations are also smooth by + applying the default animation when interrupting one and starting another. + + Finally, there is a transition out from the "alive" state and into the "dead" state. This is + a custom transition type called LightningSrikesTransition which samples every second and + triggers at random (one out of fifty times on average.) + + \snippet examples/animation/stickman/lifecycle.cpp 4 + + When it triggers, the machine will first enter a "lightningBlink" state which uses a timer to + pause for a brief period of time while the background color of the scene is white. This gives us + a flash effect when the lightning strikes. + + \snippet examples/animation/stickman/lifecycle.cpp 5 + + We start and stop a QTimer object when entering and exiting the state. Then we transition into + the "dead" state when the timer times out. + + \snippet examples/animation/stickman/lifecycle.cpp 0 + + When the machine is in the "dead" state, it will be unresponsive. This is because the "dead" + state has no transitions leading out. + + \image stickman-example3.png + +*/ diff --git a/doc/src/examples/styleplugin.qdoc b/doc/src/examples/styleplugin.qdoc new file mode 100644 index 0000000000..b676b96fe0 --- /dev/null +++ b/doc/src/examples/styleplugin.qdoc @@ -0,0 +1,133 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example tools/styleplugin + \title Style Plugin Example + + This example shows how to create a plugin that extends Qt with a new + GUI look and feel. + + \image stylepluginexample.png + + On some platforms, the native style will prevent the button + from having a red background. In this case, try to run the example + in another style (e.g., plastique). + + A plugin in Qt is a class stored in a shared library that can be + loaded by a QPluginLoader at run-time. When you create plugins in + Qt, they either extend a Qt application or Qt itself. Writing a + plugin that extends Qt itself is achieved by inheriting one of the + plugin \l{Plugin Classes}{base classes}, reimplementing functions + from that class, and adding a macro. In this example we extend Qt + by adding a new GUI look and feel (i.e., making a new QStyle + available). A high-level introduction to plugins is given in the + plugin \l{How to Create Qt Plugins}{overview document}. + + Plugins that provide new styles inherit the QStylePlugin base + class. Style plugins are loaded by Qt and made available through + QStyleFactory; we will look at this later. We have implemented \c + SimpleStylePlugin, which provides \c SimpleStyle. The new style + inherits QWindowsStyle and contributes to widget styling by + drawing button backgrounds in red - not a major contribution, but + it still makes a new style. We test the plugin with \c + StyleWindow, in which we display a QPushButton. + + The \c SimpleStyle and \c StyleWindow classes do not contain any + plugin specific functionality and their implementations are + trivial; we will therefore leap past them and head on to the \c + SimpleStylePlugin and the \c main() function. After we have looked + at that, we examine the plugin's profile. + + + \section1 SimpleStylePlugin Class Definition + + \c SimpleStylePlugin inherits QStylePlugin and is the plugin + class. + + \snippet examples/tools/styleplugin/plugin/simplestyleplugin.h 0 + + \c keys() returns a list of style names that this plugin can + create, while \c create() takes such a string and returns the + QStyle corresponding to the key. Both functions are pure virtual + functions reimplemented from QStylePlugin. When an application + requests an instance of the \c SimpleStyle style, which this + plugin creates, Qt will create it with this plugin. + + + \section1 SimpleStylePlugin Class Implementation + + Here is the implementation of \c keys(): + + \snippet examples/tools/styleplugin/plugin/simplestyleplugin.cpp 0 + + Since this plugin only supports one style, we return a QStringList + with the class name of that style. + + Here is the \c create() function: + + \snippet examples/tools/styleplugin/plugin/simplestyleplugin.cpp 1 + + Note that the key for style plugins are case insensitive. + The case sensitivity varies from plugin to plugin, so you need to + check this when implementing new plugins. + + \section1 The \c main() function + + \snippet examples/tools/styleplugin/stylewindow/main.cpp 0 + + Qt loads the available style plugins when the QApplication object + is initialized. The QStyleFactory class knows about all styles and + produces them with \l{QStyleFactory::}{create()} (it is a + wrapper around all the style plugins). + + \section1 The Simple Style Plugin Profile + + The \c SimpleStylePlugin lives in its own directory and have + its own profile: + + \snippet examples/tools/styleplugin/plugin/plugin.pro 0 + + In the plugin profile we need to set the lib template as we are + building a shared library instead of an executable. We must also + set the config to plugin. We set the library to be stored in the + styles folder under stylewindow because this is a path in which Qt + will search for style plugins. + + \section1 Related articles and examples + + In addition to the plugin \l{How to Create Qt Plugins}{overview + document}, we have other examples and articles that concern + plugins. + + In the \l{Echo Plugin Example}{echo plugin example} we show how to + implement plugins that extends Qt applications rather than Qt + itself, which is the case with the style plugin of this example. + The \l{Plug & Paint Example}{plug & paint} example shows how to + implement a static plugin as well as being a more involved example + on plugins that extend applications. +*/ diff --git a/doc/src/examples/styles.qdoc b/doc/src/examples/styles.qdoc new file mode 100644 index 0000000000..93c3df78ae --- /dev/null +++ b/doc/src/examples/styles.qdoc @@ -0,0 +1,472 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example widgets/styles + \title Styles Example + + The Styles example illustrates how to create custom widget + drawing styles using Qt, and demonstrates Qt's predefined styles. + + \image styles-enabledwood.png Screenshot of the Styles example + + A style in Qt is a subclass of QStyle or of one of its + subclasses. Styles perform drawing on behalf of widgets. Qt + provides a whole range of predefined styles, either built into + the \l QtGui library or found in plugins. Custom styles are + usually created by subclassing one of Qt's existing style and + reimplementing a few virtual functions. + + In this example, the custom style is called \c NorwegianWoodStyle + and derives from QMotifStyle. Its main features are the wooden + textures used for filling most of the widgets and its round + buttons and comboboxes. + + To implement the style, we use some advanced features provided by + QPainter, such as \l{QPainter::Antialiasing}{antialiasing} (to + obtain smoother button edges), \l{QColor::alpha()}{alpha blending} + (to make the buttons appeared raised or sunken), and + \l{QPainterPath}{painter paths} (to fill the buttons and draw the + outline). We also use many features of QBrush and QPalette. + + The example consists of the following classes: + + \list + \o \c NorwegianWoodStyle inherits from QMotifStyle and implements + the Norwegian Wood style. + \o \c WidgetGallery is a \c QDialog subclass that shows the most + common widgets and allows the user to switch style + dynamically. + \endlist + + \section1 NorwegianWoodStyle Class Definition + + Here's the definition of the \c NorwegianWoodStyle class: + + \snippet examples/widgets/styles/norwegianwoodstyle.h 0 + + The public functions are all declared in QStyle (QMotifStyle's + grandparent class) and reimplemented here to override the Motif + look and feel. The private functions are helper functions. + + \section1 NorwegianWoodStyle Class Implementation + + We will now review the implementation of the \c + NorwegianWoodStyle class. + + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 0 + + The \c polish() function is reimplemented from QStyle. It takes a + QPalette as a reference and adapts the palette to fit the style. + Most styles don't need to reimplement that function. The + Norwegian Wood style reimplements it to set a "wooden" palette. + + We start by defining a few \l{QColor}s that we'll need. Then we + load two PNG images. The \c : prefix in the file path indicates + that the PNG files are \l{The Qt Resource System}{embedded + resources}. + + \table + \row \o \inlineimage widgets/styles/images/woodbackground.png + + \o \bold{woodbackground.png} + + This texture is used as the background of most widgets. + The wood pattern is horizontal. + + \row \o \inlineimage widgets/styles/images/woodbutton.png + + \o \bold{woodbutton.png} + + This texture is used for filling push buttons and + comboboxes. The wood pattern is vertical and more reddish + than the texture used for the background. + \endtable + + The \c midImage variable is initialized to be the same as \c + buttonImage, but then we use a QPainter and fill it with a 25% + opaque black color (a black with an \l{QColor::alpha()}{alpha + channel} of 63). The result is a somewhat darker image than \c + buttonImage. This image will be used for filling buttons that the + user is holding down. + + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 1 + + We initialize the palette. Palettes have various + \l{QPalette::ColorRole}{color roles}, such as QPalette::Base + (used for filling text editors, item views, etc.), QPalette::Text + (used for foreground text), and QPalette::Background (used for + the background of most widgets). Each role has its own QBrush, + which usually is a plain color but can also be a brush pattern or + even a texture (a QPixmap). + + In addition to the roles, palettes have several + \l{QPalette::ColorGroup}{color groups}: active, disabled, and + inactive. The active color group is used for painting widgets in + the active window. The disabled group is used for disabled + widgets. The inactive group is used for all other widgets. Most + palettes have identical active and inactive groups, while the + disabled group uses darker shades. + + We initialize the QPalette object with a brown color. Qt + automatically derivates all color roles for all color groups from + that single color. We then override some of the default values. For + example, we use Qt::darkGreen instead of the default + (Qt::darkBlue) for the QPalette::Highlight role. The + QPalette::setBrush() overload that we use here sets the same + color or brush for all three color groups. + + The \c setTexture() function is a private function that sets the + texture for a certain color role, while preserving the existing + color in the QBrush. A QBrush can hold both a solid color and a + texture at the same time. The solid color is used for drawing + text and other graphical elements where textures don't look good. + + At the end, we set the brush for the disabled color group of the + palette. We use \c woodbackground.png as the texture for all + disabled widgets, including buttons, and use a darker color to + accompany the texture. + + \image styles-disabledwood.png The Norwegian Wood style with disabled widgets + + Let's move on to the other functions reimplemented from + QMotifStyle: + + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 3 + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 4 + + This QStyle::polish() overload is called once on every widget + drawn using the style. We reimplement it to set the Qt::WA_Hover + attribute on \l{QPushButton}s and \l{QComboBox}es. When this + attribute is set, Qt generates paint events when the mouse + pointer enters or leaves the widget. This makes it possible to + render push buttons and comboboxes differently when the mouse + pointer is over them. + + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 5 + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 6 + + This QStyle::unpolish() overload is called to undo any + modification done to the widget in \c polish(). For simplicity, + we assume that the flag wasn't set before \c polish() was called. + In an ideal world, we would remember the original state for each + widgets (e.g., using a QMap<QWidget *, bool>) and restore it in + \c unpolish(). + + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 7 + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 8 + + The \l{QStyle::pixelMetric()}{pixelMetric()} function returns the + size in pixels for a certain user interface element. By + reimplementing this function, we can affect the way certain + widgets are drawn and their size hint. Here, we return 8 as the + width around a shown in a QComboBox, ensuring that there is + enough place around the text and the arrow for the Norwegian Wood + round corners. The default value for this setting in the Motif + style is 2. + + We also change the extent of \l{QScrollBar}s, i.e., the height + for a horizontal scroll bar and the width for a vertical scroll + bar, to be 4 pixels more than in the Motif style. This makes the + style a bit more distinctive. + + For all other QStyle::PixelMetric elements, we use the Motif + settings. + + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 9 + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 10 + + The \l{QStyle::styleHint()}{styleHint()} function returns some + hints to widgets or to the base style (in our case QMotifStyle) + about how to draw the widgets. The Motif style returns \c true + for the QStyle::SH_DitherDisabledText hint, resulting in a most + unpleasing visual effect. We override this behavior and return \c + false instead. We also return \c true for the + QStyle::SH_EtchDisabledText hint, meaning that disabled text is + rendered with an embossed look (as QWindowsStyle does). + + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 11 + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 12 + + The \l{QStyle::drawPrimitive()}{drawPrimitive()} function is + called by Qt widgets to draw various fundamental graphical + elements. Here we reimplement it to draw QPushButton and + QComboBox with round corners. The button part of these widgets is + drawn using the QStyle::PE_PanelButtonCommand primitive element. + + The \c option parameter, of type QStyleOption, contains + everything we need to know about the widget we want to draw on. + In particular, \c option->rect gives the rectangle within which + to draw the primitive element. The \c painter parameter is a + QPainter object that we can use to draw on the widget. + + The \c widget parameter is the widget itself. Normally, all the + information we need is available in \c option and \c painter, so + we don't need \c widget. We can use it to perform special + effects; for example, QMacStyle uses it to animate default + buttons. If you use it, be aware that the caller is allowed to + pass a null pointer. + + We start by defining three \l{QColor}s that we'll need later on. + We also put the x, y, width, and height components of the + widget's rectangle in local variables. The value used for the \c + semiTransparentWhite and for the \c semiTransparentBlack color's + alpha channel depends on whether the mouse cursor is over the + widget or not. Since we set the Qt::WA_Hover attribute on + \l{QPushButton}s and \l{QComboBox}es, we can rely on the + QStyle::State_MouseOver flag to be set when the mouse is over the + widget. + + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 13 + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 14 + + The \c roundRect variable is a QPainterPath. A QPainterPath is is + a vectorial specification of a shape. Any shape (rectangle, + ellipse, spline, etc.) or combination of shapes can be expressed + as a path. We will use \c roundRect both for filling the button + background with a wooden texture and for drawing the outline. The + \c roundRectPath() function is a private function; we will come + back to it later. + + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 15 + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 16 + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 17 + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 18 + + We define two variables, \c brush and \c darker, and initialize + them based on the state of the button: + + \list + \o If the button is a \l{QPushButton::flat}{flat button}, we use + the \l{QPalette::Background}{Background} brush. We set \c + darker to \c true if the button is + \l{QAbstractButton::down}{down} or + \l{QAbstractButton::checked}{checked}. + \o If the button is currently held down by the user or in the + \l{QAbstractButton::checked}{checked} state, we use the + \l{QPalette::Mid}{Mid} component of the palette. We set + \c darker to \c true if the button is + \l{QAbstractButton::checked}{checked}. + \o Otherwise, we use the \l{QPalette::Button}{Button} component + of the palette. + \endlist + + The screenshot below illustrates how \l{QPushButton}s are + rendered based on their state: + + \image styles-woodbuttons.png Norwegian Wood buttons in different states + + To discover whether the button is flat or not, we need to cast + the \c option parameter to QStyleOptionButton and check if the + \l{QStyleOptionButton::features}{features} member specifies the + QStyleOptionButton::Flat flag. The qstyleoption_cast() function + performs a dynamic cast; if \c option is not a + QStyleOptionButton, qstyleoption_cast() returns a null pointer. + + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 19 + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 20 + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 21 + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 22 + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 23 + + We turn on antialiasing on QPainter. Antialiasing is a technique + that reduces the visual distortion that occurs when the edges of + a shape are converted into pixels. For the Norwegian Wood style, + we use it to obtain smoother edges for the round buttons. + + \image styles-aliasing.png Norwegian wood buttons with and without antialiasing + + The first call to QPainter::fillPath() draws the background of + the button with a wooden texture. The second call to + \l{QPainter::fillPath()}{fillPath()} paints the same area with a + semi-transparent black color (a black color with an alpha channel + of 63) to make the area darker if \c darker is true. + + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 24 + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 25 + + Next, we draw the outline. The top-left half of the outline and + the bottom-right half of the outline are drawn using different + \l{QPen}s to produce a 3D effect. Normally, the top-left half of + the outline is drawn lighter whereas the bottom-right half is + drawn darker, but if the button is + \l{QAbstractButton::down}{down} or + \l{QAbstractButton::checked}{checked}, we invert the two + \l{QPen}s to give a sunken look to the button. + + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 26 + + We draw the top-left part of the outline by calling + QPainter::drawPath() with an appropriate + \l{QPainter::setClipRegion()}{clip region}. If the + \l{QStyleOption::direction}{layout direction} is right-to-left + instead of left-to-right, we swap the \c x1, \c x2, \c x3, and \c + x4 variables to obtain correct results. On right-to-left desktop, + the "light" comes from the top-right corner of the screen instead + of the top-left corner; raised and sunken widgets must be drawn + accordingly. + + The diagram below illustrates how 3D effects are drawn according + to the layout direction. The area in red on the diagram + corresponds to the \c topHalf polygon: + + \image styles-3d.png + + An easy way to test how a style looks in right-to-left mode is to + pass the \c -reverse command-line option to the application. This + option is recognized by the QApplication constructor. + + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 32 + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 33 + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 34 + + The bottom-right part of the outline is drawn in a similar + fashion. Then we draw a one-pixel wide outline around the entire + button, using the \l{QPalette::Foreground}{Foreground} component + of the QPalette. + + This completes the QStyle::PE_PanelButtonCommand case of the \c + switch statement. Other primitive elements are handled by the + base style. Let's now turn to the other \c NorwegianWoodStyle + member functions: + + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 35 + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 36 + + We reimplement QStyle::drawControl() to draw the text on a + QPushButton in a bright color when the button is + \l{QAbstractButton::down}{down} or + \l{QAbstractButton::checked}{checked}. + + If the \c option parameter points to a QStyleOptionButton object + (it normally should), we take a copy of the object and modify its + \l{QStyleOption::palette}{palette} member to make the + QPalette::ButtonText be the same as the QPalette::BrightText + component (unless the widget is disabled). + + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 37 + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 38 + + The \c setTexture() function is a private function that sets the + \l{QBrush::texture()}{texture} component of the \l{QBrush}es for + a certain \l{QPalette::ColorRole}{color role}, for all three + \l{QPalette::ColorGroup}{color groups} (active, disabled, + inactive). We used it to initialize the Norwegian Wood palette in + \c polish(QPalette &). + + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 39 + \snippet examples/widgets/styles/norwegianwoodstyle.cpp 40 + + The \c roundRectPath() function is a private function that + constructs a QPainterPath object for round buttons. The path + consists of eight segments: four arc segments for the corners and + four lines for the sides. + + With around 250 lines of code, we have a fully functional custom + style based on one of the predefined styles. Custom styles can be + used to provide a distinct look to an application or family of + applications. + + \section1 WidgetGallery Class + + For completeness, we will quickly review the \c WidgetGallery + class, which contains the most common Qt widgets and allows the + user to change style dynamically. Here's the class definition: + + \snippet examples/widgets/styles/widgetgallery.h 0 + \dots + \snippet examples/widgets/styles/widgetgallery.h 1 + + Here's the \c WidgetGallery constructor: + + \snippet examples/widgets/styles/widgetgallery.cpp 0 + + We start by creating child widgets. The \gui Style combobox is + initialized with all the styles known to QStyleFactory, in + addition to \c NorwegianWood. The \c create...() functions are + private functions that set up the various parts of the \c + WidgetGallery. + + \snippet examples/widgets/styles/widgetgallery.cpp 1 + \snippet examples/widgets/styles/widgetgallery.cpp 2 + + We connect the \gui Style combobox to the \c changeStyle() + private slot, the \gui{Use style's standard palette} check box to + the \c changePalette() slot, and the \gui{Disable widgets} check + box to the child widgets' + \l{QWidget::setDisabled()}{setDisabled()} slot. + + \snippet examples/widgets/styles/widgetgallery.cpp 3 + \snippet examples/widgets/styles/widgetgallery.cpp 4 + + Finally, we put the child widgets in layouts. + + \snippet examples/widgets/styles/widgetgallery.cpp 5 + \snippet examples/widgets/styles/widgetgallery.cpp 6 + + When the user changes the style in the combobox, we call + QApplication::setStyle() to dynamically change the style of the + application. + + \snippet examples/widgets/styles/widgetgallery.cpp 7 + \snippet examples/widgets/styles/widgetgallery.cpp 8 + + If the user turns the \gui{Use style's standard palette} on, the + current style's \l{QStyle::standardPalette()}{standard palette} + is used; otherwise, the system's default palette is honored. + + For the Norwegian Wood style, this makes no difference because we + always override the palette with our own palette in \c + NorwegianWoodStyle::polish(). + + \snippet examples/widgets/styles/widgetgallery.cpp 9 + \snippet examples/widgets/styles/widgetgallery.cpp 10 + + The \c advanceProgressBar() slot is called at regular intervals + to advance the progress bar. Since we don't know how long the + user will keep the Styles application running, we use a + logarithmic formula: The closer the progress bar gets to 100%, + the slower it advances. + + We will review \c createProgressBar() in a moment. + + \snippet examples/widgets/styles/widgetgallery.cpp 11 + \snippet examples/widgets/styles/widgetgallery.cpp 12 + + The \c createTopLeftGroupBox() function creates the QGroupBox + that occupies the top-left corner of the \c WidgetGallery. We + skip the \c createTopRightGroupBox(), \c + createBottomLeftTabWidget(), and \c createBottomRightGroupBox() + functions, which are very similar. + + \snippet examples/widgets/styles/widgetgallery.cpp 13 + + In \c createProgressBar(), we create a QProgressBar at the bottom + of the \c WidgetGallery and connect its + \l{QTimer::timeout()}{timeout()} signal to the \c + advanceProgressBar() slot. +*/ diff --git a/doc/src/examples/stylesheet.qdoc b/doc/src/examples/stylesheet.qdoc new file mode 100644 index 0000000000..5bcb1d1521 --- /dev/null +++ b/doc/src/examples/stylesheet.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example widgets/stylesheet + \title Style Sheet Example + + The Style Sheet Example shows how to use style sheets. + + \image stylesheet-pagefold.png Screen Shot of the Pagefold style sheet +*/ + diff --git a/doc/src/examples/svgalib.qdoc b/doc/src/examples/svgalib.qdoc new file mode 100644 index 0000000000..e13cd7fd2c --- /dev/null +++ b/doc/src/examples/svgalib.qdoc @@ -0,0 +1,345 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example qws/svgalib + \title Accelerated Graphics Driver Example + + The Accelerated Graphics Driver example shows how you can write + your own accelerated graphics driver and \l {add your graphics + driver to Qt for Embedded Linux}. In \l{Qt for Embedded Linux}, + painting is a pure software implementation and is normally performed + in two steps: + The clients render each window onto a corresponding surface + (stored in memory) using a paint engine, and then the server uses + the graphics driver to compose the surface images and copy them to + the screen. (See the \l{Qt for Embedded Linux Architecture} documentation + for details.) + + The rendering can be accelerated in two ways: Either by + accelerating the copying of pixels to the screen, or by + accelerating the explicit painting operations. The first is done + in the graphics driver implementation, the latter is performed by + the paint engine implementation. Typically, both the pixel copying + and the painting operations are accelerated using the following + approach: + + \list 1 + \o \l {Step 1: Creating a Custom Graphics Driver} + {Creating a Custom Graphics Driver} + + \o \l {Step 2: Implementing a Custom Raster Paint Engine} + {Implementing a Custom Paint Engine} + + \o \l {Step 3: Making the Widgets Aware of the Custom Paint + Engine}{Making the Widgets Aware of the Custom Paint Engine} + + \endlist + + After compiling the example code, install the graphics driver + plugin with the command \c {make install}. To start an application + using the graphics driver, you can either set the environment + variable \l QWS_DISPLAY and then run the application, or you can + just run the application using the \c -display switch: + + \snippet doc/src/snippets/code/doc_src_examples_svgalib.qdoc 0 + + \table + \header \o SVGAlib + \row \o + + Instead of interfacing the graphics hardware directly, this + example relies on \l {http://www.svgalib.org}{SVGAlib} being + installed on your system. \l {http://www.svgalib.org}{SVGAlib} is + a small graphics library which provides acceleration for many + common graphics cards used on desktop computers. It should work on + most workstations and has a small and simple API. + + \endtable + + \section1 Step 1: Creating a Custom Graphics Driver + + The custom graphics driver is created by deriving from the QScreen + class. QScreen is the base class for implementing screen/graphics + drivers in Qt for Embedded Linux. + + \snippet examples/qws/svgalib/svgalibscreen.h 0 + \codeline + \snippet examples/qws/svgalib/svgalibscreen.h 1 + + The \l {QScreen::}{connect()}, \l {QScreen::}{disconnect()}, \l + {QScreen::}{initDevice()} and \l {QScreen::}{shutdownDevice()} + functions are declared as pure virtual functions in QScreen and + must be implemented. They are used to configure the hardware, or + query its configuration: \l {QScreen::}{connect()} and \l + {QScreen::}{disconnect()} are called by both the server and client + processes, while the \l {QScreen::}{initDevice()} and \l + {QScreen::}{shutdownDevice()} functions are only called by the + server process. + + QScreen's \l {QScreen::}{setMode()} and \l {QScreen::}{blank()} + functions are also pure virtual, but our driver's implementations + are trivial. The last two functions (\l {QScreen::}{blit()} and \l + {QScreen::}{solidFill()}) are the ones involved in putting pixels + on the screen, i.e., we reimplement these functions to perform the + pixel copying acceleration. + + Finally, the \c context variable is a pointer to a \l + {http://www.svgalib.org}{SVGAlib} specific type. Note that the + details of using the \l {http://www.svgalib.org}{SVGAlib} library + is beyond the scope of this example. + + \section2 SvgalibScreen Class Implementation + + The \l {QScreen::}{connect()} function is the first function that + is called after the constructor returns. It queries \l + {http://www.svgalib.org}{SVGAlib} about the graphics mode and + initializes the variables. + + \snippet examples/qws/svgalib/svgalibscreen.cpp 0 + + It is important that the \l {QScreen::}{connect()} function + initializes the \c data, \c lstep, \c w, \c h, \c dw, \c dh, \c d, + \c physWidth and \c physHeight variables (inherited from QScreen) + to ensure that the driver is in a state consistent with the driver + configuration. + + In this particular example we do not have any information of the + real physical size of the screen, so we set these values with the + assumption of a screen with 72 DPI. + + \snippet examples/qws/svgalib/svgalibscreen.cpp 1 + + When the \l {QScreen::}{connect()} function returns, the server + process calls the \l {QScreen::}{initDevice()} function which is + expected to do the necessary hardware initialization, leaving the + hardware in a state consistent with the driver configuration. + + Note that we have chosen to use the software cursor. If you want + to use a hardware cursor, you should create a subclass of + QScreenCursor, create an instance of it, and make the global + variable \c qt_screencursor point to this instance. + + \snippet examples/qws/svgalib/svgalibscreen.cpp 2 + \codeline + \snippet examples/qws/svgalib/svgalibscreen.cpp 3 + + Before exiting, the server process will call the \l + {QScreen::}{shutdownDevice()} function to do the necessary + hardware cleanup. Again, it is important that the function leaves + the hardware in a state consistent with the driver + configuration. When \l {QScreen::}{shutdownDevice()} returns, the + \l {QScreen::}{disconnect()} function is called. Our + implementation of the latter function is trivial. + + Note that, provided that the \c QScreen::data variable points to a + valid linear framebuffer, the graphics driver is fully functional + as a simple screen driver at this point. The rest of this example + will show where to take advantage of the accelerated capabilities + available on the hardware. + + Whenever an area on the screen needs to be updated, the server will + call the \l {QScreen::}{exposeRegion()} function that paints the + given region on screen. The default implementation will do the + necessary composing of the top-level windows and call \l + {QScreen::}{solidFill()} and \l {QScreen::}{blit()} whenever it is + required. We do not want to change this behavior in the driver so + we do not reimplement \l {QScreen::}{exposeRegion()}. + + To control how the pixels are put onto the screen we need to + reimplement the \l {QScreen::}{solidFill()} and \l + {QScreen::}{blit()} functions. + + \snippet examples/qws/svgalib/svgalibscreen.cpp 4 + \codeline + \snippet examples/qws/svgalib/svgalibscreen.cpp 5 + + \section1 Step 2: Implementing a Custom Raster Paint Engine + + \l{Qt for Embedded Linux} uses QRasterPaintEngine (a raster-based + implementation of QPaintEngine) to implement the painting + operations. + + Acceleration of the painting operations is done by deriving from + QRasterPaintEngine class. This is a powerful mechanism for + accelerating graphic primitives while getting software fallbacks + for all the primitives you do not accelerate. + + \snippet examples/qws/svgalib/svgalibpaintengine.h 0 + + In this example, we will only accelerate one of the \l + {QRasterPaintEngine::}{drawRects()} functions, i.e., only + non-rotated, aliased and opaque rectangles will be rendered using + accelerated painting. All other primitives are rendered using the + base class's unaccelerated implementation. + + The paint engine's state is stored in the private member + variables, and we reimplement the \l + {QPaintEngine::}{updateState()} function to ensure that our + custom paint engine's state is updated properly whenever it is + required. The private \c setClip() and \c updateClip() functions + are only helper function used to simplify the \l + {QPaintEngine::}{updateState()} implementation. + + We also reimplement QRasterPaintEngine's \l + {QRasterPaintEngine::}{begin()} and \l + {QRasterPaintEngine::}{end()} functions to initialize the paint + engine and to do the cleanup when we are done rendering, + respectively. + + \table + \header \o Private Header Files + \row + \o + + Note the \c include statement used by this class. The files + prefixed with \c private/ are private headers file within + \l{Qt for Embedded Linux}. Private header files are not part of + the standard installation and are only present while + compiling Qt. To be able to compile using + private header files you need to use a \c qmake binary within a + compiled \l{Qt for Embedded Linux} package. + + \warning Private header files may change without notice between + releases. + + \endtable + + The \l {QRasterPaintEngine::}{begin()} function initializes the + internal state of the paint engine. Note that it also calls the + base class implementation to initialize the parts inherited from + QRasterPaintEngine: + + \snippet examples/qws/svgalib/svgalibpaintengine.cpp 0 + \codeline + \snippet examples/qws/svgalib/svgalibpaintengine.cpp 1 + + The implementation of the \l {QRasterPaintEngine::}{end()} + function removes the clipping constraints that might have been set + in \l {http://www.svgalib.org}{SVGAlib}, before calling the + corresponding base class implementation. + + \snippet examples/qws/svgalib/svgalibpaintengine.cpp 2 + + The \l {QPaintEngine::}{updateState()} function updates our + custom paint engine's state. The QPaintEngineState class provides + information about the active paint engine's current state. + + Note that we only accept and save the current matrix if it doesn't + do any shearing. The pen is accepted if it is opaque and only one + pixel wide. The rest of the engine's properties are updated + following the same pattern. Again it is important that the + QPaintEngine::updateState() function is called to update the + parts inherited from the base class. + + \snippet examples/qws/svgalib/svgalibpaintengine.cpp 3 + \codeline + \snippet examples/qws/svgalib/svgalibpaintengine.cpp 4 + + The \c setClip() helper function is called from our custom + implementation of \l {QPaintEngine::}{updateState()}, and + enables clipping to the given region. An empty region means that + clipping is disabled. + + Our custom update function also makes use of the \c updateClip() + helper function that checks if the clip is "simple", i.e., that it + can be represented by only one rectangle, and updates the clip + region in \l {http://www.svgalib.org}{SVGAlib}. + + \snippet examples/qws/svgalib/svgalibpaintengine.cpp 5 + + Finally, we accelerated that drawing of non-rotated, aliased and + opaque rectangles in our reimplementation of the \l + {QRasterPaintEngine::}{drawRects()} function. The + QRasterPaintEngine fallback is used whenever the rectangle is not + simple enough. + + \section1 Step 3: Making the Widgets Aware of the Custom Paint Engine + + To activate the custom paint engine, we also need to implement a + corresponding paint device and window surface and make some minor + adjustments of the graphics driver. + + \list + \o \l {Implementing a Custom Paint Device} + \o \l {Implementing a Custom Window Surface} + \o \l {Adjusting the Graphics Driver} + \endlist + + \section2 Implementing a Custom Paint Device + + The custom paint device can be derived from the + QCustomRasterPaintDevice class. Reimplement its \l + {QCustomRasterPaintDevice::}{paintEngine()} and \l + {QCustomRasterPaintDevice::}{memory()} functions to activate the + accelerated paint engine: + + \snippet examples/qws/svgalib/svgalibpaintdevice.h 0 + + The \l {QCustomRasterPaintDevice::}{paintEngine()} function should + return an instance of the \c SvgalibPaintEngine class. The \l + {QCustomRasterPaintDevice::}{memory()} function should return a + pointer to the buffer which should be used when drawing the + widget. + + Our example driver is rendering directly to the screen without any + buffering, i.e., our custom pain device's \l + {QCustomRasterPaintDevice::}{memory()} function returns a pointer + to the framebuffer. For this reason, we must also reimplement the + \l {QPaintDevice::}{metric()} function to reflect the metrics of + framebuffer. + + \section2 Implementing a Custom Window Surface + + The custom window surface can be derived from the QWSWindowSurface + class. QWSWindowSurface manages the memory used when drawing a + window. + + \snippet examples/qws/svgalib/svgalibsurface.h 0 + + We can implement most of the pure virtual functions inherited from + QWSWindowSurface as trivial inline functions, except the scroll() + function that actually makes use of some hardware acceleration: + + \snippet examples/qws/svgalib/svgalibsurface.cpp 0 + + \section2 Adjusting the Graphics Driver + + Finally, we enable the graphics driver to recognize an instance of + our custom window surface: + + \snippet examples/qws/svgalib/svgalibscreen.cpp 7 + \codeline + \snippet examples/qws/svgalib/svgalibscreen.cpp 8 + + The \l {QScreen::}{createSurface()} functions are factory + functions that determines what kind of surface a top-level window + is using. In our example we only use the custom surface if the + given window has the Qt::WA_PaintOnScreen attribute or the + QT_ONSCREEN_PAINT environment variable is set. +*/ + diff --git a/doc/src/examples/syntaxhighlighter.qdoc b/doc/src/examples/syntaxhighlighter.qdoc new file mode 100644 index 0000000000..4018be81a8 --- /dev/null +++ b/doc/src/examples/syntaxhighlighter.qdoc @@ -0,0 +1,242 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example richtext/syntaxhighlighter + \title Syntax Highlighter Example + + The Syntax Highlighter example shows how to perform simple syntax + highlighting by subclassing the QSyntaxHighlighter class. + + \image syntaxhighlighter-example.png + + The Syntax Highlighter application displays C++ files with custom + syntax highlighting. + + The example consists of two classes: + + \list + \o The \c Highlighter class defines and applies the + highlighting rules. + \o The \c MainWindow widget is the application's main window. + \endlist + + We will first review the \c Highlighter class to see how you can + customize the QSyntaxHighlighter class to fit your preferences, + then we will take a look at the relevant parts of the \c + MainWindow class to see how you can use your custom highlighter + class in an application. + + \section1 Highlighter Class Definition + + \snippet examples/richtext/syntaxhighlighter/highlighter.h 0 + + To provide your own syntax highlighting, you must subclass + QSyntaxHighlighter, reimplement the \l + {QSyntaxHighlighter::highlightBlock()}{highlightBlock()} function, + and define your own highlighting rules. + + We have chosen to store our highlighting rules using a private + struct: A rule consists of a QRegExp pattern and a QTextCharFormat + instance. The various rules are then stored using a QVector. + + The QTextCharFormat class provides formatting information for + characters in a QTextDocument specifying the visual properties of + the text, as well as information about its role in a hypertext + document. In this example, we will only define the font weight and + color using the QTextCharFormat::setFontWeight() and + QTextCharFormat::setForeground() functions. + + \section1 Highlighter Class Implementation + + When subclassing the QSyntaxHighlighter class you must pass the + parent parameter to the base class constructor. The parent is the + text document upon which the syntax highligning will be + applied. In this example, we have also chosen to define our + highlighting rules in the constructor: + + \snippet examples/richtext/syntaxhighlighter/highlighter.cpp 0 + \snippet examples/richtext/syntaxhighlighter/highlighter.cpp 1 + + First we define a keyword rule which recognizes the most common + C++ keywords. We give the \c keywordFormat a bold, dark blue + font. For each keyword, we assign the keyword and the specified + format to a HighlightingRule object and append the object to our + list of rules. + + \snippet examples/richtext/syntaxhighlighter/highlighter.cpp 2 + \codeline + \snippet examples/richtext/syntaxhighlighter/highlighter.cpp 4 + \codeline + \snippet examples/richtext/syntaxhighlighter/highlighter.cpp 5 + + Then we create a format that we will apply to Qt class names. The + class names will be rendered with a dark magenta color and a bold + style. We specify a string pattern that is actually a regular + expression capturing all Qt class names. Then we assign the + regular expression and the specified format to a HighlightingRule + object and append the object to our list of rules. + + We also define highlighting rules for quotations and functions + using the same approach: The patterns have the form of regular + expressions and are stored in HighlightingRule objects with the + associated format. + + \snippet examples/richtext/syntaxhighlighter/highlighter.cpp 3 + \codeline + \snippet examples/richtext/syntaxhighlighter/highlighter.cpp 6 + + The C++ language has two variations of comments: The single line + comment (\c //) and the multiline comment (\c{/*...}\starslash). The single + line comment can easily be defined through a highlighting rule + similar to the previous ones. But the multiline comment needs + special care due to the design of the QSyntaxHighlighter class. + + After a QSyntaxHighlighter object is created, its \l + {QSyntaxHighlighter::highlightBlock()}{highlightBlock()} function + will be called automatically whenever it is necessary by the rich + text engine, highlighting the given text block. The problem + appears when a comment spans several text blocks. We will take a + closer look at how this problem can be solved when reviewing the + implementation of the \c Highlighter::highlightBlock() + function. At this point we only specify the multiline comment's + color. + + \snippet examples/richtext/syntaxhighlighter/highlighter.cpp 7 + + The highlightBlock() function is called automatically whenever it + is necessary by the rich text engine, i.e. when there are text + blocks that have changed. + + First we apply the syntax highlighting rules that we stored in the + \c highlightingRules vector. For each rule (i.e. for each + HighlightingRule object) we search for the pattern in the given + textblock using the QString::indexOf() function. When the first + occurrence of the pattern is found, we use the + QRegExp::matchedLength() function to determine the string that + will be formatted. QRegExp::matchedLength() returns the length of + the last matched string, or -1 if there was no match. + + To perform the actual formatting the QSyntaxHighlighter class + provides the \l {QSyntaxHighlighter::setFormat()}{setFormat()} + function. This function operates on the text block that is passed + as argument to the \c highlightBlock() function. The specified + format is applied to the text from the given start position for + the given length. The formatting properties set in the given + format are merged at display time with the formatting information + stored directly in the document. Note that the document itself + remains unmodified by the format set through this function. + + This process is repeated until the last occurrence of the pattern + in the current text block is found. + + \snippet examples/richtext/syntaxhighlighter/highlighter.cpp 8 + + To deal with constructs that can span several text blocks (like + the C++ multiline comment), it is necessary to know the end state + of the previous text block (e.g. "in comment"). Inside your \c + highlightBlock() implementation you can query the end state of the + previous text block using the + QSyntaxHighlighter::previousBlockState() function. After parsing + the block you can save the last state using + QSyntaxHighlighter::setCurrentBlockState(). + + The \l + {QSyntaxHighlighter::previousBlockState()}{previousBlockState()} + function return an int value. If no state is set, the returned + value is -1. You can designate any other value to identify any + given state using the \l + {QSyntaxHighlighter::setCurrentBlockState()}{setCurrentBlockState()} + function. Once the state is set, the QTextBlock keeps that value + until it is set again or until the corresponding paragraph of text + is deleted. + + In this example we have chosen to use 0 to represent the "not in + comment" state, and 1 for the "in comment" state. When the stored + syntax highlighting rules are applied we initialize the current + block state to 0. + + \snippet examples/richtext/syntaxhighlighter/highlighter.cpp 9 + + If the previous block state was "in comment" (\c + {previousBlockState() == 1}), we start the search for an end + expression at the beginning of the text block. If the + previousBlockState() returns 0, we start the search at the + location of the first occurrence of a start expression. + + \snippet examples/richtext/syntaxhighlighter/highlighter.cpp 10 + \snippet examples/richtext/syntaxhighlighter/highlighter.cpp 11 + + When an end expression is found, we calculate the length of the + comment and apply the multiline comment format. Then we search for + the next occurrence of the start expression and repeat the + process. If no end expression can be found in the current text + block we set the current block state to 1, i.e. "in comment". + + This completes the \c Highlighter class implementation; it is now + ready for use. + + \section1 MainWindow Class Definition + + Using a QSyntaxHighlighter subclass is simple; just provide your + application with an instance of the class and pass it the document + upon which you want the highlighting to be applied. + + \snippet examples/richtext/syntaxhighlighter/mainwindow.h 0 + + In this example we declare a pointer to a \c Highlighter instance + which we later will initialize in the private \c setupEditor() + function. + + \section1 MainWindow Class Implementation + + The constructor of the main window is straight forward. We first + set up the menus, then we initialize the editor and make it the + central widget of the application. Finally we set the main + window's title. + + \snippet examples/richtext/syntaxhighlighter/mainwindow.cpp 0 + + We initialize and install the \c Highlighter object in the private + setupEditor() convenience function: + + \snippet examples/richtext/syntaxhighlighter/mainwindow.cpp 1 + + First we create the font we want to use in the editor, then we + create the editor itself which is an instance of the QTextEdit + class. Before we initialize the editor with the \c MainWindow + class definition file, we create a \c Highlighter instance passing + the editor's document as argument. This is the document that the + highlighting will be applied to. Then we are done. + + A QSyntaxHighlighter object can only be installed on one document + at the time, but you can easily reinstall the highlighter on + another document using the QSyntaxHighlighter::setDocument() + function. The QSyntaxHighlighter class also provides the \l + {QSyntaxHighlighter::document()}{document()} function which + returns the currently set document. +*/ diff --git a/doc/src/examples/tabdialog.qdoc b/doc/src/examples/tabdialog.qdoc new file mode 100644 index 0000000000..543ec4dce8 --- /dev/null +++ b/doc/src/examples/tabdialog.qdoc @@ -0,0 +1,134 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example dialogs/tabdialog + \title Tab Dialog Example + + The Tab Dialog example shows how to construct a tab dialog using the + QTabWidget class. + + Dialogs provide an efficient way for the application to communicate + with the user, but complex dialogs suffer from the problem that they + often take up too much screen area. By using a number of tabs in a + dialog, information can be split into different categories, while + remaining accessible. + + \image tabdialog-example.png + + The Tab Dialog example consists of a single \c TabDialog class that + provides three tabs, each containing information about a particular + file, and two standard push buttons that are used to accept or reject + the contents of the dialog. + + \section1 TabDialog Class Definition + + The \c TabDialog class is a subclass of QDialog that displays a + QTabWidget and two standard dialog buttons. The class definition + only contain the class constructor and a private data member for + the QTabWidget: + + \snippet examples/dialogs/tabdialog/tabdialog.h 3 + + In the example, the widget will be used as a top-level window, but + we define the constructor so that it can take a parent widget. This + allows the dialog to be centered on top of an application's main + window. + + \section1 TabDialog Class Implementation + + The constructor calls the QDialog constructor and creates a QFileInfo + object for the specified filename. + + \snippet examples/dialogs/tabdialog/tabdialog.cpp 0 + + The tab widget is populated with three custom widgets that each + contain information about the file. We construct each of these + without a parent widget because the tab widget will reparent + them as they are added to it. + + We create two standard push buttons, and connect each of them to + the appropriate slots in the dialog: + + \snippet examples/dialogs/tabdialog/tabdialog.cpp 1 + \snippet examples/dialogs/tabdialog/tabdialog.cpp 3 + + We arrange the tab widget above the buttons in the dialog: + + \snippet examples/dialogs/tabdialog/tabdialog.cpp 4 + + Finally, we set the dialog's title: + + \snippet examples/dialogs/tabdialog/tabdialog.cpp 5 + + Each of the tabs are subclassed from QWidget, and only provide + constructors. + + \section1 GeneralTab Class Definition + + The GeneralTab widget definition is simple because we are only interested + in displaying the contents of a widget within a tab: + + \snippet examples/dialogs/tabdialog/tabdialog.h 0 + + \section1 GeneralTab Class Implementation + + The GeneralTab widget simply displays some information about the file + passed by the TabDialog. Various widgets for this purpose, and these + are arranged within a vertical layout: + + \snippet examples/dialogs/tabdialog/tabdialog.cpp 6 + + \section1 PermissionsTab Class Definition + + Like the GeneralTab, the PermissionsTab is just used as a placeholder + widget for its children: + + \snippet examples/dialogs/tabdialog/tabdialog.h 1 + + \section1 PermissionsTab Class Implementation + + The PermissionsTab shows information about the file's access information, + displaying details of the file permissions and owner in widgets that are + arranged in nested layouts: + + \snippet examples/dialogs/tabdialog/tabdialog.cpp 7 + + \section1 ApplicationsTab Class Definition + + The ApplicationsTab is another placeholder widget that is mostly + cosmetic: + + \snippet examples/dialogs/tabdialog/tabdialog.h 2 + + \section1 ApplicationsTab Class Implementation + + The ApplicationsTab does not show any useful information, but could be + used as a template for a more complicated example: + + \snippet examples/dialogs/tabdialog/tabdialog.cpp 8 +*/ diff --git a/doc/src/examples/tablemodel.qdoc b/doc/src/examples/tablemodel.qdoc new file mode 100644 index 0000000000..0d4dffb74e --- /dev/null +++ b/doc/src/examples/tablemodel.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example sql/tablemodel + \title Table Model Example + + The Table Model example shows how to use a specialized SQL table model with table + views to edit information in a database. + + \image tablemodel-example.png +*/ diff --git a/doc/src/examples/tablet.qdoc b/doc/src/examples/tablet.qdoc new file mode 100644 index 0000000000..f4cb3e9d32 --- /dev/null +++ b/doc/src/examples/tablet.qdoc @@ -0,0 +1,369 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example widgets/tablet + \title Tablet Example + + This example shows how to use a Wacom tablet in Qt applications. + + \image tabletexample.png + + When you use a tablet with Qt applications, \l{QTabletEvent}s are + generated. You need to reimplement the + \l{QWidget::}{tabletEvent()} event handler if you want to handle + tablet events. Events are generated when the device used for + drawing enters and leaves the proximity of the tablet (i.e., when + it is close but not pressed down on it), when a device is pushed + down and released from it, and when a device is moved on the + tablet. + + The information available in QTabletEvent depends on the device + used. The tablet in this example has two different devices for + drawing: a stylus and an airbrush. For both devices the event + contains the position of the device, pressure on the tablet, + vertical tilt, and horizontal tilt (i.e, the angle between the + device and the perpendicular of the tablet). The airbrush has a + finger wheel; the position of this is also available in the tablet + event. + + In this example we implement a drawing program. You can use the + stylus to draw on the tablet as you use a pencil on paper. When + you draw with the airbrush you get a spray of paint; the finger + wheel is used to change the density of the spray. The pressure and + tilt can change the alpha and saturation values of the QColor and the + width of the QPen used for drawing. + + The example consists of the following: + + \list + \o The \c MainWindow class inherits QMainWindow and creates + the examples menus and connect their slots and signals. + \o The \c TabletCanvas class inherits QWidget and + receives tablet events. It uses the events to paint on a + offscreen pixmap, which it draws onto itself. + \o The \c TabletApplication class inherits QApplication. This + class handles tablet events that are not sent to \c tabletEvent(). + We will look at this later. + \o The \c main() function creates a \c MainWindow and shows it + as a top level window. + \endlist + + + \section1 MainWindow Class Definition + + The \c MainWindow creates a \c TabletCanvas and sets it as its + center widget. + + \snippet examples/widgets/tablet/mainwindow.h 0 + + The QActions let the user select if the tablets pressure and + tilt should change the pen width, color alpha component and color + saturation. \c createActions() creates all actions, and \c + createMenus() sets up the menus with the actions. We have one + QActionGroup for the actions that alter the alpha channel, color + saturation and line width respectively. The action groups are + connected to the \c alphaActionTriggered(), \c + colorSaturationActiontriggered(), and \c + lineWidthActionTriggered() slots, which calls functions in \c + myCanvas. + + + \section1 MainWindow Class Implementation + + We start width a look at the constructor \c MainWindow(): + + \snippet examples/widgets/tablet/mainwindow.cpp 0 + + In the constructor we create the canvas, actions, and menus. + We set the canvas as the center widget. We also initialize the + canvas to match the state of our menus and start drawing with a + red color. + + Here is the implementation of \c brushColorAct(): + + \snippet examples/widgets/tablet/mainwindow.cpp 1 + + We let the user pick a color with a QColorDialog. If it is valid, + we set a new drawing color with \c setColor(). + + Here is the implementation of \c alphaActionTriggered(): + + \snippet examples/widgets/tablet/mainwindow.cpp 2 + + The \c TabletCanvas class supports two ways by which the alpha + channel of the drawing color can be changed: tablet pressure and + tilt. We have one action for each and an action if the alpha + channel should not be changed. + + Here is the implementation of \c lineWidthActionTriggered(): + + \snippet examples/widgets/tablet/mainwindow.cpp 3 + + We check which action is selected in \c lineWidthGroup, and set + how the canvas should change the drawing line width. + + Here is the implementation of \c saturationActionTriggered(): + + \snippet examples/widgets/tablet/mainwindow.cpp 4 + + We check which action is selected in \c colorSaturationGroup, and + set how the canvas should change the color saturation of the + drawing color. + + Here is the implementation of \c saveAct(): + + \snippet examples/widgets/tablet/mainwindow.cpp 5 + + We use the QFileDialog to let the user select a file to save the + drawing in. It is the \c TabletCanvas that save the drawing, so we + call its \c saveImage() function. + + Here is the implementation of \c loadAct(): + + \snippet examples/widgets/tablet/mainwindow.cpp 6 + + We let the user select the image file to be opened with + a QFileDialog; we then ask the canvas to load the image with \c + loadImage(). + + Here is the implementation of \c aboutAct(): + + \snippet examples/widgets/tablet/mainwindow.cpp 7 + + We show a message box with a short description of the example. + + \c createActions() creates all actions and action groups of + the example. We look at the creation of one action group and its + actions. See the \l{Application Example}{application example} if + you want a high-level introduction to QActions. + + Here is the implementation of \c createActions: + + \snippet examples/widgets/tablet/mainwindow.cpp 8 + \dots + \snippet examples/widgets/tablet/mainwindow.cpp 9 + + We want the user to be able to choose if the drawing color's + alpha component should be changed by the tablet pressure or tilt. + We have one action for each choice and an action if the alpha + channel is not to be changed, i.e, the color is opaque. We make + the actions checkable; the \c alphaChannelGroup will then ensure + that only one of the actions are checked at any time. The \c + triggered() signal is emitted when an action is checked. + + \dots + \snippet examples/widgets/tablet/mainwindow.cpp 10 + + Here is the implementation of \c createMenus(): + + \snippet examples/widgets/tablet/mainwindow.cpp 11 + + We create the menus of the example and add the actions to them. + + + \section1 TabletCanvas Class Definition + + The \c TabletCanvas class provides a surface on which the + user can draw with a tablet. + + \snippet examples/widgets/tablet/tabletcanvas.h 0 + + The canvas can change the alpha channel, color saturation, + and line width of the drawing. We have one enum for each of + these; their values decide if it is the tablet pressure or tilt + that will alter them. We keep a private variable for each, the \c + alphaChannelType, \c colorSturationType, and \c penWidthType, + which we provide access functions for. + + We draw on a QPixmap with \c myPen and \c myBrush using \c + myColor. The \c saveImage() and \c loadImage() saves and loads + the QPixmap to disk. The pixmap is drawn on the widget in \c + paintEvent(). The \c pointerType and \c deviceType keeps the type + of pointer, which is either a pen or an eraser, and device + currently used on the tablet, which is either a stylus or an + airbrush. + + The interpretation of events from the tablet is done in \c + tabletEvent(); \c paintPixmap(), \c updateBrush(), and \c + brushPattern() are helper functions used by \c tabletEvent(). + + + \section1 TabletCanvas Class Implementation + + We start with a look at the constructor: + + \snippet examples/widgets/tablet/tabletcanvas.cpp 0 + + In the constructor we initialize our class variables. We need + to draw the background of our pixmap, as the default is gray. + + Here is the implementation of \c saveImage(): + + \snippet examples/widgets/tablet/tabletcanvas.cpp 1 + + QPixmap implements functionality to save itself to disk, so we + simply call \l{QPixmap::}{save()}. + + Here is the implementation of \c loadImage(): + + \snippet examples/widgets/tablet/tabletcanvas.cpp 2 + + We simply call \l{QPixmap::}{load()}, which loads the image in \a + file. + + Here is the implementation of \c tabletEvent(): + + \snippet examples/widgets/tablet/tabletcanvas.cpp 3 + + We get three kind of events to this function: TabletPress, + TabletRelease, and TabletMove, which is generated when a device + is pressed down on, leaves, or moves on the tablet. We set the \c + deviceDown to true when a device is pressed down on the tablet; + we then know when we should draw when we receive move events. We + have implemented the \c updateBrush() and \c paintPixmap() helper + functions to update \c myBrush and \c myPen after the state of \c + alphaChannelType, \c colorSaturationType, and \c lineWidthType. + + Here is the implementation of \c paintEvent(): + + \snippet examples/widgets/tablet/tabletcanvas.cpp 4 + + We simply draw the pixmap to the top left of the widget. + + Here is the implementation of \c paintPixmap(): + + \snippet examples/widgets/tablet/tabletcanvas.cpp 5 + + In this function we draw on the pixmap based on the movement of the + device. If the device used on the tablet is a stylus we want to draw a + line between the positions of the stylus recorded in \c polyLine. We + also assume that this is a reasonable handling of any unknown device, + but update the statusbar with a warning so that the user can see that + for his tablet he might have to implement special handling. + If it is an airbrush we want to draw a circle of points with a + point density based on the tangential pressure, which is the position + of the finger wheel on the airbrush. We use the Qt::BrushStyle to + draw the points as it has styles that draw points with different + density; we select the style based on the tangential pressure in + \c brushPattern(). + + \snippet examples/widgets/tablet/tabletcanvas.cpp 6 + + We return a brush style with a point density that increases with + the tangential pressure. + + In \c updateBrush() we set the pen and brush used for drawing + to match \c alphaChannelType, \c lineWidthType, \c + colorSaturationType, and \c myColor. We will examine the code to + set up \c myBrush and \c myPen for each of these variables: + + \snippet examples/widgets/tablet/tabletcanvas.cpp 7 + + We fetch the current drawingcolor's hue, saturation, value, + and alpha values. \c hValue and \c vValue are set to the + horizontal and vertical tilt as a number from 0 to 255. The + original values are in degrees from -60 to 60, i.e., 0 equals + -60, 127 equals 0, and 255 equals 60 degrees. The angle measured + is between the device and the perpendicular of the tablet (see + QTabletEvent for an illustration). + + \snippet examples/widgets/tablet/tabletcanvas.cpp 8 + + The alpha channel of QColor is given as a number between 0 + and 255 where 0 is transparent and 255 is opaque. + \l{QTabletEvent::}{pressure()} returns the pressure as a qreal + between 0.0 and 1.0. By subtracting 127 from the tilt values and + taking the absolute value we get the smallest alpha values (i.e., + the color is most transparent) when the pen is perpendicular to + the tablet. We select the largest of the vertical and horizontal + tilt value. + + \snippet examples/widgets/tablet/tabletcanvas.cpp 9 + + The colorsaturation is given as a number between 0 and 255. It is + set with \l{QColor::}{setHsv()}. We can set the tilt values + directly, but must multiply the pressure to a number between 0 and + 255. + + \snippet examples/widgets/tablet/tabletcanvas.cpp 10 + + The width of the pen increases with the pressure. When the pen + width is controlled with the tilt we let the width increse with + the angle between the device and the perpendicular of the tablet. + + \snippet examples/widgets/tablet/tabletcanvas.cpp 11 + + We finally check wether the pointer is the stylus or the eraser. + If it is the eraser, we set the color to the background color of + the pixmap an let the pressure decide the pen width, else we set + the colors we have set up previously in the function. + + + \section1 TabletApplication Class Definition + + We inherit QApplication in this class because we want to + reimplement the \l{QApplication::}{event()} function. + + \snippet examples/widgets/tablet/tabletapplication.h 0 + + We keep a \c TabletCanvas we send the device type of the events we + handle in the \c event() function to. The TabletEnterProximity + and TabletLeaveProximity events are not sendt to the QApplication + object, while other tablet events are sendt to the QWidget's + \c event(), which sends them on to \l{QWidget::}{tabletEvent()}. + Since we want to handle these events we have implemented \c + TabletApplication. + + + \section1 TabletApplication Class Implementation + + Here is the implementation of \c event(): + + \snippet examples/widgets/tablet/tabletapplication.cpp 0 + + We use this function to handle the TabletEnterProximity and + TabletLeaveProximity events, which is generated when a device + enters and leaves the proximity of the tablet. The intended use of these + events is to do work that is dependent on what kind of device is + used on the tablet. This way, you don't have to do this work + when other events are generated, which is more frequently than the + leave and enter proximity events. We call \c setTabletDevice() in + \c TabletCanvas. + + \section1 The \c main() function + + Here is the examples \c main() function: + + \snippet examples/widgets/tablet/main.cpp 0 + + In the \c main() function we create a \c MainWinow and display it + as a top level window. We use the \c TabletApplication class. We + need to set the canvas after the application is created. We cannot + use classes that implement event handling before an QApplication + object is instantiated. +*/ diff --git a/doc/src/examples/tetrix.qdoc b/doc/src/examples/tetrix.qdoc new file mode 100644 index 0000000000..00bc092289 --- /dev/null +++ b/doc/src/examples/tetrix.qdoc @@ -0,0 +1,431 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example widgets/tetrix + \title Tetrix Example + + The Tetrix example is a Qt version of the classic Tetrix game. + + \image tetrix-example.png + + The object of the game is to stack pieces dropped from the top of the + playing area so that they fill entire rows at the bottom of the playing area. + + When a row is filled, all the blocks on that row are removed, the player earns + a number of points, and the pieces above are moved down to occupy that row. + If more than one row is filled, the blocks on each row are removed, and the + player earns extra points. + + The \gui{Left} cursor key moves the current piece one space to the left, the + \gui{Right} cursor key moves it one space to the right, the \gui{Up} cursor + key rotates the piece counter-clockwise by 90 degrees, and the \gui{Down} + cursor key rotates the piece clockwise by 90 degrees. + + To avoid waiting for a piece to fall to the bottom of the board, press \gui{D} + to immediately move the piece down by one row, or press the \gui{Space} key to + drop it as close to the bottom of the board as possible. + + This example shows how a simple game can be created using only three classes: + + \list + \o The \c TetrixWindow class is used to display the player's score, number of + lives, and information about the next piece to appear. + \o The \c TetrixBoard class contains the game logic, handles keyboard input, and + displays the pieces on the playing area. + \o The \c TetrixPiece class contains information about each piece. + \endlist + + In this approach, the \c TetrixBoard class is the most complex class, since it + handles the game logic and rendering. One benefit of this is that the + \c TetrixWindow and \c TetrixPiece classes are very simple and contain only a + minimum of code. + + \section1 TetrixWindow Class Definition + + The \c TetrixWindow class is used to display the game information and contains + the playing area: + + \snippet examples/widgets/tetrix/tetrixwindow.h 0 + + We use private member variables for the board, various display widgets, and + buttons to allow the user to start a new game, pause the current game, and quit. + + Although the window inherits QWidget, the constructor does not provide an + argument to allow a parent widget to be specified. This is because the window + will always be used as a top-level widget. + + \section1 TetrixWindow Class Implementation + + The constructor sets up the user interface elements for the game: + + \snippet examples/widgets/tetrix/tetrixwindow.cpp 0 + + We begin by constructing a \c TetrixBoard instance for the playing area and a + label that shows the next piece to be dropped into the playing area; the label + is initially empty. + + Three QLCDNumber objects are used to display the score, number of lives, and + lines removed. These initially show default values, and will be filled in + when a game begins: + + \snippet examples/widgets/tetrix/tetrixwindow.cpp 1 + + Three buttons with shortcuts are constructed so that the user can start a + new game, pause the current game, and quit the application: + + \snippet examples/widgets/tetrix/tetrixwindow.cpp 2 + \snippet examples/widgets/tetrix/tetrixwindow.cpp 3 + + These buttons are configured so that they never receive the keyboard focus; + we want the keyboard focus to remain with the \c TetrixBoard instance so that + it receives all the keyboard events. Nonetheless, the buttons will still respond + to \key{Alt} key shortcuts. + + We connect \l{QAbstractButton::}{clicked()} signals from the \gui{Start} + and \gui{Pause} buttons to the board, and from the \gui{Quit} button to the + application's \l{QApplication::}{quit()} slot. + + \snippet examples/widgets/tetrix/tetrixwindow.cpp 4 + \snippet examples/widgets/tetrix/tetrixwindow.cpp 5 + + Signals from the board are also connected to the LCD widgets for the purpose of + updating the score, number of lives, and lines removed from the playing area. + + We place the label, LCD widgets, and the board into a QGridLayout + along with some labels that we create with the \c createLabel() convenience + function: + + \snippet examples/widgets/tetrix/tetrixwindow.cpp 6 + + Finally, we set the grid layout on the widget, give the window a title, and + resize it to an appropriate size. + + The \c createLabel() convenience function simply creates a new label on the + heap, gives it an appropriate alignment, and returns it to the caller: + + \snippet examples/widgets/tetrix/tetrixwindow.cpp 7 + + Since each label will be used in the widget's layout, it will become a child + of the \c TetrixWindow widget and, as a result, it will be deleted when the + window is deleted. + + \section1 TetrixPiece Class Definition + + The \c TetrixPiece class holds information about a piece in the game's + playing area, including its shape, position, and the range of positions it can + occupy on the board: + + \snippet examples/widgets/tetrix/tetrixpiece.h 0 + + Each shape contains four blocks, and these are defined by the \c coords private + member variable. Additionally, each piece has a high-level description that is + stored internally in the \c pieceShape variable. + + The constructor is written inline in the definition, and simply ensures that + each piece is initially created with no shape. The \c shape() function simply + returns the contents of the \c pieceShape variable, and the \c x() and \c y() + functions return the x and y-coordinates of any given block in the shape. + + \section1 TetrixPiece Class Implementation + + The \c setRandomShape() function is used to select a random shape for a piece: + + \snippet examples/widgets/tetrix/tetrixpiece.cpp 0 + + For convenience, it simply chooses a random shape from the \c TetrixShape enum + and calls the \c setShape() function to perform the task of positioning the + blocks. + + The \c setShape() function uses a look-up table of pieces to associate each + shape with an array of block positions: + + \snippet examples/widgets/tetrix/tetrixpiece.cpp 1 + \snippet examples/widgets/tetrix/tetrixpiece.cpp 2 + + These positions are read from the table into the piece's own array of positions, + and the piece's internal shape information is updated to use the new shape. + + The \c x() and \c y() functions are implemented inline in the class definition, + returning positions defined on a grid that extends horizontally and vertically + with coordinates from -2 to 2. Although the predefined coordinates for each + piece only vary horizontally from -1 to 1 and vertically from -1 to 2, each + piece can be rotated by 90, 180, and 270 degrees. + + The \c minX() and \c maxX() functions return the minimum and maximum horizontal + coordinates occupied by the blocks that make up the piece: + + \snippet examples/widgets/tetrix/tetrixpiece.cpp 3 + \snippet examples/widgets/tetrix/tetrixpiece.cpp 4 + + Similarly, the \c minY() and \c maxY() functions return the minimum and maximum + vertical coordinates occupied by the blocks: + + \snippet examples/widgets/tetrix/tetrixpiece.cpp 5 + \snippet examples/widgets/tetrix/tetrixpiece.cpp 6 + + The \c rotatedLeft() function returns a new piece with the same shape as an + existing piece, but rotated counter-clockwise by 90 degrees: + + \snippet examples/widgets/tetrix/tetrixpiece.cpp 7 + + Similarly, the \c rotatedRight() function returns a new piece with the same + shape as an existing piece, but rotated clockwise by 90 degrees: + + \snippet examples/widgets/tetrix/tetrixpiece.cpp 9 + + These last two functions enable each piece to create rotated copies of itself. + + \section1 TetrixBoard Class Definition + + The \c TetrixBoard class inherits from QFrame and contains the game logic and display features: + + \snippet examples/widgets/tetrix/tetrixboard.h 0 + + Apart from the \c setNextPieceLabel() function and the \c start() and \c pause() + public slots, we only provide public functions to reimplement QWidget::sizeHint() + and QWidget::minimumSizeHint(). The signals are used to communicate changes to + the player's information to the \c TetrixWindow instance. + + The rest of the functionality is provided by reimplementations of protected event + handlers and private functions: + + \snippet examples/widgets/tetrix/tetrixboard.h 1 + + The board is composed of a fixed-size array whose elements correspond to + spaces for individual blocks. Each element in the array contains a \c TetrixShape + value corresponding to the type of shape that occupies that element. + + Each shape on the board will occupy four elements in the array, and these will + all contain the enum value that corresponds to the type of the shape. + + We use a QBasicTimer to control the rate at which pieces fall toward the bottom + of the playing area. This allows us to provide an implementation of + \l{QObject::}{timerEvent()} that we can use to update the widget. + + \section1 TetrixBoard Class Implementation + + In the constructor, we customize the frame style of the widget, ensure that + keyboard input will be received by the widget by using Qt::StrongFocus for the + focus policy, and initialize the game state: + + \snippet examples/widgets/tetrix/tetrixboard.cpp 0 + + The first (next) piece is also set up with a random shape. + + The \c setNextPieceLabel() function is used to pass in an externally-constructed + label to the board, so that it can be shown alongside the playing area: + + \snippet examples/widgets/tetrix/tetrixboard.cpp 1 + + We provide a reasonable size hint and minimum size hint for the board, based on + the size of the space for each block in the playing area: + + \snippet examples/widgets/tetrix/tetrixboard.cpp 2 + \snippet examples/widgets/tetrix/tetrixboard.cpp 3 + + By using a minimum size hint, we indicate to the layout in the parent widget + that the board should not shrink below a minimum size. + + A new game is started when the \c start() slot is called. This resets the + game's state, the player's score and level, and the contents of the board: + + \snippet examples/widgets/tetrix/tetrixboard.cpp 4 + + We also emit signals to inform other components of these changes before creating + a new piece that is ready to be dropped into the playing area. We start the + timer that determines how often the piece drops down one row on the board. + + The \c pause() slot is used to temporarily stop the current game by stopping the + internal timer: + + \snippet examples/widgets/tetrix/tetrixboard.cpp 5 + \snippet examples/widgets/tetrix/tetrixboard.cpp 6 + + We perform checks to ensure that the game can only be paused if it is already + running and not already paused. + + The \c paintEvent() function is straightforward to implement. We begin by + calling the base class's implementation of \l{QWidget::}{paintEvent()} before + constructing a QPainter for use on the board: + + \snippet examples/widgets/tetrix/tetrixboard.cpp 7 + + Since the board is a subclass of QFrame, we obtain a QRect that covers the area + \e inside the frame decoration before drawing our own content. + + If the game is paused, we want to hide the existing state of the board and + show some text. We achieve this by painting text onto the widget and returning + early from the function. The rest of the painting is performed after this point. + + The position of the top of the board is found by subtracting the total height + of each space on the board from the bottom of the frame's internal rectangle. + For each space on the board that is occupied by a piece, we call the + \c drawSquare() function to draw a block at that position. + + \snippet examples/widgets/tetrix/tetrixboard.cpp 8 + \snippet examples/widgets/tetrix/tetrixboard.cpp 9 + + Spaces that are not occupied by blocks are left blank. + + Unlike the existing pieces on the board, the current piece is drawn + block-by-block at its current position: + + \snippet examples/widgets/tetrix/tetrixboard.cpp 10 + \snippet examples/widgets/tetrix/tetrixboard.cpp 11 + \snippet examples/widgets/tetrix/tetrixboard.cpp 12 + + The \c keyPressEvent() handler is called whenever the player presses a key while + the \c TetrixBoard widget has the keyboard focus. + + \snippet examples/widgets/tetrix/tetrixboard.cpp 13 + + If there is no current game, the game is running but paused, or if there is no + current shape to control, we simply pass on the event to the base class. + + We check whether the event is about any of the keys that the player uses to + control the current piece and, if so, we call the relevant function to handle + the input: + + \snippet examples/widgets/tetrix/tetrixboard.cpp 14 + + In the case where the player presses a key that we are not interested in, we + again pass on the event to the base class's implementation of + \l{QWidget::}{keyPressEvent()}. + + The \c timerEvent() handler is called every time the class's QBasicTimer + instance times out. We need to check that the event we receive corresponds to + our timer. If it does, we can update the board: + + \snippet examples/widgets/tetrix/tetrixboard.cpp 15 + \snippet examples/widgets/tetrix/tetrixboard.cpp 16 + \snippet examples/widgets/tetrix/tetrixboard.cpp 17 + + If a row (or line) has just been filled, we create a new piece and reset the + timer; otherwise we move the current piece down by one row. We let the base + class handle other timer events that we receive. + + The \c clearBoard() function simply fills the board with the + \c TetrixShape::NoShape value: + + \snippet examples/widgets/tetrix/tetrixboard.cpp 18 + + The \c dropDown() function moves the current piece down as far as possible on + the board, either until it is touching the bottom of the playing area or it is + stacked on top of another piece: + + \snippet examples/widgets/tetrix/tetrixboard.cpp 19 + \snippet examples/widgets/tetrix/tetrixboard.cpp 20 + + The number of rows the piece has dropped is recorded and passed to the + \c pieceDropped() function so that the player's score can be updated. + + The \c oneLineDown() function is used to move the current piece down by one row + (line), either when the user presses the \gui{D} key or when the piece is + scheduled to move: + + \snippet examples/widgets/tetrix/tetrixboard.cpp 21 + + If the piece cannot drop down by one line, we call the \c pieceDropped() function + with zero as the argument to indicate that it cannot fall any further, and that + the player should receive no extra points for the fall. + + The \c pieceDropped() function itself is responsible for awarding points to the + player for positioning the current piece, checking for full rows on the board + and, if no lines have been removed, creating a new piece to replace the current + one: + + \snippet examples/widgets/tetrix/tetrixboard.cpp 22 + \snippet examples/widgets/tetrix/tetrixboard.cpp 23 + + We call \c removeFullLines() each time a piece has been dropped. This scans + the board from bottom to top, looking for blank spaces on each row. + + \snippet examples/widgets/tetrix/tetrixboard.cpp 24 + \snippet examples/widgets/tetrix/tetrixboard.cpp 25 + \snippet examples/widgets/tetrix/tetrixboard.cpp 26 + \snippet examples/widgets/tetrix/tetrixboard.cpp 27 + + If a row contains no blank spaces, the rows above it are copied down by one row + to compress the stack of pieces, the top row on the board is cleared, and the + number of full lines found is incremented. + + \snippet examples/widgets/tetrix/tetrixboard.cpp 28 + \snippet examples/widgets/tetrix/tetrixboard.cpp 29 + + If some lines have been removed, the player's score and the total number of lines + removed are updated. The \c linesRemoved() and \c scoreChanged() signals are + emitted to send these new values to other widgets in the window. + + Additionally, we set the timer to elapse after half a second, set the + \c isWaitingAfterLine flag to indicate that lines have been removed, unset + the piece's shape to ensure that it is not drawn, and update the widget. + The next time that the \c timerEvent() handler is called, a new piece will be + created and the game will continue. + + The \c newPiece() function places the next available piece at the top of the + board, and creates a new piece with a random shape: + + \snippet examples/widgets/tetrix/tetrixboard.cpp 30 + \snippet examples/widgets/tetrix/tetrixboard.cpp 31 + + We place a new piece in the middle of the board at the top. The game is over if + the piece can't move, so we unset its shape to prevent it from being drawn, stop + the timer, and unset the \c isStarted flag. + + The \c showNextPiece() function updates the label that shows the next piece to + be dropped: + + \snippet examples/widgets/tetrix/tetrixboard.cpp 32 + \snippet examples/widgets/tetrix/tetrixboard.cpp 33 + + We draw the piece's component blocks onto a pixmap that is then set on the label. + + The \c tryMove() function is used to determine whether a piece can be positioned + at the specified coordinates: + + \snippet examples/widgets/tetrix/tetrixboard.cpp 34 + + We examine the spaces on the board that the piece needs to occupy and, if they + are already occupied by other pieces, we return \c false to indicate that the + move has failed. + + \snippet examples/widgets/tetrix/tetrixboard.cpp 35 + + If the piece could be placed on the board at the desired location, we update the + current piece and its position, update the widget, and return \c true to indicate + success. + + The \c drawSquare() function draws the blocks (normally squares) that make up + each piece using different colors for pieces with different shapes: + + \snippet examples/widgets/tetrix/tetrixboard.cpp 36 + + We obtain the color to use from a look-up table that relates each shape to an + RGB value, and use the painter provided to draw the block at the specified + coordinates. +*/ diff --git a/doc/src/examples/textfinder.qdoc b/doc/src/examples/textfinder.qdoc new file mode 100644 index 0000000000..f5f41d72b7 --- /dev/null +++ b/doc/src/examples/textfinder.qdoc @@ -0,0 +1,159 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example uitools/textfinder + \title Text Finder Example + + The Text Finder example demonstrates how to dynamically process forms + using the QtUiTools module. Dynamic form processing enables a form to + be processed at run-time only by changing the UI file for the project. + The program allows the user to look up a particular word within the + contents of a text file. This text file is included in the project's + resource and is loaded into the display at startup. + + \table + \row \o \inlineimage textfinder-example-find.png + \o \inlineimage textfinder-example-find2.png + \endtable + + \section1 Setting Up The Resource File + + The resources required for Text Finder are: + \list + \o \e{textfinder.ui} - the user interface file created in QtDesigner + \o \e{input.txt} - a text file containing some text to be displayed + in the QTextEdit + \endlist + + \e{textfinder.ui} contains all the necessary QWidget objects for the + Text Finder. A QLineEdit is used for the user input, a QTextEdit is + used to display the contents of \e{input.txt}, a QLabel is used to + display the text "Keyword", and a QPushButton is used for the "Find" + button. The screenshot below shows the preview obtained in QtDesigner. + + \image textfinder-example-userinterface.png + + A \e{textfinder.qrc} file is used to store both the \e{textfinder.ui} + and \e{input.txt} in the application's executable. The file contains + the following code: + + \quotefile examples/uitools/textfinder/textfinder.qrc + + For more information on resource files, see \l{The Qt Resource System}. + + To generate a form at run-time, the example is linked against the + QtUiTools module library. This is done in the \c{textfinder.pro} file + that contains the following lines: + + \snippet doc/src/snippets/code/doc_src_examples_textfinder.pro 0 + + \section1 TextFinder Class Definition + + The \c TextFinder class is a subclass of QWidget and it hosts the + \l{QWidget}s we need to access in the user interface. The QLabel in the + user interface is not declared here as we do not need to access it. + + \snippet examples/uitools/textfinder/textfinder.h 0 + + The slot \c{on_findButton_clicked()} is a slot named according to the + \l{Using a Designer UI File in Your Application#Automatic Connections} + {Automatic Connection} naming convention required + by \c uic. + + \section1 TextFinder Class Implementation + + The \c TextFinder class's constructor calls the \c loadUiFile() function + and then uses \c qFindChild() to access the user interface's + \l{QWidget}s. + + \snippet examples/uitools/textfinder/textfinder.cpp 0 + + We then use QMetaObject's system to enable signal and slot connections. + + \snippet examples/uitools/textfinder/textfinder.cpp 2 + + The loadTextFile() function is called to load \c{input.txt} into + QTextEdit to displays its contents. + + \snippet examples/uitools/textfinder/textfinder.cpp 3a + + The \c{TextFinder}'s layout is set with \l{QWidget::}{setLayout()}. + + \snippet examples/uitools/textfinder/textfinder.cpp 3b + + Finally, the window title is set to \e {Text Finder} and \c isFirstTime is + set to true. + + \c isFirstTime is used as a flag to indicate whether the search operation + has been performed more than once. This is further explained with the + \c{on_findButton_clicked()} function. + + The \c{loadUiFile()} function is used to load the user interface file + previously created in QtDesigner. The QUiLoader class is instantiated + and its \c load() function is used to load the form into \c{formWidget} + that acts as a place holder for the user interface. The function then + returns \c{formWidget} to its caller. + + \snippet examples/uitools/textfinder/textfinder.cpp 4 + + As mentioned earlier, the loadTextFile() function loads \e{input.txt} + into QTextEdit to display its contents. Data is read using QTextStream + into a QString object, \c line with the QTextStream::readAll() function. + The contents of \c line are then appended to \c{ui_textEdit}. + + \snippet examples/uitools/textfinder/textfinder.cpp 5 + + The \c{on_findButton_clicked()} function is a slot that is connected to + \c{ui_findButton}'s \c clicked() signal. The \c searchString is extracted + from the \c ui_lineEdit and the \c document is extracted from \c textEdit. + In event there is an empty \c searchString, a QMessageBox is used, + requesting the user to enter a word. Otherwise, we traverse through the + words in \c ui_textEdit, and highlight all ocurrences of the + \c searchString . Two QTextCursor objects are used: One to traverse through + the words in \c line and another to keep track of the edit blocks. + + \snippet examples/uitools/textfinder/textfinder.cpp 7 + + The \c isFirstTime flag is set to false the moment \c findButton is + clicked. This is necessary to undo the previous text highlight before + highlighting the user's next search string. Also, the \c found flag + is used to indicate if the \c searchString was found within the contents + of \c ui_textEdit. If it was not found, a QMessageBox is used + to inform the user. + + \snippet examples/uitools/textfinder/textfinder.cpp 9 + + \section1 \c main() Function + + \snippet examples/uitools/textfinder/main.cpp 0 + + The \c main() function initialises the \e{textfinder.qrc} resource file + and instantiates as well as displays \c TextFinder. + + \sa{Calculator Builder Example}, {World Time Clock Builder Example} + */ diff --git a/doc/src/examples/textures.qdoc b/doc/src/examples/textures.qdoc new file mode 100644 index 0000000000..143b0dfc48 --- /dev/null +++ b/doc/src/examples/textures.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example opengl/textures + \title Textures Example + + The Textures example demonstrates the use of Qt's image classes as textures in + applications that use both OpenGL and Qt to display graphics. + + \image textures-example.png +*/ diff --git a/doc/src/examples/threadedfortuneserver.qdoc b/doc/src/examples/threadedfortuneserver.qdoc new file mode 100644 index 0000000000..285d7fd513 --- /dev/null +++ b/doc/src/examples/threadedfortuneserver.qdoc @@ -0,0 +1,107 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example network/threadedfortuneserver + \title Threaded Fortune Server Example + + The Threaded Fortune Server example shows how to create a server for a + simple network service that uses threads to handle requests from different + clients. It is intended to be run alongside the Fortune Client example. + + \image threadedfortuneserver-example.png + + The implementation of this example is similar to that of the + \l{network/fortuneserver}{Fortune Server} example, but here we will + implement a subclass of QTcpServer that starts each connection in a + different thread. + + For this we need two classes: FortuneServer, a QTcpServer subclass, and + FortuneThread, which inherits QThread. + + \snippet examples/network/threadedfortuneserver/fortuneserver.h 0 + + FortuneServer inherits QTcpServer and reimplements + QTcpServer::incomingConnection(). We also use it for storing the list of + random fortunes. + + \snippet examples/network/threadedfortuneserver/fortuneserver.cpp 0 + + We use FortuneServer's constructor to simply generate the list of + fortunes. + + \snippet examples/network/threadedfortuneserver/fortuneserver.cpp 1 + + Our implementation of QTcpServer::incomingConnection() creates a + FortuneThread object, passing the incoming socket descriptor and a random + fortune to FortuneThread's constructor. By connecting FortuneThread's + finished() signal to QObject::deleteLater(), we ensure that the thread + gets deleted once it has finished. We can then call QThread::start(), + which starts the thread. + + \snippet examples/network/threadedfortuneserver/fortunethread.h 0 + + Moving on to the FortuneThread class, this is a QThread subclass whose job + is to write the fortune to the connected socket. The class reimplements + QThread::run(), and it has a signal for reporting errors. + + \snippet examples/network/threadedfortuneserver/fortunethread.cpp 0 + + FortuneThread's constructor simply stores the socket descriptor and + fortune text, so that they are available for run() later on. + + \snippet examples/network/threadedfortuneserver/fortunethread.cpp 1 + + The first thing our run() function does is to create a QTcpSocket object + on the stack. What's worth noticing is that we are creating this object + inside the thread, which automatically associates the socket to the + thread's event loop. This ensures that Qt will not try to deliver events + to our socket from the main thread while we are accessing it from + FortuneThread::run(). + + \snippet examples/network/threadedfortuneserver/fortunethread.cpp 2 + + The socket is initialized by calling QTcpSocket::setSocketDescriptor(), + passing our socket descriptor as an argument. We expect this to succeed, + but just to be sure, (although unlikely, the system may run out of + resources,) we catch the return value and report any error. + + \snippet examples/network/threadedfortuneserver/fortunethread.cpp 3 + + As with the \l{network/fortuneserver}{Fortune Server} example, we encode + the fortune into a QByteArray using QDataStream. + + \snippet examples/network/threadedfortuneserver/fortunethread.cpp 4 + + But unlike the previous example, we finish off by calling + QTcpSocket::waitForDisconnected(), which blocks the calling thread until + the socket has disconnected. Because we are running in a separate thread, + the GUI will remain responsive. + + \sa {Fortune Server Example}, {Fortune Client Example}, {Blocking Fortune + Client Example} +*/ diff --git a/doc/src/examples/tooltips.qdoc b/doc/src/examples/tooltips.qdoc new file mode 100644 index 0000000000..5558fd2d15 --- /dev/null +++ b/doc/src/examples/tooltips.qdoc @@ -0,0 +1,394 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example widgets/tooltips + \title Tool Tips Example + + The Tool Tips example shows how to provide static and dynamic tool + tips for an application's widgets. + + The simplest and most common way to set a widget's tool tip is by + calling its QWidget::setToolTip() function (static tool + tips). Then the tool tip is shown whenever the cursor points at + the widget. We show how to do this with our application's tool + buttons. But it is also possible to show different tool tips + depending on the cursor's position (dynamic tooltips). This + approach uses mouse tracking and event handling to determine what + widgets are located under the cursor at any point in time, and + displays their tool tips. The tool tips for the shape items in our + application are implemented using the latter approach. + + \image tooltips-example.png + + With the \c Tooltips application the user can create new shape + items with the provided tool buttons, and move the items around + using the mouse. Tooltips are provided whenever the cursor is + pointing to a shape item or one of the buttons. + + The Tooltips example consists of two classes: + + \list + \o \c ShapeItem is a custom widget representing one single shape item. + \o \c SortingBox inherits from QWidget and is the application's main + widget. + \endlist + + First we will review the \c SortingBox class, then we will take a + look at the \c ShapeItem class. + + \section1 SortingBox Class Definition + + \snippet examples/widgets/tooltips/sortingbox.h 0 + + The \c SortingBox class inherits QWidget, and it is the Tooltips + application's main widget. We reimplement several of the event + handlers. + + The \c event() function provides tooltips, the \c resize() + function makes sure the application appears consistently when the + user resizes the main widget, and the \c paintEvent() function + displays the shape items within the \c SortingBox widget. The + mouse event handlers are reimplemented to make the user able to + move the items around. + + In addition we need three private slots to make the user able to + create new shape items. + + \snippet examples/widgets/tooltips/sortingbox.h 1 + + We also create several private functions: We use the \c + initialItemPosition(), \c initialItemColor() and \c + createToolButton() functions when we are constructing the widget, + and we use the \c updateButtonGeometry() function whenever the + user is resizing the application's main widget. + + The \c itemAt() function determines if there is a shape item at a + particular position, and the \c moveItemTo() function moves an + item to a new position. We use the \c createShapeItem(), \c + randomItemPosition() and \c randomItemColor() functions to create + new shape items. + + \snippet examples/widgets/tooltips/sortingbox.h 2 + + We keep all the shape items in a QList, and we keep three + QPainterPath objects holding the shapes of a circle, a square and + a triangle. We also need to have a pointer to an item when it is + moving, and we need to know its previous position. + + \section1 SortingBox Class Implementation + + \snippet examples/widgets/tooltips/sortingbox.cpp 0 + + In the constructor, we first set the Qt::WA_StaticContents + attribute on the widget. This attribute indicates that the widget + contents are north-west aligned and static. On resize, such a + widget will receive paint events only for the newly visible part + of itself. + + \snippet examples/widgets/tooltips/sortingbox.cpp 1 + + To be able to show the appropiate tooltips while the user is + moving the cursor around, we need to enable mouse tracking for the + widget. + + If mouse tracking is disabled (the default), the widget only + receives mouse move events when at least one mouse button is + pressed while the mouse is being moved. If mouse tracking is + enabled, the widget receives mouse move events even if no buttons + are pressed. + + \snippet examples/widgets/tooltips/sortingbox.cpp 2 + + A widget's background role defines the brush from the widget's + palette that is used to render the background, and QPalette::Base + is typically white. + + \snippet examples/widgets/tooltips/sortingbox.cpp 3 + + After creating the application's tool buttons using the private \c + createToolButton() function, we construct the shapes of a circle, + a square and a triangle using QPainterPath. + + The QPainterPath class provides a container for painting + operations, enabling graphical shapes to be constructed and + reused. The main advantage of painter paths over normal drawing + operations is that complex shapes only need to be created once, + but they can be drawn many times using only calls to + QPainter::drawPath(). + + \snippet examples/widgets/tooltips/sortingbox.cpp 4 + + Then we set the window title, resize the widget to a suitable + size, and finally create three initial shape items using the + private \c createShapeItem(), \c initialItemPosition() and \c + initialItemColor() functions. + + \snippet examples/widgets/tooltips/sortingbox.cpp 5 + + QWidget::event() is the main event handler and receives all the + widget's events. Normally, we recommend reimplementing one of the + specialized event handlers instead of this function. But here we + want to catch the QEvent::ToolTip events, and since these are + rather rare, there exists no specific event handler. For that + reason we reimplement the main event handler, and the first thing + we need to do is to determine the event's type: + + \snippet examples/widgets/tooltips/sortingbox.cpp 6 + + If the type is QEvent::ToolTip, we cast the event to a QHelpEvent, + otherwise we propagate the event using the QWidget::event() + function. + + The QHelpEvent class provides an event that is used to request + helpful information about a particular point in a widget. + + For example, the QHelpEvent::pos() function returns the event's + position relative to the widget to which the event is dispatched. + Here we use this information to determine if the position of the + event is contained within the area of any of the shape items. If + it is, we display the shape item's tooltip at the position of the + event. If not, we hide the tooltip and explicitly ignore the event. + This makes sure that the calling code does not start any tooltip + specific modes as a result of the event. Note that the + QToolTip::showText() function needs the event's position in global + coordinates provided by QHelpEvent::globalPos(). + + \snippet examples/widgets/tooltips/sortingbox.cpp 7 + + The \c resizeEvent() function is reimplemented to receive the + resize events dispatched to the widget. It makes sure that the + tool buttons keep their position relative to the main widget when + the widget is resized. We want the buttons to always be vertically + aligned in the application's bottom right corner, so each time the + main widget is resized we update the buttons geometry. + + \snippet examples/widgets/tooltips/sortingbox.cpp 8 + + The \c paintEvent() function is reimplemented to receive paint + events for the widget. We create a QPainter for the \c SortingBox + widget, and run through the list of created shape items, drawing + each item at its defined position. + + \snippet examples/widgets/tooltips/sortingbox.cpp 9 + + The painter will by default draw all the shape items at position + (0,0) in the \c SortingBox widget. The QPainter::translate() + function translates the coordinate system by the given offset, + making each shape item appear at its defined position. But + remember to translate the coordinate system back when the item is + drawn, otherwise the next shape item will appear at a position + relative to the item we drawed last. + + \snippet examples/widgets/tooltips/sortingbox.cpp 10 + + The QPainter::setBrush() function sets the current brush used by + the painter. When the provided argument is a QColor, the function + calls the appropiate QBrush constructor which creates a brush with + the specified color and Qt::SolidPattern style. The + QPainter::drawPath() function draws the given path using the + current pen for outline and the current brush for filling. + + \snippet examples/widgets/tooltips/sortingbox.cpp 11 + + The \c mousePressEvent() function is reimplemented to receive the + mouse press events dispatched to the widget. It determines if an + event's position is contained within the area of any of the shape + items, using the private \c itemAt() function. + + If an item covers the position, we store a pointer to that item + and the event's position. If several of the shape items cover the + position, we store the pointer to the uppermost item. Finally, we + move the shape item to the end of the list, and make a call to the + QWidget::update() function to make the item appear on top. + + The QWidget::update() function does not cause an immediate + repaint; instead it schedules a paint event for processing when Qt + returns to the main event loop. + + \snippet examples/widgets/tooltips/sortingbox.cpp 12 + + The \c mouseMoveEvent() function is reimplemented to receive mouse + move events for the widget. If the left mouse button is pressed + and there exists a shape item in motion, we use the private \c + moveItemTo() function to move the item with an offset + corresponding to the offset between the positions of the current + mouse event and the previous one. + + \snippet examples/widgets/tooltips/sortingbox.cpp 13 + + The \c mouseReleaseEvent() function is reimplemented to receive + the mouse release events dispatched to the widget. If the left + mouse button is pressed and there exists a shape item in motion, + we use the private \c moveItemTo() function to move the item like + we did in \c mouseMoveEvent(). But then we remove the pointer to + the item in motion, making the shape item's position final for + now. To move the item further, the user will need to press the + left mouse button again. + + \snippet examples/widgets/tooltips/sortingbox.cpp 14 + \codeline + \snippet examples/widgets/tooltips/sortingbox.cpp 15 + \codeline + \snippet examples/widgets/tooltips/sortingbox.cpp 16 + + The \c createNewCircle(), \c createNewSquare() and \c + createNewTriangle() slots simply create new shape items, using the + private \c createShapeItem(), \c randomItemPosition() and \c + randomItemColor() functions. + + \snippet examples/widgets/tooltips/sortingbox.cpp 17 + + In the \c itemAt() function, we run through the list of created + shape items to check if the given position is contained within the + area of any of the shape items. + + For each shape item we use the QPainterPath::contains() function + to find out if the item's painter path contains the position. If + it does we return the index of the item, otherwise we return + -1. We run through the list backwards to get the index of the + uppermost shape item in case several items cover the position. + + \snippet examples/widgets/tooltips/sortingbox.cpp 18 + + The \c moveItemTo() function moves the shape item in motion, and + the parameter \c pos is the position of a mouse event. First we + calculate the offset between the parameter \c pos and the previous + mouse event position. Then we add the offset to the current + position of the item in motion. + + It is tempting to simply set the position of the item to be the + parameter \c pos. But an item's position defines the top left + corner of the item's bounding rectangle, and the parameter \c pos + can be any point; The suggested shortcut would cause the item to + jump to a position where the cursor is pointing to the bounding + rectangle's top left corner, regardless of the item's previous + position. + + \snippet examples/widgets/tooltips/sortingbox.cpp 19 + + Finally, we update the previous mouse event position, and make a + call to the QWidget::update() function to make the item appear at + its new position. + + \snippet examples/widgets/tooltips/sortingbox.cpp 20 + + In the \c updateButtonGeometry() function we set the geometry for + the given button. The parameter coordinates define the bottom + right corner of the button. We use these coordinates and the + button's size hint to determine the position of the upper left + corner. This position, and the button's width and height, are the + arguments required by the QWidget::setGeometry() function. + + In the end, we calculate and return the y-coordinate of the bottom + right corner of the next button. We use the QWidget::style() + function to retrieve the widget's GUI style, and then + QStyle::pixelMetric() to determine the widget's preferred default + spacing between its child widgets. + + \snippet examples/widgets/tooltips/sortingbox.cpp 21 + + The \c createShapeItem() function creates a single shape item. It + sets the path, tooltip, position and color, using the item's own + functions. In the end, the function appends the new item to the + list of shape items, and calls the QWidget::update() function to + make it appear with the other items within the \c SortingBox + widget. + + \snippet examples/widgets/tooltips/sortingbox.cpp 22 + + The \c createToolButton() function is called from the \c + SortingBox constructor. We create a tool button with the given + tooltip and icon. The button's parent is the \c SortingBox widget, + and its size is 32 x 32 pixels. Before we return the button, we + connect it to the given slot. + + \snippet examples/widgets/tooltips/sortingbox.cpp 23 + + The \c initialItemPosition() function is also called from the + constructor. We want the three first items to initially be + centered in the middle of the \c SortingBox widget, and we use + this function to calculate their positions. + + \snippet examples/widgets/tooltips/sortingbox.cpp 24 + + Whenever the user creates a new shape item, we want the new item + to appear at a random position, and we use the \c + randomItemPosition() function to calculate such a position. We + make sure that the item appears within the visible area of the + \c SortingBox widget, using the widget's current width and heigth + when calculating the random coordinates. + + \snippet examples/widgets/tooltips/sortingbox.cpp 25 + + As with \c initialItemPosition(), the \c initialItemColor() + function is called from the constructor. The purposes of both + functions are purely cosmetic: We want to control the inital + position and color of the three first items. + + \snippet examples/widgets/tooltips/sortingbox.cpp 26 + + Finally the \c randomItemColor() function is implemented to give + the shape items the user creates, a random color. + + \section1 ShapeItem Class Definition + + \snippet examples/widgets/tooltips/shapeitem.h 0 + + The \c ShapeItem class is a custom widget representing one single + shape item. The widget has a path, a position, a color and a + tooltip. We need functions to set or modify these objects, as well + as functions that return them. We make the latter functions \c + const to prohibit any modifications of the objects, + i.e. prohibiting unauthorized manipulation of the shape items + appearance. + + \section1 ShapeItem Class Implementation + + \snippet examples/widgets/tooltips/shapeitem.cpp 0 + \codeline + \snippet examples/widgets/tooltips/shapeitem.cpp 1 + \codeline + \snippet examples/widgets/tooltips/shapeitem.cpp 2 + \codeline + \snippet examples/widgets/tooltips/shapeitem.cpp 3 + + This first group of functions simply return the objects that are + requested. The objects are returned as constants, i.e. they cannot + be modified. + + \snippet examples/widgets/tooltips/shapeitem.cpp 4 + \codeline + \snippet examples/widgets/tooltips/shapeitem.cpp 5 + \codeline + \snippet examples/widgets/tooltips/shapeitem.cpp 6 + \codeline + \snippet examples/widgets/tooltips/shapeitem.cpp 7 + + The last group of functions set or modify the shape item's path, + position, color and tooltip, respectively. +*/ diff --git a/doc/src/examples/torrent.qdoc b/doc/src/examples/torrent.qdoc new file mode 100644 index 0000000000..779e0b24a1 --- /dev/null +++ b/doc/src/examples/torrent.qdoc @@ -0,0 +1,69 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example network/torrent + \title Torrent Example + + The Torrent example is a functional BitTorrent client that + illustrates how to write a complex TCP/IP application using Qt. + + \image torrent-example.png + + \section1 License Information + + The implementation of the US Secure Hash Algorithm 1 (SHA1) in this example is + derived from the original description in \l{RFC 3174}. + + \legalese + Copyright (C) The Internet Society (2001). All Rights Reserved. + + This document and translations of it may be copied and furnished to + others, and derivative works that comment on or otherwise explain it + or assist in its implementation may be prepared, copied, published + and distributed, in whole or in part, without restriction of any + kind, provided that the above copyright notice and this paragraph are + included on all such copies and derivative works. However, this + document itself may not be modified in any way, such as by removing + the copyright notice or references to the Internet Society or other + Internet organizations, except as needed for the purpose of + developing Internet standards in which case the procedures for + copyrights defined in the Internet Standards process must be + followed, or as required to translate it into languages other than + English. + + The limited permissions granted above are perpetual and will not be + revoked by the Internet Society or its successors or assigns. + + This document and the information contained herein is provided on an + "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING + TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING + BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION + HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF + MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + \endlegalese +*/ diff --git a/doc/src/examples/trafficlight.qdoc b/doc/src/examples/trafficlight.qdoc new file mode 100644 index 0000000000..25cb198aeb --- /dev/null +++ b/doc/src/examples/trafficlight.qdoc @@ -0,0 +1,85 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example statemachine/trafficlight + \title Traffic Light Example + + The Traffic Light example shows how to use \l{The State Machine Framework} + to implement the control flow of a traffic light. + + \image trafficlight-example.png + + In this example we write a TrafficLightWidget class. The traffic light has + three lights: Red, yellow and green. The traffic light transitions from + one light to another (red to yellow to green to yellow to red again) at + certain intervals. + + \snippet examples/statemachine/trafficlight/main.cpp 0 + + The LightWidget class represents a single light of the traffic light. It + provides an \c on property and two slots, turnOn() and turnOff(), to turn + the light on and off, respectively. The widget paints itself in the color + that's passed to the constructor. + + \snippet examples/statemachine/trafficlight/main.cpp 1 + + The TrafficLightWidget class represents the visual part of the traffic + light; it's a widget that contains three lights arranged vertically, and + provides accessor functions for these. + + \snippet examples/statemachine/trafficlight/main.cpp 2 + + The createLightState() function creates a state that turns a light on when + the state is entered, and off when the state is exited. The state uses a + timer, and as we shall see the timeout is used to transition from one + LightState to another. Here is the statechart for the light state: + + \img trafficlight-example1.png + \omit + \caption This is a caption + \endomit + + \snippet examples/statemachine/trafficlight/main.cpp 3 + + The TrafficLight class combines the TrafficLightWidget with a state + machine. The state graph has four states: red-to-yellow, yellow-to-green, + green-to-yellow and yellow-to-red. The initial state is red-to-yellow; + when the state's timer times out, the state machine transitions to + yellow-to-green. The same process repeats through the other states. + This is what the statechart looks like: + + \img trafficlight-example2.png + \omit + \caption This is a caption + \endomit + + \snippet examples/statemachine/trafficlight/main.cpp 4 + + The main() function constructs a TrafficLight and shows it. + +*/ diff --git a/doc/src/examples/transformations.qdoc b/doc/src/examples/transformations.qdoc new file mode 100644 index 0000000000..ad4962f7d3 --- /dev/null +++ b/doc/src/examples/transformations.qdoc @@ -0,0 +1,371 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example painting/transformations + \title Transformations Example + + The Transformations example shows how transformations influence + the way that QPainter renders graphics primitives. In particular + it shows how the order of transformations affect the result. + + \image transformations-example.png + + The application allows the user to manipulate the rendering of a + shape by changing the translation, rotation and scale of + QPainter's coordinate system. + + The example consists of two classes and a global enum: + + \list + \o The \c RenderArea class controls the rendering of a given shape. + \o The \c Window class is the application's main window. + \o The \c Operation enum describes the various transformation + operations available in the application. + \endlist + + First we will take a quick look at the \c Operation enum, then we + will review the \c RenderArea class to see how a shape is + rendered. Finally, we will take a look at the Transformations + application's features implemented in the \c Window class. + + \section1 Transformation Operations + + Normally, the QPainter operates on the associated device's own + coordinate system, but it also has good support for coordinate + transformations. + + The default coordinate system of a paint device has its origin at + the top-left corner. The x values increase to the right and the y + values increase downwards. You can scale the coordinate system by + a given offset using the QPainter::scale() function, you can + rotate it clockwise using the QPainter::rotate() function and you + can translate it (i.e. adding a given offset to the points) using + the QPainter::translate() function. You can also twist the + coordinate system around the origin (called shearing) using the + QPainter::shear() function. + + All the tranformation operations operate on QPainter's + tranformation matrix that you can retrieve using the + QPainter::worldTransform() function. A matrix transforms a point in the + plane to another point. For more information about the + transformation matrix, see the \l {Coordinate System} and + QTransform documentation. + + \snippet examples/painting/transformations/renderarea.h 0 + + The global \c Operation enum is declared in the \c renderarea.h + file and describes the various transformation operations available + in the Transformations application. + + \section1 RenderArea Class Definition + + The \c RenderArea class inherits QWidget, and controls the + rendering of a given shape. + + \snippet examples/painting/transformations/renderarea.h 1 + + We declare two public functions, \c setOperations() and + \c setShape(), to be able to specify the \c RenderArea widget's shape + and to transform the coordinate system the shape is rendered + within. + + We reimplement the QWidget's \l + {QWidget::minimumSizeHint()}{minimumSizeHint()} and \l + {QWidget::sizeHint()}{sizeHint()} functions to give the \c + RenderArea widget a reasonable size within our application, and we + reimplement the QWidget::paintEvent() event handler to draw the + render area's shape applying the user's transformation choices. + + \snippet examples/painting/transformations/renderarea.h 2 + + We also declare several convenience functions to draw the shape, + the coordinate system's outline and the coordinates, and to + transform the painter according to the chosen transformations. + + In addition, the \c RenderArea widget keeps a list of the + currently applied transformation operations, a reference to its + shape, and a couple of convenience variables that we will use when + rendering the coordinates. + + \section1 RenderArea Class Implementation + + The \c RenderArea widget controls the rendering of a given shape, + including the transformations of the coordinate system, by + reimplementing the QWidget::paintEvent() event handler. But first + we will take a quick look at the constructor and at the functions + that provides access to the \c RenderArea widget: + + \snippet examples/painting/transformations/renderarea.cpp 0 + + In the constructor we pass the parent parameter on to the base + class, and customize the font that we will use to render the + coordinates. The QWidget::font() funtion returns the font + currently set for the widget. As long as no special font has been + set, or after QWidget::setFont() is called, this is either a + special font for the widget class, the parent's font or (if this + widget is a top level widget) the default application font. + + After ensuring that the font's size is 12 points, we extract the + rectangles enclosing the coordinate letters, 'x' and 'y', using the + QFontMetrics class. + + QFontMetrics provides functions to access the individual metrics + of the font, its characters, and for strings rendered in the + font. The QFontMetrics::boundingRect() function returns the + bounding rectangle of the given character relative to the + left-most point on the base line. + + \snippet examples/painting/transformations/renderarea.cpp 1 + \codeline + \snippet examples/painting/transformations/renderarea.cpp 2 + + In the \c setShape() and \c setOperations() functions we update + the \c RenderArea widget by storing the new value or values + followed by a call to the QWidget::update() slot which schedules a + paint event for processing when Qt returns to the main event loop. + + \snippet examples/painting/transformations/renderarea.cpp 3 + \codeline + \snippet examples/painting/transformations/renderarea.cpp 4 + + We reimplement the QWidget's \l + {QWidget::minimumSizeHint()}{minimumSizeHint()} and \l + {QWidget::sizeHint()}{sizeHint()} functions to give the \c + RenderArea widget a reasonable size within our application. The + default implementations of these functions returns an invalid size + if there is no layout for this widget, and returns the layout's + minimum size or preferred size, respectively, otherwise. + + \snippet examples/painting/transformations/renderarea.cpp 5 + + The \c paintEvent() event handler recieves the \c RenderArea + widget's paint events. A paint event is a request to repaint all + or part of the widget. It can happen as a result of + QWidget::repaint() or QWidget::update(), or because the widget was + obscured and has now been uncovered, or for many other reasons. + + First we create a QPainter for the \c RenderArea widget. The \l + {QPainter::RenderHint}{QPainter::Antialiasing} render hint + indicates that the engine should antialias edges of primitives if + possible. Then we erase the area that needs to be repainted using + the QPainter::fillRect() function. + + We also translate the coordinate system with an constant offset to + ensure that the original shape is renderend with a suitable + margin. + + \snippet examples/painting/transformations/renderarea.cpp 6 + + Before we start to render the shape, we call the QPainter::save() + function. + + QPainter::save() saves the current painter state (i.e. pushes the + state onto a stack) including the current coordinate system. The + rationale for saving the painter state is that the following call + to the \c transformPainter() function will transform the + coordinate system depending on the currently chosen transformation + operations, and we need a way to get back to the original state to + draw the outline. + + After transforming the coordinate system, we draw the \c + RenderArea's shape, and then we restore the painter state using + the QPainter::restore() function (i.e. popping the saved state off + the stack). + + \snippet examples/painting/transformations/renderarea.cpp 7 + + Then we draw the square outline. + + \snippet examples/painting/transformations/renderarea.cpp 8 + + Since we want the coordinates to correspond with the coordinate + system the shape is rendered within, we must make another call to + the \c transformPainter() function. + + The order of the painting operations is essential with respect to + the shared pixels. The reason why we don't render the coordinates + when the coordinate system already is transformed to render the + shape, but instead defer their rendering to the end, is that we + want the coordinates to appear on top of the shape and its + outline. + + There is no need to save the QPainter state this time since + drawing the coordinates is the last painting operation. + + \snippet examples/painting/transformations/renderarea.cpp 9 + \codeline + \snippet examples/painting/transformations/renderarea.cpp 10 + \codeline + \snippet examples/painting/transformations/renderarea.cpp 11 + + The \c drawCoordinates(), \c drawOutline() and \c drawShape() are + convenience functions called from the \c paintEvent() event + handler. For more information about QPainter's basic drawing + operations and how to display basic graphics primitives, see the + \l {painting/basicdrawing}{Basic Drawing} example. + + \snippet examples/painting/transformations/renderarea.cpp 12 + + The \c transformPainter() convenience function is also called from + the \c paintEvent() event handler, and transforms the given + QPainter's coordinate system according to the user's + transformation choices. + + \section1 Window Class Definition + + The \c Window class is the Transformations application's main + window. + + The application displays four \c RenderArea widgets. The left-most + widget renders the shape in QPainter's default coordinate system, + the others render the shape with the chosen transformation in + addition to all the transformations applied to the \c RenderArea + widgets to their left. + + \snippet examples/painting/transformations/window.h 0 + + We declare two public slots to make the application able to + respond to user interaction, updating the displayed \c RenderArea + widgets according to the user's transformation choices. + + The \c operationChanged() slot updates each of the \c RenderArea + widgets applying the currently chosen transformation operations, and + is called whenever the user changes the selected operations. The + \c shapeSelected() slot updates the \c RenderArea widgets' shapes + whenever the user changes the preferred shape. + + \snippet examples/painting/transformations/window.h 1 + + We also declare a private convenience function, \c setupShapes(), + that is used when constructing the \c Window widget, and we + declare pointers to the various components of the widget. We + choose to keep the available shapes in a QList of \l + {QPainterPath}s. In addition we declare a private enum counting + the number of displayed \c RenderArea widgets except the widget + that renders the shape in QPainter's default coordinate system. + + \section1 Window Class Implementation + + In the constructor we create and initialize the application's + components: + + \snippet examples/painting/transformations/window.cpp 0 + + First we create the \c RenderArea widget that will render the + shape in the default coordinate system. We also create the + associated QComboBox that allows the user to choose among four + different shapes: A clock, a house, a text and a truck. The shapes + themselves are created at the end of the constructor, using the + \c setupShapes() convenience function. + + \snippet examples/painting/transformations/window.cpp 1 + + Then we create the \c RenderArea widgets that will render their + shapes with coordinate tranformations. By default the applied + operation is \gui {No Transformation}, i.e. the shapes are + rendered within the default coordinate system. We create and + initialize the associated \l {QComboBox}es with items + corresponding to the various transformation operations decribed by + the global \c Operation enum. + + We also connect the \l {QComboBox}es' \l + {QComboBox::activated()}{activated()} signal to the \c + operationChanged() slot to update the application whenever the + user changes the selected transformation operations. + + \snippet examples/painting/transformations/window.cpp 2 + + Finally, we set the layout for the application window using the + QWidget::setLayout() function, construct the available shapes + using the private \c setupShapes() convenience function, and make + the application show the clock shape on startup using the public + \c shapeSelected() slot before we set the window title. + + + \snippet examples/painting/transformations/window.cpp 3 + \snippet examples/painting/transformations/window.cpp 4 + \snippet examples/painting/transformations/window.cpp 5 + \snippet examples/painting/transformations/window.cpp 6 + \dots + + \snippet examples/painting/transformations/window.cpp 7 + + The \c setupShapes() function is called from the constructor and + create the QPainterPath objects representing the shapes that are + used in the application. For construction details, see the \l + {painting/transformations/window.cpp}{window.cpp} example + file. The shapes are stored in a QList. The QList::append() + function inserts the given shape at the end of the list. + + We also connect the associated QComboBox's \l + {QComboBox::activated()}{activated()} signal to the \c + shapeSelected() slot to update the application when the user + changes the preferred shape. + + \snippet examples/painting/transformations/window.cpp 8 + + The public \c operationChanged() slot is called whenever the user + changes the selected operations. + + We retrieve the chosen transformation operation for each of the + transformed \c RenderArea widgets by querying the associated \l + {QComboBox}{QComboBoxes}. The transformed \c RenderArea widgets + are supposed to render the shape with the transformation specified + by its associated combobox \e {in addition to} all the + transformations applied to the \c RenderArea widgets to its + left. For that reason, for each widget we query, we append the + associated operation to a QList of transformations which we apply + to the widget before proceeding to the next. + + \snippet examples/painting/transformations/window.cpp 9 + + The \c shapeSelected() slot is called whenever the user changes + the preferred shape, updating the \c RenderArea widgets using + their public \c setShape() function. + + \section1 Summary + + The Transformations example shows how transformations influence + the way that QPainter renders graphics primitives. Normally, the + QPainter operates on the device's own coordinate system, but it + also has good support for coordinate transformations. With the + Transformations application you can scale, rotate and translate + QPainter's coordinate system. The order in which these + tranformations are applied is essential for the result. + + All the tranformation operations operate on QPainter's + tranformation matrix. For more information about the + transformation matrix, see the \l {Coordinate System} and + QTransform documentation. + + The Qt reference documentation provides several painting + demos. Among these is the \l {demos/affine}{Affine + Transformations} demo that shows Qt's ability to perform + transformations on painting operations. The demo also allows the + user to experiment with the various transformation operations. +*/ diff --git a/doc/src/examples/treemodelcompleter.qdoc b/doc/src/examples/treemodelcompleter.qdoc new file mode 100644 index 0000000000..6e9840a476 --- /dev/null +++ b/doc/src/examples/treemodelcompleter.qdoc @@ -0,0 +1,171 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example tools/treemodelcompleter + \title Tree Model Completer Example + + The Tree Model Completer example shows how to provide completion + facilities for a hierarchical model, using a period as the separator + to access Child, GrandChild and GrandGrandChild level objects. + + \image treemodelcompleter-example.png + + Similar to the \l{Completer Example}, we provide QComboBox objects to + enable selection for completion mode and case sensitivity, as well as + a QCheckBox for wrap completions. + + \section1 The Resource File + + The contents of the TreeModelCompleter is read from \e treemodel.txt. + This file is embedded within the \e treemodelcompleter.qrc resource file, + which contains the following: + + \quotefile examples/tools/treemodelcompleter/treemodelcompleter.qrc + + \section1 TreeModelCompleter Class Definition + + The \c TreeModelCompleter is a subclass of QCompleter with two + constructors - one with \a parent as an argument and another with + \a parent and \a model as arguments. + + \snippet examples/tools/treemodelcompleter/treemodelcompleter.h 0 + + The class reimplements the protected functions + \l{QCompleter::splitPath()}{splitPath()} and + \l{QCompleter::pathFromIndex()}{pathFromIndex()} to suit a tree model. + For more information on customizing QCompleter to suit tree models, refer + to \l{QCompleter#Handling Tree Models}{Handling Tree Models}. + + \c TreeModelCompleter also has a separator property which is declared + using the Q_PROPERTY() macro. The separator has READ and WRITE attributes + and the corresponding functions \c separator() and \c setSeparator(). For + more information on Q_PROPERTY(), refer to \l{Qt's Property System}. + + \section1 TreeModelCompleter Class Implementation + + The first constructor constructs a \c TreeModelCompleter object with a + parent while the second constructor constructs an object with a parent + and a QAbstractItemModel, \a model. + + \snippet examples/tools/treemodelcompleter/treemodelcompleter.cpp 0 + \codeline + \snippet examples/tools/treemodelcompleter/treemodelcompleter.cpp 1 + + The \c separator() function is a getter function that returns the + separator string. + + \snippet examples/tools/treemodelcompleter/treemodelcompleter.cpp 2 + + As mentioned earlier, the \c splitPath() function is reimplemented because + the default implementation is more suited to QDirModel or list models. In + order for QCompleter to split the path into a list of strings that are + matched at each level, we split it using QString::split() with \c sep as its + separator. + + \snippet examples/tools/treemodelcompleter/treemodelcompleter.cpp 3 + + The \c pathFromIndex() function returns data for the completionRole() for a + tree model. This function is reimplemented as its default implementation is + more suitable for list models. If there is no separator, we use + \l{QCompleter}'s default implementation, otherwise we use the + \l{QStringList::prepend()}{prepend()} function to navigate upwards and + accumulate the data. The function then returns a QStringList, \c dataList, + using a separator to join objects of different levels. + + \snippet examples/tools/treemodelcompleter/treemodelcompleter.cpp 4 + + \section1 MainWindow Class Definition + + The \c MainWindow class is a subclass of QMainWindow and implements five + custom slots: \c about(), \c changeCase(), \c changeMode(), + \c highlight(), and \c updateContentsLabel(). + + \snippet examples/tools/treemodelcompleter/mainwindow.h 0 + + In addition, the class has two private functions, \c createMenu() and + \c modelFromFile(), as well as private instances of QTreeView, QComboBox, + QLabel, \c TreeModelCompleter and QLineEdit. + + \snippet examples/tools/treemodelcompleter/mainwindow.h 1 + + \section1 MainWindow Class Implementation + + The \c{MainWindow}'s constructor creates a \c MainWindow object with a + parent and initializes the \c completer and \c lineEdit. The + \c createMenu() function is invoked to set up the "File" menu and "Help" + menu. The \c{completer}'s model is set to the QAbstractItemModel obtained + from \c modelFromFile(), and the \l{QCompleter::highlighted()} + {highlighted()} signal is connected to \c{MainWindow}'s \c highlight() + slot. + + \snippet examples/tools/treemodelcompleter/mainwindow.cpp 0 + + The QLabel objects \c modelLabel, \c modeLabel and \c caseLabel are + instantiated. Also, the QComboBox objects, \c modeCombo and \c caseCombo, + are instantiated and populated. By default, the \c{completer}'s mode is + "Filtered Popup" and the case is insensitive. + + \snippet examples/tools/treemodelcompleter/mainwindow.cpp 1 + \codeline + \snippet examples/tools/treemodelcompleter/mainwindow.cpp 2 + + We use a QGridLayout to place all the objects in the \c MainWindow. + + \snippet examples/tools/treemodelcompleter/mainwindow.cpp 3 + + The \c createMenu() function sets up the QAction objects required and + adds them to the "File" menu and "Help" menu. The + \l{QAction::triggered()}{triggered()} signals from these actions are + connected to their respective slots. + + \snippet examples/tools/treemodelcompleter/mainwindow.cpp 4 + + The \c changeMode() function accepts an \a index corresponding to the + user's choice of completion mode and changes the \c{completer}'s mode + accordingly. + + \snippet examples/tools/treemodelcompleter/mainwindow.cpp 5 + + The \c about() function provides a brief description on the Tree Model + Completer example. + + \snippet examples/tools/treemodelcompleter/mainwindow.cpp 6 + + The \c changeCase() function alternates between \l{Qt::CaseSensitive} + {Case Sensitive} and \l{Qt::CaseInsensitive}{Case Insensitive} modes, + depending on the value of \a cs. + + \snippet examples/tools/treemodelcompleter/mainwindow.cpp 7 + + \section1 \c main() Function + + The \c main() function instantiates \c MainWindow and invokes the + \l{QWidget::show()}{show()} function to display it. + + \snippet examples/tools/treemodelcompleter/main.cpp 0 +*/ diff --git a/doc/src/examples/trivialwizard.qdoc b/doc/src/examples/trivialwizard.qdoc new file mode 100644 index 0000000000..ceea18db55 --- /dev/null +++ b/doc/src/examples/trivialwizard.qdoc @@ -0,0 +1,82 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example dialogs/trivialwizard + \title Trivial Wizard Example + + The Trivial Wizard example illustrates how to create a linear three-page + registration wizard using three instances of QWizardPage and one instance + of QWizard. + + \image trivialwizard-example-flow.png + + \section1 Introduction Page + + \image trivialwizard-example-introduction.png + + The introduction page is created with the \c createIntroPage() + function where a QWizardPage is created and its title is set to + "Introduction". A QLabel is used to hold the description of \c page. + A QVBoxLayout is used to hold the \c label. This \c page is returned + when the \c createIntroPage() function is called. + + \snippet examples/dialogs/trivialwizard/trivialwizard.cpp 0 + + \section1 Registration Page + + \image trivialwizard-example-registration.png + + The registration page is created with the \c createRegistrationPage() + function. QLineEdit objects are used to allow the user to input a name + and an e-mail address. A QGridLayout is used to hold the QLabel and + QLineEdit objects. + + \snippet examples/dialogs/trivialwizard/trivialwizard.cpp 2 + + \section1 Conclusion Page + + \image trivialwizard-example-conclusion.png + + The conclusion page is created in the \c createConclusionPage() + function. This function's content is similar to \c createIntroPage(). A + QLabel is used to inform the user that the registration process has + completed successfully. + + \snippet examples/dialogs/trivialwizard/trivialwizard.cpp 6 + + \section1 \c main() Function + + The \c main() function instantiates a QWizard object, \c wizard, and + adds all three QWizardPage objects to it. The \c wizard window title is + set to "Trivial Wizard" and its \c show() function is invoked to display + it. + + \snippet examples/dialogs/trivialwizard/trivialwizard.cpp 10 + + \sa QWizard, {Class Wizard Example}, {License Wizard Example} +*/ diff --git a/doc/src/examples/trollprint.qdoc b/doc/src/examples/trollprint.qdoc new file mode 100644 index 0000000000..a93811e890 --- /dev/null +++ b/doc/src/examples/trollprint.qdoc @@ -0,0 +1,261 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example linguist/trollprint + \title Troll Print Example + + Troll Print is an example application that lets the user choose + printer settings. It comes in two versions: English and + Portuguese. + + \image linguist-trollprint_10_en.png + + We've included a translation file, \c trollprint_pt.ts, which contains some + Portuguese translations for this example. + + We will consider two releases of the same application: Troll Print + 1.0 and 1.1. We will learn to reuse the translations created for one + release in a subsequent release. (In this tutorial, you need to edit + some source files. It's probably best to copy all the files to a new + temporary directory and work from there.) + + See the \l{Qt Linguist manual} for more information about + translating Qt application. + + \section1 Line by Line Walkthrough + + The \c PrintPanel class is defined in \c printpanel.h. + + \snippet examples/linguist/trollprint/printpanel.h 0 + + \c PrintPanel is a QWidget. It needs the \c Q_OBJECT macro for \c + tr() to work properly. + + The implementation file is \c printpanel.cpp. + + \snippet examples/linguist/trollprint/printpanel.cpp 0 + + Some of the code is commented out in Troll Print 1.0; you will + uncomment it later, for Troll Print 1.1. + + \snippet examples/linguist/trollprint/printpanel.cpp 1 + \snippet examples/linguist/trollprint/printpanel.cpp 2 + + Notice the two occurrences of \c tr("Enabled") and of \c + tr("Disabled") in PrintPanel. Since both "Enabled"s and "Disabled"s + appear in the same context \e {Qt Linguist} will only display one + occurrence of each and will use the same translations for the + duplicates that it doesn't display. Whilst this is a useful + timesaver, in some languages, such as Portuguese, the second + occurrence requires a separate translation. We will see how \e {Qt + Linguist} can be made to display all the occurrences for separate + translation shortly. + + The header file for \c MainWindow, \c mainwindow.h, contains no + surprises. In the implementation, \c mainwindow.cpp, we have some + user-visible source texts that must be marked for translation. + + \snippet examples/linguist/trollprint/mainwindow.cpp 0 + + We must translate the window title. + + \snippet examples/linguist/trollprint/mainwindow.cpp 1 + \snippet examples/linguist/trollprint/mainwindow.cpp 3 + + We also need to translate the actions and menus. Note that the + two argument form of \c tr() is used for the keyboard + accelerator, "Ctrl+Q", since the second argument is the only clue + the translator has to indicate what function that accelerator + will perform. + + \snippet examples/linguist/trollprint/main.cpp 0 + + The \c main() function in \c main.cpp is the same as the one in + the \l{linguist/arrowpad}{Arrow Pad} example. In particular, it + chooses a translation file based on the current locale. + + \section1 Running Troll Print 1.0 in English and in Portuguese + + We will use the translations in the \c trollprint_pt.ts file that is provided. + + Set the \c LANG environment variable to \c pt, and then run \c + trollprint. You should still see the English version. Now run \c + lrelease, e.g. \c {lrelease trollprint.pro}, and then run the + example again. Now you should see the Portuguese edition (Troll + Imprimir 1.0): + + \image linguist-trollprint_10_pt_bad.png + + Whilst the translation has appeared correctly, it is in fact wrong. In + good Portuguese, the second occurrence of "Enabled" should be + "Ativadas", not "Ativado" and the ending for the second translation of + "Disabled" must change similarly too. + + If you open \c trollprint_pt.ts using \e {Qt Linguist}, you will see that + there is just one occurrence of "Enabled" and of "Disabled" in the + translation source file, even though there are two of each in the + source code. This is because \e {Qt Linguist} tries to minimize the + translator's work by using the same translation for duplicate source + texts. In cases such as this where an identical translation is wrong, + the programmer must disambiguate the duplicate occurrences. This is + easily achieved by using the two argument form of \c tr(). + + We can easily determine which file must be changed because the + translator's "context" is in fact the class name for the class where + the texts that must be changed appears. In this case the file is \c + printpanel.cpp, where there are four lines to change. Add the + second argument "two-sided" in the appropriate \c tr() calls to the + first pair of radio buttons: + + \snippet doc/src/snippets/code/doc_src_examples_trollprint.cpp 0 + + and add the second argument "colors" in the appropriate \c tr() calls + for the second pair of radio buttons: + + \snippet doc/src/snippets/code/doc_src_examples_trollprint.cpp 1 + + Now run \c lupdate and open \c trollprint_pt.ts with \e {Qt Linguist}. You + should now see two changes. + + First, the translation source file now contains \e three "Enabled", + "Disabled" pairs. The first pair is marked "(obs.)" signifying that they + are obsolete. This is because these texts appeared in \c tr() calls that + have been replaced by new calls with two arguments. The second pair has + "two-sided" as their comment, and the third pair has "colors" as their + comment. The comments are shown in the \gui {Source text and comments} + area in \e {Qt Linguist}. + + Second, the translation text "Ativado" and "Desativado" have been + automatically used as translations for the new "Enabled" and "Disabled" + texts, again to minimize the translator's work. Of course in this case + these are not correct for the second occurrence of each word, but they + provide a good starting point. + + Change the second "Ativado" into "Ativadas" and the second + "Desativado" into "Desativadas", then save and quit. Run \c lrelease + to obtain an up-to-date binary \c trollprint_pt.qm file, and run Troll Print + (or rather Troll Imprimir). + + \image linguist-trollprint_10_pt_good.png + + The second argument to \c tr() calls, called "comments" in \e {Qt + Linguist}, distinguish between identical source texts that occur in + the same context (class). They are also useful in other cases to give + clues to the translator, and in the case of Ctrl key accelerators are + the only means of conveying the function performed by the accelerator to + the translator. + + An additional way of helping the translator is to provide information on + how to navigate to the particular part of the application that contains + the source texts they must translate. This helps them see the context + in which the translation appears and also helps them to find and test + the translations. This can be achieved by using a \c TRANSLATOR comment + in the source code: + + \snippet doc/src/snippets/code/doc_src_examples_trollprint.cpp 2 + + Try adding these comments to some source files, particularly to + dialog classes, describing the navigation necessary to reach the + dialogs. You could also add them to the example files, e.g. \c + mainwindow.cpp and \c printpanel.cpp are appropriate files. Run \c + lupdate and then start \e {Qt Linguist} and load in \c trollprint_pt.ts. + You should see the comments in the \gui {Source text and comments} area + as you browse through the list of source texts. + + Sometimes, particularly with large programs, it can be difficult for + the translator to find their translations and check that they're + correct. Comments that provide good navigation information can save + them time: + + \snippet doc/src/snippets/code/doc_src_examples_trollprint.cpp 3 + + \section1 Troll Print 1.1 + + We'll now prepare release 1.1 of Troll Print. Start your favorite text + editor and follow these steps: + + \list + \o Uncomment the two lines that create a QLabel with the text + "\<b\>TROLL PRINT\</b\>" in \c printpanel.cpp. + \o Word-tidying: Replace "2-sided" by "Two-sided" in \c printpanel.cpp. + \o Replace "1.0" with "1.1" everywhere it occurs in \c mainwindow.cpp. + \o Update the copyright year to 1999-2000 in \c mainwindow.cpp. + \endlist + + (Of course the version number and copyright year would be consts or + #defines in a real application.) + + Once finished, run \c lupdate, then open \c trollprint_pt.ts in \e {Qt + Linguist}. The following items are of special interest: + + \list + \o \c MainWindow + \list + \o Troll Print 1.0 - marked "(obs.)", obsolete + \o About Troll Print 1.0 - marked "(obs.)", obsolete + \o Troll Print 1.0. Copyright 1999 Software, Inc. - + marked obsolete + \o Troll Print 1.1 - automatically translated as + "Troll Imprimir 1.1" + \o About Troll Print 1.1 - automatically translated as + "Troll Imprimir 1.1" + \o Troll Print 1.1. Copyright 1999-2000 Software, + Inc. - automatically translated as "Troll Imprimir 1.1. + Copyright 1999-2000 Software, Inc." + \endlist + \o \c PrintPanel + \list + \o 2-sided - marked "(obs.)", obsolete + \o \<b\>TROLL PRINT\</b\> - unmarked, i.e. untranslated + \o Two-sided - unmarked, i.e. untranslated. + \endlist + \endlist + + Notice that \c lupdate works hard behind the scenes to make revisions + easier, and it's pretty smart with numbers. + + Go over the translations in \c MainWindow and mark these as "done". + Translate "\<b\>TROLL PRINT\</b\>" as "\<b\>TROLL IMPRIMIR\</b\>". + When you're translating "Two-sided", press the \gui {Guess Again} + button to translate "Two-sided", but change the "2" into "Dois". + + Save and quit, then run \c lrelease. The Portuguese version + should look like this: + + \image linguist-trollprint_11_pt.png + + Choose \gui{Ajuda|Sobre} (\gui{Help|About}) to see the about box. + + If you choose \gui {Ajuda|Sobre Qt} (\gui {Help|About Qt}), you'll get + an English dialog. Oops! Qt itself needs to be translated. See + \l{Internationalization with Qt} for details. + + Now set \c LANG=en to get the original English version: + + \image linguist-trollprint_11_en.png +*/ diff --git a/doc/src/examples/twowaybutton.qdoc b/doc/src/examples/twowaybutton.qdoc new file mode 100644 index 0000000000..e5fe4391a5 --- /dev/null +++ b/doc/src/examples/twowaybutton.qdoc @@ -0,0 +1,68 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example statemachine/twowaybutton + \title Two-way Button Example + + The Two-way button example shows how to use \l{The State Machine + Framework} to implement a simple state machine that toggles the current + state when a button is clicked. + + \snippet examples/statemachine/twowaybutton/main.cpp 0 + + The application's main() function begins by constructing the application + object, a button and a state machine. + + \snippet examples/statemachine/twowaybutton/main.cpp 1 + + The state machine has two states; \c on and \c off. When either state is + entered, the text of the button will be set accordingly. + + \snippet examples/statemachine/twowaybutton/main.cpp 2 + + When the state machine is in the \c off state and the button is clicked, + it will transition to the \c on state; when the state machine is in the \c + on state and the button is clicked, it will transition to the \c off + state. + + \snippet examples/statemachine/twowaybutton/main.cpp 3 + + The states are added to the state machine; they become top-level (sibling) + states. + + \snippet examples/statemachine/twowaybutton/main.cpp 4 + + The initial state is \c off; this is the state the state machine will + immediately transition to once the state machine is started. + + \snippet examples/statemachine/twowaybutton/main.cpp 5 + + Finally, the button is resized and made visible, and the application event + loop is entered. + +*/ diff --git a/doc/src/examples/undoframework.qdoc b/doc/src/examples/undoframework.qdoc new file mode 100644 index 0000000000..65104bd921 --- /dev/null +++ b/doc/src/examples/undoframework.qdoc @@ -0,0 +1,291 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example tools/undoframework + \title Undo Framework Example + + This example shows how to implement undo/redo functionality + with the Qt undo framework. + + \image undoframeworkexample.png The Undo Diagram Example + + In the Qt undo framework, all actions that the user performs are + implemented in classes that inherit QUndoCommand. An undo command + class knows how to both \l{QUndoCommand::}{redo()} - or just do + the first time - and \l{QUndoCommand::}{undo()} an action. For + each action the user performs, a command is placed on a + QUndoStack. Since the stack contains all commands executed + (stacked in chronological order) on the document, it can roll the + state of the document backwards and forwards by undoing and redoing + its commands. See the \l{Overview of Qt's Undo Framework}{overview + document} for a high-level introduction to the undo framework. + + The undo example implements a simple diagram application. It is + possible to add and delete items, which are either box or + rectangular shaped, and move the items by dragging them with the + mouse. The undo stack is shown in a QUndoView, which is a list in + which the commands are shown as list items. Undo and redo are + available through the edit menu. The user can also select a command + from the undo view. + + We use the \l{Graphics View Framework}{graphics view + framework} to implement the diagram. We only treat the related + code briefly as the framework has examples of its own (e.g., the + \l{Diagram Scene Example}). + + The example consists of the following classes: + + \list + \o \c MainWindow is the main window and arranges the + example's widgets. It creates the commands based + on user input and keeps them on the command stack. + \o \c AddCommand adds an item to the scene. + \o \c DeleteCommand deletes an item from the scene. + \o \c MoveCommand when an item is moved the MoveCommand keeps record + of the start and stop positions of the move, and it + moves the item according to these when \c redo() and \c undo() + is called. + \o \c DiagramScene inherits QGraphicsScene and + emits signals for the \c MoveComands when an item is moved. + \o \c DiagramItem inherits QGraphicsPolygonItem and represents + an item in the diagram. + \endlist + + \section1 MainWindow Class Definition + + \snippet examples/tools/undoframework/mainwindow.h 0 + + The \c MainWindow class maintains the undo stack, i.e., it creates + \l{QUndoCommand}s and pushes and pops them from the stack when it + receives the \c triggered() signal from \c undoAction and \c + redoAction. + + \section1 MainWindow Class Implementation + + We will start with a look at the constructor: + + \snippet examples/tools/undoframework/mainwindow.cpp 0 + + In the constructor, we set up the DiagramScene and QGraphicsView. + + Here is the \c createUndoView() function: + + \snippet examples/tools/undoframework/mainwindow.cpp 1 + + The QUndoView is a widget that display the text, which is set with + the \l{QUndoCommand::}{setText()} function, for each QUndoCommand + in the undo stack in a list. + + Here is the \c createActions() function: + + \snippet examples/tools/undoframework/mainwindow.cpp 2 + \codeline + \snippet examples/tools/undoframework/mainwindow.cpp 3 + \dots + \snippet examples/tools/undoframework/mainwindow.cpp 5 + + The \c createActions() function sets up all the examples actions + in the manner shown above. The + \l{QUndoStack::}{createUndoAction()} and + \l{QUndoStack::}{createRedoAction()} helps us crate actions that + are disabled and enabled based on the state of the stack. Also, + the text of the action will be updated automatically based on the + \l{QUndoCommand::}{text()} of the undo commands. For the other + actions we have implemented slots in the \c MainWindow class. + + Here is the \c createMenus() function: + + \snippet examples/tools/undoframework/mainwindow.cpp 6 + + \dots + \snippet examples/tools/undoframework/mainwindow.cpp 7 + \dots + \snippet examples/tools/undoframework/mainwindow.cpp 8 + + We have to use the QMenu \c aboutToShow() and \c aboutToHide() + signals since we only want \c deleteAction to be enabled when we + have selected an item. + + Here is the \c itemMoved() slot: + + \snippet examples/tools/undoframework/mainwindow.cpp 9 + + We simply push a MoveCommand on the stack, which calls \c redo() + on it. + + Here is the \c deleteItem() slot: + + \snippet examples/tools/undoframework/mainwindow.cpp 10 + + An item must be selected to be deleted. We need to check if it is + selected as the \c deleteAction may be enabled even if an item is + not selected. This can happen as we do not catch a signal or event + when an item is selected. + + Here is the \c itemMenuAboutToShow() and itemMenuAboutToHide() slots: + + \snippet examples/tools/undoframework/mainwindow.cpp 11 + \codeline + \snippet examples/tools/undoframework/mainwindow.cpp 12 + + We implement \c itemMenuAboutToShow() and \c itemMenuAboutToHide() + to get a dynamic item menu. These slots are connected to the + \l{QMenu::}{aboutToShow()} and \l{QMenu::}{aboutToHide()} signals. + We need this to disable or enable the \c deleteAction. + + Here is the \c addBox() slot: + + \snippet examples/tools/undoframework/mainwindow.cpp 13 + + The \c addBox() function creates an AddCommand and pushes it on + the undo stack. + + Here is the \c addTriangle() sot: + + \snippet examples/tools/undoframework/mainwindow.cpp 14 + + The \c addTriangle() function creates an AddCommand and pushes it + on the undo stack. + + Here is the implementation of \c about(): + + \snippet examples/tools/undoframework/mainwindow.cpp 15 + + The about slot is triggered by the \c aboutAction and displays an + about box for the example. + + \section1 AddCommand Class Definition + + \snippet examples/tools/undoframework/commands.h 2 + + The \c AddCommand class adds DiagramItem graphics items to the + DiagramScene. + + \section1 AddCommand Class Implementation + + We start with the constructor: + + \snippet examples/tools/undoframework/commands.cpp 7 + + We first create the DiagramItem to add to the DiagramScene. The + \l{QUndoCommand::}{setText()} function let us set a QString that + describes the command. We use this to get custom messages in the + QUndoView and in the menu of the main window. + + \snippet examples/tools/undoframework/commands.cpp 8 + + \c undo() removes the item from the scene. + + \snippet examples/tools/undoframework/commands.cpp 9 + + We set the position of the item as we do not do this in the + constructor. + + \section1 DeleteCommand Class Definition + + \snippet examples/tools/undoframework/commands.h 1 + + The DeleteCommand class implements the functionality to remove an + item from the scene. + + \section1 DeleteCommand Class Implementation + + \snippet examples/tools/undoframework/commands.cpp 4 + + We know that there must be one selected item as it is not possible + to create a DeleteCommand unless the item to be deleted is + selected and that only one item can be selected at any time. + The item must be unselected if it is inserted back into the + scene. + + \snippet examples/tools/undoframework/commands.cpp 5 + + The item is simply reinserted into the scene. + + \snippet examples/tools/undoframework/commands.cpp 6 + + The item is removed from the scene. + + \section1 MoveCommand Class Definition + + \snippet examples/tools/undoframework/commands.h 0 + + The \l{QUndoCommand::}{mergeWith()} is reimplemented to make + consecutive moves of an item one MoveCommand, i.e, the item will + be moved back to the start position of the first move. + + \section1 MoveCommand Class Implementation + + + The constructor of MoveCommand looks like this: + + \snippet examples/tools/undoframework/commands.cpp 0 + + We save both the old and new positions for undo and redo + respectively. + + \snippet examples/tools/undoframework/commands.cpp 2 + + We simply set the items old position and update the scene. + + \snippet examples/tools/undoframework/commands.cpp 3 + + We set the item to its new position. + + \snippet examples/tools/undoframework/commands.cpp 1 + + Whenever a MoveCommand is created, this function is called to + check if it should be merged with the previous command. It is the + previous command object that is kept on the stack. The function + returns true if the command is merged; otherwise false. + + We first check whether it is the same item that has been moved + twice, in which case we merge the commands. We update the position + of the item so that it will take the last position in the move + sequence when undone. + + \section1 DiagramScene Class Definition + + \snippet examples/tools/undoframework/diagramscene.h 0 + + The DiagramScene implements the functionality to move a + DiagramItem with the mouse. It emits a signal when a move is + completed. This is caught by the \c MainWindow, which makes + MoveCommands. We do not examine the implementation of DiagramScene + as it only deals with graphics framework issues. + + \section1 The \c main() Function + + The \c main() function of the program looks like this: + + \snippet examples/tools/undoframework/main.cpp 0 + + We draw a grid in the background of the DiagramScene, so we use a + resource file. The rest of the function creates the \c MainWindow and + shows it as a top level window. +*/ diff --git a/doc/src/examples/waitconditions.qdoc b/doc/src/examples/waitconditions.qdoc new file mode 100644 index 0000000000..f43d5e77ec --- /dev/null +++ b/doc/src/examples/waitconditions.qdoc @@ -0,0 +1,152 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example threads/waitconditions + \title Wait Conditions Example + + The Wait Conditions example shows how to use QWaitCondition and + QMutex to control access to a circular buffer shared by a + producer thread and a consumer thread. + + The producer writes data to the buffer until it reaches the end + of the buffer, at which point it restarts from the beginning, + overwriting existing data. The consumer thread reads the data as + it is produced and writes it to standard error. + + Wait conditions make it possible to have a higher level of + concurrency than what is possible with mutexes alone. If accesses + to the buffer were simply guarded by a QMutex, the consumer + thread couldn't access the buffer at the same time as the + producer thread. Yet, there is no harm in having both threads + working on \e{different parts} of the buffer at the same time. + + The example comprises two classes: \c Producer and \c Consumer. + Both inherit from QThread. The circular buffer used for + communicating between these two classes and the synchronization + tools that protect it are global variables. + + An alternative to using QWaitCondition and QMutex to solve the + producer-consumer problem is to use QSemaphore. This is what the + \l{threads/semaphores}{Semaphores} example does. + + \section1 Global Variables + + Let's start by reviewing the circular buffer and the associated + synchronization tools: + + \snippet examples/threads/waitconditions/waitconditions.cpp 0 + + \c DataSize is the amount of data that the producer will generate. + To keep the example as simple as possible, we make it a constant. + \c BufferSize is the size of the circular buffer. It is less than + \c DataSize, meaning that at some point the producer will reach + the end of the buffer and restart from the beginning. + + To synchronize the producer and the consumer, we need two wait + conditions and one mutex. The \c bufferNotEmpty condition is + signalled when the producer has generated some data, telling the + consumer that it can start reading it. The \c bufferNotFull + condition is signalled when the consumer has read some data, + telling the producer that it can generate more. The \c numUsedBytes + is the number of bytes in the buffer that contain data. + + Together, the wait conditions, the mutex, and the \c numUsedBytes + counter ensure that the producer is never more than \c BufferSize + bytes ahead of the consumer, and that the consumer never reads + data that the producer hasn't generated yet. + + \section1 Producer Class + + Let's review the code for the \c Producer class: + + \snippet examples/threads/waitconditions/waitconditions.cpp 1 + \snippet examples/threads/waitconditions/waitconditions.cpp 2 + + The producer generates \c DataSize bytes of data. Before it + writes a byte to the circular buffer, it must first check whether + the buffer is full (i.e., \c numUsedBytes equals \c BufferSize). + If the buffer is full, the thread waits on the \c bufferNotFull + condition. + + At the end, the producer increments \c numUsedBytes and signalls + that the condition \c bufferNotEmpty is true, since \c + numUsedBytes is necessarily greater than 0. + + We guard all accesses to the \c numUsedBytes variable with a + mutex. In addition, the QWaitCondition::wait() function accepts a + mutex as its argument. This mutex is unlocked before the thread + is put to sleep and locked when the thread wakes up. Furthermore, + the transition from the locked state to the wait state is atomic, + to prevent race conditions from occurring. + + \section1 Consumer Class + + Let's turn to the \c Consumer class: + + \snippet examples/threads/waitconditions/waitconditions.cpp 3 + \snippet examples/threads/waitconditions/waitconditions.cpp 4 + + The code is very similar to the producer. Before we read the + byte, we check whether the buffer is empty (\c numUsedBytes is 0) + instead of whether it's full and wait on the \c bufferNotEmpty + condition if it's empty. After we've read the byte, we decrement + \c numUsedBytes (instead of incrementing it), and we signal the + \c bufferNotFull condition (instead of the \c bufferNotEmpty + condition). + + \section1 The main() Function + + In \c main(), we create the two threads and call QThread::wait() + to ensure that both threads get time to finish before we exit: + + \snippet examples/threads/waitconditions/waitconditions.cpp 5 + \snippet examples/threads/waitconditions/waitconditions.cpp 6 + + So what happens when we run the program? Initially, the producer + thread is the only one that can do anything; the consumer is + blocked waiting for the \c bufferNotEmpty condition to be + signalled (\c numUsedBytes is 0). Once the producer has put one + byte in the buffer, \c numUsedBytes is \c BufferSize - 1 and the + \c bufferNotEmpty condition is signalled. At that point, two + things can happen: Either the consumer thread takes over and + reads that byte, or the consumer gets to produce a second byte. + + The producer-consumer model presented in this example makes it + possible to write highly concurrent multithreaded applications. + On a multiprocessor machine, the program is potentially up to + twice as fast as the equivalent mutex-based program, since the + two threads can be active at the same time on different parts of + the buffer. + + Be aware though that these benefits aren't always realized. + Locking and unlocking a QMutex has a cost. In practice, it would + probably be worthwhile to divide the buffer into chunks and to + operate on chunks instead of individual bytes. The buffer size is + also a parameter that must be selected carefully, based on + experimentation. +*/ diff --git a/doc/src/examples/wiggly.qdoc b/doc/src/examples/wiggly.qdoc new file mode 100644 index 0000000000..d3452c3ee0 --- /dev/null +++ b/doc/src/examples/wiggly.qdoc @@ -0,0 +1,167 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example widgets/wiggly + \title Wiggly Example + + The Wiggly example shows how to animate a widget using + QBasicTimer and \l{QObject::timerEvent()}{timerEvent()}. In + addition, the example demonstrates how to use QFontMetrics to + determine the size of text on screen. + + \image wiggly-example.png Screenshot of the Wiggly example + + QBasicTimer is a low-level class for timers. Unlike QTimer, + QBasicTimer doesn't inherit from QObject; instead of emitting a + \l{QTimer::timeout()}{timeout()} signal when a certain amount of + time has passed, it sends a QTimerEvent to a QObject of our + choice. This makes QBasicTimer a more lightweight alternative to + QTimer. Qt's built-in widgets use it internally, and it is + provided in Qt's API for highly-optimized applications (e.g., + \l{Qt for Embedded Linux} applications). + + The example consists of two classes: + + \list + \o \c WigglyWidget is the custom widget displaying the text + in a wiggly line. + + \o \c Dialog is the dialog widget allowing the user to enter a + text. It combines a \c WigglyWidget and a \c QLineEdit. + \endlist + + We will first take a quick look at the \c Dialog class, then we + will review the \c WigglyWidget class. + + \section1 Dialog Class Definition + + \snippet examples/widgets/wiggly/dialog.h 0 + + The \c Dialog class provides a dialog widget that allows the user + to enter a text. The text is then rendered by \c WigglyWidget. + + \section1 Dialog Class Implementation + + \snippet examples/widgets/wiggly/dialog.cpp 0 + + In the constructor we create a wiggly widget along with a + \l{QLineEdit}{line edit}, and we put the two widgets in a + vertical layout. We connect the line edit's \l + {QLineEdit::textChanged()}{textChanged()} signal to the wiggly + widget's \c setText() slot to obtain the real time interaction + with the wiggly widget. The widget's default text is "Hello + world!". + + \section1 WigglyWidget Class Definition + + \snippet examples/widgets/wiggly/wigglywidget.h 0 + + The \c WigglyWidget class provides the wiggly line displaying the + text. We subclass QWidget and reimplement the standard \l + {QWidget::paintEvent()}{paintEvent()} and \l + {QObject::timerEvent()}{timerEvent()} functions to draw and update + the widget. In addition we implement a public \c setText() slot + that sets the widget's text. + + The \c timer variable, of type QBasicTimer, is used to update the + widget at regular intervals, making the widget move. The \c text + variable is used to store the currently displayed text, and \c + step to calculate position and color for each character on the + wiggly line. + + \section1 WigglyWidget Class Implementation + + \snippet examples/widgets/wiggly/wigglywidget.cpp 0 + + In the constructor, we make the widget's background slightly + lighter than the usual background using the QPalette::Midlight + color role. The background role defines the brush from the + widget's palette that Qt uses to paint the background. Then we + enlarge the widget's font with 20 points. + + Finally we start the timer; the call to QBasicTimer::start() + makes sure that \e this particular wiggly widget will receive the + timer events generated when the timer times out (every 60 + milliseconds). + + \snippet examples/widgets/wiggly/wigglywidget.cpp 1 + \snippet examples/widgets/wiggly/wigglywidget.cpp 2 + + The \c paintEvent() function is called whenever a QPaintEvent is + sent to the widget. Paint events are sent to widgets that need to + update themselves, for instance when part of a widget is exposed + because a covering widget was moved. For the wiggly widget, a + paint event will also be generated every 60 milliseconds from + the \c timerEvent() slot. + + The \c sineTable represents y-values of the sine curve, + multiplied by 100. It is used to make the wiggly widget move + along the sine curve. + + The QFontMetrics object provides information about the widget's + font. The \c x variable is the horizontal position where we start + drawing the text. The \c y variable is the vertical position of + the text's base line. Both variables are computed so that the + text is horizontally and vertically centered. To compute the base + line, we take into account the font's ascent (the height of the + font above the base line) and font's descent (the height of the + font below the base line). If the descent equals the ascent, they + cancel out each other and the base line is at \c height() / 2. + + \snippet examples/widgets/wiggly/wigglywidget.cpp 3 + \snippet examples/widgets/wiggly/wigglywidget.cpp 4 + + Each time the \c paintEvent() function is called, we create a + QPainter object \c painter to draw the contents of the widget. + For each character in \c text, we determine the color and the + position on the wiggly line based on \c step. In addition, \c x + is incremented by the character's width. + + For simplicity, we assume that QFontMetrics::width(\c text) + returns the sum of the individual character widths + (QFontMetrics::width(\c text[i])). In practice, this is not + always the case because QFontMetrics::width(\c text) also takes + into account the kerning between certain letters (e.g., 'A' and + 'V'). The result is that the text isn't perfectly centered. You + can verify this by typing "AVAVAVAVAVAV" in the line edit. + + \snippet examples/widgets/wiggly/wigglywidget.cpp 5 + \snippet examples/widgets/wiggly/wigglywidget.cpp 6 + + The \c timerEvent() function receives all the timer events that + are generated for this widget. If a timer event is sent from the + widget's QBasicTimer, we increment \c step to make the text move, + and call QWidget::update() to refresh the display. Any other + timer event is passed on to the base class's implementation of + the \l{QWidget::timerEvent()}{timerEvent()} function. + + The QWidget::update() slot does not cause an immediate repaint; + instead the slot schedules a paint event for processing when Qt + returns to the main event loop. The paint events are then handled + by \c{WigglyWidget}'s \c paintEvent() function. +*/ diff --git a/doc/src/examples/windowflags.qdoc b/doc/src/examples/windowflags.qdoc new file mode 100644 index 0000000000..06fae10e6e --- /dev/null +++ b/doc/src/examples/windowflags.qdoc @@ -0,0 +1,216 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example widgets/windowflags + \title Window Flags Example + + The Window Flags example shows how to use the window flags + available in Qt. + + A window flag is either a type or a hint. A type is used to + specify various window-system properties for the widget. A widget + can only have one type, and the default is Qt::Widget. However, a + widget can have zero or more hints. The hints are used to + customize the appearance of top-level windows. + + A widget's flags are stored in a Qt::WindowFlags type which stores + an OR combination of the flags. + + \image windowflags-example.png Screenshot of the Window Flags example + + The example consists of two classes: + + \list + \o \c ControllerWindow is the main application widget that allows + the user to choose among the available window flags, and displays + the effect on a separate preview window. + \o \c PreviewWindow is a custom widget displaying the name of + its currently set window flags in a read-only text editor. + \endlist + + We will start by reviewing the \c ControllerWindow class, then we + will take a look at the \c PreviewWindow class. + + \section1 ControllerWindow Class Definition + + \snippet examples/widgets/windowflags/controllerwindow.h 0 + + The \c ControllerWindow class inherits QWidget. The widget allows + the user to choose among the available window flags, and displays + the effect on a separate preview window. + + We declare a private \c updatePreview() slot to refresh the + preview window whenever the user changes the window flags. + + We also declare several private functions to simplify the + constructor: We call the \c createTypeGroupBox() function to + create a radio button for each available window type, using the + private \c createButton() function, and gather them within a group + box. In a similar way we use the \c createHintsGroupBox() function + to create a check box for each available hint, using the private + \c createCheckBox() function. + + In addition to the various radio buttons and checkboxes, we need + an associated \c PreviewWindow to show the effect of the currently + chosen window flags. + + \image windowflags_controllerwindow.png Screenshot of the Controller Window + + \section1 ControllerWindow Class Implementation + + \snippet examples/widgets/windowflags/controllerwindow.cpp 0 + + In the constructor we first create the preview window. Then we + create the group boxes containing the available window flags using + the private \c createTypeGroupBox() and \c createHintsGroupBox() + functions. In addition we create a \gui Quit button. We put the + button and a stretchable space in a separate layout to make the + button appear in the \c WindowFlag widget's right bottom corner. + + Finally, we add the button's layout and the two goup boxes to a + QVBoxLayout, set the window title and refresh the preview window + using the \c updatePreview() slot. + + \snippet examples/widgets/windowflags/controllerwindow.cpp 1 + \snippet examples/widgets/windowflags/controllerwindow.cpp 2 + + The \c updatePreview() slot is called whenever the user changes + any of the window flags. First we create an empty Qt::WindowFlags + \c flags, then we determine which one of the types that is checked + and add it to \c flags. + + \snippet examples/widgets/windowflags/controllerwindow.cpp 3 + + We also determine which of the hints that are checked, and add + them to \c flags using an OR operator. We use \c flags to set the + window flags for the preview window. + + \snippet examples/widgets/windowflags/controllerwindow.cpp 4 + + We adjust the position of the preview window. The reason we do + that, is that playing around with the window's frame may on some + platforms cause the window's position to be changed behind our + back. If a window is located in the upper left corner of the + screen, parts of the window may not be visible. So we adjust the + widget's position to make sure that, if this happens, the window + is moved within the screen's boundaries. Finally, we call + QWidget::show() to make sure the preview window is visible. + + \omit + \skipto pos + \printuntil /^\}/ + \endomit + + \snippet examples/widgets/windowflags/controllerwindow.cpp 5 + + The private \c createTypeGroupBox() function is called from the + constructor. + + First we create a group box, and then we create a radio button + (using the private \c createRadioButton() function) for each of + the available types among the window flags. We make Qt::Window the + initially applied type. We put the radio buttons into a + QGridLayout and install the layout on the group box. + + We do not include the default Qt::Widget type. The reason is that + it behaves somewhat different than the other types. If the type is + not specified for a widget, and it has no parent, the widget is a + window. However, if it has a parent, it is a standard child + widget. The other types are all top-level windows, and since the + hints only affect top-level windows, we abandon the Qt::Widget + type. + + \snippet examples/widgets/windowflags/controllerwindow.cpp 6 + + The private \c createHintsGroupBox() function is also called from + the constructor. + + Again, the first thing we do is to create a group box. Then we + create a checkbox, using the private \c createCheckBox() function, + for each of the available hints among the window flags. We put the + checkboxes into a QGridLayout and install the layout on the group + box. + + \snippet examples/widgets/windowflags/controllerwindow.cpp 7 + + The private \c createCheckBox() function is called from \c + createHintsGroupBox(). + + We simply create a QCheckBox with the provided text, connect it to + the private \c updatePreview() slot, and return a pointer to the + checkbox. + + \snippet examples/widgets/windowflags/controllerwindow.cpp 8 + + In the private \c createRadioButton() function it is a + QRadioButton we create with the provided text, and connect to the + private \c updatePreview() slot. The function is called from \c + createTypeGroupBox(), and returns a pointer to the button. + + \section1 PreviewWindow Class Definition + + \snippet examples/widgets/windowflags/previewwindow.h 0 + + The \c PreviewWindow class inherits QWidget. It is a custom widget + that displays the names of its currently set window flags in a + read-only text editor. It is also provided with a QPushbutton that + closes the window. + + We reimplement the constructor to create the \gui Close button and + the text editor, and the QWidget::setWindowFlags() function to + display the names of the window flags. + + \image windowflags_previewwindow.png Screenshot of the Preview Window + + \section1 PreviewWindow Class Implementation + + \snippet examples/widgets/windowflags/previewwindow.cpp 0 + + In the constructor, we first create a QTextEdit and make sure that + it is read-only. + + We also prohibit any line wrapping in the text editor using the + QTextEdit::setLineWrapMode() function. The result is that a + horizontal scrollbar appears when a window flag's name exceeds the + width of the editor. This is a reasonable solution since we + construct the displayed text with built-in line breaks. If no line + breaks were guaranteed, using another QTextEdit::LineWrapMode + would perhaps make more sense. + + Then we create the \gui Close button, and put both the widgets + into a QVBoxLayout before we set the window title. + + \snippet examples/widgets/windowflags/previewwindow.cpp 1 + + In our reimplementation of the \c setWindowFlags() function, we + first set the widgets flags using the QWidget::setWindowFlags() + function. Then we run through the available window flags, creating + a text that contains the names of the flags that matches the \c + flags parameter. Finally, we display the text in the widgets text + editor. +*/ diff --git a/doc/src/examples/xmlstreamlint.qdoc b/doc/src/examples/xmlstreamlint.qdoc new file mode 100644 index 0000000000..c3ba356e5f --- /dev/null +++ b/doc/src/examples/xmlstreamlint.qdoc @@ -0,0 +1,72 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example xml/xmlstreamlint + \title XML Stream Lint Example + + The XML Stream Lint example provides a simple command line utility that + accepts a file name as its single argument and writes it to the standard + output file. + + The specified file is parsed using an QXmlStreamReader object and written + to the standard output file using an QXmlStreamWriter object. If the file + does not contain a well-formed XML document or the use of namespaces in + the document is incorrect, a description of the error is printed to + the standard error file and will appear in the console. + + \section1 Basic Operation + + The main function of the example opens the file specified by the user + for input (\c inputFile), and it uses QFile to access the standard output + file. + + Reading XML is handled by an instance of the QXmlStreamReader class, which + operates on the input file object; writing is handled by an instance of + QXmlStreamWriter operating on the output file object: + + \snippet examples/xml/xmlstreamlint/main.cpp 0 + + The work of parsing and rewriting the XML is done in a while loop, and is + driven by input from the reader: + + \snippet examples/xml/xmlstreamlint/main.cpp 1 + + If more input is available, the next token from the input file is read + and parsed. If an error occurred, information is written to the standard + error file via a stream, and the example exits by returning a non-zero + value from the main function. + + \snippet examples/xml/xmlstreamlint/main.cpp 2 + + For valid input, the writer is fed the current token from the reader, + and this is written to the output file that was specified when it was + constructed. + + When there is no more input, the loop terminates, and the example can + exit successfully. +*/ diff --git a/doc/src/files-and-resources/datastreamformat.qdoc b/doc/src/files-and-resources/datastreamformat.qdoc new file mode 100644 index 0000000000..086c74e9f9 --- /dev/null +++ b/doc/src/files-and-resources/datastreamformat.qdoc @@ -0,0 +1,361 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page datastreamformat.html + \title Serializing Qt Data Types + \ingroup qt-network + \brief Representations of data types that can be serialized by QDataStream. + + The \l QDataStream allows you to serialize some of the Qt data types. + The table below lists the data types that QDataStream can serialize + and how they are represented. The format described below is + \l{QDataStream::setVersion()}{version 12}. + + It is always best to cast integers to a Qt integer type, such as + qint16 or quint32, when reading and writing. This ensures that + you always know exactly what size integers you are reading and + writing, no matter what the underlying platform and architecture + the application happens to be running on. + + \table + \row \o bool + \o \list + \o boolean + \endlist + \row \o qint8 + \o \list + \o signed byte + \endlist + \row \o qint16 + \o \list + \o signed 16-bit integer + \endlist + \row \o qint32 + \o \list + \o signed 32-bit integer + \endlist + \row \o qint64 + \o \list + \o signed 64-bit integer + \endlist + \row \o quint8 + \o \list + \o unsigned byte + \endlist + \row \o quint16 + \o \list + \o unsigned 16-bit integer + \endlist + \row \o quint32 + \o \list + \o unsigned 32-bit integer + \endlist + \row \o quint64 + \o \list + \o unsigned 64-bit integer + \endlist + \row \o \c float + \o \list + \o 32-bit floating point number using the standard IEEE 754 format + \endlist + \row \o \c double + \o \list + \o 64-bit floating point number using the standard IEEE 754 format + \endlist + \row \o \c {const char *} + \o \list + \o The string length (quint32) + \o The string bytes, excluding the terminating 0 + \endlist + \row \o QBitArray + \o \list + \o The array size (quint32) + \o The array bits, i.e. (size + 7)/8 bytes + \endlist + \row \o QBrush + \o \list + \o The brush style (quint8) + \o The brush color (QColor) + \o If style is CustomPattern, the brush pixmap (QPixmap) + \endlist + \row \o QByteArray + \o \list + \o If the byte array is null: 0xFFFFFFFF (quint32) + \o Otherwise: the array size (quint32) followed by the array bytes, i.e. size bytes + \endlist + \row \o \l QColor + \o \list + \o Color spec (qint8) + \o Alpha value (quint16) + \o Red value (quint16) + \o Green value (quint16) + \o Blue value (quint16) + \o Pad value (quint16) + \endlist + \row \o QCursor + \o \list + \o Shape ID (qint16) + \o If shape is BitmapCursor: The bitmap (QPixmap), mask (QPixmap), and hot spot (QPoint) + \endlist + \row \o QDate + \o \list + \o Julian day (quint32) + \endlist + \row \o QDateTime + \o \list + \o Date (QDate) + \o Time (QTime) + \o 0 for Qt::LocalTime, 1 for Qt::UTC (quint8) + \endlist + \row \o QEasingCurve + \o \list + \o type (quint8) + \o func (quint64) + \o hasConfig (bool) + \o If hasConfig is true then these fields follow: + \o list + \o period (double) + \o amplitude (double) + \o overshoot (double) + \endlist + \row \o QFont + \o \list + \o The family (QString) + \o The point size (qint16) + \o The style hint (quint8) + \o The char set (quint8) + \o The weight (quint8) + \o The font bits (quint8) + \endlist + \row \o QHash<Key, T> + \o \list + \o The number of items (quint32) + \o For all items, the key (Key) and value (T) + \endlist + \row \o QIcon + \o \list + \o The number of pixmap entries (quint32) + \o For all pixmap entries: + \list + \o The pixmap (QPixmap) + \o The file name (QString) + \o The pixmap size (QSize) + \o The \l{QIcon::Mode}{mode} (quint32) + \o The \l{QIcon::State}{state} (quint32) + \endlist + \endlist + \row \o QImage + \o \list + \o If the image is null a "null image" marker is saved; + otherwise the image is saved in PNG or BMP format (depending + on the stream version). If you want control of the format, + stream the image into a QBuffer (using QImageIO) and stream + that. + \endlist + \row \o QKeySequence + \o \list + \o A QList<int>, where each integer is a key in the key sequence + \endlist + \row \o QLinkedList<T> + \o \list + \o The number of items (quint32) + \o The items (T) + \endlist + \row \o QList<T> + \o \list + \o The number of items (quint32) + \o The items (T) + \endlist + \row \o QMap<Key, T> + \o \list + \o The number of items (quint32) + \o For all items, the key (Key) and value (T) + \endlist + \row \o QMatrix + \o \list + \o m11 (double) + \o m12 (double) + \o m21 (double) + \o m22 (double) + \o dx (double) + \o dy (double) + \endlist + \row \o QMatrix4x4 + \o \list + \o m11 (double) + \o m12 (double) + \o m13 (double) + \o m14 (double) + \o m21 (double) + \o m22 (double) + \o m23 (double) + \o m24 (double) + \o m31 (double) + \o m32 (double) + \o m33 (double) + \o m34 (double) + \o m41 (double) + \o m42 (double) + \o m43 (double) + \o m44 (double) + \endlist + \row \o QPair<T1, T2> + \o \list + \o first (T1) + \o second (T2) + \endlist + \row \o QPalette + \o The disabled, active, and inactive color groups, each of which consists + of the following: + \list + \o foreground (QBrush) + \o button (QBrush) + \o light (QBrush) + \o midlight (QBrush) + \o dark (QBrush) + \o mid (QBrush) + \o text (QBrush) + \o brightText (QBrush) + \o buttonText (QBrush) + \o base (QBrush) + \o background (QBrush) + \o shadow (QBrush) + \o highlight (QBrush) + \o highlightedText (QBrush) + \o link (QBrush) + \o linkVisited (QBrush) + \endlist + \row \o QPen + \o \list + \o The pen styles (quint8) + \o The pen width (quint16) + \o The pen color (QColor) + \endlist + \row \o QPicture + \o \list + \o The size of the picture data (quint32) + \o The raw bytes of picture data (char) + \endlist + \row \o QPixmap + \o \list + \o Save it as a PNG image. + \endlist + \row \o QPoint + \o \list + \o The x coordinate (qint32) + \o The y coordinate (qint32) + \endlist + \row \o QQuaternion + \o \list + \o The scalar component (double) + \o The x coordinate (double) + \o The y coordinate (double) + \o The z coordinate (double) + \endlist + \row \o QRect + \o \list + \o left (qint32) + \o top (qint32) + \o right (qint32) + \o bottom (qint32) + \endlist + \row \o QRegExp + \o \list + \o The regexp pattern (QString) + \o Case sensitivity (quint8) + \o Regular expression syntax (quint8) + \o Minimal matching (quint8) + \endlist + \row \o QRegion + \o \list + \o The size of the data, i.e. 8 + 16 * (number of rectangles) (quint32) + \o 10 (qint32) + \o The number of rectangles (quint32) + \o The rectangles in sequential order (QRect) + \endlist + \row \o QSize + \o \list + \o width (qint32) + \o height (qint32) + \endlist + \row \o QString + \o \list + \o If the string is null: 0xFFFFFFFF (quint32) + \o Otherwise: The string length in bytes (quint32) followed by the data in UTF-16 + \endlist + \row \o QTime + \o \list + \o Milliseconds since midnight (quint32) + \endlist + \row \o QTransform + \o \list + \o m11 (double) + \o m12 (double) + \o m13 (double) + \o m21 (double) + \o m22 (double) + \o m23 (double) + \o m31 (double) + \o m32 (double) + \o m33 (double) + \endlist + \row \o QUrl + \o \list + \o Holds an URL (QString) + \endlist + \row \o QVariant + \o \list + \o The type of the data (quint32) + \o The null flag (qint8) + \o The data of the specified type + \endlist + \row \o QVector2D + \o \list + \o the x coordinate (double) + \o the y coordinate (double) + \endlist + \row \o QVector3D + \o \list + \o the x coordinate (double) + \o the y coordinate (double) + \o the z coordinate (double) + \endlist + \row \o QVector4D + \o \list + \o the x coordinate (double) + \o the y coordinate (double) + \o the z coordinate (double) + \o the w coordinate (double) + \endlist + \row \o QVector<T> + \o \list + \o The number of items (quint32) + \o The items (T) + \endlist + \endtable +*/ diff --git a/doc/src/files-and-resources/resources.qdoc b/doc/src/files-and-resources/resources.qdoc new file mode 100644 index 0000000000..35e6a9086f --- /dev/null +++ b/doc/src/files-and-resources/resources.qdoc @@ -0,0 +1,214 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \group io + \title Input/Output and Networking + \ingroup groups + + \brief Classes providing file input and output along with directory and + network handling. + + These classes are used to handle input and output to and from external + devices, processes, files etc. as well as manipulating files and directories. +*/ + +/*! + \page resources.html + \title The Qt Resource System + \ingroup qt-network + \brief A platform-independent mechanism for storing binary files in an application. + + \keyword resource system + + The Qt resource system is a platform-independent mechanism for + storing binary files in the application's executable. This is + useful if your application always needs a certain set of files + (icons, translation files, etc.) and you don't want to run the + risk of losing the files. + + The resource system is based on tight cooperation between \l qmake, + \l rcc (Qt's resource compiler), and QFile. It obsoletes Qt 3's + \c qembed tool and the + \l{http://qt.nokia.com/doc/qq/qq05-iconography.html#imagestorage}{image + collection} mechanism. + + \section1 Resource Collection Files (\c{.qrc}) + + The resources associated with an application are specified in a + \c .qrc file, an XML-based file format that lists files on the + disk and optionally assigns them a resource name that the + application must use to access the resource. + + Here's an example \c .qrc file: + + \quotefile mainwindows/application/application.qrc + + The resource files listed in the \c .qrc file are files that are + part of the application's source tree. The specified paths are + relative to the directory containing the \c .qrc file. Note that + the listed resource files must be located in the same directory as + the \c .qrc file, or one of its subdirectories. + + Resource data can either be compiled into the binary and thus accessed + immediately in application code, or a binary resource can be created + and at a later point in application code registered with the resource + system. + + By default, resources are accessible in the application under the + same file name as they have in the source tree, with a \c :/ prefix, + or by a \link QUrl URL\endlink with a \c qrc scheme. + + For example, the file path \c :/images/cut.png or the URL + \c qrc:///images/cut.png would give access to the + \c cut.png file, whose location in the application's source tree + is \c images/cut.png. This can be changed using the \c file tag's + \c alias attribute: + + \snippet doc/src/snippets/code/doc_src_resources.qdoc 0 + + The file is then accessible as \c :/cut-img.png from the + application. It is also possible to specify a path prefix for all + files in the \c .qrc file using the \c qresource tag's \c prefix + attribute: + + \snippet doc/src/snippets/code/doc_src_resources.qdoc 1 + + In this case, the file is accessible as \c + :/myresources/cut-img.png. + + Some resources, such as translation files and icons, many need to + change based on the user's locale. This is done by adding a \c lang + attribute to the \c qresource tag, specifying a suitable locale + string. For example: + + \snippet doc/src/snippets/code/doc_src_resources.qdoc 2 + + If the user's locale is French (i.e., QLocale::system().name() returns + "fr_FR"), \c :/cut.jpg becomes a reference to the \c cut_fr.jpg + image. For other locales, \c cut.jpg is used. + + See the QLocale documentation for a description of the format to use + for locale strings. + + + \section2 External Binary Resources + + For an external binary resource to be created you must create the resource + data (commonly given the \c .rcc extension) by passing the -binary switch to + \l rcc. Once the binary resource is created you can register the resource + with the QResource API. + + For example, a set of resource data specified in a \c .qrc file can be + compiled in the following way: + + \snippet doc/src/snippets/code/doc_src_resources.qdoc 3 + + In the application, this resource would be registered with code like this: + + \snippet doc/src/snippets/code/doc_src_resources.cpp 4 + + \section2 Compiled-In Resources + + For a resource to be compiled into the binary the \c .qrc file must be + mentioned in the application's \c .pro file so that \c qmake knows + about it. For example: + + \snippet examples/mainwindows/application/application.pro 0 + + \c qmake will produce make rules to generate a file called \c + qrc_application.cpp that is linked into the application. This + file contains all the data for the images and other resources as + static C++ arrays of compressed binary data. The \c + qrc_application.cpp file is automatically regenerated whenever + the \c .qrc file changes or one of the files that it refers to + changes. If you don't use \c .pro files, you can either invoke + \c rcc manually or add build rules to your build system. + + \image resources.png Building resources into an application + + Currently, Qt always stores the data directly in the executable, + even on Windows and Mac OS X, where the operating system provides + native support for resources. This might change in a future Qt + release. + + \section1 Compression + + Resources are compressed by default (in the \c ZIP format). It is + possible to turn off compression. This can be useful if your + resources already contain a compressed format, such as \c .png + files. You do this by giving the \c {-no-compress} command line + argument. + + \code + rcc -no-compress myresources.qrc + \endcode + + \c rcc also gives you some control over the compression. You can + specify the compression level and the threshold level to consider + while compressing files, for example: + + \code + rcc -compress 2 -threshold 3 myresources.qrc + \endcode + + \section1 Using Resources in the Application + + In the application, resource paths can be used in most places + instead of ordinary file system paths. In particular, you can + pass a resource path instead of a file name to the QIcon, QImage, + or QPixmap constructor: + + \snippet examples/mainwindows/application/mainwindow.cpp 21 + + See the \l{mainwindows/application}{Application} example for an + actual application that uses Qt's resource system to store its + icons. + + In memory, resources are represented by a tree of resource + objects. The tree is automatically built at startup and used by + QFile for resolving paths to resources. You can use a QDir initialized + with ":/" to navigate through the resource tree from the root. + + Qt's resources support the concept of a search path list. If you then + refer to a resource with \c : instead of \c :/ as the prefix, the + resource will be looked up using the search path list. The search + path list is empty at startup; call QDir::addSearchPath() to + add paths to it. + + If you have resources in a static library, you might need to + force initialization of your resources by calling \l + Q_INIT_RESOURCE() with the base name of the \c .qrc file. For + example: + + \snippet doc/src/snippets/code/doc_src_resources.cpp 5 + + Similarly, if you must unload a set of resources explicitly + (because a plugin is being unloaded or the resources are not valid + any longer), you can force removal of your resources by calling + Q_CLEANUP_RESOURCE() with the same base name as above. +*/ diff --git a/doc/src/images/2dpainting-example.png b/doc/src/images/2dpainting-example.png Binary files differnew file mode 100644 index 0000000000..2a77e7d7d5 --- /dev/null +++ b/doc/src/images/2dpainting-example.png diff --git a/doc/src/images/addressbook-adddialog.png b/doc/src/images/addressbook-adddialog.png Binary files differnew file mode 100644 index 0000000000..e2bab80c53 --- /dev/null +++ b/doc/src/images/addressbook-adddialog.png diff --git a/doc/src/images/addressbook-classes.png b/doc/src/images/addressbook-classes.png Binary files differnew file mode 100644 index 0000000000..2920f1636c --- /dev/null +++ b/doc/src/images/addressbook-classes.png diff --git a/doc/src/images/addressbook-editdialog.png b/doc/src/images/addressbook-editdialog.png Binary files differnew file mode 100644 index 0000000000..fd41ee63f7 --- /dev/null +++ b/doc/src/images/addressbook-editdialog.png diff --git a/doc/src/images/addressbook-example.png b/doc/src/images/addressbook-example.png Binary files differnew file mode 100644 index 0000000000..b743c166da --- /dev/null +++ b/doc/src/images/addressbook-example.png diff --git a/doc/src/images/addressbook-newaddresstab.png b/doc/src/images/addressbook-newaddresstab.png Binary files differnew file mode 100644 index 0000000000..ff215a4b20 --- /dev/null +++ b/doc/src/images/addressbook-newaddresstab.png diff --git a/doc/src/images/addressbook-signals.png b/doc/src/images/addressbook-signals.png Binary files differnew file mode 100644 index 0000000000..cda426930b --- /dev/null +++ b/doc/src/images/addressbook-signals.png diff --git a/doc/src/images/addressbook-tutorial-part1-labeled-layout.png b/doc/src/images/addressbook-tutorial-part1-labeled-layout.png Binary files differnew file mode 100644 index 0000000000..b19cb360a1 --- /dev/null +++ b/doc/src/images/addressbook-tutorial-part1-labeled-layout.png diff --git a/doc/src/images/addressbook-tutorial-part1-labeled-screenshot.png b/doc/src/images/addressbook-tutorial-part1-labeled-screenshot.png Binary files differnew file mode 100644 index 0000000000..f9b91eebe6 --- /dev/null +++ b/doc/src/images/addressbook-tutorial-part1-labeled-screenshot.png diff --git a/doc/src/images/addressbook-tutorial-part1-screenshot.png b/doc/src/images/addressbook-tutorial-part1-screenshot.png Binary files differnew file mode 100644 index 0000000000..454b0959e6 --- /dev/null +++ b/doc/src/images/addressbook-tutorial-part1-screenshot.png diff --git a/doc/src/images/addressbook-tutorial-part2-add-contact.png b/doc/src/images/addressbook-tutorial-part2-add-contact.png Binary files differnew file mode 100644 index 0000000000..6f2b947b21 --- /dev/null +++ b/doc/src/images/addressbook-tutorial-part2-add-contact.png diff --git a/doc/src/images/addressbook-tutorial-part2-add-flowchart.png b/doc/src/images/addressbook-tutorial-part2-add-flowchart.png Binary files differnew file mode 100644 index 0000000000..ca9af3720d --- /dev/null +++ b/doc/src/images/addressbook-tutorial-part2-add-flowchart.png diff --git a/doc/src/images/addressbook-tutorial-part2-add-successful.png b/doc/src/images/addressbook-tutorial-part2-add-successful.png Binary files differnew file mode 100644 index 0000000000..99a2154007 --- /dev/null +++ b/doc/src/images/addressbook-tutorial-part2-add-successful.png diff --git a/doc/src/images/addressbook-tutorial-part2-labeled-layout.png b/doc/src/images/addressbook-tutorial-part2-labeled-layout.png Binary files differnew file mode 100644 index 0000000000..1e000c8f31 --- /dev/null +++ b/doc/src/images/addressbook-tutorial-part2-labeled-layout.png diff --git a/doc/src/images/addressbook-tutorial-part2-signals-and-slots.png b/doc/src/images/addressbook-tutorial-part2-signals-and-slots.png Binary files differnew file mode 100644 index 0000000000..e49f8dc262 --- /dev/null +++ b/doc/src/images/addressbook-tutorial-part2-signals-and-slots.png diff --git a/doc/src/images/addressbook-tutorial-part2-stretch-effects.png b/doc/src/images/addressbook-tutorial-part2-stretch-effects.png Binary files differnew file mode 100644 index 0000000000..d9f7f31227 --- /dev/null +++ b/doc/src/images/addressbook-tutorial-part2-stretch-effects.png diff --git a/doc/src/images/addressbook-tutorial-part3-labeled-layout.png b/doc/src/images/addressbook-tutorial-part3-labeled-layout.png Binary files differnew file mode 100644 index 0000000000..1981ba8cb6 --- /dev/null +++ b/doc/src/images/addressbook-tutorial-part3-labeled-layout.png diff --git a/doc/src/images/addressbook-tutorial-part3-linkedlist.png b/doc/src/images/addressbook-tutorial-part3-linkedlist.png Binary files differnew file mode 100644 index 0000000000..e7f4725dce --- /dev/null +++ b/doc/src/images/addressbook-tutorial-part3-linkedlist.png diff --git a/doc/src/images/addressbook-tutorial-part3-screenshot.png b/doc/src/images/addressbook-tutorial-part3-screenshot.png Binary files differnew file mode 100644 index 0000000000..75159b4045 --- /dev/null +++ b/doc/src/images/addressbook-tutorial-part3-screenshot.png diff --git a/doc/src/images/addressbook-tutorial-part4-remove.png b/doc/src/images/addressbook-tutorial-part4-remove.png Binary files differnew file mode 100644 index 0000000000..8eb259ef02 --- /dev/null +++ b/doc/src/images/addressbook-tutorial-part4-remove.png diff --git a/doc/src/images/addressbook-tutorial-part5-finddialog.png b/doc/src/images/addressbook-tutorial-part5-finddialog.png Binary files differnew file mode 100644 index 0000000000..743d92ef6f --- /dev/null +++ b/doc/src/images/addressbook-tutorial-part5-finddialog.png diff --git a/doc/src/images/addressbook-tutorial-part5-notfound.png b/doc/src/images/addressbook-tutorial-part5-notfound.png Binary files differnew file mode 100644 index 0000000000..2d35766ab5 --- /dev/null +++ b/doc/src/images/addressbook-tutorial-part5-notfound.png diff --git a/doc/src/images/addressbook-tutorial-part5-screenshot.png b/doc/src/images/addressbook-tutorial-part5-screenshot.png Binary files differnew file mode 100644 index 0000000000..3abe2775c2 --- /dev/null +++ b/doc/src/images/addressbook-tutorial-part5-screenshot.png diff --git a/doc/src/images/addressbook-tutorial-part5-signals-and-slots.png b/doc/src/images/addressbook-tutorial-part5-signals-and-slots.png Binary files differnew file mode 100644 index 0000000000..1771e7bbbf --- /dev/null +++ b/doc/src/images/addressbook-tutorial-part5-signals-and-slots.png diff --git a/doc/src/images/addressbook-tutorial-part6-load.png b/doc/src/images/addressbook-tutorial-part6-load.png Binary files differnew file mode 100644 index 0000000000..a027a1decb --- /dev/null +++ b/doc/src/images/addressbook-tutorial-part6-load.png diff --git a/doc/src/images/addressbook-tutorial-part6-save.png b/doc/src/images/addressbook-tutorial-part6-save.png Binary files differnew file mode 100644 index 0000000000..757feeb9ac --- /dev/null +++ b/doc/src/images/addressbook-tutorial-part6-save.png diff --git a/doc/src/images/addressbook-tutorial-part6-screenshot.png b/doc/src/images/addressbook-tutorial-part6-screenshot.png Binary files differnew file mode 100644 index 0000000000..7bb2f749bf --- /dev/null +++ b/doc/src/images/addressbook-tutorial-part6-screenshot.png diff --git a/doc/src/images/addressbook-tutorial-part7-screenshot.png b/doc/src/images/addressbook-tutorial-part7-screenshot.png Binary files differnew file mode 100644 index 0000000000..3e7b3ca522 --- /dev/null +++ b/doc/src/images/addressbook-tutorial-part7-screenshot.png diff --git a/doc/src/images/addressbook-tutorial-screenshot.png b/doc/src/images/addressbook-tutorial-screenshot.png Binary files differnew file mode 100644 index 0000000000..3fba6e849e --- /dev/null +++ b/doc/src/images/addressbook-tutorial-screenshot.png diff --git a/doc/src/images/affine-demo.png b/doc/src/images/affine-demo.png Binary files differnew file mode 100644 index 0000000000..534d6956ae --- /dev/null +++ b/doc/src/images/affine-demo.png diff --git a/doc/src/images/alphachannelimage.png b/doc/src/images/alphachannelimage.png Binary files differnew file mode 100644 index 0000000000..57b17c6aa0 --- /dev/null +++ b/doc/src/images/alphachannelimage.png diff --git a/doc/src/images/analogclock-example.png b/doc/src/images/analogclock-example.png Binary files differnew file mode 100644 index 0000000000..ffd7baa716 --- /dev/null +++ b/doc/src/images/analogclock-example.png diff --git a/doc/src/images/animatedtiles-example.png b/doc/src/images/animatedtiles-example.png Binary files differnew file mode 100644 index 0000000000..082ac57b7c --- /dev/null +++ b/doc/src/images/animatedtiles-example.png diff --git a/doc/src/images/appchooser-example.png b/doc/src/images/appchooser-example.png Binary files differnew file mode 100644 index 0000000000..885476e8b9 --- /dev/null +++ b/doc/src/images/appchooser-example.png diff --git a/doc/src/images/application-menus.png b/doc/src/images/application-menus.png Binary files differnew file mode 100644 index 0000000000..1815a2a4e3 --- /dev/null +++ b/doc/src/images/application-menus.png diff --git a/doc/src/images/application.png b/doc/src/images/application.png Binary files differnew file mode 100644 index 0000000000..2fb7f2f18e --- /dev/null +++ b/doc/src/images/application.png diff --git a/doc/src/images/basicdrawing-example.png b/doc/src/images/basicdrawing-example.png Binary files differnew file mode 100644 index 0000000000..043acbe8d9 --- /dev/null +++ b/doc/src/images/basicdrawing-example.png diff --git a/doc/src/images/basicgraphicslayouts-example.png b/doc/src/images/basicgraphicslayouts-example.png Binary files differnew file mode 100644 index 0000000000..5c8f4cbc5d --- /dev/null +++ b/doc/src/images/basicgraphicslayouts-example.png diff --git a/doc/src/images/basiclayouts-example.png b/doc/src/images/basiclayouts-example.png Binary files differnew file mode 100644 index 0000000000..f293423a8e --- /dev/null +++ b/doc/src/images/basiclayouts-example.png diff --git a/doc/src/images/basicsortfiltermodel-example.png b/doc/src/images/basicsortfiltermodel-example.png Binary files differnew file mode 100644 index 0000000000..7f3bfdf360 --- /dev/null +++ b/doc/src/images/basicsortfiltermodel-example.png diff --git a/doc/src/images/bearermonitor-example.png b/doc/src/images/bearermonitor-example.png Binary files differnew file mode 100644 index 0000000000..1b8a9c3834 --- /dev/null +++ b/doc/src/images/bearermonitor-example.png diff --git a/doc/src/images/blockingfortuneclient-example.png b/doc/src/images/blockingfortuneclient-example.png Binary files differnew file mode 100644 index 0000000000..cdb7cac0d3 --- /dev/null +++ b/doc/src/images/blockingfortuneclient-example.png diff --git a/doc/src/images/blurpickereffect-example.png b/doc/src/images/blurpickereffect-example.png Binary files differnew file mode 100644 index 0000000000..88943385e2 --- /dev/null +++ b/doc/src/images/blurpickereffect-example.png diff --git a/doc/src/images/books-demo.png b/doc/src/images/books-demo.png Binary files differnew file mode 100644 index 0000000000..5bcc20b478 --- /dev/null +++ b/doc/src/images/books-demo.png diff --git a/doc/src/images/borderlayout-example.png b/doc/src/images/borderlayout-example.png Binary files differnew file mode 100644 index 0000000000..e856e06572 --- /dev/null +++ b/doc/src/images/borderlayout-example.png diff --git a/doc/src/images/boxes-demo.png b/doc/src/images/boxes-demo.png Binary files differnew file mode 100644 index 0000000000..6ad253c113 --- /dev/null +++ b/doc/src/images/boxes-demo.png diff --git a/doc/src/images/broadcastreceiver-example.png b/doc/src/images/broadcastreceiver-example.png Binary files differnew file mode 100644 index 0000000000..b83789523c --- /dev/null +++ b/doc/src/images/broadcastreceiver-example.png diff --git a/doc/src/images/broadcastsender-example.png b/doc/src/images/broadcastsender-example.png Binary files differnew file mode 100644 index 0000000000..bf7ccbeb9e --- /dev/null +++ b/doc/src/images/broadcastsender-example.png diff --git a/doc/src/images/brush-styles.png b/doc/src/images/brush-styles.png Binary files differnew file mode 100644 index 0000000000..eecb006af1 --- /dev/null +++ b/doc/src/images/brush-styles.png diff --git a/doc/src/images/cachedtable-example.png b/doc/src/images/cachedtable-example.png Binary files differnew file mode 100644 index 0000000000..db770dfdf2 --- /dev/null +++ b/doc/src/images/cachedtable-example.png diff --git a/doc/src/images/calculator-example.png b/doc/src/images/calculator-example.png Binary files differnew file mode 100644 index 0000000000..6f1158d733 --- /dev/null +++ b/doc/src/images/calculator-example.png diff --git a/doc/src/images/calculator-ugly.png b/doc/src/images/calculator-ugly.png Binary files differnew file mode 100644 index 0000000000..cdfa902c4c --- /dev/null +++ b/doc/src/images/calculator-ugly.png diff --git a/doc/src/images/calendar-example.png b/doc/src/images/calendar-example.png Binary files differnew file mode 100644 index 0000000000..895ce76b09 --- /dev/null +++ b/doc/src/images/calendar-example.png diff --git a/doc/src/images/calendarwidgetexample.png b/doc/src/images/calendarwidgetexample.png Binary files differnew file mode 100644 index 0000000000..464be90999 --- /dev/null +++ b/doc/src/images/calendarwidgetexample.png diff --git a/doc/src/images/cde-calendarwidget.png b/doc/src/images/cde-calendarwidget.png Binary files differnew file mode 100644 index 0000000000..9615eaeab8 --- /dev/null +++ b/doc/src/images/cde-calendarwidget.png diff --git a/doc/src/images/cde-checkbox.png b/doc/src/images/cde-checkbox.png Binary files differnew file mode 100644 index 0000000000..b2528dc5de --- /dev/null +++ b/doc/src/images/cde-checkbox.png diff --git a/doc/src/images/cde-combobox.png b/doc/src/images/cde-combobox.png Binary files differnew file mode 100644 index 0000000000..74586433eb --- /dev/null +++ b/doc/src/images/cde-combobox.png diff --git a/doc/src/images/cde-dateedit.png b/doc/src/images/cde-dateedit.png Binary files differnew file mode 100644 index 0000000000..ebb24d59cf --- /dev/null +++ b/doc/src/images/cde-dateedit.png diff --git a/doc/src/images/cde-datetimeedit.png b/doc/src/images/cde-datetimeedit.png Binary files differnew file mode 100644 index 0000000000..9ac659a3f3 --- /dev/null +++ b/doc/src/images/cde-datetimeedit.png diff --git a/doc/src/images/cde-dial.png b/doc/src/images/cde-dial.png Binary files differnew file mode 100644 index 0000000000..956d19cb6c --- /dev/null +++ b/doc/src/images/cde-dial.png diff --git a/doc/src/images/cde-doublespinbox.png b/doc/src/images/cde-doublespinbox.png Binary files differnew file mode 100644 index 0000000000..30a9af66fa --- /dev/null +++ b/doc/src/images/cde-doublespinbox.png diff --git a/doc/src/images/cde-fontcombobox.png b/doc/src/images/cde-fontcombobox.png Binary files differnew file mode 100644 index 0000000000..043ca1d20f --- /dev/null +++ b/doc/src/images/cde-fontcombobox.png diff --git a/doc/src/images/cde-frame.png b/doc/src/images/cde-frame.png Binary files differnew file mode 100644 index 0000000000..221576e849 --- /dev/null +++ b/doc/src/images/cde-frame.png diff --git a/doc/src/images/cde-groupbox.png b/doc/src/images/cde-groupbox.png Binary files differnew file mode 100644 index 0000000000..8bad69be4e --- /dev/null +++ b/doc/src/images/cde-groupbox.png diff --git a/doc/src/images/cde-horizontalscrollbar.png b/doc/src/images/cde-horizontalscrollbar.png Binary files differnew file mode 100644 index 0000000000..6e7cde8da1 --- /dev/null +++ b/doc/src/images/cde-horizontalscrollbar.png diff --git a/doc/src/images/cde-label.png b/doc/src/images/cde-label.png Binary files differnew file mode 100644 index 0000000000..4e906eaa00 --- /dev/null +++ b/doc/src/images/cde-label.png diff --git a/doc/src/images/cde-lcdnumber.png b/doc/src/images/cde-lcdnumber.png Binary files differnew file mode 100644 index 0000000000..97324c1a6c --- /dev/null +++ b/doc/src/images/cde-lcdnumber.png diff --git a/doc/src/images/cde-lineedit.png b/doc/src/images/cde-lineedit.png Binary files differnew file mode 100644 index 0000000000..6c1527ba19 --- /dev/null +++ b/doc/src/images/cde-lineedit.png diff --git a/doc/src/images/cde-listview.png b/doc/src/images/cde-listview.png Binary files differnew file mode 100644 index 0000000000..2e58140880 --- /dev/null +++ b/doc/src/images/cde-listview.png diff --git a/doc/src/images/cde-progressbar.png b/doc/src/images/cde-progressbar.png Binary files differnew file mode 100644 index 0000000000..41715deb48 --- /dev/null +++ b/doc/src/images/cde-progressbar.png diff --git a/doc/src/images/cde-pushbutton.png b/doc/src/images/cde-pushbutton.png Binary files differnew file mode 100644 index 0000000000..2d9bdd25a4 --- /dev/null +++ b/doc/src/images/cde-pushbutton.png diff --git a/doc/src/images/cde-radiobutton.png b/doc/src/images/cde-radiobutton.png Binary files differnew file mode 100644 index 0000000000..e053665f5a --- /dev/null +++ b/doc/src/images/cde-radiobutton.png diff --git a/doc/src/images/cde-slider.png b/doc/src/images/cde-slider.png Binary files differnew file mode 100644 index 0000000000..bd84371898 --- /dev/null +++ b/doc/src/images/cde-slider.png diff --git a/doc/src/images/cde-spinbox.png b/doc/src/images/cde-spinbox.png Binary files differnew file mode 100644 index 0000000000..5f53c8e902 --- /dev/null +++ b/doc/src/images/cde-spinbox.png diff --git a/doc/src/images/cde-tableview.png b/doc/src/images/cde-tableview.png Binary files differnew file mode 100644 index 0000000000..7a99217560 --- /dev/null +++ b/doc/src/images/cde-tableview.png diff --git a/doc/src/images/cde-tabwidget.png b/doc/src/images/cde-tabwidget.png Binary files differnew file mode 100644 index 0000000000..8cf5473fc2 --- /dev/null +++ b/doc/src/images/cde-tabwidget.png diff --git a/doc/src/images/cde-textedit.png b/doc/src/images/cde-textedit.png Binary files differnew file mode 100644 index 0000000000..c65b8da8f4 --- /dev/null +++ b/doc/src/images/cde-textedit.png diff --git a/doc/src/images/cde-timeedit.png b/doc/src/images/cde-timeedit.png Binary files differnew file mode 100644 index 0000000000..6a5a4b953f --- /dev/null +++ b/doc/src/images/cde-timeedit.png diff --git a/doc/src/images/cde-toolbox.png b/doc/src/images/cde-toolbox.png Binary files differnew file mode 100644 index 0000000000..c0dd4e9400 --- /dev/null +++ b/doc/src/images/cde-toolbox.png diff --git a/doc/src/images/cde-toolbutton.png b/doc/src/images/cde-toolbutton.png Binary files differnew file mode 100644 index 0000000000..baff25c25b --- /dev/null +++ b/doc/src/images/cde-toolbutton.png diff --git a/doc/src/images/cde-treeview.png b/doc/src/images/cde-treeview.png Binary files differnew file mode 100644 index 0000000000..df3184b31b --- /dev/null +++ b/doc/src/images/cde-treeview.png diff --git a/doc/src/images/charactermap-example.png b/doc/src/images/charactermap-example.png Binary files differnew file mode 100644 index 0000000000..c1f25a5b83 --- /dev/null +++ b/doc/src/images/charactermap-example.png diff --git a/doc/src/images/chart-example.png b/doc/src/images/chart-example.png Binary files differnew file mode 100644 index 0000000000..98236663e5 --- /dev/null +++ b/doc/src/images/chart-example.png diff --git a/doc/src/images/chip-demo.png b/doc/src/images/chip-demo.png Binary files differnew file mode 100644 index 0000000000..8889424023 --- /dev/null +++ b/doc/src/images/chip-demo.png diff --git a/doc/src/images/classwizard-flow.png b/doc/src/images/classwizard-flow.png Binary files differnew file mode 100644 index 0000000000..ad9446c430 --- /dev/null +++ b/doc/src/images/classwizard-flow.png diff --git a/doc/src/images/classwizard.png b/doc/src/images/classwizard.png Binary files differnew file mode 100644 index 0000000000..ea740bd213 --- /dev/null +++ b/doc/src/images/classwizard.png diff --git a/doc/src/images/cleanlooks-calendarwidget.png b/doc/src/images/cleanlooks-calendarwidget.png Binary files differnew file mode 100644 index 0000000000..99c57b61ee --- /dev/null +++ b/doc/src/images/cleanlooks-calendarwidget.png diff --git a/doc/src/images/cleanlooks-checkbox.png b/doc/src/images/cleanlooks-checkbox.png Binary files differnew file mode 100644 index 0000000000..aaf2daae4e --- /dev/null +++ b/doc/src/images/cleanlooks-checkbox.png diff --git a/doc/src/images/cleanlooks-combobox.png b/doc/src/images/cleanlooks-combobox.png Binary files differnew file mode 100644 index 0000000000..5fff4c87f6 --- /dev/null +++ b/doc/src/images/cleanlooks-combobox.png diff --git a/doc/src/images/cleanlooks-dateedit.png b/doc/src/images/cleanlooks-dateedit.png Binary files differnew file mode 100644 index 0000000000..384136a162 --- /dev/null +++ b/doc/src/images/cleanlooks-dateedit.png diff --git a/doc/src/images/cleanlooks-datetimeedit.png b/doc/src/images/cleanlooks-datetimeedit.png Binary files differnew file mode 100644 index 0000000000..7a62cebfb4 --- /dev/null +++ b/doc/src/images/cleanlooks-datetimeedit.png diff --git a/doc/src/images/cleanlooks-dial.png b/doc/src/images/cleanlooks-dial.png Binary files differnew file mode 100644 index 0000000000..259a0888b6 --- /dev/null +++ b/doc/src/images/cleanlooks-dial.png diff --git a/doc/src/images/cleanlooks-doublespinbox.png b/doc/src/images/cleanlooks-doublespinbox.png Binary files differnew file mode 100644 index 0000000000..93b11f919a --- /dev/null +++ b/doc/src/images/cleanlooks-doublespinbox.png diff --git a/doc/src/images/cleanlooks-fontcombobox.png b/doc/src/images/cleanlooks-fontcombobox.png Binary files differnew file mode 100644 index 0000000000..47a5907f56 --- /dev/null +++ b/doc/src/images/cleanlooks-fontcombobox.png diff --git a/doc/src/images/cleanlooks-frame.png b/doc/src/images/cleanlooks-frame.png Binary files differnew file mode 100644 index 0000000000..2427b08d8f --- /dev/null +++ b/doc/src/images/cleanlooks-frame.png diff --git a/doc/src/images/cleanlooks-groupbox.png b/doc/src/images/cleanlooks-groupbox.png Binary files differnew file mode 100644 index 0000000000..89c6eb2f39 --- /dev/null +++ b/doc/src/images/cleanlooks-groupbox.png diff --git a/doc/src/images/cleanlooks-horizontalscrollbar.png b/doc/src/images/cleanlooks-horizontalscrollbar.png Binary files differnew file mode 100644 index 0000000000..ca1c806c91 --- /dev/null +++ b/doc/src/images/cleanlooks-horizontalscrollbar.png diff --git a/doc/src/images/cleanlooks-label.png b/doc/src/images/cleanlooks-label.png Binary files differnew file mode 100644 index 0000000000..199758fd69 --- /dev/null +++ b/doc/src/images/cleanlooks-label.png diff --git a/doc/src/images/cleanlooks-lcdnumber.png b/doc/src/images/cleanlooks-lcdnumber.png Binary files differnew file mode 100644 index 0000000000..c6e34127cf --- /dev/null +++ b/doc/src/images/cleanlooks-lcdnumber.png diff --git a/doc/src/images/cleanlooks-lineedit.png b/doc/src/images/cleanlooks-lineedit.png Binary files differnew file mode 100644 index 0000000000..3e9f1a4be3 --- /dev/null +++ b/doc/src/images/cleanlooks-lineedit.png diff --git a/doc/src/images/cleanlooks-listview.png b/doc/src/images/cleanlooks-listview.png Binary files differnew file mode 100644 index 0000000000..95f836c66b --- /dev/null +++ b/doc/src/images/cleanlooks-listview.png diff --git a/doc/src/images/cleanlooks-progressbar.png b/doc/src/images/cleanlooks-progressbar.png Binary files differnew file mode 100644 index 0000000000..53fc6c1faa --- /dev/null +++ b/doc/src/images/cleanlooks-progressbar.png diff --git a/doc/src/images/cleanlooks-pushbutton.png b/doc/src/images/cleanlooks-pushbutton.png Binary files differnew file mode 100644 index 0000000000..7b3b3357c1 --- /dev/null +++ b/doc/src/images/cleanlooks-pushbutton.png diff --git a/doc/src/images/cleanlooks-radiobutton.png b/doc/src/images/cleanlooks-radiobutton.png Binary files differnew file mode 100644 index 0000000000..4e077688c2 --- /dev/null +++ b/doc/src/images/cleanlooks-radiobutton.png diff --git a/doc/src/images/cleanlooks-slider.png b/doc/src/images/cleanlooks-slider.png Binary files differnew file mode 100644 index 0000000000..8dfaa01092 --- /dev/null +++ b/doc/src/images/cleanlooks-slider.png diff --git a/doc/src/images/cleanlooks-spinbox.png b/doc/src/images/cleanlooks-spinbox.png Binary files differnew file mode 100644 index 0000000000..ad5b5a01b6 --- /dev/null +++ b/doc/src/images/cleanlooks-spinbox.png diff --git a/doc/src/images/cleanlooks-tableview.png b/doc/src/images/cleanlooks-tableview.png Binary files differnew file mode 100644 index 0000000000..d89fecc5ad --- /dev/null +++ b/doc/src/images/cleanlooks-tableview.png diff --git a/doc/src/images/cleanlooks-tabwidget.png b/doc/src/images/cleanlooks-tabwidget.png Binary files differnew file mode 100644 index 0000000000..bcff2967aa --- /dev/null +++ b/doc/src/images/cleanlooks-tabwidget.png diff --git a/doc/src/images/cleanlooks-textedit.png b/doc/src/images/cleanlooks-textedit.png Binary files differnew file mode 100644 index 0000000000..0c825a1e04 --- /dev/null +++ b/doc/src/images/cleanlooks-textedit.png diff --git a/doc/src/images/cleanlooks-timeedit.png b/doc/src/images/cleanlooks-timeedit.png Binary files differnew file mode 100644 index 0000000000..00420a2f18 --- /dev/null +++ b/doc/src/images/cleanlooks-timeedit.png diff --git a/doc/src/images/cleanlooks-toolbox.png b/doc/src/images/cleanlooks-toolbox.png Binary files differnew file mode 100644 index 0000000000..63366e5422 --- /dev/null +++ b/doc/src/images/cleanlooks-toolbox.png diff --git a/doc/src/images/cleanlooks-toolbutton.png b/doc/src/images/cleanlooks-toolbutton.png Binary files differnew file mode 100644 index 0000000000..bcf86ea26f --- /dev/null +++ b/doc/src/images/cleanlooks-toolbutton.png diff --git a/doc/src/images/cleanlooks-treeview.png b/doc/src/images/cleanlooks-treeview.png Binary files differnew file mode 100644 index 0000000000..5bc4a06a3c --- /dev/null +++ b/doc/src/images/cleanlooks-treeview.png diff --git a/doc/src/images/clock.png b/doc/src/images/clock.png Binary files differnew file mode 100755 index 0000000000..c7f6a1b296 --- /dev/null +++ b/doc/src/images/clock.png diff --git a/doc/src/images/codecs-example.png b/doc/src/images/codecs-example.png Binary files differnew file mode 100644 index 0000000000..8e7ae95317 --- /dev/null +++ b/doc/src/images/codecs-example.png diff --git a/doc/src/images/codeeditor-example.png b/doc/src/images/codeeditor-example.png Binary files differnew file mode 100644 index 0000000000..b17640695d --- /dev/null +++ b/doc/src/images/codeeditor-example.png diff --git a/doc/src/images/coloreditorfactoryimage.png b/doc/src/images/coloreditorfactoryimage.png Binary files differnew file mode 100644 index 0000000000..cd839a6db6 --- /dev/null +++ b/doc/src/images/coloreditorfactoryimage.png diff --git a/doc/src/images/combowidgetmapper-example.png b/doc/src/images/combowidgetmapper-example.png Binary files differnew file mode 100644 index 0000000000..910d6ed6db --- /dev/null +++ b/doc/src/images/combowidgetmapper-example.png diff --git a/doc/src/images/completer-example-country.png b/doc/src/images/completer-example-country.png Binary files differnew file mode 100644 index 0000000000..fa7c8a9938 --- /dev/null +++ b/doc/src/images/completer-example-country.png diff --git a/doc/src/images/completer-example-word.png b/doc/src/images/completer-example-word.png Binary files differnew file mode 100644 index 0000000000..aa3fb9c333 --- /dev/null +++ b/doc/src/images/completer-example-word.png diff --git a/doc/src/images/completer-example.png b/doc/src/images/completer-example.png Binary files differnew file mode 100644 index 0000000000..dcaa253bd8 --- /dev/null +++ b/doc/src/images/completer-example.png diff --git a/doc/src/images/composition-demo.png b/doc/src/images/composition-demo.png Binary files differnew file mode 100644 index 0000000000..942bc58c29 --- /dev/null +++ b/doc/src/images/composition-demo.png diff --git a/doc/src/images/concentriccircles-example.png b/doc/src/images/concentriccircles-example.png Binary files differnew file mode 100644 index 0000000000..fd308b5642 --- /dev/null +++ b/doc/src/images/concentriccircles-example.png diff --git a/doc/src/images/configdialog-example.png b/doc/src/images/configdialog-example.png Binary files differnew file mode 100644 index 0000000000..20d917b085 --- /dev/null +++ b/doc/src/images/configdialog-example.png diff --git a/doc/src/images/coordinatesystem-transformations.png b/doc/src/images/coordinatesystem-transformations.png Binary files differnew file mode 100644 index 0000000000..2736213c07 --- /dev/null +++ b/doc/src/images/coordinatesystem-transformations.png diff --git a/doc/src/images/customcompleter-example.png b/doc/src/images/customcompleter-example.png Binary files differnew file mode 100644 index 0000000000..a525208118 --- /dev/null +++ b/doc/src/images/customcompleter-example.png diff --git a/doc/src/images/customcompleter-insertcompletion.png b/doc/src/images/customcompleter-insertcompletion.png Binary files differnew file mode 100644 index 0000000000..0bb2c25c39 --- /dev/null +++ b/doc/src/images/customcompleter-insertcompletion.png diff --git a/doc/src/images/customsortfiltermodel-example.png b/doc/src/images/customsortfiltermodel-example.png Binary files differnew file mode 100644 index 0000000000..d7ee8bd7e7 --- /dev/null +++ b/doc/src/images/customsortfiltermodel-example.png diff --git a/doc/src/images/customtypesending-example.png b/doc/src/images/customtypesending-example.png Binary files differnew file mode 100644 index 0000000000..fbc395388e --- /dev/null +++ b/doc/src/images/customtypesending-example.png diff --git a/doc/src/images/dbus-chat-example.png b/doc/src/images/dbus-chat-example.png Binary files differnew file mode 100644 index 0000000000..ad66d08950 --- /dev/null +++ b/doc/src/images/dbus-chat-example.png diff --git a/doc/src/images/deform-demo.png b/doc/src/images/deform-demo.png Binary files differnew file mode 100644 index 0000000000..2f037f08a4 --- /dev/null +++ b/doc/src/images/deform-demo.png diff --git a/doc/src/images/designer-stylesheet-options.png b/doc/src/images/designer-stylesheet-options.png Binary files differnew file mode 100644 index 0000000000..a6893e770b --- /dev/null +++ b/doc/src/images/designer-stylesheet-options.png diff --git a/doc/src/images/designer-stylesheet-usage.png b/doc/src/images/designer-stylesheet-usage.png Binary files differnew file mode 100644 index 0000000000..f6875900de --- /dev/null +++ b/doc/src/images/designer-stylesheet-usage.png diff --git a/doc/src/images/designer-validator-highlighter.png b/doc/src/images/designer-validator-highlighter.png Binary files differnew file mode 100644 index 0000000000..a6661d5c95 --- /dev/null +++ b/doc/src/images/designer-validator-highlighter.png diff --git a/doc/src/images/diagramscene.png b/doc/src/images/diagramscene.png Binary files differnew file mode 100644 index 0000000000..c84fc811e4 --- /dev/null +++ b/doc/src/images/diagramscene.png diff --git a/doc/src/images/digitalclock-example.png b/doc/src/images/digitalclock-example.png Binary files differnew file mode 100644 index 0000000000..473986608c --- /dev/null +++ b/doc/src/images/digitalclock-example.png diff --git a/doc/src/images/dirview-example.png b/doc/src/images/dirview-example.png Binary files differnew file mode 100644 index 0000000000..6412ead5b2 --- /dev/null +++ b/doc/src/images/dirview-example.png diff --git a/doc/src/images/dockwidgets-example.png b/doc/src/images/dockwidgets-example.png Binary files differnew file mode 100644 index 0000000000..2a2d6f8c0c --- /dev/null +++ b/doc/src/images/dockwidgets-example.png diff --git a/doc/src/images/dombookmarks-example.png b/doc/src/images/dombookmarks-example.png Binary files differnew file mode 100644 index 0000000000..abacacbbfc --- /dev/null +++ b/doc/src/images/dombookmarks-example.png diff --git a/doc/src/images/dragdroprobot-example.png b/doc/src/images/dragdroprobot-example.png Binary files differnew file mode 100644 index 0000000000..53aae777b7 --- /dev/null +++ b/doc/src/images/dragdroprobot-example.png diff --git a/doc/src/images/draggableicons-example.png b/doc/src/images/draggableicons-example.png Binary files differnew file mode 100644 index 0000000000..003ce13d03 --- /dev/null +++ b/doc/src/images/draggableicons-example.png diff --git a/doc/src/images/draggabletext-example.png b/doc/src/images/draggabletext-example.png Binary files differnew file mode 100644 index 0000000000..f9b22816e6 --- /dev/null +++ b/doc/src/images/draggabletext-example.png diff --git a/doc/src/images/drilldown-example.png b/doc/src/images/drilldown-example.png Binary files differnew file mode 100644 index 0000000000..68353f704a --- /dev/null +++ b/doc/src/images/drilldown-example.png diff --git a/doc/src/images/dropsite-example.png b/doc/src/images/dropsite-example.png Binary files differnew file mode 100644 index 0000000000..42b988d733 --- /dev/null +++ b/doc/src/images/dropsite-example.png diff --git a/doc/src/images/dummy_tree.png b/doc/src/images/dummy_tree.png Binary files differnew file mode 100755 index 0000000000..7373ea60f6 --- /dev/null +++ b/doc/src/images/dummy_tree.png diff --git a/doc/src/images/easing-example.png b/doc/src/images/easing-example.png Binary files differnew file mode 100644 index 0000000000..de486670ce --- /dev/null +++ b/doc/src/images/easing-example.png diff --git a/doc/src/images/echopluginexample.png b/doc/src/images/echopluginexample.png Binary files differnew file mode 100644 index 0000000000..7cb1e4d63b --- /dev/null +++ b/doc/src/images/echopluginexample.png diff --git a/doc/src/images/elasticnodes-example.png b/doc/src/images/elasticnodes-example.png Binary files differnew file mode 100644 index 0000000000..840f74fe1f --- /dev/null +++ b/doc/src/images/elasticnodes-example.png diff --git a/doc/src/images/embedded-simpledecoration-example-styles.png b/doc/src/images/embedded-simpledecoration-example-styles.png Binary files differnew file mode 100644 index 0000000000..b2ad83c6bd --- /dev/null +++ b/doc/src/images/embedded-simpledecoration-example-styles.png diff --git a/doc/src/images/embedded-simpledecoration-example.png b/doc/src/images/embedded-simpledecoration-example.png Binary files differnew file mode 100644 index 0000000000..bfd04500cb --- /dev/null +++ b/doc/src/images/embedded-simpledecoration-example.png diff --git a/doc/src/images/embeddeddialogs-demo.png b/doc/src/images/embeddeddialogs-demo.png Binary files differnew file mode 100644 index 0000000000..d0da4b6dd5 --- /dev/null +++ b/doc/src/images/embeddeddialogs-demo.png diff --git a/doc/src/images/example_model.png b/doc/src/images/example_model.png Binary files differnew file mode 100755 index 0000000000..4261261c7e --- /dev/null +++ b/doc/src/images/example_model.png diff --git a/doc/src/images/extension-example.png b/doc/src/images/extension-example.png Binary files differnew file mode 100644 index 0000000000..18fab52825 --- /dev/null +++ b/doc/src/images/extension-example.png diff --git a/doc/src/images/extension_more.png b/doc/src/images/extension_more.png Binary files differnew file mode 100644 index 0000000000..407af27cab --- /dev/null +++ b/doc/src/images/extension_more.png diff --git a/doc/src/images/fetchmore-example.png b/doc/src/images/fetchmore-example.png Binary files differnew file mode 100644 index 0000000000..d2359dc8c5 --- /dev/null +++ b/doc/src/images/fetchmore-example.png diff --git a/doc/src/images/filedialogurls.png b/doc/src/images/filedialogurls.png Binary files differnew file mode 100644 index 0000000000..7d22ef33ae --- /dev/null +++ b/doc/src/images/filedialogurls.png diff --git a/doc/src/images/findfiles-example.png b/doc/src/images/findfiles-example.png Binary files differnew file mode 100644 index 0000000000..acb5ea1abf --- /dev/null +++ b/doc/src/images/findfiles-example.png diff --git a/doc/src/images/findfiles_progress_dialog.png b/doc/src/images/findfiles_progress_dialog.png Binary files differnew file mode 100644 index 0000000000..05eda2c52f --- /dev/null +++ b/doc/src/images/findfiles_progress_dialog.png diff --git a/doc/src/images/flickable-demo.png b/doc/src/images/flickable-demo.png Binary files differnew file mode 100644 index 0000000000..98f3a6940f --- /dev/null +++ b/doc/src/images/flickable-demo.png diff --git a/doc/src/images/flightinfo-demo.png b/doc/src/images/flightinfo-demo.png Binary files differnew file mode 100644 index 0000000000..4e9a4b2ba1 --- /dev/null +++ b/doc/src/images/flightinfo-demo.png diff --git a/doc/src/images/flowlayout-example.png b/doc/src/images/flowlayout-example.png Binary files differnew file mode 100644 index 0000000000..61abe1f15e --- /dev/null +++ b/doc/src/images/flowlayout-example.png diff --git a/doc/src/images/fontsampler-example.png b/doc/src/images/fontsampler-example.png Binary files differnew file mode 100644 index 0000000000..7df4a5084e --- /dev/null +++ b/doc/src/images/fontsampler-example.png diff --git a/doc/src/images/fortuneclient-example.png b/doc/src/images/fortuneclient-example.png Binary files differnew file mode 100644 index 0000000000..b34a98736d --- /dev/null +++ b/doc/src/images/fortuneclient-example.png diff --git a/doc/src/images/fortuneserver-example.png b/doc/src/images/fortuneserver-example.png Binary files differnew file mode 100644 index 0000000000..73f27d5653 --- /dev/null +++ b/doc/src/images/fortuneserver-example.png diff --git a/doc/src/images/framebufferobject2-example.png b/doc/src/images/framebufferobject2-example.png Binary files differnew file mode 100644 index 0000000000..bafb05a08b --- /dev/null +++ b/doc/src/images/framebufferobject2-example.png diff --git a/doc/src/images/frames.png b/doc/src/images/frames.png Binary files differnew file mode 100644 index 0000000000..13c08508a2 --- /dev/null +++ b/doc/src/images/frames.png diff --git a/doc/src/images/fridgemagnets-example.png b/doc/src/images/fridgemagnets-example.png Binary files differnew file mode 100644 index 0000000000..9adb572afc --- /dev/null +++ b/doc/src/images/fridgemagnets-example.png diff --git a/doc/src/images/frozencolumn-example.png b/doc/src/images/frozencolumn-example.png Binary files differnew file mode 100644 index 0000000000..66b5c103f8 --- /dev/null +++ b/doc/src/images/frozencolumn-example.png diff --git a/doc/src/images/frozencolumn-tableview.png b/doc/src/images/frozencolumn-tableview.png Binary files differnew file mode 100644 index 0000000000..d829ff5fed --- /dev/null +++ b/doc/src/images/frozencolumn-tableview.png diff --git a/doc/src/images/googlesuggest-example.png b/doc/src/images/googlesuggest-example.png Binary files differnew file mode 100644 index 0000000000..477d444cbd --- /dev/null +++ b/doc/src/images/googlesuggest-example.png diff --git a/doc/src/images/grabber-example.png b/doc/src/images/grabber-example.png Binary files differnew file mode 100644 index 0000000000..6a05b94bec --- /dev/null +++ b/doc/src/images/grabber-example.png diff --git a/doc/src/images/gradients-demo.png b/doc/src/images/gradients-demo.png Binary files differnew file mode 100644 index 0000000000..d80708e048 --- /dev/null +++ b/doc/src/images/gradients-demo.png diff --git a/doc/src/images/graphicsview-items.png b/doc/src/images/graphicsview-items.png Binary files differnew file mode 100644 index 0000000000..73be2ddaee --- /dev/null +++ b/doc/src/images/graphicsview-items.png diff --git a/doc/src/images/graphicsview-pathitem.png b/doc/src/images/graphicsview-pathitem.png Binary files differnew file mode 100644 index 0000000000..c1ddd5620a --- /dev/null +++ b/doc/src/images/graphicsview-pathitem.png diff --git a/doc/src/images/graphicsview-pixmapitem.png b/doc/src/images/graphicsview-pixmapitem.png Binary files differnew file mode 100644 index 0000000000..d14fac55e0 --- /dev/null +++ b/doc/src/images/graphicsview-pixmapitem.png diff --git a/doc/src/images/graphicsview-polygonitem.png b/doc/src/images/graphicsview-polygonitem.png Binary files differnew file mode 100644 index 0000000000..3cd2232574 --- /dev/null +++ b/doc/src/images/graphicsview-polygonitem.png diff --git a/doc/src/images/graphicsview-rectitem.png b/doc/src/images/graphicsview-rectitem.png Binary files differnew file mode 100644 index 0000000000..a5917e55dd --- /dev/null +++ b/doc/src/images/graphicsview-rectitem.png diff --git a/doc/src/images/graphicsview-zorder.png b/doc/src/images/graphicsview-zorder.png Binary files differnew file mode 100644 index 0000000000..a1cc3d0168 --- /dev/null +++ b/doc/src/images/graphicsview-zorder.png diff --git a/doc/src/images/gridlayout.png b/doc/src/images/gridlayout.png Binary files differnew file mode 100644 index 0000000000..ae76c0487b --- /dev/null +++ b/doc/src/images/gridlayout.png diff --git a/doc/src/images/groupbox-example.png b/doc/src/images/groupbox-example.png Binary files differnew file mode 100644 index 0000000000..443f812340 --- /dev/null +++ b/doc/src/images/groupbox-example.png diff --git a/doc/src/images/gtk-calendarwidget.png b/doc/src/images/gtk-calendarwidget.png Binary files differnew file mode 100644 index 0000000000..568cd1a5da --- /dev/null +++ b/doc/src/images/gtk-calendarwidget.png diff --git a/doc/src/images/gtk-checkbox.png b/doc/src/images/gtk-checkbox.png Binary files differnew file mode 100644 index 0000000000..1fd5fc77bf --- /dev/null +++ b/doc/src/images/gtk-checkbox.png diff --git a/doc/src/images/gtk-combobox.png b/doc/src/images/gtk-combobox.png Binary files differnew file mode 100644 index 0000000000..3b4544df13 --- /dev/null +++ b/doc/src/images/gtk-combobox.png diff --git a/doc/src/images/gtk-dateedit.png b/doc/src/images/gtk-dateedit.png Binary files differnew file mode 100644 index 0000000000..25229f0b3b --- /dev/null +++ b/doc/src/images/gtk-dateedit.png diff --git a/doc/src/images/gtk-datetimeedit.png b/doc/src/images/gtk-datetimeedit.png Binary files differnew file mode 100644 index 0000000000..0c934a4d0d --- /dev/null +++ b/doc/src/images/gtk-datetimeedit.png diff --git a/doc/src/images/gtk-dial.png b/doc/src/images/gtk-dial.png Binary files differnew file mode 100644 index 0000000000..18e14b3650 --- /dev/null +++ b/doc/src/images/gtk-dial.png diff --git a/doc/src/images/gtk-doublespinbox.png b/doc/src/images/gtk-doublespinbox.png Binary files differnew file mode 100644 index 0000000000..3a69043c0b --- /dev/null +++ b/doc/src/images/gtk-doublespinbox.png diff --git a/doc/src/images/gtk-fontcombobox.png b/doc/src/images/gtk-fontcombobox.png Binary files differnew file mode 100644 index 0000000000..4cb1bc1343 --- /dev/null +++ b/doc/src/images/gtk-fontcombobox.png diff --git a/doc/src/images/gtk-frame.png b/doc/src/images/gtk-frame.png Binary files differnew file mode 100644 index 0000000000..c1bf52f6a6 --- /dev/null +++ b/doc/src/images/gtk-frame.png diff --git a/doc/src/images/gtk-groupbox.png b/doc/src/images/gtk-groupbox.png Binary files differnew file mode 100644 index 0000000000..6d217c89f9 --- /dev/null +++ b/doc/src/images/gtk-groupbox.png diff --git a/doc/src/images/gtk-horizontalscrollbar.png b/doc/src/images/gtk-horizontalscrollbar.png Binary files differnew file mode 100644 index 0000000000..2887730c13 --- /dev/null +++ b/doc/src/images/gtk-horizontalscrollbar.png diff --git a/doc/src/images/gtk-label.png b/doc/src/images/gtk-label.png Binary files differnew file mode 100644 index 0000000000..006d0133d8 --- /dev/null +++ b/doc/src/images/gtk-label.png diff --git a/doc/src/images/gtk-lcdnumber.png b/doc/src/images/gtk-lcdnumber.png Binary files differnew file mode 100644 index 0000000000..142d298ffc --- /dev/null +++ b/doc/src/images/gtk-lcdnumber.png diff --git a/doc/src/images/gtk-lineedit.png b/doc/src/images/gtk-lineedit.png Binary files differnew file mode 100644 index 0000000000..8fb513c39f --- /dev/null +++ b/doc/src/images/gtk-lineedit.png diff --git a/doc/src/images/gtk-listview.png b/doc/src/images/gtk-listview.png Binary files differnew file mode 100644 index 0000000000..d32f8e8aee --- /dev/null +++ b/doc/src/images/gtk-listview.png diff --git a/doc/src/images/gtk-progressbar.png b/doc/src/images/gtk-progressbar.png Binary files differnew file mode 100644 index 0000000000..6162484bf3 --- /dev/null +++ b/doc/src/images/gtk-progressbar.png diff --git a/doc/src/images/gtk-pushbutton.png b/doc/src/images/gtk-pushbutton.png Binary files differnew file mode 100644 index 0000000000..f4f4d7c1e4 --- /dev/null +++ b/doc/src/images/gtk-pushbutton.png diff --git a/doc/src/images/gtk-radiobutton.png b/doc/src/images/gtk-radiobutton.png Binary files differnew file mode 100644 index 0000000000..b3620fa054 --- /dev/null +++ b/doc/src/images/gtk-radiobutton.png diff --git a/doc/src/images/gtk-slider.png b/doc/src/images/gtk-slider.png Binary files differnew file mode 100644 index 0000000000..3d8e0ee89e --- /dev/null +++ b/doc/src/images/gtk-slider.png diff --git a/doc/src/images/gtk-spinbox.png b/doc/src/images/gtk-spinbox.png Binary files differnew file mode 100644 index 0000000000..a39eb3aa93 --- /dev/null +++ b/doc/src/images/gtk-spinbox.png diff --git a/doc/src/images/gtk-tableview.png b/doc/src/images/gtk-tableview.png Binary files differnew file mode 100644 index 0000000000..a025193188 --- /dev/null +++ b/doc/src/images/gtk-tableview.png diff --git a/doc/src/images/gtk-tabwidget.png b/doc/src/images/gtk-tabwidget.png Binary files differnew file mode 100644 index 0000000000..089c76dad2 --- /dev/null +++ b/doc/src/images/gtk-tabwidget.png diff --git a/doc/src/images/gtk-textedit.png b/doc/src/images/gtk-textedit.png Binary files differnew file mode 100644 index 0000000000..e4b91c01c9 --- /dev/null +++ b/doc/src/images/gtk-textedit.png diff --git a/doc/src/images/gtk-timeedit.png b/doc/src/images/gtk-timeedit.png Binary files differnew file mode 100644 index 0000000000..acf6730a86 --- /dev/null +++ b/doc/src/images/gtk-timeedit.png diff --git a/doc/src/images/gtk-toolbox.png b/doc/src/images/gtk-toolbox.png Binary files differnew file mode 100644 index 0000000000..25e6137699 --- /dev/null +++ b/doc/src/images/gtk-toolbox.png diff --git a/doc/src/images/gtk-toolbutton.png b/doc/src/images/gtk-toolbutton.png Binary files differnew file mode 100644 index 0000000000..f0eb86efc5 --- /dev/null +++ b/doc/src/images/gtk-toolbutton.png diff --git a/doc/src/images/gtk-treeview.png b/doc/src/images/gtk-treeview.png Binary files differnew file mode 100644 index 0000000000..7b4e3044be --- /dev/null +++ b/doc/src/images/gtk-treeview.png diff --git a/doc/src/images/hellogl-es-example.png b/doc/src/images/hellogl-es-example.png Binary files differnew file mode 100644 index 0000000000..7e55f09a7a --- /dev/null +++ b/doc/src/images/hellogl-es-example.png diff --git a/doc/src/images/hellogl-example.png b/doc/src/images/hellogl-example.png Binary files differnew file mode 100644 index 0000000000..ecb3a3a7b0 --- /dev/null +++ b/doc/src/images/hellogl-example.png diff --git a/doc/src/images/hoverevents.png b/doc/src/images/hoverevents.png Binary files differnew file mode 100644 index 0000000000..ccc079bdf1 --- /dev/null +++ b/doc/src/images/hoverevents.png diff --git a/doc/src/images/http-example.png b/doc/src/images/http-example.png Binary files differnew file mode 100644 index 0000000000..16b0539b1b --- /dev/null +++ b/doc/src/images/http-example.png diff --git a/doc/src/images/httpstack.png b/doc/src/images/httpstack.png Binary files differnew file mode 100644 index 0000000000..658927bd81 --- /dev/null +++ b/doc/src/images/httpstack.png diff --git a/doc/src/images/i18n-example.png b/doc/src/images/i18n-example.png Binary files differnew file mode 100644 index 0000000000..20c46c9e63 --- /dev/null +++ b/doc/src/images/i18n-example.png diff --git a/doc/src/images/icons-example.png b/doc/src/images/icons-example.png Binary files differnew file mode 100644 index 0000000000..ae4b1d3234 --- /dev/null +++ b/doc/src/images/icons-example.png diff --git a/doc/src/images/icons-view-menu.png b/doc/src/images/icons-view-menu.png Binary files differnew file mode 100644 index 0000000000..7fc02a09a1 --- /dev/null +++ b/doc/src/images/icons-view-menu.png diff --git a/doc/src/images/icons_find_normal.png b/doc/src/images/icons_find_normal.png Binary files differnew file mode 100644 index 0000000000..c92c7e1740 --- /dev/null +++ b/doc/src/images/icons_find_normal.png diff --git a/doc/src/images/icons_find_normal_disabled.png b/doc/src/images/icons_find_normal_disabled.png Binary files differnew file mode 100644 index 0000000000..534d6de4cf --- /dev/null +++ b/doc/src/images/icons_find_normal_disabled.png diff --git a/doc/src/images/icons_images_groupbox.png b/doc/src/images/icons_images_groupbox.png Binary files differnew file mode 100644 index 0000000000..f4942f76fb --- /dev/null +++ b/doc/src/images/icons_images_groupbox.png diff --git a/doc/src/images/icons_monkey_active.png b/doc/src/images/icons_monkey_active.png Binary files differnew file mode 100644 index 0000000000..edb5132040 --- /dev/null +++ b/doc/src/images/icons_monkey_active.png diff --git a/doc/src/images/icons_preview_area.png b/doc/src/images/icons_preview_area.png Binary files differnew file mode 100644 index 0000000000..098afae4bc --- /dev/null +++ b/doc/src/images/icons_preview_area.png diff --git a/doc/src/images/icons_size_groupbox.png b/doc/src/images/icons_size_groupbox.png Binary files differnew file mode 100644 index 0000000000..1360280529 --- /dev/null +++ b/doc/src/images/icons_size_groupbox.png diff --git a/doc/src/images/icons_size_spinbox.png b/doc/src/images/icons_size_spinbox.png Binary files differnew file mode 100644 index 0000000000..a23ee9f110 --- /dev/null +++ b/doc/src/images/icons_size_spinbox.png diff --git a/doc/src/images/imagecomposition-example.png b/doc/src/images/imagecomposition-example.png Binary files differnew file mode 100644 index 0000000000..697c980d5a --- /dev/null +++ b/doc/src/images/imagecomposition-example.png diff --git a/doc/src/images/imageviewer-example.png b/doc/src/images/imageviewer-example.png Binary files differnew file mode 100644 index 0000000000..69b4f7ade7 --- /dev/null +++ b/doc/src/images/imageviewer-example.png diff --git a/doc/src/images/inputpanel-example.png b/doc/src/images/inputpanel-example.png Binary files differnew file mode 100644 index 0000000000..0dd93251cb --- /dev/null +++ b/doc/src/images/inputpanel-example.png diff --git a/doc/src/images/insertrowinmodelview.png b/doc/src/images/insertrowinmodelview.png Binary files differnew file mode 100644 index 0000000000..bddc401ad2 --- /dev/null +++ b/doc/src/images/insertrowinmodelview.png diff --git a/doc/src/images/interview-demo.png b/doc/src/images/interview-demo.png Binary files differnew file mode 100644 index 0000000000..d4a1956883 --- /dev/null +++ b/doc/src/images/interview-demo.png diff --git a/doc/src/images/itemviews-editabletreemodel.png b/doc/src/images/itemviews-editabletreemodel.png Binary files differnew file mode 100644 index 0000000000..a151ea857f --- /dev/null +++ b/doc/src/images/itemviews-editabletreemodel.png diff --git a/doc/src/images/javastyle/branchindicatorimage.png b/doc/src/images/javastyle/branchindicatorimage.png Binary files differnew file mode 100644 index 0000000000..f2cfc4b2e9 --- /dev/null +++ b/doc/src/images/javastyle/branchindicatorimage.png diff --git a/doc/src/images/javastyle/button.png b/doc/src/images/javastyle/button.png Binary files differnew file mode 100644 index 0000000000..c3a97425b1 --- /dev/null +++ b/doc/src/images/javastyle/button.png diff --git a/doc/src/images/javastyle/checkbox.png b/doc/src/images/javastyle/checkbox.png Binary files differnew file mode 100644 index 0000000000..bc841a6a6d --- /dev/null +++ b/doc/src/images/javastyle/checkbox.png diff --git a/doc/src/images/javastyle/checkboxexample.png b/doc/src/images/javastyle/checkboxexample.png Binary files differnew file mode 100644 index 0000000000..69217fb2e5 --- /dev/null +++ b/doc/src/images/javastyle/checkboxexample.png diff --git a/doc/src/images/javastyle/combobox.png b/doc/src/images/javastyle/combobox.png Binary files differnew file mode 100644 index 0000000000..de9745a218 --- /dev/null +++ b/doc/src/images/javastyle/combobox.png diff --git a/doc/src/images/javastyle/comboboximage.png b/doc/src/images/javastyle/comboboximage.png Binary files differnew file mode 100644 index 0000000000..1f05e5fe86 --- /dev/null +++ b/doc/src/images/javastyle/comboboximage.png diff --git a/doc/src/images/javastyle/conceptualpushbuttontree.png b/doc/src/images/javastyle/conceptualpushbuttontree.png Binary files differnew file mode 100644 index 0000000000..910000a6e8 --- /dev/null +++ b/doc/src/images/javastyle/conceptualpushbuttontree.png diff --git a/doc/src/images/javastyle/dockwidget.png b/doc/src/images/javastyle/dockwidget.png Binary files differnew file mode 100644 index 0000000000..4bfec142bf --- /dev/null +++ b/doc/src/images/javastyle/dockwidget.png diff --git a/doc/src/images/javastyle/dockwidgetimage.png b/doc/src/images/javastyle/dockwidgetimage.png Binary files differnew file mode 100644 index 0000000000..eefe171e3e --- /dev/null +++ b/doc/src/images/javastyle/dockwidgetimage.png diff --git a/doc/src/images/javastyle/groupbox.png b/doc/src/images/javastyle/groupbox.png Binary files differnew file mode 100644 index 0000000000..a39cd42c9f --- /dev/null +++ b/doc/src/images/javastyle/groupbox.png diff --git a/doc/src/images/javastyle/groupboximage.png b/doc/src/images/javastyle/groupboximage.png Binary files differnew file mode 100644 index 0000000000..5baf6092d4 --- /dev/null +++ b/doc/src/images/javastyle/groupboximage.png diff --git a/doc/src/images/javastyle/header.png b/doc/src/images/javastyle/header.png Binary files differnew file mode 100644 index 0000000000..b4546d840e --- /dev/null +++ b/doc/src/images/javastyle/header.png diff --git a/doc/src/images/javastyle/headerimage.png b/doc/src/images/javastyle/headerimage.png Binary files differnew file mode 100644 index 0000000000..41171497d5 --- /dev/null +++ b/doc/src/images/javastyle/headerimage.png diff --git a/doc/src/images/javastyle/menu.png b/doc/src/images/javastyle/menu.png Binary files differnew file mode 100644 index 0000000000..8d44da4054 --- /dev/null +++ b/doc/src/images/javastyle/menu.png diff --git a/doc/src/images/javastyle/menubar.png b/doc/src/images/javastyle/menubar.png Binary files differnew file mode 100644 index 0000000000..e68e4a3a55 --- /dev/null +++ b/doc/src/images/javastyle/menubar.png diff --git a/doc/src/images/javastyle/menubarimage.png b/doc/src/images/javastyle/menubarimage.png Binary files differnew file mode 100644 index 0000000000..b0cf28edcc --- /dev/null +++ b/doc/src/images/javastyle/menubarimage.png diff --git a/doc/src/images/javastyle/menuimage.png b/doc/src/images/javastyle/menuimage.png Binary files differnew file mode 100644 index 0000000000..282dde7159 --- /dev/null +++ b/doc/src/images/javastyle/menuimage.png diff --git a/doc/src/images/javastyle/progressbar.png b/doc/src/images/javastyle/progressbar.png Binary files differnew file mode 100644 index 0000000000..de3a838c38 --- /dev/null +++ b/doc/src/images/javastyle/progressbar.png diff --git a/doc/src/images/javastyle/progressbarimage.png b/doc/src/images/javastyle/progressbarimage.png Binary files differnew file mode 100644 index 0000000000..433b900ab5 --- /dev/null +++ b/doc/src/images/javastyle/progressbarimage.png diff --git a/doc/src/images/javastyle/pushbutton.png b/doc/src/images/javastyle/pushbutton.png Binary files differnew file mode 100644 index 0000000000..e5f92bea12 --- /dev/null +++ b/doc/src/images/javastyle/pushbutton.png diff --git a/doc/src/images/javastyle/rubberband.png b/doc/src/images/javastyle/rubberband.png Binary files differnew file mode 100644 index 0000000000..087424a3f0 --- /dev/null +++ b/doc/src/images/javastyle/rubberband.png diff --git a/doc/src/images/javastyle/rubberbandimage.png b/doc/src/images/javastyle/rubberbandimage.png Binary files differnew file mode 100644 index 0000000000..2794638dbc --- /dev/null +++ b/doc/src/images/javastyle/rubberbandimage.png diff --git a/doc/src/images/javastyle/scrollbar.png b/doc/src/images/javastyle/scrollbar.png Binary files differnew file mode 100644 index 0000000000..c1ecb5d655 --- /dev/null +++ b/doc/src/images/javastyle/scrollbar.png diff --git a/doc/src/images/javastyle/scrollbarimage.png b/doc/src/images/javastyle/scrollbarimage.png Binary files differnew file mode 100644 index 0000000000..6d3e29d8dd --- /dev/null +++ b/doc/src/images/javastyle/scrollbarimage.png diff --git a/doc/src/images/javastyle/sizegrip.png b/doc/src/images/javastyle/sizegrip.png Binary files differnew file mode 100644 index 0000000000..667e6fb465 --- /dev/null +++ b/doc/src/images/javastyle/sizegrip.png diff --git a/doc/src/images/javastyle/sizegripimage.png b/doc/src/images/javastyle/sizegripimage.png Binary files differnew file mode 100644 index 0000000000..ccbf5254d3 --- /dev/null +++ b/doc/src/images/javastyle/sizegripimage.png diff --git a/doc/src/images/javastyle/slider.png b/doc/src/images/javastyle/slider.png Binary files differnew file mode 100644 index 0000000000..a382233f58 --- /dev/null +++ b/doc/src/images/javastyle/slider.png diff --git a/doc/src/images/javastyle/sliderimage.png b/doc/src/images/javastyle/sliderimage.png Binary files differnew file mode 100644 index 0000000000..df700dd712 --- /dev/null +++ b/doc/src/images/javastyle/sliderimage.png diff --git a/doc/src/images/javastyle/spinbox.png b/doc/src/images/javastyle/spinbox.png Binary files differnew file mode 100644 index 0000000000..ec9d6e0d75 --- /dev/null +++ b/doc/src/images/javastyle/spinbox.png diff --git a/doc/src/images/javastyle/spinboximage.png b/doc/src/images/javastyle/spinboximage.png Binary files differnew file mode 100644 index 0000000000..d0d57c8ffb --- /dev/null +++ b/doc/src/images/javastyle/spinboximage.png diff --git a/doc/src/images/javastyle/tab.png b/doc/src/images/javastyle/tab.png Binary files differnew file mode 100644 index 0000000000..616580c839 --- /dev/null +++ b/doc/src/images/javastyle/tab.png diff --git a/doc/src/images/javastyle/tabwidget.png b/doc/src/images/javastyle/tabwidget.png Binary files differnew file mode 100644 index 0000000000..737155ccb9 --- /dev/null +++ b/doc/src/images/javastyle/tabwidget.png diff --git a/doc/src/images/javastyle/titlebar.png b/doc/src/images/javastyle/titlebar.png Binary files differnew file mode 100644 index 0000000000..5d7ecc481d --- /dev/null +++ b/doc/src/images/javastyle/titlebar.png diff --git a/doc/src/images/javastyle/titlebarimage.png b/doc/src/images/javastyle/titlebarimage.png Binary files differnew file mode 100644 index 0000000000..50287aeb1d --- /dev/null +++ b/doc/src/images/javastyle/titlebarimage.png diff --git a/doc/src/images/javastyle/toolbar.png b/doc/src/images/javastyle/toolbar.png Binary files differnew file mode 100644 index 0000000000..e69e8df4c8 --- /dev/null +++ b/doc/src/images/javastyle/toolbar.png diff --git a/doc/src/images/javastyle/toolbarimage.png b/doc/src/images/javastyle/toolbarimage.png Binary files differnew file mode 100644 index 0000000000..b9025f582a --- /dev/null +++ b/doc/src/images/javastyle/toolbarimage.png diff --git a/doc/src/images/javastyle/toolbox.png b/doc/src/images/javastyle/toolbox.png Binary files differnew file mode 100644 index 0000000000..c5f61ecec8 --- /dev/null +++ b/doc/src/images/javastyle/toolbox.png diff --git a/doc/src/images/javastyle/toolboximage.png b/doc/src/images/javastyle/toolboximage.png Binary files differnew file mode 100644 index 0000000000..7bcbd26432 --- /dev/null +++ b/doc/src/images/javastyle/toolboximage.png diff --git a/doc/src/images/javastyle/toolbutton.png b/doc/src/images/javastyle/toolbutton.png Binary files differnew file mode 100644 index 0000000000..9167e83f75 --- /dev/null +++ b/doc/src/images/javastyle/toolbutton.png diff --git a/doc/src/images/javastyle/toolbuttonimage.png b/doc/src/images/javastyle/toolbuttonimage.png Binary files differnew file mode 100644 index 0000000000..3217172fca --- /dev/null +++ b/doc/src/images/javastyle/toolbuttonimage.png diff --git a/doc/src/images/javastyle/windowstabimage.png b/doc/src/images/javastyle/windowstabimage.png Binary files differnew file mode 100644 index 0000000000..485e847844 --- /dev/null +++ b/doc/src/images/javastyle/windowstabimage.png diff --git a/doc/src/images/licensewizard-example.png b/doc/src/images/licensewizard-example.png Binary files differnew file mode 100644 index 0000000000..97b3aaae4b --- /dev/null +++ b/doc/src/images/licensewizard-example.png diff --git a/doc/src/images/licensewizard-flow.png b/doc/src/images/licensewizard-flow.png Binary files differnew file mode 100644 index 0000000000..76df63a98f --- /dev/null +++ b/doc/src/images/licensewizard-flow.png diff --git a/doc/src/images/lightingeffect-example.png b/doc/src/images/lightingeffect-example.png Binary files differnew file mode 100644 index 0000000000..d9dc990481 --- /dev/null +++ b/doc/src/images/lightingeffect-example.png diff --git a/doc/src/images/lightmaps-demo.png b/doc/src/images/lightmaps-demo.png Binary files differnew file mode 100644 index 0000000000..f066f939d4 --- /dev/null +++ b/doc/src/images/lightmaps-demo.png diff --git a/doc/src/images/lineedits-example.png b/doc/src/images/lineedits-example.png Binary files differnew file mode 100644 index 0000000000..ff5e3184ad --- /dev/null +++ b/doc/src/images/lineedits-example.png diff --git a/doc/src/images/linguist-arrowpad_en.png b/doc/src/images/linguist-arrowpad_en.png Binary files differnew file mode 100644 index 0000000000..9a95eb24ff --- /dev/null +++ b/doc/src/images/linguist-arrowpad_en.png diff --git a/doc/src/images/linguist-arrowpad_fr.png b/doc/src/images/linguist-arrowpad_fr.png Binary files differnew file mode 100644 index 0000000000..fc33f9fd73 --- /dev/null +++ b/doc/src/images/linguist-arrowpad_fr.png diff --git a/doc/src/images/linguist-arrowpad_nl.png b/doc/src/images/linguist-arrowpad_nl.png Binary files differnew file mode 100644 index 0000000000..f2645a81b3 --- /dev/null +++ b/doc/src/images/linguist-arrowpad_nl.png diff --git a/doc/src/images/linguist-hellotr_en.png b/doc/src/images/linguist-hellotr_en.png Binary files differnew file mode 100644 index 0000000000..6b3d8072cd --- /dev/null +++ b/doc/src/images/linguist-hellotr_en.png diff --git a/doc/src/images/linguist-hellotr_la.png b/doc/src/images/linguist-hellotr_la.png Binary files differnew file mode 100644 index 0000000000..f1ecdb07ad --- /dev/null +++ b/doc/src/images/linguist-hellotr_la.png diff --git a/doc/src/images/linguist-trollprint_10_en.png b/doc/src/images/linguist-trollprint_10_en.png Binary files differnew file mode 100644 index 0000000000..e460481f96 --- /dev/null +++ b/doc/src/images/linguist-trollprint_10_en.png diff --git a/doc/src/images/linguist-trollprint_10_pt_bad.png b/doc/src/images/linguist-trollprint_10_pt_bad.png Binary files differnew file mode 100644 index 0000000000..b96d477240 --- /dev/null +++ b/doc/src/images/linguist-trollprint_10_pt_bad.png diff --git a/doc/src/images/linguist-trollprint_10_pt_good.png b/doc/src/images/linguist-trollprint_10_pt_good.png Binary files differnew file mode 100644 index 0000000000..293c44a746 --- /dev/null +++ b/doc/src/images/linguist-trollprint_10_pt_good.png diff --git a/doc/src/images/linguist-trollprint_11_en.png b/doc/src/images/linguist-trollprint_11_en.png Binary files differnew file mode 100644 index 0000000000..f718c995c0 --- /dev/null +++ b/doc/src/images/linguist-trollprint_11_en.png diff --git a/doc/src/images/linguist-trollprint_11_pt.png b/doc/src/images/linguist-trollprint_11_pt.png Binary files differnew file mode 100644 index 0000000000..0ff8c399b3 --- /dev/null +++ b/doc/src/images/linguist-trollprint_11_pt.png diff --git a/doc/src/images/list_table_tree.png b/doc/src/images/list_table_tree.png Binary files differnew file mode 100755 index 0000000000..b2daf1f3a5 --- /dev/null +++ b/doc/src/images/list_table_tree.png diff --git a/doc/src/images/localfortuneclient-example.png b/doc/src/images/localfortuneclient-example.png Binary files differnew file mode 100644 index 0000000000..614784bf0f --- /dev/null +++ b/doc/src/images/localfortuneclient-example.png diff --git a/doc/src/images/localfortuneserver-example.png b/doc/src/images/localfortuneserver-example.png Binary files differnew file mode 100644 index 0000000000..2f04c7528e --- /dev/null +++ b/doc/src/images/localfortuneserver-example.png diff --git a/doc/src/images/loopback-example.png b/doc/src/images/loopback-example.png Binary files differnew file mode 100644 index 0000000000..2b1bd4a0f2 --- /dev/null +++ b/doc/src/images/loopback-example.png diff --git a/doc/src/images/macintosh-calendarwidget.png b/doc/src/images/macintosh-calendarwidget.png Binary files differnew file mode 100644 index 0000000000..2f743501a9 --- /dev/null +++ b/doc/src/images/macintosh-calendarwidget.png diff --git a/doc/src/images/macintosh-checkbox.png b/doc/src/images/macintosh-checkbox.png Binary files differnew file mode 100644 index 0000000000..d0130e3f22 --- /dev/null +++ b/doc/src/images/macintosh-checkbox.png diff --git a/doc/src/images/macintosh-combobox.png b/doc/src/images/macintosh-combobox.png Binary files differnew file mode 100644 index 0000000000..c1dc3c0c96 --- /dev/null +++ b/doc/src/images/macintosh-combobox.png diff --git a/doc/src/images/macintosh-dateedit.png b/doc/src/images/macintosh-dateedit.png Binary files differnew file mode 100644 index 0000000000..45aee90a9b --- /dev/null +++ b/doc/src/images/macintosh-dateedit.png diff --git a/doc/src/images/macintosh-datetimeedit.png b/doc/src/images/macintosh-datetimeedit.png Binary files differnew file mode 100644 index 0000000000..62af02d64e --- /dev/null +++ b/doc/src/images/macintosh-datetimeedit.png diff --git a/doc/src/images/macintosh-dial.png b/doc/src/images/macintosh-dial.png Binary files differnew file mode 100644 index 0000000000..df0ffe23a1 --- /dev/null +++ b/doc/src/images/macintosh-dial.png diff --git a/doc/src/images/macintosh-doublespinbox.png b/doc/src/images/macintosh-doublespinbox.png Binary files differnew file mode 100644 index 0000000000..a0695ff278 --- /dev/null +++ b/doc/src/images/macintosh-doublespinbox.png diff --git a/doc/src/images/macintosh-fontcombobox.png b/doc/src/images/macintosh-fontcombobox.png Binary files differnew file mode 100644 index 0000000000..8a5a3c78a3 --- /dev/null +++ b/doc/src/images/macintosh-fontcombobox.png diff --git a/doc/src/images/macintosh-frame.png b/doc/src/images/macintosh-frame.png Binary files differnew file mode 100644 index 0000000000..fee61a3643 --- /dev/null +++ b/doc/src/images/macintosh-frame.png diff --git a/doc/src/images/macintosh-groupbox.png b/doc/src/images/macintosh-groupbox.png Binary files differnew file mode 100644 index 0000000000..f6c7bce580 --- /dev/null +++ b/doc/src/images/macintosh-groupbox.png diff --git a/doc/src/images/macintosh-horizontalscrollbar.png b/doc/src/images/macintosh-horizontalscrollbar.png Binary files differnew file mode 100644 index 0000000000..8b63572a9e --- /dev/null +++ b/doc/src/images/macintosh-horizontalscrollbar.png diff --git a/doc/src/images/macintosh-label.png b/doc/src/images/macintosh-label.png Binary files differnew file mode 100644 index 0000000000..753aa4d138 --- /dev/null +++ b/doc/src/images/macintosh-label.png diff --git a/doc/src/images/macintosh-lcdnumber.png b/doc/src/images/macintosh-lcdnumber.png Binary files differnew file mode 100644 index 0000000000..2ea9ea0713 --- /dev/null +++ b/doc/src/images/macintosh-lcdnumber.png diff --git a/doc/src/images/macintosh-lineedit.png b/doc/src/images/macintosh-lineedit.png Binary files differnew file mode 100644 index 0000000000..0e992c7ffe --- /dev/null +++ b/doc/src/images/macintosh-lineedit.png diff --git a/doc/src/images/macintosh-listview.png b/doc/src/images/macintosh-listview.png Binary files differnew file mode 100644 index 0000000000..346e6427ff --- /dev/null +++ b/doc/src/images/macintosh-listview.png diff --git a/doc/src/images/macintosh-progressbar.png b/doc/src/images/macintosh-progressbar.png Binary files differnew file mode 100644 index 0000000000..2dfc8aba81 --- /dev/null +++ b/doc/src/images/macintosh-progressbar.png diff --git a/doc/src/images/macintosh-pushbutton.png b/doc/src/images/macintosh-pushbutton.png Binary files differnew file mode 100644 index 0000000000..7ec14910d8 --- /dev/null +++ b/doc/src/images/macintosh-pushbutton.png diff --git a/doc/src/images/macintosh-radiobutton.png b/doc/src/images/macintosh-radiobutton.png Binary files differnew file mode 100644 index 0000000000..8b02f509ff --- /dev/null +++ b/doc/src/images/macintosh-radiobutton.png diff --git a/doc/src/images/macintosh-slider.png b/doc/src/images/macintosh-slider.png Binary files differnew file mode 100644 index 0000000000..bf0c5464e9 --- /dev/null +++ b/doc/src/images/macintosh-slider.png diff --git a/doc/src/images/macintosh-spinbox.png b/doc/src/images/macintosh-spinbox.png Binary files differnew file mode 100644 index 0000000000..4196c37246 --- /dev/null +++ b/doc/src/images/macintosh-spinbox.png diff --git a/doc/src/images/macintosh-tableview.png b/doc/src/images/macintosh-tableview.png Binary files differnew file mode 100644 index 0000000000..e6512494de --- /dev/null +++ b/doc/src/images/macintosh-tableview.png diff --git a/doc/src/images/macintosh-tabwidget.png b/doc/src/images/macintosh-tabwidget.png Binary files differnew file mode 100644 index 0000000000..1d174a47e6 --- /dev/null +++ b/doc/src/images/macintosh-tabwidget.png diff --git a/doc/src/images/macintosh-textedit.png b/doc/src/images/macintosh-textedit.png Binary files differnew file mode 100644 index 0000000000..4f0ce36baf --- /dev/null +++ b/doc/src/images/macintosh-textedit.png diff --git a/doc/src/images/macintosh-timeedit.png b/doc/src/images/macintosh-timeedit.png Binary files differnew file mode 100644 index 0000000000..4bcfce33f8 --- /dev/null +++ b/doc/src/images/macintosh-timeedit.png diff --git a/doc/src/images/macintosh-toolbox.png b/doc/src/images/macintosh-toolbox.png Binary files differnew file mode 100644 index 0000000000..18d41ea595 --- /dev/null +++ b/doc/src/images/macintosh-toolbox.png diff --git a/doc/src/images/macintosh-toolbutton.png b/doc/src/images/macintosh-toolbutton.png Binary files differnew file mode 100644 index 0000000000..f91331cc51 --- /dev/null +++ b/doc/src/images/macintosh-toolbutton.png diff --git a/doc/src/images/macintosh-treeview.png b/doc/src/images/macintosh-treeview.png Binary files differnew file mode 100644 index 0000000000..afda6d8372 --- /dev/null +++ b/doc/src/images/macintosh-treeview.png diff --git a/doc/src/images/macmainwindow.png b/doc/src/images/macmainwindow.png Binary files differnew file mode 100644 index 0000000000..84eb11ca5e --- /dev/null +++ b/doc/src/images/macmainwindow.png diff --git a/doc/src/images/mainwindow-demo.png b/doc/src/images/mainwindow-demo.png Binary files differnew file mode 100644 index 0000000000..5799dc0fa3 --- /dev/null +++ b/doc/src/images/mainwindow-demo.png diff --git a/doc/src/images/mainwindow-docks-example.png b/doc/src/images/mainwindow-docks-example.png Binary files differnew file mode 100644 index 0000000000..a5641fd9cd --- /dev/null +++ b/doc/src/images/mainwindow-docks-example.png diff --git a/doc/src/images/mainwindow-docks.png b/doc/src/images/mainwindow-docks.png Binary files differnew file mode 100644 index 0000000000..24f42a28ea --- /dev/null +++ b/doc/src/images/mainwindow-docks.png diff --git a/doc/src/images/mainwindowlayout.png b/doc/src/images/mainwindowlayout.png Binary files differnew file mode 100644 index 0000000000..4776ce4f1b --- /dev/null +++ b/doc/src/images/mainwindowlayout.png diff --git a/doc/src/images/mandelbrot-example.png b/doc/src/images/mandelbrot-example.png Binary files differnew file mode 100644 index 0000000000..f5817834e1 --- /dev/null +++ b/doc/src/images/mandelbrot-example.png diff --git a/doc/src/images/masterdetail-example.png b/doc/src/images/masterdetail-example.png Binary files differnew file mode 100644 index 0000000000..bc282b7a78 --- /dev/null +++ b/doc/src/images/masterdetail-example.png diff --git a/doc/src/images/mdi-example.png b/doc/src/images/mdi-example.png Binary files differnew file mode 100644 index 0000000000..240f9e222c --- /dev/null +++ b/doc/src/images/mdi-example.png diff --git a/doc/src/images/menus-example.png b/doc/src/images/menus-example.png Binary files differnew file mode 100644 index 0000000000..81e6e0d270 --- /dev/null +++ b/doc/src/images/menus-example.png diff --git a/doc/src/images/modelindex-no-parent.png b/doc/src/images/modelindex-no-parent.png Binary files differnew file mode 100644 index 0000000000..9c6258e5d1 --- /dev/null +++ b/doc/src/images/modelindex-no-parent.png diff --git a/doc/src/images/modelview-header.png b/doc/src/images/modelview-header.png Binary files differnew file mode 100755 index 0000000000..2597635b9f --- /dev/null +++ b/doc/src/images/modelview-header.png diff --git a/doc/src/images/modelview.png b/doc/src/images/modelview.png Binary files differnew file mode 100755 index 0000000000..7b042af8a4 --- /dev/null +++ b/doc/src/images/modelview.png diff --git a/doc/src/images/motif-calendarwidget.png b/doc/src/images/motif-calendarwidget.png Binary files differnew file mode 100644 index 0000000000..4ce6aebc21 --- /dev/null +++ b/doc/src/images/motif-calendarwidget.png diff --git a/doc/src/images/motif-checkbox.png b/doc/src/images/motif-checkbox.png Binary files differnew file mode 100644 index 0000000000..2a263273a6 --- /dev/null +++ b/doc/src/images/motif-checkbox.png diff --git a/doc/src/images/motif-combobox.png b/doc/src/images/motif-combobox.png Binary files differnew file mode 100644 index 0000000000..2a288d9f40 --- /dev/null +++ b/doc/src/images/motif-combobox.png diff --git a/doc/src/images/motif-dateedit.png b/doc/src/images/motif-dateedit.png Binary files differnew file mode 100644 index 0000000000..d00c45ff65 --- /dev/null +++ b/doc/src/images/motif-dateedit.png diff --git a/doc/src/images/motif-datetimeedit.png b/doc/src/images/motif-datetimeedit.png Binary files differnew file mode 100644 index 0000000000..cc43ef888d --- /dev/null +++ b/doc/src/images/motif-datetimeedit.png diff --git a/doc/src/images/motif-dial.png b/doc/src/images/motif-dial.png Binary files differnew file mode 100644 index 0000000000..36b3ff7be0 --- /dev/null +++ b/doc/src/images/motif-dial.png diff --git a/doc/src/images/motif-doublespinbox.png b/doc/src/images/motif-doublespinbox.png Binary files differnew file mode 100644 index 0000000000..6092913ab0 --- /dev/null +++ b/doc/src/images/motif-doublespinbox.png diff --git a/doc/src/images/motif-fontcombobox.png b/doc/src/images/motif-fontcombobox.png Binary files differnew file mode 100644 index 0000000000..c07452d85e --- /dev/null +++ b/doc/src/images/motif-fontcombobox.png diff --git a/doc/src/images/motif-frame.png b/doc/src/images/motif-frame.png Binary files differnew file mode 100644 index 0000000000..55dcc32227 --- /dev/null +++ b/doc/src/images/motif-frame.png diff --git a/doc/src/images/motif-groupbox.png b/doc/src/images/motif-groupbox.png Binary files differnew file mode 100644 index 0000000000..13742b116e --- /dev/null +++ b/doc/src/images/motif-groupbox.png diff --git a/doc/src/images/motif-horizontalscrollbar.png b/doc/src/images/motif-horizontalscrollbar.png Binary files differnew file mode 100644 index 0000000000..dab1d3f6f6 --- /dev/null +++ b/doc/src/images/motif-horizontalscrollbar.png diff --git a/doc/src/images/motif-label.png b/doc/src/images/motif-label.png Binary files differnew file mode 100644 index 0000000000..7ae6674f50 --- /dev/null +++ b/doc/src/images/motif-label.png diff --git a/doc/src/images/motif-lcdnumber.png b/doc/src/images/motif-lcdnumber.png Binary files differnew file mode 100644 index 0000000000..e2cc9a8058 --- /dev/null +++ b/doc/src/images/motif-lcdnumber.png diff --git a/doc/src/images/motif-lineedit.png b/doc/src/images/motif-lineedit.png Binary files differnew file mode 100644 index 0000000000..a335c8c107 --- /dev/null +++ b/doc/src/images/motif-lineedit.png diff --git a/doc/src/images/motif-listview.png b/doc/src/images/motif-listview.png Binary files differnew file mode 100644 index 0000000000..47bd3eae6d --- /dev/null +++ b/doc/src/images/motif-listview.png diff --git a/doc/src/images/motif-progressbar.png b/doc/src/images/motif-progressbar.png Binary files differnew file mode 100644 index 0000000000..f6d6979b86 --- /dev/null +++ b/doc/src/images/motif-progressbar.png diff --git a/doc/src/images/motif-pushbutton.png b/doc/src/images/motif-pushbutton.png Binary files differnew file mode 100644 index 0000000000..9dc6a9db78 --- /dev/null +++ b/doc/src/images/motif-pushbutton.png diff --git a/doc/src/images/motif-radiobutton.png b/doc/src/images/motif-radiobutton.png Binary files differnew file mode 100644 index 0000000000..468e54cfcf --- /dev/null +++ b/doc/src/images/motif-radiobutton.png diff --git a/doc/src/images/motif-slider.png b/doc/src/images/motif-slider.png Binary files differnew file mode 100644 index 0000000000..6301e2b26d --- /dev/null +++ b/doc/src/images/motif-slider.png diff --git a/doc/src/images/motif-spinbox.png b/doc/src/images/motif-spinbox.png Binary files differnew file mode 100644 index 0000000000..9acc2821c8 --- /dev/null +++ b/doc/src/images/motif-spinbox.png diff --git a/doc/src/images/motif-tableview.png b/doc/src/images/motif-tableview.png Binary files differnew file mode 100644 index 0000000000..a1d205aaed --- /dev/null +++ b/doc/src/images/motif-tableview.png diff --git a/doc/src/images/motif-tabwidget.png b/doc/src/images/motif-tabwidget.png Binary files differnew file mode 100644 index 0000000000..19da66a76c --- /dev/null +++ b/doc/src/images/motif-tabwidget.png diff --git a/doc/src/images/motif-textedit.png b/doc/src/images/motif-textedit.png Binary files differnew file mode 100644 index 0000000000..205bc19cfa --- /dev/null +++ b/doc/src/images/motif-textedit.png diff --git a/doc/src/images/motif-timeedit.png b/doc/src/images/motif-timeedit.png Binary files differnew file mode 100644 index 0000000000..1ad459b886 --- /dev/null +++ b/doc/src/images/motif-timeedit.png diff --git a/doc/src/images/motif-toolbox.png b/doc/src/images/motif-toolbox.png Binary files differnew file mode 100644 index 0000000000..4bc3c37bb2 --- /dev/null +++ b/doc/src/images/motif-toolbox.png diff --git a/doc/src/images/motif-toolbutton.png b/doc/src/images/motif-toolbutton.png Binary files differnew file mode 100644 index 0000000000..8ef51ddd8d --- /dev/null +++ b/doc/src/images/motif-toolbutton.png diff --git a/doc/src/images/motif-treeview.png b/doc/src/images/motif-treeview.png Binary files differnew file mode 100644 index 0000000000..a7dd0f2466 --- /dev/null +++ b/doc/src/images/motif-treeview.png diff --git a/doc/src/images/move-blocks-chart.png b/doc/src/images/move-blocks-chart.png Binary files differnew file mode 100644 index 0000000000..fd0c1658a6 --- /dev/null +++ b/doc/src/images/move-blocks-chart.png diff --git a/doc/src/images/moveblocks-example.png b/doc/src/images/moveblocks-example.png Binary files differnew file mode 100644 index 0000000000..56353d1810 --- /dev/null +++ b/doc/src/images/moveblocks-example.png diff --git a/doc/src/images/movie-example.png b/doc/src/images/movie-example.png Binary files differnew file mode 100644 index 0000000000..713f56347e --- /dev/null +++ b/doc/src/images/movie-example.png diff --git a/doc/src/images/msgbox1.png b/doc/src/images/msgbox1.png Binary files differnew file mode 100644 index 0000000000..1380e20a5f --- /dev/null +++ b/doc/src/images/msgbox1.png diff --git a/doc/src/images/msgbox2.png b/doc/src/images/msgbox2.png Binary files differnew file mode 100644 index 0000000000..e7946996e4 --- /dev/null +++ b/doc/src/images/msgbox2.png diff --git a/doc/src/images/msgbox3.png b/doc/src/images/msgbox3.png Binary files differnew file mode 100644 index 0000000000..bd81f4d4da --- /dev/null +++ b/doc/src/images/msgbox3.png diff --git a/doc/src/images/msgbox4.png b/doc/src/images/msgbox4.png Binary files differnew file mode 100644 index 0000000000..dbe6701cdd --- /dev/null +++ b/doc/src/images/msgbox4.png diff --git a/doc/src/images/multicastreceiver-example.png b/doc/src/images/multicastreceiver-example.png Binary files differnew file mode 100644 index 0000000000..8de11cda63 --- /dev/null +++ b/doc/src/images/multicastreceiver-example.png diff --git a/doc/src/images/multicastsender-example.png b/doc/src/images/multicastsender-example.png Binary files differnew file mode 100644 index 0000000000..a619b047e3 --- /dev/null +++ b/doc/src/images/multicastsender-example.png diff --git a/doc/src/images/multipleinheritance-example.png b/doc/src/images/multipleinheritance-example.png Binary files differnew file mode 100644 index 0000000000..9e89292973 --- /dev/null +++ b/doc/src/images/multipleinheritance-example.png diff --git a/doc/src/images/network-chat-example.png b/doc/src/images/network-chat-example.png Binary files differnew file mode 100644 index 0000000000..949bb07d87 --- /dev/null +++ b/doc/src/images/network-chat-example.png diff --git a/doc/src/images/orderform-example-detailsdialog.png b/doc/src/images/orderform-example-detailsdialog.png Binary files differnew file mode 100644 index 0000000000..88263692db --- /dev/null +++ b/doc/src/images/orderform-example-detailsdialog.png diff --git a/doc/src/images/orderform-example.png b/doc/src/images/orderform-example.png Binary files differnew file mode 100644 index 0000000000..c8545ad23a --- /dev/null +++ b/doc/src/images/orderform-example.png diff --git a/doc/src/images/overpainting-example.png b/doc/src/images/overpainting-example.png Binary files differnew file mode 100644 index 0000000000..0368dcabc8 --- /dev/null +++ b/doc/src/images/overpainting-example.png diff --git a/doc/src/images/padnavigator-example.png b/doc/src/images/padnavigator-example.png Binary files differnew file mode 100644 index 0000000000..d766557cec --- /dev/null +++ b/doc/src/images/padnavigator-example.png diff --git a/doc/src/images/painterpaths-example.png b/doc/src/images/painterpaths-example.png Binary files differnew file mode 100644 index 0000000000..7e1220d1d5 --- /dev/null +++ b/doc/src/images/painterpaths-example.png diff --git a/doc/src/images/paintsystem-antialiasing.png b/doc/src/images/paintsystem-antialiasing.png Binary files differnew file mode 100644 index 0000000000..1275841b93 --- /dev/null +++ b/doc/src/images/paintsystem-antialiasing.png diff --git a/doc/src/images/paintsystem-core.png b/doc/src/images/paintsystem-core.png Binary files differnew file mode 100644 index 0000000000..7d6a8e591b --- /dev/null +++ b/doc/src/images/paintsystem-core.png diff --git a/doc/src/images/paintsystem-devices.png b/doc/src/images/paintsystem-devices.png Binary files differnew file mode 100644 index 0000000000..7b81b7cbb8 --- /dev/null +++ b/doc/src/images/paintsystem-devices.png diff --git a/doc/src/images/paintsystem-fancygradient.png b/doc/src/images/paintsystem-fancygradient.png Binary files differnew file mode 100644 index 0000000000..701df29e42 --- /dev/null +++ b/doc/src/images/paintsystem-fancygradient.png diff --git a/doc/src/images/paintsystem-gradients.png b/doc/src/images/paintsystem-gradients.png Binary files differnew file mode 100644 index 0000000000..50b2ed3671 --- /dev/null +++ b/doc/src/images/paintsystem-gradients.png diff --git a/doc/src/images/paintsystem-movie.png b/doc/src/images/paintsystem-movie.png Binary files differnew file mode 100644 index 0000000000..992ea9edd4 --- /dev/null +++ b/doc/src/images/paintsystem-movie.png diff --git a/doc/src/images/paintsystem-painterpath.png b/doc/src/images/paintsystem-painterpath.png Binary files differnew file mode 100644 index 0000000000..f8154f2634 --- /dev/null +++ b/doc/src/images/paintsystem-painterpath.png diff --git a/doc/src/images/paintsystem-stylepainter.png b/doc/src/images/paintsystem-stylepainter.png Binary files differnew file mode 100644 index 0000000000..a67c6c5afc --- /dev/null +++ b/doc/src/images/paintsystem-stylepainter.png diff --git a/doc/src/images/paintsystem-svg.png b/doc/src/images/paintsystem-svg.png Binary files differnew file mode 100644 index 0000000000..ecc8ef8f97 --- /dev/null +++ b/doc/src/images/paintsystem-svg.png diff --git a/doc/src/images/pangesture.png b/doc/src/images/pangesture.png Binary files differnew file mode 100644 index 0000000000..24caf91d3b --- /dev/null +++ b/doc/src/images/pangesture.png diff --git a/doc/src/images/parent-child-widgets.png b/doc/src/images/parent-child-widgets.png Binary files differnew file mode 100644 index 0000000000..094e2e96b6 --- /dev/null +++ b/doc/src/images/parent-child-widgets.png diff --git a/doc/src/images/pathstroke-demo.png b/doc/src/images/pathstroke-demo.png Binary files differnew file mode 100644 index 0000000000..2df765ff32 --- /dev/null +++ b/doc/src/images/pathstroke-demo.png diff --git a/doc/src/images/pbuffers-example.png b/doc/src/images/pbuffers-example.png Binary files differnew file mode 100644 index 0000000000..c34a6fd02b --- /dev/null +++ b/doc/src/images/pbuffers-example.png diff --git a/doc/src/images/pbuffers2-example.png b/doc/src/images/pbuffers2-example.png Binary files differnew file mode 100644 index 0000000000..4a9c7175a3 --- /dev/null +++ b/doc/src/images/pbuffers2-example.png diff --git a/doc/src/images/pinchgesture.png b/doc/src/images/pinchgesture.png Binary files differnew file mode 100644 index 0000000000..95614c4052 --- /dev/null +++ b/doc/src/images/pinchgesture.png diff --git a/doc/src/images/pixelator-example.png b/doc/src/images/pixelator-example.png Binary files differnew file mode 100644 index 0000000000..b6273c78ec --- /dev/null +++ b/doc/src/images/pixelator-example.png diff --git a/doc/src/images/plastique-calendarwidget.png b/doc/src/images/plastique-calendarwidget.png Binary files differnew file mode 100644 index 0000000000..5e65945c72 --- /dev/null +++ b/doc/src/images/plastique-calendarwidget.png diff --git a/doc/src/images/plastique-checkbox.png b/doc/src/images/plastique-checkbox.png Binary files differnew file mode 100644 index 0000000000..91a5109d65 --- /dev/null +++ b/doc/src/images/plastique-checkbox.png diff --git a/doc/src/images/plastique-colordialog.png b/doc/src/images/plastique-colordialog.png Binary files differnew file mode 100644 index 0000000000..68bf4d0b4b --- /dev/null +++ b/doc/src/images/plastique-colordialog.png diff --git a/doc/src/images/plastique-combobox.png b/doc/src/images/plastique-combobox.png Binary files differnew file mode 100644 index 0000000000..e3bf8a321f --- /dev/null +++ b/doc/src/images/plastique-combobox.png diff --git a/doc/src/images/plastique-dateedit.png b/doc/src/images/plastique-dateedit.png Binary files differnew file mode 100644 index 0000000000..2e28a40f01 --- /dev/null +++ b/doc/src/images/plastique-dateedit.png diff --git a/doc/src/images/plastique-datetimeedit.png b/doc/src/images/plastique-datetimeedit.png Binary files differnew file mode 100644 index 0000000000..810bf1660a --- /dev/null +++ b/doc/src/images/plastique-datetimeedit.png diff --git a/doc/src/images/plastique-dial.png b/doc/src/images/plastique-dial.png Binary files differnew file mode 100644 index 0000000000..b65e7c78cd --- /dev/null +++ b/doc/src/images/plastique-dial.png diff --git a/doc/src/images/plastique-doublespinbox.png b/doc/src/images/plastique-doublespinbox.png Binary files differnew file mode 100644 index 0000000000..627c4a20fe --- /dev/null +++ b/doc/src/images/plastique-doublespinbox.png diff --git a/doc/src/images/plastique-fontcombobox.png b/doc/src/images/plastique-fontcombobox.png Binary files differnew file mode 100644 index 0000000000..d3823081d8 --- /dev/null +++ b/doc/src/images/plastique-fontcombobox.png diff --git a/doc/src/images/plastique-fontdialog.png b/doc/src/images/plastique-fontdialog.png Binary files differnew file mode 100644 index 0000000000..7e799a8815 --- /dev/null +++ b/doc/src/images/plastique-fontdialog.png diff --git a/doc/src/images/plastique-frame.png b/doc/src/images/plastique-frame.png Binary files differnew file mode 100644 index 0000000000..9f81f6cba4 --- /dev/null +++ b/doc/src/images/plastique-frame.png diff --git a/doc/src/images/plastique-groupbox.png b/doc/src/images/plastique-groupbox.png Binary files differnew file mode 100644 index 0000000000..d353c40071 --- /dev/null +++ b/doc/src/images/plastique-groupbox.png diff --git a/doc/src/images/plastique-horizontalscrollbar.png b/doc/src/images/plastique-horizontalscrollbar.png Binary files differnew file mode 100644 index 0000000000..d20300c23f --- /dev/null +++ b/doc/src/images/plastique-horizontalscrollbar.png diff --git a/doc/src/images/plastique-label.png b/doc/src/images/plastique-label.png Binary files differnew file mode 100644 index 0000000000..d2a55a862c --- /dev/null +++ b/doc/src/images/plastique-label.png diff --git a/doc/src/images/plastique-lcdnumber.png b/doc/src/images/plastique-lcdnumber.png Binary files differnew file mode 100644 index 0000000000..74149ee158 --- /dev/null +++ b/doc/src/images/plastique-lcdnumber.png diff --git a/doc/src/images/plastique-lineedit.png b/doc/src/images/plastique-lineedit.png Binary files differnew file mode 100644 index 0000000000..f455383520 --- /dev/null +++ b/doc/src/images/plastique-lineedit.png diff --git a/doc/src/images/plastique-listview.png b/doc/src/images/plastique-listview.png Binary files differnew file mode 100644 index 0000000000..64bd00fe1f --- /dev/null +++ b/doc/src/images/plastique-listview.png diff --git a/doc/src/images/plastique-progressbar.png b/doc/src/images/plastique-progressbar.png Binary files differnew file mode 100644 index 0000000000..fe8dd90274 --- /dev/null +++ b/doc/src/images/plastique-progressbar.png diff --git a/doc/src/images/plastique-progressdialog.png b/doc/src/images/plastique-progressdialog.png Binary files differnew file mode 100644 index 0000000000..4373bcac16 --- /dev/null +++ b/doc/src/images/plastique-progressdialog.png diff --git a/doc/src/images/plastique-pushbutton.png b/doc/src/images/plastique-pushbutton.png Binary files differnew file mode 100644 index 0000000000..83c44fd38d --- /dev/null +++ b/doc/src/images/plastique-pushbutton.png diff --git a/doc/src/images/plastique-radiobutton.png b/doc/src/images/plastique-radiobutton.png Binary files differnew file mode 100644 index 0000000000..a2c820d7d1 --- /dev/null +++ b/doc/src/images/plastique-radiobutton.png diff --git a/doc/src/images/plastique-slider.png b/doc/src/images/plastique-slider.png Binary files differnew file mode 100644 index 0000000000..492f0fdfbd --- /dev/null +++ b/doc/src/images/plastique-slider.png diff --git a/doc/src/images/plastique-spinbox.png b/doc/src/images/plastique-spinbox.png Binary files differnew file mode 100644 index 0000000000..af15db3c23 --- /dev/null +++ b/doc/src/images/plastique-spinbox.png diff --git a/doc/src/images/plastique-statusbar.png b/doc/src/images/plastique-statusbar.png Binary files differnew file mode 100644 index 0000000000..c8f9792ab9 --- /dev/null +++ b/doc/src/images/plastique-statusbar.png diff --git a/doc/src/images/plastique-tableview.png b/doc/src/images/plastique-tableview.png Binary files differnew file mode 100644 index 0000000000..b20c1cce7f --- /dev/null +++ b/doc/src/images/plastique-tableview.png diff --git a/doc/src/images/plastique-tabwidget.png b/doc/src/images/plastique-tabwidget.png Binary files differnew file mode 100644 index 0000000000..92ae398844 --- /dev/null +++ b/doc/src/images/plastique-tabwidget.png diff --git a/doc/src/images/plastique-textedit.png b/doc/src/images/plastique-textedit.png Binary files differnew file mode 100644 index 0000000000..a802d75fcc --- /dev/null +++ b/doc/src/images/plastique-textedit.png diff --git a/doc/src/images/plastique-timeedit.png b/doc/src/images/plastique-timeedit.png Binary files differnew file mode 100644 index 0000000000..2d70b84c4c --- /dev/null +++ b/doc/src/images/plastique-timeedit.png diff --git a/doc/src/images/plastique-toolbox.png b/doc/src/images/plastique-toolbox.png Binary files differnew file mode 100644 index 0000000000..10bcd7af62 --- /dev/null +++ b/doc/src/images/plastique-toolbox.png diff --git a/doc/src/images/plastique-toolbutton.png b/doc/src/images/plastique-toolbutton.png Binary files differnew file mode 100644 index 0000000000..4e51831408 --- /dev/null +++ b/doc/src/images/plastique-toolbutton.png diff --git a/doc/src/images/plastique-treeview.png b/doc/src/images/plastique-treeview.png Binary files differnew file mode 100644 index 0000000000..db0bc01a25 --- /dev/null +++ b/doc/src/images/plastique-treeview.png diff --git a/doc/src/images/plugandpaint-plugindialog.png b/doc/src/images/plugandpaint-plugindialog.png Binary files differnew file mode 100644 index 0000000000..4b601bd58b --- /dev/null +++ b/doc/src/images/plugandpaint-plugindialog.png diff --git a/doc/src/images/plugandpaint.png b/doc/src/images/plugandpaint.png Binary files differnew file mode 100644 index 0000000000..bd5d001f91 --- /dev/null +++ b/doc/src/images/plugandpaint.png diff --git a/doc/src/images/progressBar-stylesheet.png b/doc/src/images/progressBar-stylesheet.png Binary files differnew file mode 100644 index 0000000000..b4bf755b6c --- /dev/null +++ b/doc/src/images/progressBar-stylesheet.png diff --git a/doc/src/images/progressBar2-stylesheet.png b/doc/src/images/progressBar2-stylesheet.png Binary files differnew file mode 100644 index 0000000000..8b5ecc0a66 --- /dev/null +++ b/doc/src/images/progressBar2-stylesheet.png diff --git a/doc/src/images/propagation-custom.png b/doc/src/images/propagation-custom.png Binary files differnew file mode 100644 index 0000000000..866b44d677 --- /dev/null +++ b/doc/src/images/propagation-custom.png diff --git a/doc/src/images/propagation-standard.png b/doc/src/images/propagation-standard.png Binary files differnew file mode 100644 index 0000000000..b010fccc95 --- /dev/null +++ b/doc/src/images/propagation-standard.png diff --git a/doc/src/images/qcalendarwidget-grid.png b/doc/src/images/qcalendarwidget-grid.png Binary files differnew file mode 100644 index 0000000000..3df4dd99e2 --- /dev/null +++ b/doc/src/images/qcalendarwidget-grid.png diff --git a/doc/src/images/qcalendarwidget-maximum.png b/doc/src/images/qcalendarwidget-maximum.png Binary files differnew file mode 100644 index 0000000000..1e78d20e85 --- /dev/null +++ b/doc/src/images/qcalendarwidget-maximum.png diff --git a/doc/src/images/qcalendarwidget-minimum.png b/doc/src/images/qcalendarwidget-minimum.png Binary files differnew file mode 100644 index 0000000000..f860429309 --- /dev/null +++ b/doc/src/images/qcalendarwidget-minimum.png diff --git a/doc/src/images/qcolumnview.png b/doc/src/images/qcolumnview.png Binary files differnew file mode 100644 index 0000000000..1d312bf953 --- /dev/null +++ b/doc/src/images/qcolumnview.png diff --git a/doc/src/images/qcompleter.png b/doc/src/images/qcompleter.png Binary files differnew file mode 100755 index 0000000000..d25caacc72 --- /dev/null +++ b/doc/src/images/qcompleter.png diff --git a/doc/src/images/qconicalgradient.png b/doc/src/images/qconicalgradient.png Binary files differnew file mode 100644 index 0000000000..82603066fb --- /dev/null +++ b/doc/src/images/qconicalgradient.png diff --git a/doc/src/images/qdatawidgetmapper-simple.png b/doc/src/images/qdatawidgetmapper-simple.png Binary files differnew file mode 100644 index 0000000000..784a433c0b --- /dev/null +++ b/doc/src/images/qdatawidgetmapper-simple.png diff --git a/doc/src/images/qdesktopwidget.png b/doc/src/images/qdesktopwidget.png Binary files differnew file mode 100644 index 0000000000..02f8e8b5ad --- /dev/null +++ b/doc/src/images/qdesktopwidget.png diff --git a/doc/src/images/qformlayout-with-6-children.png b/doc/src/images/qformlayout-with-6-children.png Binary files differnew file mode 100644 index 0000000000..f743599702 --- /dev/null +++ b/doc/src/images/qformlayout-with-6-children.png diff --git a/doc/src/images/qgraphicsproxywidget-embed.png b/doc/src/images/qgraphicsproxywidget-embed.png Binary files differnew file mode 100644 index 0000000000..10d8f6fddd --- /dev/null +++ b/doc/src/images/qgraphicsproxywidget-embed.png diff --git a/doc/src/images/qgridlayout-with-5-children.png b/doc/src/images/qgridlayout-with-5-children.png Binary files differnew file mode 100644 index 0000000000..8d0c2962e4 --- /dev/null +++ b/doc/src/images/qgridlayout-with-5-children.png diff --git a/doc/src/images/qhboxlayout-with-5-children.png b/doc/src/images/qhboxlayout-with-5-children.png Binary files differnew file mode 100644 index 0000000000..9b48dc5c47 --- /dev/null +++ b/doc/src/images/qhboxlayout-with-5-children.png diff --git a/doc/src/images/qimage-scaling.png b/doc/src/images/qimage-scaling.png Binary files differnew file mode 100644 index 0000000000..fcd71448f0 --- /dev/null +++ b/doc/src/images/qimage-scaling.png diff --git a/doc/src/images/qlinef-normalvector.png b/doc/src/images/qlinef-normalvector.png Binary files differnew file mode 100644 index 0000000000..b7d944f32f --- /dev/null +++ b/doc/src/images/qlinef-normalvector.png diff --git a/doc/src/images/qmatrix-representation.png b/doc/src/images/qmatrix-representation.png Binary files differnew file mode 100644 index 0000000000..2e3efd33fc --- /dev/null +++ b/doc/src/images/qmatrix-representation.png diff --git a/doc/src/images/qmdisubwindowlayout.png b/doc/src/images/qmdisubwindowlayout.png Binary files differnew file mode 100644 index 0000000000..ffe5cc3949 --- /dev/null +++ b/doc/src/images/qmdisubwindowlayout.png diff --git a/doc/src/images/qpainter-compositionmode1.png b/doc/src/images/qpainter-compositionmode1.png Binary files differnew file mode 100644 index 0000000000..6753093521 --- /dev/null +++ b/doc/src/images/qpainter-compositionmode1.png diff --git a/doc/src/images/qpainter-compositionmode2.png b/doc/src/images/qpainter-compositionmode2.png Binary files differnew file mode 100644 index 0000000000..fc05afbd8c --- /dev/null +++ b/doc/src/images/qpainter-compositionmode2.png diff --git a/doc/src/images/qpen-miterlimit.png b/doc/src/images/qpen-miterlimit.png Binary files differnew file mode 100644 index 0000000000..17a90725fb --- /dev/null +++ b/doc/src/images/qpen-miterlimit.png diff --git a/doc/src/images/qrect-coordinates.png b/doc/src/images/qrect-coordinates.png Binary files differnew file mode 100644 index 0000000000..2a2dae2d6c --- /dev/null +++ b/doc/src/images/qrect-coordinates.png diff --git a/doc/src/images/qrect-intersect.png b/doc/src/images/qrect-intersect.png Binary files differnew file mode 100644 index 0000000000..db68cd53ad --- /dev/null +++ b/doc/src/images/qrect-intersect.png diff --git a/doc/src/images/qrect-unite.png b/doc/src/images/qrect-unite.png Binary files differnew file mode 100644 index 0000000000..3f6239f405 --- /dev/null +++ b/doc/src/images/qrect-unite.png diff --git a/doc/src/images/qrectf-coordinates.png b/doc/src/images/qrectf-coordinates.png Binary files differnew file mode 100644 index 0000000000..ccc6d82063 --- /dev/null +++ b/doc/src/images/qrectf-coordinates.png diff --git a/doc/src/images/qscrollbar-picture.png b/doc/src/images/qscrollbar-picture.png Binary files differnew file mode 100644 index 0000000000..898e014c40 --- /dev/null +++ b/doc/src/images/qscrollbar-picture.png diff --git a/doc/src/images/qsortfilterproxymodel-sorting.png b/doc/src/images/qsortfilterproxymodel-sorting.png Binary files differnew file mode 100644 index 0000000000..de99d41272 --- /dev/null +++ b/doc/src/images/qsortfilterproxymodel-sorting.png diff --git a/doc/src/images/qstatustipevent-action.png b/doc/src/images/qstatustipevent-action.png Binary files differnew file mode 100644 index 0000000000..c5dcfd25f5 --- /dev/null +++ b/doc/src/images/qstatustipevent-action.png diff --git a/doc/src/images/qstatustipevent-widget.png b/doc/src/images/qstatustipevent-widget.png Binary files differnew file mode 100644 index 0000000000..3cc0a1f01b --- /dev/null +++ b/doc/src/images/qstatustipevent-widget.png diff --git a/doc/src/images/qstyle-comboboxes.png b/doc/src/images/qstyle-comboboxes.png Binary files differnew file mode 100644 index 0000000000..aecec914a0 --- /dev/null +++ b/doc/src/images/qstyle-comboboxes.png diff --git a/doc/src/images/qstyleoptiontoolbar-position.png b/doc/src/images/qstyleoptiontoolbar-position.png Binary files differnew file mode 100644 index 0000000000..5eaae7e4cd --- /dev/null +++ b/doc/src/images/qstyleoptiontoolbar-position.png diff --git a/doc/src/images/qt-embedded-client.png b/doc/src/images/qt-embedded-client.png Binary files differnew file mode 100644 index 0000000000..da64203977 --- /dev/null +++ b/doc/src/images/qt-embedded-client.png diff --git a/doc/src/images/qtexttableformat-cell.png b/doc/src/images/qtexttableformat-cell.png Binary files differnew file mode 100644 index 0000000000..bbf85ffe46 --- /dev/null +++ b/doc/src/images/qtexttableformat-cell.png diff --git a/doc/src/images/qtransform-representation.png b/doc/src/images/qtransform-representation.png Binary files differnew file mode 100644 index 0000000000..883d5dc487 --- /dev/null +++ b/doc/src/images/qtransform-representation.png diff --git a/doc/src/images/qtwizard-macpage.png b/doc/src/images/qtwizard-macpage.png Binary files differnew file mode 100644 index 0000000000..1ba3122f91 --- /dev/null +++ b/doc/src/images/qtwizard-macpage.png diff --git a/doc/src/images/qtwizard-nonmacpage.png b/doc/src/images/qtwizard-nonmacpage.png Binary files differnew file mode 100644 index 0000000000..cbe464d57f --- /dev/null +++ b/doc/src/images/qtwizard-nonmacpage.png diff --git a/doc/src/images/querymodel-example.png b/doc/src/images/querymodel-example.png Binary files differnew file mode 100644 index 0000000000..908d500e1f --- /dev/null +++ b/doc/src/images/querymodel-example.png diff --git a/doc/src/images/queuedcustomtype-example.png b/doc/src/images/queuedcustomtype-example.png Binary files differnew file mode 100644 index 0000000000..4399b631d7 --- /dev/null +++ b/doc/src/images/queuedcustomtype-example.png diff --git a/doc/src/images/qundoview.png b/doc/src/images/qundoview.png Binary files differnew file mode 100644 index 0000000000..3bdb1cf2ed --- /dev/null +++ b/doc/src/images/qundoview.png diff --git a/doc/src/images/qvboxlayout-with-5-children.png b/doc/src/images/qvboxlayout-with-5-children.png Binary files differnew file mode 100644 index 0000000000..57c37d7247 --- /dev/null +++ b/doc/src/images/qvboxlayout-with-5-children.png diff --git a/doc/src/images/qwsserver_keyboardfilter.png b/doc/src/images/qwsserver_keyboardfilter.png Binary files differnew file mode 100644 index 0000000000..9efc080b9d --- /dev/null +++ b/doc/src/images/qwsserver_keyboardfilter.png diff --git a/doc/src/images/raycasting-demo.png b/doc/src/images/raycasting-demo.png Binary files differnew file mode 100644 index 0000000000..53c5253f53 --- /dev/null +++ b/doc/src/images/raycasting-demo.png diff --git a/doc/src/images/readonlytable_role.png b/doc/src/images/readonlytable_role.png Binary files differnew file mode 100755 index 0000000000..7d2d416a53 --- /dev/null +++ b/doc/src/images/readonlytable_role.png diff --git a/doc/src/images/recentfiles-example.png b/doc/src/images/recentfiles-example.png Binary files differnew file mode 100644 index 0000000000..8a1f2e5509 --- /dev/null +++ b/doc/src/images/recentfiles-example.png diff --git a/doc/src/images/regexp-example.png b/doc/src/images/regexp-example.png Binary files differnew file mode 100644 index 0000000000..0f31a2f93f --- /dev/null +++ b/doc/src/images/regexp-example.png diff --git a/doc/src/images/relationaltable.png b/doc/src/images/relationaltable.png Binary files differnew file mode 100644 index 0000000000..bdfd40f703 --- /dev/null +++ b/doc/src/images/relationaltable.png diff --git a/doc/src/images/relationaltablemodel-example.png b/doc/src/images/relationaltablemodel-example.png Binary files differnew file mode 100644 index 0000000000..44fc858562 --- /dev/null +++ b/doc/src/images/relationaltablemodel-example.png diff --git a/doc/src/images/resources.png b/doc/src/images/resources.png Binary files differnew file mode 100644 index 0000000000..eb7af96d77 --- /dev/null +++ b/doc/src/images/resources.png diff --git a/doc/src/images/roaming-states.png b/doc/src/images/roaming-states.png Binary files differnew file mode 100644 index 0000000000..bc61cac219 --- /dev/null +++ b/doc/src/images/roaming-states.png diff --git a/doc/src/images/rogue-example.png b/doc/src/images/rogue-example.png Binary files differnew file mode 100644 index 0000000000..7aeb0e54f9 --- /dev/null +++ b/doc/src/images/rogue-example.png diff --git a/doc/src/images/rogue-statechart.png b/doc/src/images/rogue-statechart.png Binary files differnew file mode 100644 index 0000000000..c5f4048921 --- /dev/null +++ b/doc/src/images/rogue-statechart.png diff --git a/doc/src/images/rsslistingexample.png b/doc/src/images/rsslistingexample.png Binary files differnew file mode 100644 index 0000000000..6bac295b7d --- /dev/null +++ b/doc/src/images/rsslistingexample.png diff --git a/doc/src/images/samplebuffers-example.png b/doc/src/images/samplebuffers-example.png Binary files differnew file mode 100644 index 0000000000..b751c143b3 --- /dev/null +++ b/doc/src/images/samplebuffers-example.png diff --git a/doc/src/images/saxbookmarks-example.png b/doc/src/images/saxbookmarks-example.png Binary files differnew file mode 100644 index 0000000000..54d793be56 --- /dev/null +++ b/doc/src/images/saxbookmarks-example.png diff --git a/doc/src/images/screenshot-example.png b/doc/src/images/screenshot-example.png Binary files differnew file mode 100644 index 0000000000..86894867c3 --- /dev/null +++ b/doc/src/images/screenshot-example.png diff --git a/doc/src/images/scribble-example.png b/doc/src/images/scribble-example.png Binary files differnew file mode 100644 index 0000000000..a2cb1de3e8 --- /dev/null +++ b/doc/src/images/scribble-example.png diff --git a/doc/src/images/sdi-example.png b/doc/src/images/sdi-example.png Binary files differnew file mode 100644 index 0000000000..8cd7aa0128 --- /dev/null +++ b/doc/src/images/sdi-example.png diff --git a/doc/src/images/securesocketclient.png b/doc/src/images/securesocketclient.png Binary files differnew file mode 100644 index 0000000000..8736cbc264 --- /dev/null +++ b/doc/src/images/securesocketclient.png diff --git a/doc/src/images/securesocketclient2.png b/doc/src/images/securesocketclient2.png Binary files differnew file mode 100644 index 0000000000..23db851e61 --- /dev/null +++ b/doc/src/images/securesocketclient2.png diff --git a/doc/src/images/selection2.png b/doc/src/images/selection2.png Binary files differnew file mode 100755 index 0000000000..66c757f88e --- /dev/null +++ b/doc/src/images/selection2.png diff --git a/doc/src/images/settingseditor-example.png b/doc/src/images/settingseditor-example.png Binary files differnew file mode 100644 index 0000000000..7a5be05fd0 --- /dev/null +++ b/doc/src/images/settingseditor-example.png diff --git a/doc/src/images/shapedclock-dragging.png b/doc/src/images/shapedclock-dragging.png Binary files differnew file mode 100644 index 0000000000..1b25afbcf0 --- /dev/null +++ b/doc/src/images/shapedclock-dragging.png diff --git a/doc/src/images/shapedclock-example.png b/doc/src/images/shapedclock-example.png Binary files differnew file mode 100644 index 0000000000..31ceeca7f9 --- /dev/null +++ b/doc/src/images/shapedclock-example.png diff --git a/doc/src/images/sharedmemory-example_1.png b/doc/src/images/sharedmemory-example_1.png Binary files differnew file mode 100644 index 0000000000..53244d3f52 --- /dev/null +++ b/doc/src/images/sharedmemory-example_1.png diff --git a/doc/src/images/sharedmemory-example_2.png b/doc/src/images/sharedmemory-example_2.png Binary files differnew file mode 100644 index 0000000000..fc71aed56e --- /dev/null +++ b/doc/src/images/sharedmemory-example_2.png diff --git a/doc/src/images/signals-n-slots-aw-nat.png b/doc/src/images/signals-n-slots-aw-nat.png Binary files differnew file mode 100644 index 0000000000..8ab545bbb3 --- /dev/null +++ b/doc/src/images/signals-n-slots-aw-nat.png diff --git a/doc/src/images/simpledommodel-example.png b/doc/src/images/simpledommodel-example.png Binary files differnew file mode 100644 index 0000000000..b8e3f92e1c --- /dev/null +++ b/doc/src/images/simpledommodel-example.png diff --git a/doc/src/images/simpletreemodel-example.png b/doc/src/images/simpletreemodel-example.png Binary files differnew file mode 100644 index 0000000000..9655d107de --- /dev/null +++ b/doc/src/images/simpletreemodel-example.png diff --git a/doc/src/images/simplewidgetmapper-example.png b/doc/src/images/simplewidgetmapper-example.png Binary files differnew file mode 100644 index 0000000000..f85ad0e268 --- /dev/null +++ b/doc/src/images/simplewidgetmapper-example.png diff --git a/doc/src/images/sliders-example.png b/doc/src/images/sliders-example.png Binary files differnew file mode 100644 index 0000000000..a67ce1dbda --- /dev/null +++ b/doc/src/images/sliders-example.png diff --git a/doc/src/images/spinboxdelegate-example.png b/doc/src/images/spinboxdelegate-example.png Binary files differnew file mode 100644 index 0000000000..5e57a9c12b --- /dev/null +++ b/doc/src/images/spinboxdelegate-example.png diff --git a/doc/src/images/spinboxes-example.png b/doc/src/images/spinboxes-example.png Binary files differnew file mode 100644 index 0000000000..14c42d2404 --- /dev/null +++ b/doc/src/images/spinboxes-example.png diff --git a/doc/src/images/spreadsheet-demo.png b/doc/src/images/spreadsheet-demo.png Binary files differnew file mode 100644 index 0000000000..ae7dde24b0 --- /dev/null +++ b/doc/src/images/spreadsheet-demo.png diff --git a/doc/src/images/sql-widget-mapper.png b/doc/src/images/sql-widget-mapper.png Binary files differnew file mode 100644 index 0000000000..dfa64aba9e --- /dev/null +++ b/doc/src/images/sql-widget-mapper.png diff --git a/doc/src/images/sqlbrowser-demo.png b/doc/src/images/sqlbrowser-demo.png Binary files differnew file mode 100644 index 0000000000..101ec5a0a3 --- /dev/null +++ b/doc/src/images/sqlbrowser-demo.png diff --git a/doc/src/images/standarddialogs-example.png b/doc/src/images/standarddialogs-example.png Binary files differnew file mode 100644 index 0000000000..b6b8a076db --- /dev/null +++ b/doc/src/images/standarddialogs-example.png diff --git a/doc/src/images/standardwidget.png b/doc/src/images/standardwidget.png Binary files differnew file mode 100755 index 0000000000..3ccccf14a3 --- /dev/null +++ b/doc/src/images/standardwidget.png diff --git a/doc/src/images/stardelegate.png b/doc/src/images/stardelegate.png Binary files differnew file mode 100644 index 0000000000..24fa9fb0d7 --- /dev/null +++ b/doc/src/images/stardelegate.png diff --git a/doc/src/images/states-example.png b/doc/src/images/states-example.png Binary files differnew file mode 100644 index 0000000000..f87b99bec5 --- /dev/null +++ b/doc/src/images/states-example.png diff --git a/doc/src/images/stickman-example.png b/doc/src/images/stickman-example.png Binary files differnew file mode 100644 index 0000000000..a40f37b7a6 --- /dev/null +++ b/doc/src/images/stickman-example.png diff --git a/doc/src/images/stickman-example1.png b/doc/src/images/stickman-example1.png Binary files differnew file mode 100644 index 0000000000..1596a6804c --- /dev/null +++ b/doc/src/images/stickman-example1.png diff --git a/doc/src/images/stickman-example2.png b/doc/src/images/stickman-example2.png Binary files differnew file mode 100644 index 0000000000..980276adbe --- /dev/null +++ b/doc/src/images/stickman-example2.png diff --git a/doc/src/images/stickman-example3.png b/doc/src/images/stickman-example3.png Binary files differnew file mode 100644 index 0000000000..3635ff73f4 --- /dev/null +++ b/doc/src/images/stickman-example3.png diff --git a/doc/src/images/styledemo-demo.png b/doc/src/images/styledemo-demo.png Binary files differnew file mode 100644 index 0000000000..8e4ec9021f --- /dev/null +++ b/doc/src/images/styledemo-demo.png diff --git a/doc/src/images/stylepluginexample.png b/doc/src/images/stylepluginexample.png Binary files differnew file mode 100644 index 0000000000..05d8c6b5cf --- /dev/null +++ b/doc/src/images/stylepluginexample.png diff --git a/doc/src/images/styles-3d.png b/doc/src/images/styles-3d.png Binary files differnew file mode 100644 index 0000000000..8344b4c05b --- /dev/null +++ b/doc/src/images/styles-3d.png diff --git a/doc/src/images/styles-aliasing.png b/doc/src/images/styles-aliasing.png Binary files differnew file mode 100644 index 0000000000..c3514460fb --- /dev/null +++ b/doc/src/images/styles-aliasing.png diff --git a/doc/src/images/styles-disabledwood.png b/doc/src/images/styles-disabledwood.png Binary files differnew file mode 100644 index 0000000000..261bbae0ef --- /dev/null +++ b/doc/src/images/styles-disabledwood.png diff --git a/doc/src/images/styles-enabledwood.png b/doc/src/images/styles-enabledwood.png Binary files differnew file mode 100644 index 0000000000..168c1d2d2c --- /dev/null +++ b/doc/src/images/styles-enabledwood.png diff --git a/doc/src/images/styles-woodbuttons.png b/doc/src/images/styles-woodbuttons.png Binary files differnew file mode 100644 index 0000000000..176d7dff38 --- /dev/null +++ b/doc/src/images/styles-woodbuttons.png diff --git a/doc/src/images/stylesheet-border-image-normal.png b/doc/src/images/stylesheet-border-image-normal.png Binary files differnew file mode 100644 index 0000000000..8afe3c9a67 --- /dev/null +++ b/doc/src/images/stylesheet-border-image-normal.png diff --git a/doc/src/images/stylesheet-boxmodel.png b/doc/src/images/stylesheet-boxmodel.png Binary files differnew file mode 100644 index 0000000000..a0249d77b7 --- /dev/null +++ b/doc/src/images/stylesheet-boxmodel.png diff --git a/doc/src/images/stylesheet-pagefold.png b/doc/src/images/stylesheet-pagefold.png Binary files differnew file mode 100644 index 0000000000..5ccb4edbc9 --- /dev/null +++ b/doc/src/images/stylesheet-pagefold.png diff --git a/doc/src/images/stylesheet-redbutton1.png b/doc/src/images/stylesheet-redbutton1.png Binary files differnew file mode 100644 index 0000000000..cb03375e12 --- /dev/null +++ b/doc/src/images/stylesheet-redbutton1.png diff --git a/doc/src/images/stylesheet-redbutton2.png b/doc/src/images/stylesheet-redbutton2.png Binary files differnew file mode 100644 index 0000000000..5325708942 --- /dev/null +++ b/doc/src/images/stylesheet-redbutton2.png diff --git a/doc/src/images/stylesheet-redbutton3.png b/doc/src/images/stylesheet-redbutton3.png Binary files differnew file mode 100644 index 0000000000..dd976f0760 --- /dev/null +++ b/doc/src/images/stylesheet-redbutton3.png diff --git a/doc/src/images/stylesheet-scrollbar1.png b/doc/src/images/stylesheet-scrollbar1.png Binary files differnew file mode 100644 index 0000000000..666ff1119a --- /dev/null +++ b/doc/src/images/stylesheet-scrollbar1.png diff --git a/doc/src/images/stylesheet-scrollbar2.png b/doc/src/images/stylesheet-scrollbar2.png Binary files differnew file mode 100644 index 0000000000..439cf8035d --- /dev/null +++ b/doc/src/images/stylesheet-scrollbar2.png diff --git a/doc/src/images/stylesheet-treeview.png b/doc/src/images/stylesheet-treeview.png Binary files differnew file mode 100644 index 0000000000..883d190f36 --- /dev/null +++ b/doc/src/images/stylesheet-treeview.png diff --git a/doc/src/images/sub-attaq-demo.png b/doc/src/images/sub-attaq-demo.png Binary files differnew file mode 100644 index 0000000000..5a35ec6ee2 --- /dev/null +++ b/doc/src/images/sub-attaq-demo.png diff --git a/doc/src/images/swipegesture.png b/doc/src/images/swipegesture.png Binary files differnew file mode 100644 index 0000000000..0b7d35af3a --- /dev/null +++ b/doc/src/images/swipegesture.png diff --git a/doc/src/images/syntaxhighlighter-example.png b/doc/src/images/syntaxhighlighter-example.png Binary files differnew file mode 100644 index 0000000000..d0e7f1249e --- /dev/null +++ b/doc/src/images/syntaxhighlighter-example.png diff --git a/doc/src/images/system-tray.png b/doc/src/images/system-tray.png Binary files differnew file mode 100644 index 0000000000..298b193cf7 --- /dev/null +++ b/doc/src/images/system-tray.png diff --git a/doc/src/images/tabWidget-stylesheet1.png b/doc/src/images/tabWidget-stylesheet1.png Binary files differnew file mode 100644 index 0000000000..fc8fc19e74 --- /dev/null +++ b/doc/src/images/tabWidget-stylesheet1.png diff --git a/doc/src/images/tabWidget-stylesheet2.png b/doc/src/images/tabWidget-stylesheet2.png Binary files differnew file mode 100644 index 0000000000..2cbf2bf36d --- /dev/null +++ b/doc/src/images/tabWidget-stylesheet2.png diff --git a/doc/src/images/tabWidget-stylesheet3.png b/doc/src/images/tabWidget-stylesheet3.png Binary files differnew file mode 100644 index 0000000000..f57a9c9f9c --- /dev/null +++ b/doc/src/images/tabWidget-stylesheet3.png diff --git a/doc/src/images/tabdialog-example.png b/doc/src/images/tabdialog-example.png Binary files differnew file mode 100644 index 0000000000..219a85f86a --- /dev/null +++ b/doc/src/images/tabdialog-example.png diff --git a/doc/src/images/tableWidget-stylesheet.png b/doc/src/images/tableWidget-stylesheet.png Binary files differnew file mode 100644 index 0000000000..e99e7a97c8 --- /dev/null +++ b/doc/src/images/tableWidget-stylesheet.png diff --git a/doc/src/images/tablemodel-example.png b/doc/src/images/tablemodel-example.png Binary files differnew file mode 100644 index 0000000000..3ae2a8c05c --- /dev/null +++ b/doc/src/images/tablemodel-example.png diff --git a/doc/src/images/tabletexample.png b/doc/src/images/tabletexample.png Binary files differnew file mode 100644 index 0000000000..a9b098d8d1 --- /dev/null +++ b/doc/src/images/tabletexample.png diff --git a/doc/src/images/tcpstream.png b/doc/src/images/tcpstream.png Binary files differnew file mode 100644 index 0000000000..7975376c8c --- /dev/null +++ b/doc/src/images/tcpstream.png diff --git a/doc/src/images/tetrix-example.png b/doc/src/images/tetrix-example.png Binary files differnew file mode 100644 index 0000000000..c9764dcccd --- /dev/null +++ b/doc/src/images/tetrix-example.png diff --git a/doc/src/images/textedit-demo.png b/doc/src/images/textedit-demo.png Binary files differnew file mode 100644 index 0000000000..3cf2883a12 --- /dev/null +++ b/doc/src/images/textedit-demo.png diff --git a/doc/src/images/textfinder-example-userinterface.png b/doc/src/images/textfinder-example-userinterface.png Binary files differnew file mode 100644 index 0000000000..2bebe2e9dd --- /dev/null +++ b/doc/src/images/textfinder-example-userinterface.png diff --git a/doc/src/images/textures-example.png b/doc/src/images/textures-example.png Binary files differnew file mode 100644 index 0000000000..b583ede063 --- /dev/null +++ b/doc/src/images/textures-example.png diff --git a/doc/src/images/thread_clock.png b/doc/src/images/thread_clock.png Binary files differnew file mode 100644 index 0000000000..b8a8aa0a39 --- /dev/null +++ b/doc/src/images/thread_clock.png diff --git a/doc/src/images/threadedfortuneserver-example.png b/doc/src/images/threadedfortuneserver-example.png Binary files differnew file mode 100644 index 0000000000..57c66a5605 --- /dev/null +++ b/doc/src/images/threadedfortuneserver-example.png diff --git a/doc/src/images/threadvisual-example.png b/doc/src/images/threadvisual-example.png Binary files differnew file mode 100644 index 0000000000..2a49874719 --- /dev/null +++ b/doc/src/images/threadvisual-example.png diff --git a/doc/src/images/tooltips-example.png b/doc/src/images/tooltips-example.png Binary files differnew file mode 100644 index 0000000000..f2236b43de --- /dev/null +++ b/doc/src/images/tooltips-example.png diff --git a/doc/src/images/torrent-example.png b/doc/src/images/torrent-example.png Binary files differnew file mode 100644 index 0000000000..1032716e04 --- /dev/null +++ b/doc/src/images/torrent-example.png diff --git a/doc/src/images/touch-fingerpaint-example.png b/doc/src/images/touch-fingerpaint-example.png Binary files differnew file mode 100644 index 0000000000..c741b65526 --- /dev/null +++ b/doc/src/images/touch-fingerpaint-example.png diff --git a/doc/src/images/touch-pinchzoom-example.png b/doc/src/images/touch-pinchzoom-example.png Binary files differnew file mode 100644 index 0000000000..1079fb252b --- /dev/null +++ b/doc/src/images/touch-pinchzoom-example.png diff --git a/doc/src/images/trafficlight-example.png b/doc/src/images/trafficlight-example.png Binary files differnew file mode 100644 index 0000000000..3431542ad1 --- /dev/null +++ b/doc/src/images/trafficlight-example.png diff --git a/doc/src/images/transformations-example.png b/doc/src/images/transformations-example.png Binary files differnew file mode 100644 index 0000000000..0fa185b0b8 --- /dev/null +++ b/doc/src/images/transformations-example.png diff --git a/doc/src/images/tree_2_with_algorithm.png b/doc/src/images/tree_2_with_algorithm.png Binary files differnew file mode 100755 index 0000000000..ecf91012bf --- /dev/null +++ b/doc/src/images/tree_2_with_algorithm.png diff --git a/doc/src/images/treemodelcompleter-example.png b/doc/src/images/treemodelcompleter-example.png Binary files differnew file mode 100644 index 0000000000..000405fe39 --- /dev/null +++ b/doc/src/images/treemodelcompleter-example.png diff --git a/doc/src/images/treeview.png b/doc/src/images/treeview.png Binary files differnew file mode 100755 index 0000000000..af31fe9bf1 --- /dev/null +++ b/doc/src/images/treeview.png diff --git a/doc/src/images/trivialwizard-example-conclusion.png b/doc/src/images/trivialwizard-example-conclusion.png Binary files differnew file mode 100644 index 0000000000..c625ae4c75 --- /dev/null +++ b/doc/src/images/trivialwizard-example-conclusion.png diff --git a/doc/src/images/trivialwizard-example-flow.png b/doc/src/images/trivialwizard-example-flow.png Binary files differnew file mode 100644 index 0000000000..79b6fce079 --- /dev/null +++ b/doc/src/images/trivialwizard-example-flow.png diff --git a/doc/src/images/trivialwizard-example-introduction.png b/doc/src/images/trivialwizard-example-introduction.png Binary files differnew file mode 100644 index 0000000000..0bbceeda7f --- /dev/null +++ b/doc/src/images/trivialwizard-example-introduction.png diff --git a/doc/src/images/trivialwizard-example-registration.png b/doc/src/images/trivialwizard-example-registration.png Binary files differnew file mode 100644 index 0000000000..30b985e215 --- /dev/null +++ b/doc/src/images/trivialwizard-example-registration.png diff --git a/doc/src/images/udppackets.png b/doc/src/images/udppackets.png Binary files differnew file mode 100644 index 0000000000..bd66c3f65e --- /dev/null +++ b/doc/src/images/udppackets.png diff --git a/doc/src/images/undodemo.png b/doc/src/images/undodemo.png Binary files differnew file mode 100644 index 0000000000..85c3622738 --- /dev/null +++ b/doc/src/images/undodemo.png diff --git a/doc/src/images/undoframeworkexample.png b/doc/src/images/undoframeworkexample.png Binary files differnew file mode 100644 index 0000000000..7e0a1df260 --- /dev/null +++ b/doc/src/images/undoframeworkexample.png diff --git a/doc/src/images/widgetdelegate.png b/doc/src/images/widgetdelegate.png Binary files differnew file mode 100644 index 0000000000..3df4c4b6a5 --- /dev/null +++ b/doc/src/images/widgetdelegate.png diff --git a/doc/src/images/widgetmapper-combo-mapping.png b/doc/src/images/widgetmapper-combo-mapping.png Binary files differnew file mode 100644 index 0000000000..f87cfaf346 --- /dev/null +++ b/doc/src/images/widgetmapper-combo-mapping.png diff --git a/doc/src/images/widgetmapper-simple-mapping.png b/doc/src/images/widgetmapper-simple-mapping.png Binary files differnew file mode 100644 index 0000000000..3ef3f29f19 --- /dev/null +++ b/doc/src/images/widgetmapper-simple-mapping.png diff --git a/doc/src/images/widgetmapper-sql-mapping-table.png b/doc/src/images/widgetmapper-sql-mapping-table.png Binary files differnew file mode 100644 index 0000000000..98734b34b6 --- /dev/null +++ b/doc/src/images/widgetmapper-sql-mapping-table.png diff --git a/doc/src/images/widgetmapper-sql-mapping.png b/doc/src/images/widgetmapper-sql-mapping.png Binary files differnew file mode 100644 index 0000000000..88718c6a8b --- /dev/null +++ b/doc/src/images/widgetmapper-sql-mapping.png diff --git a/doc/src/images/widgetmapper.png b/doc/src/images/widgetmapper.png Binary files differnew file mode 100755 index 0000000000..9627088077 --- /dev/null +++ b/doc/src/images/widgetmapper.png diff --git a/doc/src/images/wiggly-example.png b/doc/src/images/wiggly-example.png Binary files differnew file mode 100644 index 0000000000..b20fbc445d --- /dev/null +++ b/doc/src/images/wiggly-example.png diff --git a/doc/src/images/windowflags-example.png b/doc/src/images/windowflags-example.png Binary files differnew file mode 100644 index 0000000000..9028b9b0d1 --- /dev/null +++ b/doc/src/images/windowflags-example.png diff --git a/doc/src/images/windowflags_controllerwindow.png b/doc/src/images/windowflags_controllerwindow.png Binary files differnew file mode 100644 index 0000000000..d8ce239b03 --- /dev/null +++ b/doc/src/images/windowflags_controllerwindow.png diff --git a/doc/src/images/windowflags_previewwindow.png b/doc/src/images/windowflags_previewwindow.png Binary files differnew file mode 100644 index 0000000000..cafcd37e02 --- /dev/null +++ b/doc/src/images/windowflags_previewwindow.png diff --git a/doc/src/images/windows-calendarwidget.png b/doc/src/images/windows-calendarwidget.png Binary files differnew file mode 100644 index 0000000000..ad016238ad --- /dev/null +++ b/doc/src/images/windows-calendarwidget.png diff --git a/doc/src/images/windows-checkbox.png b/doc/src/images/windows-checkbox.png Binary files differnew file mode 100644 index 0000000000..eb1be4b736 --- /dev/null +++ b/doc/src/images/windows-checkbox.png diff --git a/doc/src/images/windows-combobox.png b/doc/src/images/windows-combobox.png Binary files differnew file mode 100644 index 0000000000..d6bc483494 --- /dev/null +++ b/doc/src/images/windows-combobox.png diff --git a/doc/src/images/windows-dateedit.png b/doc/src/images/windows-dateedit.png Binary files differnew file mode 100644 index 0000000000..95587ec62e --- /dev/null +++ b/doc/src/images/windows-dateedit.png diff --git a/doc/src/images/windows-datetimeedit.png b/doc/src/images/windows-datetimeedit.png Binary files differnew file mode 100644 index 0000000000..6aa1766146 --- /dev/null +++ b/doc/src/images/windows-datetimeedit.png diff --git a/doc/src/images/windows-dial.png b/doc/src/images/windows-dial.png Binary files differnew file mode 100644 index 0000000000..0aa3a26159 --- /dev/null +++ b/doc/src/images/windows-dial.png diff --git a/doc/src/images/windows-doublespinbox.png b/doc/src/images/windows-doublespinbox.png Binary files differnew file mode 100644 index 0000000000..244b5f66cd --- /dev/null +++ b/doc/src/images/windows-doublespinbox.png diff --git a/doc/src/images/windows-fontcombobox.png b/doc/src/images/windows-fontcombobox.png Binary files differnew file mode 100644 index 0000000000..bf98cad922 --- /dev/null +++ b/doc/src/images/windows-fontcombobox.png diff --git a/doc/src/images/windows-frame.png b/doc/src/images/windows-frame.png Binary files differnew file mode 100644 index 0000000000..5979b31b25 --- /dev/null +++ b/doc/src/images/windows-frame.png diff --git a/doc/src/images/windows-groupbox.png b/doc/src/images/windows-groupbox.png Binary files differnew file mode 100644 index 0000000000..88f46a3832 --- /dev/null +++ b/doc/src/images/windows-groupbox.png diff --git a/doc/src/images/windows-horizontalscrollbar.png b/doc/src/images/windows-horizontalscrollbar.png Binary files differnew file mode 100644 index 0000000000..1f36b9a352 --- /dev/null +++ b/doc/src/images/windows-horizontalscrollbar.png diff --git a/doc/src/images/windows-label.png b/doc/src/images/windows-label.png Binary files differnew file mode 100644 index 0000000000..a1c3a396a9 --- /dev/null +++ b/doc/src/images/windows-label.png diff --git a/doc/src/images/windows-lcdnumber.png b/doc/src/images/windows-lcdnumber.png Binary files differnew file mode 100644 index 0000000000..b463511aab --- /dev/null +++ b/doc/src/images/windows-lcdnumber.png diff --git a/doc/src/images/windows-lineedit.png b/doc/src/images/windows-lineedit.png Binary files differnew file mode 100644 index 0000000000..270e4517ff --- /dev/null +++ b/doc/src/images/windows-lineedit.png diff --git a/doc/src/images/windows-listview.png b/doc/src/images/windows-listview.png Binary files differnew file mode 100644 index 0000000000..2884fae1b1 --- /dev/null +++ b/doc/src/images/windows-listview.png diff --git a/doc/src/images/windows-progressbar.png b/doc/src/images/windows-progressbar.png Binary files differnew file mode 100644 index 0000000000..361799a70e --- /dev/null +++ b/doc/src/images/windows-progressbar.png diff --git a/doc/src/images/windows-pushbutton.png b/doc/src/images/windows-pushbutton.png Binary files differnew file mode 100644 index 0000000000..14528d6808 --- /dev/null +++ b/doc/src/images/windows-pushbutton.png diff --git a/doc/src/images/windows-radiobutton.png b/doc/src/images/windows-radiobutton.png Binary files differnew file mode 100644 index 0000000000..db328cb563 --- /dev/null +++ b/doc/src/images/windows-radiobutton.png diff --git a/doc/src/images/windows-slider.png b/doc/src/images/windows-slider.png Binary files differnew file mode 100644 index 0000000000..fde85024b6 --- /dev/null +++ b/doc/src/images/windows-slider.png diff --git a/doc/src/images/windows-spinbox.png b/doc/src/images/windows-spinbox.png Binary files differnew file mode 100644 index 0000000000..d4e93c584a --- /dev/null +++ b/doc/src/images/windows-spinbox.png diff --git a/doc/src/images/windows-tableview.png b/doc/src/images/windows-tableview.png Binary files differnew file mode 100644 index 0000000000..89da89fb5f --- /dev/null +++ b/doc/src/images/windows-tableview.png diff --git a/doc/src/images/windows-tabwidget.png b/doc/src/images/windows-tabwidget.png Binary files differnew file mode 100644 index 0000000000..8622f7ec6a --- /dev/null +++ b/doc/src/images/windows-tabwidget.png diff --git a/doc/src/images/windows-textedit.png b/doc/src/images/windows-textedit.png Binary files differnew file mode 100644 index 0000000000..fd21ade02f --- /dev/null +++ b/doc/src/images/windows-textedit.png diff --git a/doc/src/images/windows-timeedit.png b/doc/src/images/windows-timeedit.png Binary files differnew file mode 100644 index 0000000000..6ae0e406bc --- /dev/null +++ b/doc/src/images/windows-timeedit.png diff --git a/doc/src/images/windows-toolbox.png b/doc/src/images/windows-toolbox.png Binary files differnew file mode 100644 index 0000000000..99b471e6df --- /dev/null +++ b/doc/src/images/windows-toolbox.png diff --git a/doc/src/images/windows-toolbutton.png b/doc/src/images/windows-toolbutton.png Binary files differnew file mode 100644 index 0000000000..9ceb846ed4 --- /dev/null +++ b/doc/src/images/windows-toolbutton.png diff --git a/doc/src/images/windows-treeview.png b/doc/src/images/windows-treeview.png Binary files differnew file mode 100644 index 0000000000..f55cd69c79 --- /dev/null +++ b/doc/src/images/windows-treeview.png diff --git a/doc/src/images/windowsvista-calendarwidget.png b/doc/src/images/windowsvista-calendarwidget.png Binary files differnew file mode 100644 index 0000000000..3cb1ab78dc --- /dev/null +++ b/doc/src/images/windowsvista-calendarwidget.png diff --git a/doc/src/images/windowsvista-checkbox.png b/doc/src/images/windowsvista-checkbox.png Binary files differnew file mode 100644 index 0000000000..b9bc909988 --- /dev/null +++ b/doc/src/images/windowsvista-checkbox.png diff --git a/doc/src/images/windowsvista-combobox.png b/doc/src/images/windowsvista-combobox.png Binary files differnew file mode 100644 index 0000000000..f53192f45a --- /dev/null +++ b/doc/src/images/windowsvista-combobox.png diff --git a/doc/src/images/windowsvista-dateedit.png b/doc/src/images/windowsvista-dateedit.png Binary files differnew file mode 100644 index 0000000000..bb79482849 --- /dev/null +++ b/doc/src/images/windowsvista-dateedit.png diff --git a/doc/src/images/windowsvista-datetimeedit.png b/doc/src/images/windowsvista-datetimeedit.png Binary files differnew file mode 100644 index 0000000000..0a104de084 --- /dev/null +++ b/doc/src/images/windowsvista-datetimeedit.png diff --git a/doc/src/images/windowsvista-dial.png b/doc/src/images/windowsvista-dial.png Binary files differnew file mode 100644 index 0000000000..7081269c31 --- /dev/null +++ b/doc/src/images/windowsvista-dial.png diff --git a/doc/src/images/windowsvista-doublespinbox.png b/doc/src/images/windowsvista-doublespinbox.png Binary files differnew file mode 100644 index 0000000000..6efa9379fd --- /dev/null +++ b/doc/src/images/windowsvista-doublespinbox.png diff --git a/doc/src/images/windowsvista-fontcombobox.png b/doc/src/images/windowsvista-fontcombobox.png Binary files differnew file mode 100644 index 0000000000..3771e84bd4 --- /dev/null +++ b/doc/src/images/windowsvista-fontcombobox.png diff --git a/doc/src/images/windowsvista-frame.png b/doc/src/images/windowsvista-frame.png Binary files differnew file mode 100644 index 0000000000..63b8422d2b --- /dev/null +++ b/doc/src/images/windowsvista-frame.png diff --git a/doc/src/images/windowsvista-groupbox.png b/doc/src/images/windowsvista-groupbox.png Binary files differnew file mode 100644 index 0000000000..967d8878a7 --- /dev/null +++ b/doc/src/images/windowsvista-groupbox.png diff --git a/doc/src/images/windowsvista-horizontalscrollbar.png b/doc/src/images/windowsvista-horizontalscrollbar.png Binary files differnew file mode 100644 index 0000000000..996865d66c --- /dev/null +++ b/doc/src/images/windowsvista-horizontalscrollbar.png diff --git a/doc/src/images/windowsvista-label.png b/doc/src/images/windowsvista-label.png Binary files differnew file mode 100644 index 0000000000..caef8d8361 --- /dev/null +++ b/doc/src/images/windowsvista-label.png diff --git a/doc/src/images/windowsvista-lcdnumber.png b/doc/src/images/windowsvista-lcdnumber.png Binary files differnew file mode 100644 index 0000000000..911438e2b1 --- /dev/null +++ b/doc/src/images/windowsvista-lcdnumber.png diff --git a/doc/src/images/windowsvista-lineedit.png b/doc/src/images/windowsvista-lineedit.png Binary files differnew file mode 100644 index 0000000000..9fcde3a851 --- /dev/null +++ b/doc/src/images/windowsvista-lineedit.png diff --git a/doc/src/images/windowsvista-listview.png b/doc/src/images/windowsvista-listview.png Binary files differnew file mode 100644 index 0000000000..36a03438ab --- /dev/null +++ b/doc/src/images/windowsvista-listview.png diff --git a/doc/src/images/windowsvista-progressbar.png b/doc/src/images/windowsvista-progressbar.png Binary files differnew file mode 100644 index 0000000000..0bda010811 --- /dev/null +++ b/doc/src/images/windowsvista-progressbar.png diff --git a/doc/src/images/windowsvista-pushbutton.png b/doc/src/images/windowsvista-pushbutton.png Binary files differnew file mode 100644 index 0000000000..3bc438dc10 --- /dev/null +++ b/doc/src/images/windowsvista-pushbutton.png diff --git a/doc/src/images/windowsvista-radiobutton.png b/doc/src/images/windowsvista-radiobutton.png Binary files differnew file mode 100644 index 0000000000..fdfd2d66dd --- /dev/null +++ b/doc/src/images/windowsvista-radiobutton.png diff --git a/doc/src/images/windowsvista-slider.png b/doc/src/images/windowsvista-slider.png Binary files differnew file mode 100644 index 0000000000..be2fffb7b5 --- /dev/null +++ b/doc/src/images/windowsvista-slider.png diff --git a/doc/src/images/windowsvista-spinbox.png b/doc/src/images/windowsvista-spinbox.png Binary files differnew file mode 100644 index 0000000000..4a2293e724 --- /dev/null +++ b/doc/src/images/windowsvista-spinbox.png diff --git a/doc/src/images/windowsvista-tableview.png b/doc/src/images/windowsvista-tableview.png Binary files differnew file mode 100644 index 0000000000..96f4937bc1 --- /dev/null +++ b/doc/src/images/windowsvista-tableview.png diff --git a/doc/src/images/windowsvista-tabwidget.png b/doc/src/images/windowsvista-tabwidget.png Binary files differnew file mode 100644 index 0000000000..259c4f1a89 --- /dev/null +++ b/doc/src/images/windowsvista-tabwidget.png diff --git a/doc/src/images/windowsvista-textedit.png b/doc/src/images/windowsvista-textedit.png Binary files differnew file mode 100644 index 0000000000..5e5696623e --- /dev/null +++ b/doc/src/images/windowsvista-textedit.png diff --git a/doc/src/images/windowsvista-timeedit.png b/doc/src/images/windowsvista-timeedit.png Binary files differnew file mode 100644 index 0000000000..e24fdd268a --- /dev/null +++ b/doc/src/images/windowsvista-timeedit.png diff --git a/doc/src/images/windowsvista-toolbox.png b/doc/src/images/windowsvista-toolbox.png Binary files differnew file mode 100644 index 0000000000..8cfe5f9cab --- /dev/null +++ b/doc/src/images/windowsvista-toolbox.png diff --git a/doc/src/images/windowsvista-toolbutton.png b/doc/src/images/windowsvista-toolbutton.png Binary files differnew file mode 100644 index 0000000000..0baa9809c1 --- /dev/null +++ b/doc/src/images/windowsvista-toolbutton.png diff --git a/doc/src/images/windowsvista-treeview.png b/doc/src/images/windowsvista-treeview.png Binary files differnew file mode 100644 index 0000000000..db211e4b5f --- /dev/null +++ b/doc/src/images/windowsvista-treeview.png diff --git a/doc/src/images/windowsxp-calendarwidget.png b/doc/src/images/windowsxp-calendarwidget.png Binary files differnew file mode 100644 index 0000000000..9a5fa6ebcd --- /dev/null +++ b/doc/src/images/windowsxp-calendarwidget.png diff --git a/doc/src/images/windowsxp-checkbox.png b/doc/src/images/windowsxp-checkbox.png Binary files differnew file mode 100644 index 0000000000..505d3a3641 --- /dev/null +++ b/doc/src/images/windowsxp-checkbox.png diff --git a/doc/src/images/windowsxp-combobox.png b/doc/src/images/windowsxp-combobox.png Binary files differnew file mode 100644 index 0000000000..2363c8401c --- /dev/null +++ b/doc/src/images/windowsxp-combobox.png diff --git a/doc/src/images/windowsxp-dateedit.png b/doc/src/images/windowsxp-dateedit.png Binary files differnew file mode 100644 index 0000000000..060ba07b2c --- /dev/null +++ b/doc/src/images/windowsxp-dateedit.png diff --git a/doc/src/images/windowsxp-datetimeedit.png b/doc/src/images/windowsxp-datetimeedit.png Binary files differnew file mode 100644 index 0000000000..4e41f0fc14 --- /dev/null +++ b/doc/src/images/windowsxp-datetimeedit.png diff --git a/doc/src/images/windowsxp-dial.png b/doc/src/images/windowsxp-dial.png Binary files differnew file mode 100644 index 0000000000..0aa3a26159 --- /dev/null +++ b/doc/src/images/windowsxp-dial.png diff --git a/doc/src/images/windowsxp-doublespinbox.png b/doc/src/images/windowsxp-doublespinbox.png Binary files differnew file mode 100644 index 0000000000..3165a61b93 --- /dev/null +++ b/doc/src/images/windowsxp-doublespinbox.png diff --git a/doc/src/images/windowsxp-fontcombobox.png b/doc/src/images/windowsxp-fontcombobox.png Binary files differnew file mode 100644 index 0000000000..96292b84ef --- /dev/null +++ b/doc/src/images/windowsxp-fontcombobox.png diff --git a/doc/src/images/windowsxp-frame.png b/doc/src/images/windowsxp-frame.png Binary files differnew file mode 100644 index 0000000000..5979b31b25 --- /dev/null +++ b/doc/src/images/windowsxp-frame.png diff --git a/doc/src/images/windowsxp-groupbox.png b/doc/src/images/windowsxp-groupbox.png Binary files differnew file mode 100644 index 0000000000..0b6f7e21ad --- /dev/null +++ b/doc/src/images/windowsxp-groupbox.png diff --git a/doc/src/images/windowsxp-horizontalscrollbar.png b/doc/src/images/windowsxp-horizontalscrollbar.png Binary files differnew file mode 100644 index 0000000000..38812ec107 --- /dev/null +++ b/doc/src/images/windowsxp-horizontalscrollbar.png diff --git a/doc/src/images/windowsxp-label.png b/doc/src/images/windowsxp-label.png Binary files differnew file mode 100644 index 0000000000..a1c3a396a9 --- /dev/null +++ b/doc/src/images/windowsxp-label.png diff --git a/doc/src/images/windowsxp-lcdnumber.png b/doc/src/images/windowsxp-lcdnumber.png Binary files differnew file mode 100644 index 0000000000..102023c8ed --- /dev/null +++ b/doc/src/images/windowsxp-lcdnumber.png diff --git a/doc/src/images/windowsxp-lineedit.png b/doc/src/images/windowsxp-lineedit.png Binary files differnew file mode 100644 index 0000000000..9102b53ca4 --- /dev/null +++ b/doc/src/images/windowsxp-lineedit.png diff --git a/doc/src/images/windowsxp-listview.png b/doc/src/images/windowsxp-listview.png Binary files differnew file mode 100644 index 0000000000..b0fc9bd3a7 --- /dev/null +++ b/doc/src/images/windowsxp-listview.png diff --git a/doc/src/images/windowsxp-progressbar.png b/doc/src/images/windowsxp-progressbar.png Binary files differnew file mode 100644 index 0000000000..c8a73d6754 --- /dev/null +++ b/doc/src/images/windowsxp-progressbar.png diff --git a/doc/src/images/windowsxp-pushbutton.png b/doc/src/images/windowsxp-pushbutton.png Binary files differnew file mode 100644 index 0000000000..bf6b7bf15d --- /dev/null +++ b/doc/src/images/windowsxp-pushbutton.png diff --git a/doc/src/images/windowsxp-radiobutton.png b/doc/src/images/windowsxp-radiobutton.png Binary files differnew file mode 100644 index 0000000000..ad8a908fb2 --- /dev/null +++ b/doc/src/images/windowsxp-radiobutton.png diff --git a/doc/src/images/windowsxp-slider.png b/doc/src/images/windowsxp-slider.png Binary files differnew file mode 100644 index 0000000000..9e2fca7c40 --- /dev/null +++ b/doc/src/images/windowsxp-slider.png diff --git a/doc/src/images/windowsxp-spinbox.png b/doc/src/images/windowsxp-spinbox.png Binary files differnew file mode 100644 index 0000000000..e42073cd6b --- /dev/null +++ b/doc/src/images/windowsxp-spinbox.png diff --git a/doc/src/images/windowsxp-tableview.png b/doc/src/images/windowsxp-tableview.png Binary files differnew file mode 100644 index 0000000000..5d12137ad5 --- /dev/null +++ b/doc/src/images/windowsxp-tableview.png diff --git a/doc/src/images/windowsxp-tabwidget.png b/doc/src/images/windowsxp-tabwidget.png Binary files differnew file mode 100644 index 0000000000..3c8e777a0b --- /dev/null +++ b/doc/src/images/windowsxp-tabwidget.png diff --git a/doc/src/images/windowsxp-textedit.png b/doc/src/images/windowsxp-textedit.png Binary files differnew file mode 100644 index 0000000000..d89c75c71b --- /dev/null +++ b/doc/src/images/windowsxp-textedit.png diff --git a/doc/src/images/windowsxp-timeedit.png b/doc/src/images/windowsxp-timeedit.png Binary files differnew file mode 100644 index 0000000000..751cca9e6a --- /dev/null +++ b/doc/src/images/windowsxp-timeedit.png diff --git a/doc/src/images/windowsxp-toolbox.png b/doc/src/images/windowsxp-toolbox.png Binary files differnew file mode 100644 index 0000000000..99b471e6df --- /dev/null +++ b/doc/src/images/windowsxp-toolbox.png diff --git a/doc/src/images/windowsxp-toolbutton.png b/doc/src/images/windowsxp-toolbutton.png Binary files differnew file mode 100644 index 0000000000..ea63e16aae --- /dev/null +++ b/doc/src/images/windowsxp-toolbutton.png diff --git a/doc/src/images/windowsxp-treeview.png b/doc/src/images/windowsxp-treeview.png Binary files differnew file mode 100644 index 0000000000..050cc2f4d6 --- /dev/null +++ b/doc/src/images/windowsxp-treeview.png diff --git a/doc/src/network-programming/bearermanagement.qdoc b/doc/src/network-programming/bearermanagement.qdoc new file mode 100644 index 0000000000..708a72fa19 --- /dev/null +++ b/doc/src/network-programming/bearermanagement.qdoc @@ -0,0 +1,271 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\page bearer-management.html + +\title Bearer Management +\ingroup qt-network +\brief An API to control the system's connectivity state. + +Bearer Management controls the connectivity state of the system so that +the user can start or stop interfaces or roam transparently between +access points. + +\tableofcontents + + +\section1 Overview + +The Bearer Management API controls the system's connectivity state. This +incorporates simple information such as whether the device is online and +how many interfaces there are as well as enables the application developer +to start, stop network interfaces and influences other connection specific +details. Depending on the platform's capabilities it may even provide +session management so that a network interface remains up for as long as +clients have a registered interest in them while at the same time +optimizes the interface's uptime. + +This API does not provide support for management of network configurations +themselves. It is up to the platform to provide infrastructure which +enables to user to create, edit or delete network configurations. + +\section2 The API in Detail + +Computer systems manage their network interfaces via a set of configurations. +Each configuration describes a set of parameters which instruct the system +how a particular network interface is started. One of the most simplistic +examples might be an Ethernet configuration that links a network card to a +DHCP server. A more complex example might be a Wireless LAN configuration +which may comprise of hardware details such as the WLAN card address, +WLAN access point details (e.g ESSID, encryption details) and user specific +information (for example username and password). Once the network interface +was configured and started according to the configuration blue print, +multiple applications are free to use this link layer connection/session +for their own socket operations. Note that the QNetworkConfiguration object +only provides limited information about the configuration details themselves. +It's main purpose is to act as a configuration identifier through which link +layer connections can be created, destroyed and monitored. + +QNetworkSession provides two types of use cases. It enables the monitoring of +physical network interfaces and management of network sessions. Network sessions +are a common feature on mobile devices where multiple applications +can request network sessions as they see fit. The system consolidates and tracks +active network sessions for the same network interface by maintaining the link +layer connections until the last session has been closed. The subsequent table +lists the major QNetworkSession functions and how they fit into the session and +hardware management categories: + +\table 60% +\header \o Interface management \o Session management +\row \o QNetworkSession::stop() \o QNetworkSession::open() +\row \o QNetworkSession::interface() \o QNetworkSession::close() +\row \o QNetworkSession::state() \o QNetworkSession::isOpen() +\row \o QNetworkSession::bytesWritten() \o QNetworkSession::migrate() +\row \o QNetworkSession::bytesReceived() \o QNetworkSession::ignore() +\row \o QNetworkSession::activeTime() \o QNetworkSession::accept() +\row \o QNetworkSession::stateChanged() \o QNetworkSession::reject() +\row \o \o QNetworkSession::opened() +\row \o \o QNetworkSession::closed() +\endtable + +The state of the session represents the state of the underlying access point +whereas the session's openness implies the networking/connectivity state available +to the current process. + +Possible use cases for interface management are network management related +applications which intend to monitor the connectivity state but do not engage +in network communication themselves. Any application wanting to open a socket +to a remote address will typically use session management related functionality. + +\section3 Service networks + +Some mobile platforms use the concept of grouped access points (also +called SNAP or Service Network Access Point). In principle multiple +configurations are grouped together and possibly even prioritized when +compared to each other. This is useful for use cases where all +configurations serve a similar purpose or context. A common context could +be that they provide access to the public Internet or possibly only to the +office Intranet. By providing a pool of configurations the system can make +a decision based on given priorities which usually map to factors such as +speed, availability and cost. Furthermore the system can automatically +roam from one access point to the next one while ensuring minimal impact on +the user experience. + +The \l{QNetworkConfiguration::Type} flag specifies to what category a +configuration belongs. The \l{QNetworkConfiguration::InternetAccessPoint} +type is the most common example. It represents a configuration that can be +used to create a session. The above mentioned grouping behavior is provided +by \l {QNetworkConfiguration::ServiceNetwork} configurations. Service +networks are place holders until such time when the user attempts to +\l {QNetworkSession::open()}{open()} a new session. At that point in time +the system determines which of the configurations \l{QNetworkConfiguration::children()} +is best to use. The selection algorithm is provided by the platform and is usually managed +by network settings applications. A service network can only have one level of indirection +which implies children can only be of type \l {QNetworkConfiguration::InternetAccessPoint}. + +Most systems allow the user to define the systems default configuration. +Usually the default behavior is either a service network, a particular +Internet access point or the user instructs the platform to ask the user +once an application requests the network. User interaction is generally +implemented by some sort of system dialog which shows up at the appropriate +point in time. The application does not have to handle the user input. This +API provides the \l QNetworkConfigurationManager::defaultConfiguration() +call which serves a similar purpose. The subsequent code snippet provides +a quick way how an application can quickly create a new network session +without (or only minimal) user interaction: + +\code + // Set Internet Access Point + QNetworkConfigurationManager manager; + const bool canStartIAP = (manager.capabilities() + & QNetworkConfigurationManager::CanStartAndStopInterfaces); + // Is there default access point, use it + QNetworkConfiguration cfg = manager.defaultConfiguration(); + if (!cfg.isValid() || (!canStartIAP && cfg.state() != QNetworkConfiguration::Active)) { + QMessageBox::information(this, tr("Network"), tr( + "No Access Point found.")); + return; + } + + session = new QNetworkSession(cfg, this); + session->open(); + session->waitForOpened(-1); +\endcode + +To accommodate the "Ask user" use case the default configuration can be of +type QNetworkConfiguration::UserChoice. A user choice configuration is +resolved as part of the \l {QNetworkSession::open()} call. Note that a +\l{QNetworkConfiguration::UserChoice}{UserChoice} configuration is only +ever returned via \l {QNetworkConfigurationManager::defaultConfiguration()} +and not \l QNetworkConfigurationManager::allConfigurations(). + +On systems which do not maintain a list of +\l {QNetworkConfigurationManager::defaultConfiguration()}{defaultConfiguration()} +an invalid configuration is returned. A possible workaround could be to +implement a custom dialog which is populated based on what +\l QNetworkConfigurationManager::allConfigurations() returns. + +\section3 Managing network sessions + +A QNetworkSession object separates a \l {QNetworkSession::state()}{state()} +and an \l{QNetworkSession::isOpen()}{isOpen()} condition. + +The state() attribute enables developers to detect whether the system +currently maintains a global network session for the given +QNetworkConfiguration. If \l {QNetworkSession::isOpen()}{isOpen()} +returns true the QNetworkSession instance at hand was at least one of the +entities requesting the global network session. This distinction is +required to support the notion of session registrations. For as long as +there are one or more open QNetworkSession instances the underlying +network interface is not shut down. Therefore the session +\l{QNetworkSession::state()}{state()} can be used to monitor the state of +network interfaces. + +An open session is created by calling \l {QNetworkSession::open()} and +closed via \l{QNetworkSession::close()}, respectively. If the session +is \l{QNetworkSession::Disconnected}{disconnected} at the time of the +\l{QNetworkSession::open()}{open()} call the underlying interface is started; +otherwise only the reference counter against the global session is +incremented. The opposite behavior can be observed when using +\l{QNetworkSession::close()}{close()}. + +In some use cases it may be necessary to turn the interface off despite of +open sessions. This can be achieved by calling +\l{QNetworkSession::stop()}{stop()}. An example use case could be a +network manager type of application allowing the user to control the +overall state of the devices connectivity. + +Global (inter-process) session support is platform dependent and can be +detected via \l {QNetworkConfigurationManager::SystemSessionSupport}. +If the system does not support global session calling +\l{QNetworkSession::close()}{close()} never stops the interface. + +\section3 Roaming + +Roaming is the process of reconnecting a device from one network to another +while minimizing the impact on the application. The system notifies the application +about link layer changes so that the required preparation can be taken. +The most common reaction would be to reinitialize sockets and to renegotiate +stateful connections with other parties. In the most extreme cases applications +may even prevent the roaming altogether. + +Roaming is initiated when the system determines that a more appropriate access point +becomes available to the user. In general such a decision is based on cost, network speed +or network type (access to certain private networks may only be provided via certain access points). +Almost all devices providing roaming support have some form of global configuration application +enabling the user to define such groups of access points (service networks) and priorities. + +This API supports two types of roaming. Application level roaming (ALR) +provides the most control over the process. Applications will be notified about upcoming +link layer changes and get the opportunity to test the new access point. Eventually they can +reject or accept the link layer change. The second form of roaming is referred to as Forced Roaming. +The system simply changes the link layer without consulting the application. It is up to +the application to detect that some of its internal socket may have become invalid. As a consequence +it has to reinitialize those sockets and reestablish the previous user session without +any interruption. Forced roaming has the advantage that applications don't have to +manage the entire roaming process by themselves. + +QNetworkSession is the central class for managing roaming related issues. + +\section3 Platform capabilities + +Some API features are not available on all platforms. The +\l QNetworkConfigurationManager::Capability should be used to detect +platform features at runtime. The following table lists the various +platform APIs being used by this API. This may assist in the process of +determining the feature support: + +\table + \header + \o Platform + \o Backend capabilities + \row + \o Linux\unicode{0xAE} + \o Linux uses the \l {http://projects.gnome.org/NetworkManager}{NetworkManager API} which supports interface notifications and starting and stopping of network interfaces. + \row + \o Windows\unicode{0xAE} XP + \o This platform supports interface notifications without active polling. + \row + \o Windows XP SP2+Hotfixes, Windows XP SP3, Windows Vista, Windows 7 + \o In addition to standard Windows XP wifi access point monitoring has been improved which includes the ability to start and stop wifi interfaces. This requires Windows to manage the wifi interfaces. + \row + \o Symbian\unicode{0xAE} Platform & S60 3.1 + \o Symbian support is based on Symbian platforms RConnection. In addition to interface notifications, starting and stopping of network it provides system wide session support and direct connection routing. + \row + \o Symbian Platform & S60 3.2+ + \o This platform enjoys the most comprehensive feature set. In addition to the features support by the S60 3.1 Network roaming is supported. + \row + \o Mac OS\unicode{0xAE} + \o This platform has full support by way of CoreWLAN offered in Mac OS 10.6. Previous + versions of Mac OS - 10.5 and 10.4 have limited support. + \row + \o All other platforms (*nix, Windows Mobile) + \o This backend is the fallback for all platforms supports network interface notifications via active polling only. +\endtable + +*/ diff --git a/doc/src/network-programming/qtnetwork.qdoc b/doc/src/network-programming/qtnetwork.qdoc new file mode 100644 index 0000000000..61ff2c5fbe --- /dev/null +++ b/doc/src/network-programming/qtnetwork.qdoc @@ -0,0 +1,350 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \group network + \title Network Programming API + \brief Classes for Network Programming + + \ingroup groups +*/ + +/*! + \page network-programming.html + \title Network Programming + \ingroup qt-network + \brief An Introduction to Network Programming with Qt + + The QtNetwork module offers classes that allow you to write TCP/IP clients + and servers. It offers classes such as QFtp that implement specific + application-level protocols, lower-level classes such as QTcpSocket, + QTcpServer and QUdpSocket that represent low level network concepts, + and high level classes such as QNetworkRequest, QNetworkReply and + QNetworkAccessManager to perform network operations using common protocols. + It also offers classes such as QNetworkConfiguration, + QNetworkConfigurationManager and QNetworkSession that implement bearer + management. + + \tableofcontents + + \section1 Qt's Classes for Network Programming + + The following classes provide support for network programming in Qt. + + \annotatedlist network + + \section1 High Level Network Operations for HTTP and FTP + + The Network Access API is a collection of classes for performing + common network operations. The API provides an abstraction layer + over the specific operations and protocols used (for example, + getting and posting data over HTTP), and only exposes classes, + functions, and signals for general or high level concepts. + + Network requests are represented by the QNetworkRequest class, + which also acts as a general container for information associated + with a request, such as any header information and the encryption + used. The URL specified when a request object is constructed + determines the protocol used for a request. + Currently HTTP, FTP and local file URLs are supported for uploading + and downloading. + + The coordination of network operations is performed by the + QNetworkAccessManager class. Once a request has been created, + this class is used to dispatch it and emit signals to report on + its progress. The manager also coordinates the use of + \l{QNetworkCookieJar}{cookies} to store data on the client, + authentication requests, and the use of proxies. + + Replies to network requests are represented by the QNetworkReply + class; these are created by QNetworkAccessManager when a request + is dispatched. The signals provided by QNetworkReply can be used + to monitor each reply individually, or developers may choose to + use the manager's signals for this purpose instead and discard + references to replies. Since QNetworkReply is a subclass of + QIODevice, replies can be handled synchronously or asynchronously; + i.e., as blocking or non-blocking operations. + + Each application or library can create one or more instances of + QNetworkAccessManager to handle network communication. + + \section1 Writing FTP Clients with QFtp + + FTP (File Transfer Protocol) is a protocol used almost exclusively + for browsing remote directories and for transferring files. + + \image httpstack.png FTP Client and Server + + FTP uses two network connections, one for sending + commands and one for transferring data. The + FTP protocol has a state and requires the client to send several + commands before a file transfer takes place. + FTP clients establish a connection + and keeps it open throughout the session. In each session, multiple + transfers can occur. + + The QFtp class provides client-side support for FTP. + It has the following characteristics: + \list + + \o \e{Non-blocking behavior.} QFtp is asynchronous. + You can schedule a series of commands which are executed later, + when control returns to Qt's event loop. + + \o \e{Command IDs.} Each command has a unique ID number that you + can use to follow the execution of the command. For example, QFtp + emits the \l{QFtp::commandStarted()}{commandStarted()} and + \l{QFtp::commandFinished()}{commandFinished()} signal with the + command ID for each command that is executed. + + \o \e{Data transfer progress indicators.} QFtp emits signals + whenever data is transferred (QFtp::dataTransferProgress(), + QNetworkReply::downloadProgress(), and + QNetworkReply::uploadProgress()). You could connect these signals + to QProgressBar::setProgress() or QProgressDialog::setProgress(), + for example. + + \o \e{QIODevice support.} The class supports convenient + uploading from and downloading to \l{QIODevice}s, in addition to a + QByteArray-based API. + + \endlist + + There are two main ways of using QFtp. The most common + approach is to keep track of the command IDs and follow the + execution of every command by connecting to the appropriate + signals. The other approach is to schedule all commands at once + and only connect to the done() signal, which is emitted when all + scheduled commands have been executed. The first approach + requires more work, but it gives you more control over the + execution of individual commands and allows you to initiate new + commands based on the result of a previous command. It also + enables you to provide detailed feedback to the user. + + The \l{network/qftp}{FTP} example + illustrates how to write an FTP client. + Writing your own FTP (or HTTP) server is possible using the + lower-level classes QTcpSocket and QTcpServer. + + \section1 Using TCP with QTcpSocket and QTcpServer + + TCP (Transmission Control Protocol) is a low-level network + protocol used by most Internet protocols, including HTTP and FTP, + for data transfer. It is a reliable, stream-oriented, + connection-oriented transport protocol. It is particularly well + suited to the continuous transmission of data. + + \image tcpstream.png A TCP Stream + + The QTcpSocket class provides an interface for TCP. You can use + QTcpSocket to implement standard network protocols such as POP3, + SMTP, and NNTP, as well as custom protocols. + + A TCP connection must be established to a remote host and port + before any data transfer can begin. Once the connection has been + established, the IP address and port of the peer are available + through QTcpSocket::peerAddress() and QTcpSocket::peerPort(). At + any time, the peer can close the connection, and data transfer + will then stop immediately. + + QTcpSocket works asynchronously and emits signals to report status + changes and errors, just like QNetworkAccessManager and QFtp. It + relies on the event loop to detect incoming data and to + automatically flush outgoing data. You can write data to the + socket using QTcpSocket::write(), and read data using + QTcpSocket::read(). QTcpSocket represents two independent streams + of data: one for reading and one for writing. + + Since QTcpSocket inherits QIODevice, you can use it with + QTextStream and QDataStream. When reading from a QTcpSocket, you + must make sure that enough data is available by calling + QTcpSocket::bytesAvailable() beforehand. + + If you need to handle incoming TCP connections (e.g., in a server + application), use the QTcpServer class. Call QTcpServer::listen() + to set up the server, and connect to the + QTcpServer::newConnection() signal, which is emitted once for + every client that connects. In your slot, call + QTcpServer::nextPendingConnection() to accept the connection and + use the returned QTcpSocket to communicate with the client. + + Although most of its functions work asynchronously, it's possible + to use QTcpSocket synchronously (i.e., blocking). To get blocking + behavior, call QTcpSocket's waitFor...() functions; these suspend + the calling thread until a signal has been emitted. For example, + after calling the non-blocking QTcpSocket::connectToHost() + function, call QTcpSocket::waitForConnected() to block the thread + until the \l{QTcpSocket::connected()}{connected()} signal has + been emitted. + + Synchronous sockets often lead to code with a simpler flow of + control. The main disadvantage of the waitFor...() approach is + that events won't be processed while a waitFor...() function is + blocking. If used in the GUI thread, this might freeze the + application's user interface. For this reason, we recommend that + you use synchronous sockets only in non-GUI threads. When used + synchronously, QTcpSocket doesn't require an event loop. + + The \l{network/fortuneclient}{Fortune Client} and + \l{network/fortuneserver}{Fortune Server} examples show how to use + QTcpSocket and QTcpServer to write TCP client-server + applications. See also \l{network/blockingfortuneclient}{Blocking + Fortune Client} for an example on how to use a synchronous + QTcpSocket in a separate thread (without using an event loop), + and \l{network/threadedfortuneserver}{Threaded Fortune Server} + for an example of a multithreaded TCP server with one thread per + active client. + + \section1 Using UDP with QUdpSocket + + UDP (User Datagram Protocol) is a lightweight, unreliable, + datagram-oriented, connectionless protocol. It can be used when + reliability isn't important. For example, a server that reports + the time of day could choose UDP. If a datagram with the time of + day is lost, the client can simply make another request. + + \image udppackets.png UDP Packets + + The QUdpSocket class allows you to send and receive UDP + datagrams. It inherits QAbstractSocket, and it therefore shares + most of QTcpSocket's interface. The main difference is that + QUdpSocket transfers data as datagrams instead of as a continuous + stream of data. In short, a datagram is a data packet of limited + size (normally smaller than 512 bytes), containing the IP address + and port of the datagram's sender and receiver in addition to the + data being transferred. + + QUdpSocket supports IPv4 broadcasting. Broadcasting is often used + to implement network discovery protocols, such as finding which + host on the network has the most free hard disk space. One host + broadcasts a datagram to the network that all other hosts + receive. Each host that receives a request then sends a reply + back to the sender with its current amount of free disk space. + The originator waits until it has received replies from all + hosts, and can then choose the server with most free space to + store data. To broadcast a datagram, simply send it to the + special address QHostAddress::Broadcast (255.255.255.255), or + to your local network's broadcast address. + + QUdpSocket::bind() prepares the socket for accepting incoming + datagrams, much like QTcpServer::listen() for TCP servers. + Whenever one or more datagrams arrive, QUdpSocket emits the + \l{QUdpSocket::readyRead()}{readyRead()} signal. Call + QUdpSocket::readDatagram() to read the datagram. + + The \l{network/broadcastsender}{Broadcast Sender} and + \l{network/broadcastreceiver}{Broadcast Receiver} examples show how to + write a UDP sender and a UDP receiver using Qt. + + QUdpSocket also supports multicasting. The + \l{network/multicastsender}{Multicast Sender} and + \l{network/multicastreceiver}{Multicast Receiver} examples show how to use + write UDP multicast clients. + + \section1 Resolving Host Names using QHostInfo + + Before establishing a network connection, QTcpSocket and + QUdpSocket perform a name lookup, translating the host name + you're connecting to into an IP address. This operation is + usually performed using the DNS (Domain Name Service) protocol. + + QHostInfo provides a static function that lets you perform such a + lookup yourself. By calling QHostInfo::lookupHost() with a host + name, a QObject pointer, and a slot signature, QHostInfo will + perform the name lookup and invoke the given slot when the + results are ready. The actual lookup is done in a separate + thread, making use of the operating system's own methods for + performing name lookups. + + QHostInfo also provides a static function called + QHostInfo::fromName() that takes the host name as argument and + returns the results. In this case, the name lookup is performed + in the same thread as the caller. This overload is useful for + non-GUI applications or for doing name lookups in a separate, + non-GUI thread. (Calling this function in a GUI thread may cause + your user interface to freeze while the function blocks as + it performs the lookup.) + + \section1 Support for Network Proxies + + Network communication with Qt can be performed through proxies, + which direct or filter network traffic between local and remote + connections. + + Individual proxies are represented by the QNetworkProxy class, + which is used to describe and configure the connection to a proxy. + Proxy types which operate on different levels of network communication + are supported, with SOCKS 5 support allowing proxying of network + traffic at a low level, and HTTP and FTP proxying working at the + protocol level. See QNetworkProxy::ProxyType for more information. + + Proxying can be enabled on a per-socket basis or for all network + communication in an application. A newly opened socket can be + made to use a proxy by calling its QAbstractSocket::setProxy() + function before it is connected. Application-wide proxying can + be enabled for all subsequent socket connections through the use + of the QNetworkProxy::setApplicationProxy() function. + + Proxy factories are used to create policies for proxy use. + QNetworkProxyFactory supplies proxies based on queries for specific + proxy types. The queries themselves are encoded in QNetworkProxyQuery + objects which enable proxies to be selected based on key criteria, + such as the purpose of the proxy (TCP, UDP, TCP server, URL request), + local port, remote host and port, and the protocol in use (HTTP, FTP, + etc.). + + QNetworkProxyFactory::proxyForQuery() is used to query the factory + directly. An application-wide policy for proxying can be implemented + by passing a factory to QNetworkProxyFactory::setApplicationProxyFactory() + and a custom proxying policy can be created by subclassing + QNetworkProxyFactory; see the class documentation for details. + + \section1 Bearer Management Support + + Bearer Management controls the connectivity state of the device such that + the application can start or stop network interfaces and roam + transparently between access points. + + The QNetworkConfigurationManager class manages the list of network + configurations known to the device. A network configuration describes the + set of parameters used to start a network interface and is represented by + the QNetworkConfiguration class. + + A network interface is started by openning a QNetworkSession based on a + given network configuration. In most situations creating a network session + based on the platform specified default network configuration is + appropriate. The default network configuration is returned by the + QNetworkConfigurationManager::defaultConfiguration() function. + + On some platforms it is a platform requirement that the application open a + network session before any network operations can be performed. This can be + tested by the presents of the + QNetworkConfigurationManager::NetworkSessionRequired flag in the value + returned by the QNetworkConfigurationManager::capabilities() function. + + \sa {Bearer Management} +*/ diff --git a/doc/src/network-programming/ssl.qdoc b/doc/src/network-programming/ssl.qdoc new file mode 100644 index 0000000000..898ca5de34 --- /dev/null +++ b/doc/src/network-programming/ssl.qdoc @@ -0,0 +1,79 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page ssl.html + \title Secure Sockets Layer (SSL) Classes + \brief Classes for secure communication over network sockets. + \ingroup qt-network + + \keyword SSL + + The classes below provide support for secure network communication using + the Secure Sockets Layer (SSL) protocol, using the \l{OpenSSL Toolkit} to + perform encryption and protocol handling. + + See the \l{General Qt Requirements} page for information about the + versions of OpenSSL that are known to work with Qt. + + \section1 Enabling and Disabling SSL Support + + When building Qt from source, the configuration system checks for the presence + of the \c{openssl/opensslv.h} header provided by source or developer packages + of OpenSSL. + + By default, an SSL-enabled Qt library dynamically loads any installed OpenSSL + library at run-time. However, it is possible to link against the library at + compile-time by configuring Qt with the \c{-openssl-linked} option. + + When building a version of Qt linked against OpenSSL, the build system will + attempt to link with libssl and libcrypt libraries located in the default + location on the developer's system. This location is configurable: + set the \c OPENSSL_LIBS environment variable to contain the linker options + required to link Qt against the installed library. For example, on a Unix/Linux + system: + + \code + ./configure -openssl-linked OPENSSL_LIBS='-L/opt/ssl/lib -lssl -lcrypto' + \endcode + + To disable SSL support in a Qt build, configure Qt with the \c{-no-openssl} + option. + + \section1 Licensing Information + + \note Due to import and export restrictions in some parts of the world, we + are unable to supply the OpenSSL Toolkit with Qt packages. Developers wishing + to use SSL communication in their deployed applications should either ensure + that their users have the appropriate libraries installed, or they should + consult a suitably qualified legal professional to ensure that applications + using code from the OpenSSL project are correctly certified for import + and export in relevant regions of the world. + + When the QtNetwork module is built with SSL support, the library is linked + against OpenSSL in a way that requires OpenSSL license compliance. +*/ diff --git a/doc/src/objectmodel/metaobjects.qdoc b/doc/src/objectmodel/metaobjects.qdoc new file mode 100644 index 0000000000..099a6a9942 --- /dev/null +++ b/doc/src/objectmodel/metaobjects.qdoc @@ -0,0 +1,137 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page metaobjects.html + \title The Meta-Object System + \brief An overview of Qt's meta-object system and introspection capabilities. + + \ingroup qt-basic-concepts + \keyword meta-object + \target Meta-Object System + + Qt's meta-object system provides the signals and slots mechanism for + inter-object communication, run-time type information, and the dynamic + property system. + + The meta-object system is based on three things: + + \list 1 + \o The \l QObject class provides a base class for objects that can + take advantage of the meta-object system. + \o The Q_OBJECT macro inside the private section of the class + declaration is used to enable meta-object features, such as + dynamic properties, signals, and slots. + \o The \l{moc}{Meta-Object Compiler} (\c moc) supplies each + QObject subclass with the necessary code to implement + meta-object features. + \endlist + + The \c moc tool reads a C++ source file. If it finds one or more + class declarations that contain the Q_OBJECT macro, it + produces another C++ source file which contains the meta-object + code for each of those classes. This generated source file is + either \c{#include}'d into the class's source file or, more + usually, compiled and linked with the class's implementation. + + In addition to providing the \l{signals and slots} mechanism for + communication between objects (the main reason for introducing + the system), the meta-object code provides the following + additional features: + + \list + \o QObject::metaObject() returns the associated + \l{QMetaObject}{meta-object} for the class. + \o QMetaObject::className() returns the class name as a + string at run-time, without requiring native run-time type information + (RTTI) support through the C++ compiler. + \o QObject::inherits() function returns whether an object is an + instance of a class that inherits a specified class within the + QObject inheritance tree. + \o QObject::tr() and QObject::trUtf8() translate strings for + \l{Internationalization with Qt}{internationalization}. + \o QObject::setProperty() and QObject::property() + dynamically set and get properties by name. + \o QMetaObject::newInstance() constructs a new instance of the class. + \endlist + + \target qobjectcast + It is also possible to perform dynamic casts using qobject_cast() + on QObject classes. The qobject_cast() function behaves similarly + to the standard C++ \c dynamic_cast(), with the advantages + that it doesn't require RTTI support and it works across dynamic + library boundaries. It attempts to cast its argument to the pointer + type specified in angle-brackets, returning a non-zero pointer if the + object is of the correct type (determined at run-time), or 0 + if the object's type is incompatible. + + For example, let's assume \c MyWidget inherits from QWidget and + is declared with the Q_OBJECT macro: + + \snippet doc/src/snippets/qtcast/qtcast.cpp 0 + + The \c obj variable, of type \c{QObject *}, actually refers to a + \c MyWidget object, so we can cast it appropriately: + + \snippet doc/src/snippets/qtcast/qtcast.cpp 1 + + The cast from QObject to QWidget is successful, because the + object is actually a \c MyWidget, which is a subclass of QWidget. + Since we know that \c obj is a \c MyWidget, we can also cast it to + \c{MyWidget *}: + + \snippet doc/src/snippets/qtcast/qtcast.cpp 2 + + The cast to \c MyWidget is successful because qobject_cast() + makes no distinction between built-in Qt types and custom types. + + \snippet doc/src/snippets/qtcast/qtcast.cpp 3 + \snippet doc/src/snippets/qtcast/qtcast.cpp 4 + + The cast to QLabel, on the other hand, fails. The pointer is then + set to 0. This makes it possible to handle objects of different + types differently at run-time, based on the type: + + \snippet doc/src/snippets/qtcast/qtcast.cpp 5 + \snippet doc/src/snippets/qtcast/qtcast.cpp 6 + + While it is possible to use QObject as a base class without the + Q_OBJECT macro and without meta-object code, neither signals + and slots nor the other features described here will be available + if the Q_OBJECT macro is not used. From the meta-object + system's point of view, a QObject subclass without meta code is + equivalent to its closest ancestor with meta-object code. This + means for example, that QMetaObject::className() will not return + the actual name of your class, but the class name of this + ancestor. + + Therefore, we strongly recommend that all subclasses of QObject + use the Q_OBJECT macro regardless of whether or not they + actually use signals, slots, and properties. + + \sa QMetaObject, {Qt's Property System}, {Signals and Slots} +*/ diff --git a/doc/src/objectmodel/object.qdoc b/doc/src/objectmodel/object.qdoc new file mode 100644 index 0000000000..2112b10aa4 --- /dev/null +++ b/doc/src/objectmodel/object.qdoc @@ -0,0 +1,124 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page object.html + \title Object Model + \ingroup qt-basic-concepts + \brief A description of the powerful features made possible by Qt's dynamic object model. + + The standard C++ object model provides very efficient runtime + support for the object paradigm. But its static nature is + inflexibile in certain problem domains. Graphical user interface + programming is a domain that requires both runtime efficiency and + a high level of flexibility. Qt provides this, by combining the + speed of C++ with the flexibility of the Qt Object Model. + + Qt adds these features to C++: + + \list + \o a very powerful mechanism for seamless object + communication called \l{signals and slots} + \o queryable and designable \l{Qt's Property System}{object + properties} + \o powerful \l{The Event System}{events and event filters} + \o contextual \l{i18n}{string translation for internationalization} + \o sophisticated interval driven \l timers that make it possible + to elegantly integrate many tasks in an event-driven GUI + \o hierarchical and queryable \l{Object Trees & Ownership}{object + trees} that organize object ownership in a natural way + \o guarded pointers (QPointer) that are automatically + set to 0 when the referenced object is destroyed, unlike normal C++ + pointers which become dangling pointers when their objects are destroyed + \o a \l{metaobjects.html#qobjectcast}{dynamic cast} that works across + library boundaries. + \endlist + + Many of these Qt features are implemented with standard C++ + techniques, based on inheritance from QObject. Others, like the + object communication mechanism and the dynamic property system, + require the \l{Meta-Object System} provided + by Qt's own \l{moc}{Meta-Object Compiler (moc)}. + + The meta-object system is a C++ extension that makes the language + better suited to true component GUI programming. Although + templates can be used to extend C++, the meta-object system + provides benefits using standard C++ that cannot be achieved with + templates; see \l{Why Doesn't Qt Use Templates for Signals and + Slots?} + + \section1 Important Classes + + These classes form the basis of the Qt Object Model. + + \annotatedlist objectmodel + + \target Identity vs Value + \section1 Qt Objects: Identity vs Value + + Some of the added features listed above for the Qt Object Model, + require that we think of Qt Objects as identities, not values. + Values are copied or assigned; identities are cloned. Cloning + means to create a new identity, not an exact copy of the old + one. For example, twins have different identities. They may look + identical, but they have different names, different locations, and + may have completely different social networks. + + Then cloning an identity is a more complex operation than copying + or assigning a value. We can see what this means in the Qt Object + Model. + + \bold{A Qt Object...} + + \list + + \o might have a unique \l{QObject::objectName()}. If we copy a Qt + Object, what name should we give the copy? + + \o has a location in an \l{Object Trees & Ownership} + {object hierarchy}. If we copy a Qt Object, where should the copy + be located? + + \o can be connected to other Qt Objects to emit signals to them or + to receive signals emitted by them. If we copy a Qt Object, how + should we transfer these connections to the copy? + + \o can have \l{Qt's Property System} {new properties} added to it + at runtime that are not declared in the C++ class. If we copy a Qt + Object, should the copy include the properties that were added to + the original? + + \endlist + + For these reasons, Qt Objects should be treated as identities, not + as values. Identities are cloned, not copied or assigned, and + cloning an identity is a more complex operation than copying or + assigning a value. Therefore, QObject and all subclasses of + QObject (direct or indirect) have their \l{No copy constructor} + {copy constructor and assignment operator} disabled. + + */ diff --git a/doc/src/objectmodel/objecttrees.qdoc b/doc/src/objectmodel/objecttrees.qdoc new file mode 100644 index 0000000000..cb63c17ab1 --- /dev/null +++ b/doc/src/objectmodel/objecttrees.qdoc @@ -0,0 +1,102 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page objecttrees.html + \title Object Trees & Ownership + \ingroup qt-basic-concepts + \brief Information about the parent-child pattern used to describe + object ownership in Qt. + + \section1 Overview + + \link QObject QObjects\endlink organize themselves in object trees. + When you create a QObject with another object as parent, it's added to + the parent's \link QObject::children() children() \endlink list, and + is deleted when the parent is. It turns out that this approach fits + the needs of GUI objects very well. For example, a \l QShortcut + (keyboard shortcut) is a child of the relevant window, so when the + user closes that window, the shorcut is deleted too. + + \l QWidget, the base class of everything that appears on the screen, + extends the parent-child relationship. A child normally also becomes a + child widget, i.e. it is displayed in its parent's coordinate system + and is graphically clipped by its parent's boundaries. For example, + when the application deletes a message box after it has been + closed, the message box's buttons and label are also deleted, just as + we'd want, because the buttons and label are children of the message + box. + + You can also delete child objects yourself, and they will remove + themselves from their parents. For example, when the user removes a + toolbar it may lead to the application deleting one of its \l QToolBar + objects, in which case the tool bar's \l QMainWindow parent would + detect the change and reconfigure its screen space accordingly. + + The debugging functions \l QObject::dumpObjectTree() and \l + QObject::dumpObjectInfo() are often useful when an application looks or + acts strangely. + + \target note on the order of construction/destruction of QObjects + \section1 Construction/Destruction Order of QObjects + + When \l {QObject} {QObjects} are created on the heap (i.e., created + with \e new), a tree can be constructed from them in any order, and + later, the objects in the tree can be destroyed in any order. When any + QObject in the tree is deleted, if the object has a parent, the + destructor automatically removes the object from its parent. If the + object has children, the destructor automatically deletes each + child. No QObject is deleted twice, regardless of the order of + destruction. + + When \l {QObject} {QObjects} are created on the stack, the same + behavior applies. Normally, the order of destruction still doesn't + present a problem. Consider the following snippet: + + \snippet doc/src/snippets/code/doc_src_objecttrees.cpp 0 + + The parent, \c window, and the child, \c quit, are both \l {QObject} + {QObjects} because QPushButton inherits QWidget, and QWidget inherits + QObject. This code is correct: the destructor of \c quit is \e not + called twice because the C++ language standard \e {(ISO/IEC 14882:2003)} + specifies that destructors of local objects are called in the reverse + order of their constructors. Therefore, the destructor of + the child, \c quit, is called first, and it removes itself from its + parent, \c window, before the destructor of \c window is called. + + But now consider what happens if we swap the order of construction, as + shown in this second snippet: + + \snippet doc/src/snippets/code/doc_src_objecttrees.cpp 1 + + In this case, the order of destruction causes a problem. The parent's + destructor is called first because it was created last. It then calls + the destructor of its child, \c quit, which is incorrect because \c + quit is a local variable. When \c quit subsequently goes out of scope, + its destructor is called again, this time correctly, but the damage has + already been done. +*/ diff --git a/doc/src/objectmodel/properties.qdoc b/doc/src/objectmodel/properties.qdoc new file mode 100644 index 0000000000..92c182e0b9 --- /dev/null +++ b/doc/src/objectmodel/properties.qdoc @@ -0,0 +1,273 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page properties.html + \title The Property System + \brief An overview of Qt's property system. + + \ingroup qt-basic-concepts + \target Qt's Property System + + Qt provides a sophisticated property system similar to the ones + supplied by some compiler vendors. However, as a compiler- and + platform-independent library, Qt does not rely on non-standard + compiler features like \c __property or \c [property]. The Qt + solution works with \e any standard C++ compiler on every platform + Qt supports. It is based on the \l {Meta-Object System} that also + provides inter-object communication via \l{signals and slots}. + + \section1 Requirements for Declaring Properties + + To declare a property, use the \l {Q_PROPERTY()} {Q_PROPERTY()} + macro in a class that inherits QObject. + + \snippet doc/src/snippets/code/doc_src_properties.cpp 0 + + Here are some typical examples of property declarations taken from + class QWidget. + + \snippet doc/src/snippets/code/doc_src_properties.cpp 1 + + A property behaves like a class data member, but it has additional + features accessible through the \l {Meta-Object System}. + + \list + + \o A \c READ accessor function is required. It is for reading the + property value. Ideally, a const function is used for this purpose, + and it must return either the property's type or a pointer or + reference to that type. e.g., QWidget::focus is a read-only property + with \c READ function, QWidget::hasFocus(). + + \o A \c WRITE accessor function is optional. It is for setting the + property value. It must return void and must take exactly one + argument, either of the property's type or a pointer or reference + to that type. e.g., QWidget::enabled has the \c WRITE function + QWidget::setEnabled(). Read-only properties do not need \c WRITE + functions. e.g., QWidget::focus has no \c WRITE function. + + \o A \c RESET function is optional. It is for setting the property + back to its context specific default value. e.g., QWidget::cursor + has the typical \c READ and \c WRITE functions, QWidget::cursor() + and QWidget::setCursor(), and it also has a \c RESET function, + QWidget::unsetCursor(), since no call to QWidget::setCursor() can + mean \e {reset to the context specific cursor}. The \c RESET + function must return void and take no parameters. + + \o A \c NOTIFY signal is optional. If defined, it should specify one + existing signal in that class that is emitted whenever the value + of the property changes. + + \o A \c REVISION number is optional. If included, it defines the + the property and its notifier signal to be used in a particular + revision of the API that is exposed to QML. + + \o The \c DESIGNABLE attribute indicates whether the property + should be visible in the property editor of GUI design tool (e.g., + \l {Qt Designer}). Most properties are \c DESIGNABLE (default + true). Instead of true or false, you can specify a boolean + member function. + + \o The \c SCRIPTABLE attribute indicates whether this property + should be accessible by a scripting engine (default true). + Instead of true or false, you can specify a boolean member + function. + + \o The \c STORED attribute indicates whether the property should + be thought of as existing on its own or as depending on other + values. It also indicates whether the property value must be saved + when storing the object's state. Most properties are \c STORED + (default true), but e.g., QWidget::minimumWidth() has \c STORED + false, because its value is just taken from the width component + of property QWidget::minimumSize(), which is a QSize. + + \o The \c USER attribute indicates whether the property is + designated as the user-facing or user-editable property for the + class. Normally, there is only one \c USER property per class + (default false). e.g., QAbstractButton::checked is the user + editable property for (checkable) buttons. Note that QItemDelegate + gets and sets a widget's \c USER property. + + \o The presence of the \c CONSTANT attibute indicates that the property + value is constant. For a given object instance, the READ method of a + constant property must return the same value every time it is called. This + constant value may be different for different instances of the object. A + constant property cannot have a WRITE method or a NOTIFY signal. + + \o The presence of the \c FINAL attribute indicates that the property + will not be overridden by a derived class. This can be used for performance + optimizations in some cases, but is not enforced by moc. Care must be taken + never to override a \c FINAL property. + + \endlist + + The \c READ, \c WRITE, and \c RESET functions can be inherited. + They can also be virtual. When they are inherited in classes where + multiple inheritance is used, they must come from the first + inherited class. + + The property type can be any type supported by QVariant, or it can + be a user-defined type. In this example, class QDate is considered + to be a user-defined type. + + \snippet doc/src/snippets/code/doc_src_properties.cpp 2 + + Because QDate is user-defined, you must include the \c{<QDate>} + header file with the property declaration. + + For QMap, QList, and QValueList properties, the property value is + a QVariant whose value is the entire list or map. Note that the + Q_PROPERTY string cannot contain commas, because commas separate + macro arguments. Therefore, you must use \c QMap as the property + type instead of \c QMap<QString,QVariant>. For consistency, also + use \c QList and \c QValueList instead of \c QList<QVariant> and + \c QValueList<QVariant>. + + \section1 Reading and Writing Properties with the Meta-Object System + + A property can be read and written using the generic functions + QObject::property() and QObject::setProperty(), without knowing + anything about the owning class except the property's name. In + the code snippet below, the call to QAbstractButton::setDown() and + the call to QObject::setProperty() both set property "down". + + \snippet doc/src/snippets/code/doc_src_properties.cpp 3 + + Accessing a property through its \c WRITE accessor is the better + of the two, because it is faster and gives better diagnostics at + compile time, but setting the property this way requires that you + know about the class at compile time. Accessing properties by name + lets you access classes you don't know about at compile time. You + can \e discover a class's properties at run time by querying its + QObject, QMetaObject, and \l {QMetaProperty} {QMetaProperties}. + + \snippet doc/src/snippets/code/doc_src_properties.cpp 4 + + In the above snippet, QMetaObject::property() is used to get \l + {QMetaProperty} {metadata} about each property defined in some + unknown class. The property name is fetched from the metadata and + passed to QObject::property() to get the \l {QVariant} {value} of + the property in the current \l {QObject}{object}. + + \section1 A Simple Example + + Suppose we have a class MyClass, which is derived from QObject and + which uses the Q_OBJECT macro in its private section. We want to + declare a property in MyClass to keep track of a priorty + value. The name of the property will be \e priority, and its type + will be an enumeration type named \e Priority, which is defined in + MyClass. + + We declare the property with the Q_PROPERTY() macro in the private + section of the class. The required \c READ function is named \c + priority, and we include a \c WRITE function named \c setPriority. + The enumeration type must be registered with the \l {Meta-Object + System} using the Q_ENUMS() macro. Registering an enumeration type + makes the enumerator names available for use in calls to + QObject::setProperty(). We must also provide our own declarations + for the \c READ and \c WRITE functions. The declaration of MyClass + then might look like this: + + \snippet doc/src/snippets/code/doc_src_properties.cpp 5 + + The \c READ function is const and returns the property type. The + \c WRITE function returns void and has exactly one parameter of + the property type. The meta-object compiler enforces these + requirements. + + Given a pointer to an instance of MyClass or a pointer to a + QObject that is an instance of MyClass, we have two ways to set + its priority property: + + \snippet doc/src/snippets/code/doc_src_properties.cpp 6 + + In the example, the enumeration type that is the property type is + declared in MyClass and registered with the \l{Meta-Object System} + using the Q_ENUMS() macro. This makes the enumeration values + available as strings for use as in the call to setProperty(). Had + the enumeration type been declared in another class, its fully + qualified name (i.e., OtherClass::Priority) would be required, and + that other class would also have to inherit QObject and register + the enumeration type there using the Q_ENUMS() macro. + + A similar macro, Q_FLAGS(), is also available. Like Q_ENUMS(), it + registers an enumeration type, but it marks the type as being a + set of \e flags, i.e. values that can be OR'd together. An I/O + class might have enumeration values \c Read and \c Write and then + QObject::setProperty() could accept \c{Read | Write}. Q_FLAGS() + should be used to register this enumeration type. + + \section1 Dynamic Properties + + QObject::setProperty() can also be used to add \e new properties + to an instance of a class at runtime. When it is called with a + name and a value, if a property with the given name exists in the + QObject, and if the given value is compatible with the property's + type, the value is stored in the property, and true is returned. + If the value is \e not compatible with the property's type, the + property is \e not changed, and false is returned. But if the + property with the given name doesn't exist in the QObject (i.e., + if it wasn't declared with Q_PROPERTY(), a new property with the + given name and value is automatically added to the QObject, but + false is still returned. This means that a return of false can't + be used to determine whether a particular property was actually + set, unless you know in advance that the property already exists + in the QObject. + + Note that \e dynamic properties are added on a per instance basis, + i.e., they are added to QObject, not QMetaObject. A property can + be removed from an instance by passing the property name and an + invalid QVariant value to QObject::setProperty(). The default + constructor for QVariant constructs an invalid QVariant. + + Dynamic properties can be queried with QObject::property(), just + like properties declared at compile time with Q_PROPERTY(). + + \sa {Meta-Object System}, {Signals and Slots} + + \section1 Properties and Custom Types + + Custom types used by properties need to be registered using the + Q_DECLARE_METATYPE() macro so that their values can be stored in + QVariant objects. This makes them suitable for use with both + static properties declared using the Q_PROPERTY() macro in class + definitions and dynamic properties created at run-time. + + \sa Q_DECLARE_METATYPE(), QMetaType, QVariant + + \section1 Adding Additional Information to a Class + + Connected to the property system is an additional macro, + Q_CLASSINFO(), that can be used to attach additional + \e{name}--\e{value} pairs to a class's meta-object, for example: + + \snippet doc/src/snippets/code/doc_src_properties.cpp 7 + + Like other meta-data, class information is accessible at run-time + through the meta-object; see QMetaObject::classInfo() for details. +*/ diff --git a/doc/src/objectmodel/signalsandslots.qdoc b/doc/src/objectmodel/signalsandslots.qdoc new file mode 100644 index 0000000000..8b52df5b1a --- /dev/null +++ b/doc/src/objectmodel/signalsandslots.qdoc @@ -0,0 +1,451 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page signalsandslots.html + \title Signals & Slots + \ingroup qt-basic-concepts + \brief An overview of Qt's signals and slots inter-object + communication mechanism. + + Signals and slots are used for communication between objects. The + signals and slots mechanism is a central feature of Qt and + probably the part that differs most from the features provided by + other frameworks. + + \tableofcontents + + \section1 Introduction + + In GUI programming, when we change one widget, we often want + another widget to be notified. More generally, we want objects of + any kind to be able to communicate with one another. For example, + if a user clicks a \gui{Close} button, we probably want the + window's \l{QWidget::close()}{close()} function to be called. + + Older toolkits achieve this kind of communication using + callbacks. A callback is a pointer to a function, so if you want + a processing function to notify you about some event you pass a + pointer to another function (the callback) to the processing + function. The processing function then calls the callback when + appropriate. Callbacks have two fundamental flaws: Firstly, they + are not type-safe. We can never be certain that the processing + function will call the callback with the correct arguments. + Secondly, the callback is strongly coupled to the processing + function since the processing function must know which callback + to call. + + \section1 Signals and Slots + + In Qt, we have an alternative to the callback technique: We use + signals and slots. A signal is emitted when a particular event + occurs. Qt's widgets have many predefined signals, but we can + always subclass widgets to add our own signals to them. A slot + is a function that is called in response to a particular signal. + Qt's widgets have many pre-defined slots, but it is common + practice to subclass widgets and add your own slots so that you + can handle the signals that you are interested in. + + \img abstract-connections.png + \omit + \caption An abstract view of some signals and slots connections + \endomit + + The signals and slots mechanism is type safe: The signature of a + signal must match the signature of the receiving slot. (In fact a + slot may have a shorter signature than the signal it receives + because it can ignore extra arguments.) Since the signatures are + compatible, the compiler can help us detect type mismatches. + Signals and slots are loosely coupled: A class which emits a + signal neither knows nor cares which slots receive the signal. + Qt's signals and slots mechanism ensures that if you connect a + signal to a slot, the slot will be called with the signal's + parameters at the right time. Signals and slots can take any + number of arguments of any type. They are completely type safe. + + All classes that inherit from QObject or one of its subclasses + (e.g., QWidget) can contain signals and slots. Signals are emitted by + objects when they change their state in a way that may be interesting + to other objects. This is all the object does to communicate. It + does not know or care whether anything is receiving the signals it + emits. This is true information encapsulation, and ensures that the + object can be used as a software component. + + Slots can be used for receiving signals, but they are also normal + member functions. Just as an object does not know if anything receives + its signals, a slot does not know if it has any signals connected to + it. This ensures that truly independent components can be created with + Qt. + + You can connect as many signals as you want to a single slot, and a + signal can be connected to as many slots as you need. It is even + possible to connect a signal directly to another signal. (This will + emit the second signal immediately whenever the first is emitted.) + + Together, signals and slots make up a powerful component programming + mechanism. + + \section1 A Small Example + + A minimal C++ class declaration might read: + + \snippet doc/src/snippets/signalsandslots/signalsandslots.h 0 + + A small QObject-based class might read: + + \snippet doc/src/snippets/signalsandslots/signalsandslots.h 1 + \codeline + \snippet doc/src/snippets/signalsandslots/signalsandslots.h 2 + \snippet doc/src/snippets/signalsandslots/signalsandslots.h 3 + + The QObject-based version has the same internal state, and provides + public methods to access the state, but in addition it has support + for component programming using signals and slots. This class can + tell the outside world that its state has changed by emitting a + signal, \c{valueChanged()}, and it has a slot which other objects + can send signals to. + + All classes that contain signals or slots must mention + Q_OBJECT at the top of their declaration. They must also derive + (directly or indirectly) from QObject. + + Slots are implemented by the application programmer. + Here is a possible implementation of the \c{Counter::setValue()} + slot: + + \snippet doc/src/snippets/signalsandslots/signalsandslots.cpp 0 + + The \c{emit} line emits the signal \c valueChanged() from the + object, with the new value as argument. + + In the following code snippet, we create two \c Counter objects + and connect the first object's \c valueChanged() signal to the + second object's \c setValue() slot using QObject::connect(): + + \snippet doc/src/snippets/signalsandslots/signalsandslots.cpp 1 + \snippet doc/src/snippets/signalsandslots/signalsandslots.cpp 2 + \codeline + \snippet doc/src/snippets/signalsandslots/signalsandslots.cpp 3 + \snippet doc/src/snippets/signalsandslots/signalsandslots.cpp 4 + + Calling \c{a.setValue(12)} makes \c{a} emit a + \c{valueChanged(12)} signal, which \c{b} will receive in its + \c{setValue()} slot, i.e. \c{b.setValue(12)} is called. Then + \c{b} emits the same \c{valueChanged()} signal, but since no slot + has been connected to \c{b}'s \c{valueChanged()} signal, the + signal is ignored. + + Note that the \c{setValue()} function sets the value and emits + the signal only if \c{value != m_value}. This prevents infinite + looping in the case of cyclic connections (e.g., if + \c{b.valueChanged()} were connected to \c{a.setValue()}). + + By default, for every connection you make, a signal is emitted; + two signals are emitted for duplicate connections. You can break + all of these connections with a single disconnect() call. + If you pass the Qt::UniqueConnection \a type, the connection will only + be made if it is not a duplicate. If there is already a duplicate + (exact same signal to the exact same slot on the same objects), + the connection will fail and connect will return false + + This example illustrates that objects can work together without needing to + know any information about each other. To enable this, the objects only + need to be connected together, and this can be achieved with some simple + QObject::connect() function calls, or with \c{uic}'s + \l{Using a Designer UI File in Your Application#Automatic Connections} + {automatic connections} feature. + + \section1 Building the Example + + The C++ preprocessor changes or removes the \c{signals}, + \c{slots}, and \c{emit} keywords so that the compiler is + presented with standard C++. + + By running the \l moc on class definitions that contain signals + or slots, a C++ source file is produced which should be compiled + and linked with the other object files for the application. If + you use \l qmake, the makefile rules to automatically invoke \c + moc will be added to your project's makefile. + + \section1 Signals + + Signals are emitted by an object when its internal state has changed + in some way that might be interesting to the object's client or owner. + Only the class that defines a signal and its subclasses can emit the + signal. + + When a signal is emitted, the slots connected to it are usually + executed immediately, just like a normal function call. When this + happens, the signals and slots mechanism is totally independent of + any GUI event loop. Execution of the code following the \c emit + statement will occur once all slots have returned. The situation is + slightly different when using \l{Qt::ConnectionType}{queued + connections}; in such a case, the code following the \c emit keyword + will continue immediately, and the slots will be executed later. + + If several slots are connected to one signal, the slots will be + executed one after the other, in the order they have been connected, + when the signal is emitted. + + Signals are automatically generated by the \l moc and must not be + implemented in the \c .cpp file. They can never have return types + (i.e. use \c void). + + A note about arguments: Our experience shows that signals and slots + are more reusable if they do not use special types. If + QScrollBar::valueChanged() were to use a special type such as the + hypothetical QScrollBar::Range, it could only be connected to + slots designed specifically for QScrollBar. Connecting different + input widgets together would be impossible. + + \section1 Slots + + A slot is called when a signal connected to it is emitted. Slots are + normal C++ functions and can be called normally; their only special + feature is that signals can be connected to them. + + Since slots are normal member functions, they follow the normal C++ + rules when called directly. However, as slots, they can be invoked + by any component, regardless of its access level, via a signal-slot + connection. This means that a signal emitted from an instance of an + arbitrary class can cause a private slot to be invoked in an instance + of an unrelated class. + + You can also define slots to be virtual, which we have found quite + useful in practice. + + Compared to callbacks, signals and slots are slightly slower + because of the increased flexibility they provide, although the + difference for real applications is insignificant. In general, + emitting a signal that is connected to some slots, is + approximately ten times slower than calling the receivers + directly, with non-virtual function calls. This is the overhead + required to locate the connection object, to safely iterate over + all connections (i.e. checking that subsequent receivers have not + been destroyed during the emission), and to marshall any + parameters in a generic fashion. While ten non-virtual function + calls may sound like a lot, it's much less overhead than any \c + new or \c delete operation, for example. As soon as you perform a + string, vector or list operation that behind the scene requires + \c new or \c delete, the signals and slots overhead is only + responsible for a very small proportion of the complete function + call costs. + + The same is true whenever you do a system call in a slot; or + indirectly call more than ten functions. On an i586-500, you can + emit around 2,000,000 signals per second connected to one + receiver, or around 1,200,000 per second connected to two + receivers. The simplicity and flexibility of the signals and + slots mechanism is well worth the overhead, which your users + won't even notice. + + Note that other libraries that define variables called \c signals + or \c slots may cause compiler warnings and errors when compiled + alongside a Qt-based application. To solve this problem, \c + #undef the offending preprocessor symbol. + + \section1 Meta-Object Information + + The meta-object compiler (\l moc) parses the class declaration in + a C++ file and generates C++ code that initializes the + meta-object. The meta-object contains the names of all the signal + and slot members, as well as pointers to these functions. + + The meta-object contains additional information such as the + object's \link QObject::className() class name\endlink. You can + also check if an object \link QObject::inherits() + inherits\endlink a specific class, for example: + + \snippet doc/src/snippets/signalsandslots/signalsandslots.cpp 5 + \snippet doc/src/snippets/signalsandslots/signalsandslots.cpp 6 + + The meta-object information is also used by qobject_cast<T>(), which + is similar to QObject::inherits() but is less error-prone: + + \snippet doc/src/snippets/signalsandslots/signalsandslots.cpp 7 + + See \l{Meta-Object System} for more information. + + \section1 A Real Example + + Here is a simple commented example of a widget. + + \snippet doc/src/snippets/signalsandslots/lcdnumber.h 0 + \snippet doc/src/snippets/signalsandslots/lcdnumber.h 1 + \codeline + \snippet doc/src/snippets/signalsandslots/lcdnumber.h 2 + \codeline + \snippet doc/src/snippets/signalsandslots/lcdnumber.h 3 + \snippet doc/src/snippets/signalsandslots/lcdnumber.h 4 + \snippet doc/src/snippets/signalsandslots/lcdnumber.h 5 + + \c LcdNumber inherits QObject, which has most of the signal-slot + knowledge, via QFrame and QWidget. It is somewhat similar to the + built-in QLCDNumber widget. + + The Q_OBJECT macro is expanded by the preprocessor to declare + several member functions that are implemented by the \c{moc}; if + you get compiler errors along the lines of "undefined reference + to vtable for \c{LcdNumber}", you have probably forgotten to + \l{moc}{run the moc} or to include the moc output in the link + command. + + \snippet doc/src/snippets/signalsandslots/lcdnumber.h 6 + \snippet doc/src/snippets/signalsandslots/lcdnumber.h 7 + + It's not obviously relevant to the moc, but if you inherit + QWidget you almost certainly want to have the \c parent argument + in your constructor and pass it to the base class's constructor. + + Some destructors and member functions are omitted here; the \c + moc ignores member functions. + + \snippet doc/src/snippets/signalsandslots/lcdnumber.h 8 + \snippet doc/src/snippets/signalsandslots/lcdnumber.h 9 + + \c LcdNumber emits a signal when it is asked to show an impossible + value. + + If you don't care about overflow, or you know that overflow + cannot occur, you can ignore the \c overflow() signal, i.e. don't + connect it to any slot. + + If on the other hand you want to call two different error + functions when the number overflows, simply connect the signal to + two different slots. Qt will call both (in the order they were connected). + + \snippet doc/src/snippets/signalsandslots/lcdnumber.h 10 + \snippet doc/src/snippets/signalsandslots/lcdnumber.h 11 + \snippet doc/src/snippets/signalsandslots/lcdnumber.h 12 + \codeline + \snippet doc/src/snippets/signalsandslots/lcdnumber.h 13 + + A slot is a receiving function used to get information about + state changes in other widgets. \c LcdNumber uses it, as the code + above indicates, to set the displayed number. Since \c{display()} + is part of the class's interface with the rest of the program, + the slot is public. + + Several of the example programs connect the + \l{QScrollBar::valueChanged()}{valueChanged()} signal of a + QScrollBar to the \c display() slot, so the LCD number + continuously shows the value of the scroll bar. + + Note that \c display() is overloaded; Qt will select the + appropriate version when you connect a signal to the slot. With + callbacks, you'd have to find five different names and keep track + of the types yourself. + + Some irrelevant member functions have been omitted from this + example. + + \section1 Signals And Slots With Default Arguments + + The signatures of signals and slots may contain arguments, and the + arguments can have default values. Consider QObject::destroyed(): + + \code + void destroyed(QObject* = 0); + \endcode + + When a QObject is deleted, it emits this QObject::destroyed() + signal. We want to catch this signal, wherever we might have a + dangling reference to the deleted QObject, so we can clean it up. + A suitable slot signature might be: + + \code + void objectDestroyed(QObject* obj = 0); + \endcode + + To connect the signal to the slot, we use QObject::connect() and + the \c{SIGNAL()} and \c{SLOT()} macros. The rule about whether to + include arguments or not in the \c{SIGNAL()} and \c{SLOT()} + macros, if the arguments have default values, is that the + signature passed to the \c{SIGNAL()} macro must \e not have fewer + arguments than the signature passed to the \c{SLOT()} macro. + + All of these would work: + \code + connect(sender, SIGNAL(destroyed(QObject*)), this, SLOT(objectDestroyed(Qbject*))); + connect(sender, SIGNAL(destroyed(QObject*)), this, SLOT(objectDestroyed())); + connect(sender, SIGNAL(destroyed()), this, SLOT(objectDestroyed())); + \endcode + But this one won't work: + \code + connect(sender, SIGNAL(destroyed()), this, SLOT(objectDestroyed(QObject*))); + \endcode + + ...because the slot will be expecting a QObject that the signal + will not send. This connection will report a runtime error. + + \section1 Advanced Signals and Slots Usage + + For cases where you may require information on the sender of the + signal, Qt provides the QObject::sender() function, which returns + a pointer to the object that sent the signal. + + The QSignalMapper class is provided for situations where many + signals are connected to the same slot and the slot needs to + handle each signal differently. + + Suppose you have three push buttons that determine which file you + will open: "Tax File", "Accounts File", or "Report File". + + In order to open the correct file, you use QSignalMapper::setMapping() to + map all the clicked() signals to a QSignalMapper object. Then you connect + the file's QPushButton::clicked() signal to the QSignalMapper::map() slot. + + \snippet doc/src/snippets/signalmapper/filereader.cpp 0 + + Then, you connect the \l{QSignalMapper::}{mapped()} signal to + \c{readFile()} where a different file will be opened, depending on + which push button is pressed. + + \snippet doc/src/snippets/signalmapper/filereader.cpp 1 + + \note The following code will compile and run, but due to signature normalization, the code will be slower. + + \snippet doc/src/snippets/signalmapper/filereader.cpp 2 + + \sa {Meta-Object System}, {Qt's Property System} + + \target 3rd Party Signals and Slots + \section2 Using Qt with 3rd Party Signals and Slots + + It is possible to use Qt with a 3rd party signal/slot mechanism. + You can even use both mechanisms in the same project. Just add the + following line to your qmake project (.pro) file. + + \snippet doc/src/snippets/code/doc_src_containers.cpp 22 + + It tells Qt not to define the moc keywords \c{signals}, \c{slots}, + and \c{emit}, because these names will be used by a 3rd party + library, e.g. Boost. Then to continue using Qt signals and slots + with the \c{no_keywords} flag, simply replace all uses of the Qt + moc keywords in your sources with the corresponding Qt macros + Q_SIGNALS (or Q_SIGNAL), Q_SLOTS (or Q_SLOT), and Q_EMIT. +*/ diff --git a/doc/src/painting-and-printing/coordsys.qdoc b/doc/src/painting-and-printing/coordsys.qdoc new file mode 100644 index 0000000000..d0906d82a1 --- /dev/null +++ b/doc/src/painting-and-printing/coordsys.qdoc @@ -0,0 +1,461 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page coordsys.html + \title Coordinate System + \ingroup qt-graphics + \ingroup best-practices + \brief Information about the coordinate system used by the paint + system. + + The coordinate system is controlled by the QPainter + class. Together with the QPaintDevice and QPaintEngine classes, + QPainter form the basis of Qt's painting system, Arthur. QPainter + is used to perform drawing operations, QPaintDevice is an + abstraction of a two-dimensional space that can be painted on + using a QPainter, and QPaintEngine provides the interface that the + painter uses to draw onto different types of devices. + + The QPaintDevice class is the base class of objects that can be + painted: Its drawing capabilities are inherited by the QWidget, + QPixmap, QPicture, QImage, and QPrinter classes. The default + coordinate system of a paint device has its origin at the top-left + corner. The \e x values increase to the right and the \e y values + increase downwards. The default unit is one pixel on pixel-based + devices and one point (1/72 of an inch) on printers. + + The mapping of the logical QPainter coordinates to the physical + QPaintDevice coordinates are handled by QPainter's transformation + matrix, viewport and "window". The logical and physical coordinate + systems coincide by default. QPainter also supports coordinate + transformations (e.g. rotation and scaling). + + \tableofcontents + + \section1 Rendering + + \section2 Logical Representation + + The size (width and height) of a graphics primitive always + correspond to its mathematical model, ignoring the width of the + pen it is rendered with: + + \table + \row + \o \inlineimage coordinatesystem-rect.png + \o \inlineimage coordinatesystem-line.png + \row + \o QRect(1, 2, 6, 4) + \o QLine(2, 7, 6, 1) + \endtable + + \section2 Aliased Painting + + When drawing, the pixel rendering is controlled by the + QPainter::Antialiasing render hint. + + The \l {QPainter::RenderHint}{RenderHint} enum is used to specify + flags to QPainter that may or may not be respected by any given + engine. The QPainter::Antialiasing value indicates that the engine + should antialias edges of primitives if possible, i.e. smoothing + the edges by using different color intensities. + + But by default the painter is \e aliased and other rules apply: + When rendering with a one pixel wide pen the pixels will be + rendered to the \e {right and below the mathematically defined + points}. For example: + + \table + \row + \o \inlineimage coordinatesystem-rect-raster.png + \o \inlineimage coordinatesystem-line-raster.png + + \row + \o + \snippet doc/src/snippets/code/doc_src_coordsys.cpp 0 + + \o + \snippet doc/src/snippets/code/doc_src_coordsys.cpp 1 + \endtable + + When rendering with a pen with an even number of pixels, the + pixels will be rendered symetrically around the mathematical + defined points, while rendering with a pen with an odd number of + pixels, the spare pixel will be rendered to the right and below + the mathematical point as in the one pixel case. See the QRectF + diagrams below for concrete examples. + + \table + \header + \o {3,1} QRectF + \row + \o \inlineimage qrect-diagram-zero.png + \o \inlineimage qrectf-diagram-one.png + \row + \o Logical representation + \o One pixel wide pen + \row + \o \inlineimage qrectf-diagram-two.png + \o \inlineimage qrectf-diagram-three.png + \row + \o Two pixel wide pen + \o Three pixel wide pen + \endtable + + Note that for historical reasons the return value of the + QRect::right() and QRect::bottom() functions deviate from the true + bottom-right corner of the rectangle. + + QRect's \l {QRect::right()}{right()} function returns \l + {QRect::left()}{left()} + \l {QRect::width()}{width()} - 1 and the + \l {QRect::bottom()}{bottom()} function returns \l + {QRect::top()}{top()} + \l {QRect::height()}{height()} - 1. The + bottom-right green point in the diagrams shows the return + coordinates of these functions. + + We recommend that you simply use QRectF instead: The QRectF class + defines a rectangle in the plane using floating point coordinates + for accuracy (QRect uses integer coordinates), and the + QRectF::right() and QRectF::bottom() functions \e do return the + true bottom-right corner. + + Alternatively, using QRect, apply \l {QRect::x()}{x()} + \l + {QRect::width()}{width()} and \l {QRect::y()}{y()} + \l + {QRect::height()}{height()} to find the bottom-right corner, and + avoid the \l {QRect::right()}{right()} and \l + {QRect::bottom()}{bottom()} functions. + + \section2 Anti-aliased Painting + + If you set QPainter's \l {QPainter::Antialiasing}{anti-aliasing} + render hint, the pixels will be rendered symetrically on both + sides of the mathematically defined points: + + \table + \row + \o \inlineimage coordinatesystem-rect-antialias.png + \o \inlineimage coordinatesystem-line-antialias.png + \row + \o + + \snippet doc/src/snippets/code/doc_src_coordsys.cpp 2 + + \o + \snippet doc/src/snippets/code/doc_src_coordsys.cpp 3 + \endtable + + \section1 Transformations + + By default, the QPainter operates on the associated device's own + coordinate system, but it also has complete support for affine + coordinate transformations. + + You can scale the coordinate system by a given offset using the + QPainter::scale() function, you can rotate it clockwise using the + QPainter::rotate() function and you can translate it (i.e. adding + a given offset to the points) using the QPainter::translate() + function. + + \table + \row + \o \inlineimage qpainter-clock.png + \o \inlineimage qpainter-rotation.png + \o \inlineimage qpainter-scale.png + \o \inlineimage qpainter-translation.png + \row + \o nop + \o \l {QPainter::rotate()}{rotate()} + \o \l {QPainter::scale()}{scale()} + \o \l {QPainter::translate()}{translate()} + \endtable + + You can also twist the coordinate system around the origin using + the QPainter::shear() function. See the \l {demos/affine}{Affine + Transformations} demo for a visualization of a sheared coordinate + system. All the transformation operations operate on QPainter's + transformation matrix that you can retrieve using the + QPainter::worldTransform() function. A matrix transforms a point + in the plane to another point. + + If you need the same transformations over and over, you can also + use QTransform objects and the QPainter::worldTransform() and + QPainter::setWorldTransform() functions. You can at any time save the + QPainter's transformation matrix by calling the QPainter::save() + function which saves the matrix on an internal stack. The + QPainter::restore() function pops it back. + + One frequent need for the transformation matrix is when reusing + the same drawing code on a variety of paint devices. Without + transformations, the results are tightly bound to the resolution + of the paint device. Printers have high resolution, e.g. 600 dots + per inch, whereas screens often have between 72 and 100 dots per + inch. + + \table 100% + \header + \o {2,1} Analog Clock Example + \row + \o \inlineimage coordinatesystem-analogclock.png + \o + The Analog Clock example shows how to draw the contents of a + custom widget using QPainter's transformation matrix. + + Qt's example directory provides a complete walk-through of the + example. Here, we will only review the example's \l + {QWidget::paintEvent()}{paintEvent()} function to see how we can + use the transformation matrix (i.e. QPainter's matrix functions) + to draw the clock's face. + + We recommend compiling and running this example before you read + any further. In particular, try resizing the window to different + sizes. + + \row + \o {2,1} + + \snippet examples/widgets/analogclock/analogclock.cpp 9 + + First, we set up the painter. We translate the coordinate system + so that point (0, 0) is in the widget's center, instead of being + at the top-left corner. We also scale the system by \c side / 100, + where \c side is either the widget's width or the height, + whichever is shortest. We want the clock to be square, even if the + device isn't. + + This will give us a 200 x 200 square area, with the origin (0, 0) + in the center, that we can draw on. What we draw will show up in + the largest possible square that will fit in the widget. + + See also the \l {Window-Viewport Conversion} section. + + \snippet examples/widgets/analogclock/analogclock.cpp 18 + + We draw the clock's hour hand by rotating the coordinate system + and calling QPainter::drawConvexPolygon(). Thank's to the + rotation, it's drawn pointed in the right direction. + + The polygon is specified as an array of alternating \e x, \e y + values, stored in the \c hourHand static variable (defined at the + beginning of the function), which corresponds to the four points + (2, 0), (0, 2), (-2, 0), and (0, -25). + + The calls to QPainter::save() and QPainter::restore() surrounding + the code guarantees that the code that follows won't be disturbed + by the transformations we've used. + + \snippet examples/widgets/analogclock/analogclock.cpp 24 + + We do the same for the clock's minute hand, which is defined by + the four points (1, 0), (0, 1), (-1, 0), and (0, -40). These + coordinates specify a hand that is thinner and longer than the + minute hand. + + \snippet examples/widgets/analogclock/analogclock.cpp 27 + + Finally, we draw the clock face, which consists of twelve short + lines at 30-degree intervals. At the end of that, the painter is + rotated in a way which isn't very useful, but we're done with + painting so that doesn't matter. + \endtable + + For a demonstation of Qt's ability to perform affine + transformations on painting operations, see the \l + {demos/affine}{Affine Transformations} demo which allows the user + to experiment with the transformation operations. See also the \l + {painting/transformations}{Transformations} example which shows + how transformations influence the way that QPainter renders + graphics primitives. In particular, it shows how the order of + transformations affects the result. + + For more information about the transformation matrix, see the + QTransform documentation. + + \section1 Window-Viewport Conversion + + When drawing with QPainter, we specify points using logical + coordinates which then are converted into the physical coordinates + of the paint device. + + The mapping of the logical coordinates to the physical coordinates + are handled by QPainter's world transformation \l + {QPainter::worldTransform()}{worldTransform()} (described in the \l + Transformations section), and QPainter's \l + {QPainter::viewport()}{viewport()} and \l + {QPainter::window()}{window()}. The viewport represents the + physical coordinates specifying an arbitrary rectangle. The + "window" describes the same rectangle in logical coordinates. By + default the logical and physical coordinate systems coincide, and + are equivalent to the paint device's rectangle. + + Using window-viewport conversion you can make the logical + coordinate system fit your preferences. The mechanism can also be + used to make the drawing code independent of the paint device. You + can, for example, make the logical coordinates extend from (-50, + -50) to (50, 50) with (0, 0) in the center by calling the + QPainter::setWindow() function: + + \snippet doc/src/snippets/code/doc_src_coordsys.cpp 4 + + Now, the logical coordinates (-50,-50) correspond to the paint + device's physical coordinates (0, 0). Independent of the paint + device, your painting code will always operate on the specified + logical coordinates. + + By setting the "window" or viewport rectangle, you perform a + linear transformation of the coordinates. Note that each corner of + the "window" maps to the corresponding corner of the viewport, and + vice versa. For that reason it normally is a good idea to let the + viewport and "window" maintain the same aspect ratio to prevent + deformation: + + \snippet doc/src/snippets/code/doc_src_coordsys.cpp 5 + + If we make the logical coordinate system a square, we should also + make the viewport a square using the QPainter::setViewport() + function. In the example above we make it equivalent to the + largest square that fit into the paint device's rectangle. By + taking the paint device's size into consideration when setting the + window or viewport, it is possible to keep the drawing code + independent of the paint device. + + Note that the window-viewport conversion is only a linear + transformation, i.e. it does not perform clipping. This means that + if you paint outside the currently set "window", your painting is + still transformed to the viewport using the same linear algebraic + approach. + + \image coordinatesystem-transformations.png + + The viewport, "window" and transformation matrix determine how + logical QPainter coordinates map to the paint device's physical + coordinates. By default the world transformation matrix is the + identity matrix, and the "window" and viewport settings are + equivalent to the paint device's settings, i.e. the world, + "window" and device coordinate systems are equivalent, but as we + have seen, the systems can be manipulated using transformation + operations and window-viewport conversion. The illustration above + describes the process. + + \omit + \section1 Related Classes + + Qt's paint system, Arthur, is primarily based on the QPainter, + QPaintDevice, and QPaintEngine classes: + + \table + \header \o Class \o Description + \row + \o QPainter + \o + The QPainter class performs low-level painting on widgets and + other paint devices. QPainter can operate on any object that + inherits the QPaintDevice class, using the same code. + \row + \o QPaintDevice + \o + The QPaintDevice class is the base class of objects that can be + painted. Qt provides several devices: QWidget, QImage, QPixmap, + QPrinter and QPicture, and other devices can also be defined by + subclassing QPaintDevice. + \row + \o QPaintEngine + \o + The QPaintEngine class provides an abstract definition of how + QPainter draws to a given device on a given platform. Qt 4 + provides several premade implementations of QPaintEngine for the + different painter backends we support; it provides one paint + engine for each supported window system and painting + frameworkt. You normally don't need to use this class directly. + \endtable + + The 2D transformations of the coordinate system are specified + using the QTransform class: + + \table + \header \o Class \o Description + \row + \o QTransform + \o + A 3 x 3 transformation matrix. Use QTransform to rotate, shear, + scale, or translate the coordinate system. + \endtable + + In addition Qt provides several graphics primitive classes. Some + of these classes exist in two versions: an \c{int}-based version + and a \c{qreal}-based version. For these, the \c qreal version's + name is suffixed with an \c F. + + \table + \header \o Class \o Description + \row + \o \l{QPoint}(\l{QPointF}{F}) + \o + A single 2D point in the coordinate system. Most functions in Qt + that deal with points can accept either a QPoint, a QPointF, two + \c{int}s, or two \c{qreal}s. + \row + \o \l{QSize}(\l{QSizeF}{F}) + \o + A single 2D vector. Internally, QPoint and QSize are the same, but + a point is not the same as a size, so both classes exist. Again, + most functions accept either QSizeF, a QSize, two \c{int}s, or two + \c{qreal}s. + \row + \o \l{QRect}(\l{QRectF}{F}) + \o + A 2D rectangle. Most functions accept either a QRectF, a QRect, + four \c{int}s, or four \c {qreal}s. + \row + \o \l{QLine}(\l{QLineF}{F}) + \o + A 2D finite-length line, characterized by a start point and an end + point. + \row + \o \l{QPolygon}(\l{QPolygonF}{F}) + \o + A 2D polygon. A polygon is a vector of \c{QPoint(F)}s. If the + first and last points are the same, the polygon is closed. + \row + \o QPainterPath + \o + A vectorial specification of a 2D shape. Painter paths are the + ultimate painting primitive, in the sense that any shape + (rectange, ellipse, spline) or combination of shapes can be + expressed as a path. A path specifies both an outline and an area. + \row + \o QRegion + \o + An area in a paint device, expressed as a list of + \l{QRect}s. In general, we recommend using the vectorial + QPainterPath class instead of QRegion for specifying areas, + because QPainterPath handles painter transformations much better. + \endtable + \endomit + + \sa {Analog Clock Example}, {Transformations Example} +*/ diff --git a/doc/src/painting-and-printing/paintsystem.qdoc b/doc/src/painting-and-printing/paintsystem.qdoc new file mode 100644 index 0000000000..d93fb952a8 --- /dev/null +++ b/doc/src/painting-and-printing/paintsystem.qdoc @@ -0,0 +1,560 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \group painting + \title Painting Classes + \ingroup groups + + \brief Classes that provide support for painting. + + See also this introduction to the \link coordsys.html Qt + coordinate system. \endlink +*/ + +/*! + \group painting-3D + \title Rendering in 3D + \ingroup groups + + \brief Classes that provide support for rendering in 3D. +*/ + +/*! + \page paintsystem.html + \title Paint System + \brief A system for painting on the screen or on print devices using the same API + \ingroup qt-graphics + \ingroup frameworks-technologies + \ingroup qt-basic-concepts + + + Qt's paint system enables painting on screen and print devices + using the same API, and is primarily based on the QPainter, + QPaintDevice, and QPaintEngine classes. + + QPainter is used to perform drawing operations, QPaintDevice is an + abstraction of a two-dimensional space that can be painted on + using a QPainter, and QPaintEngine provides the interface that the + painter uses to draw onto different types of devices. The + QPaintEngine class is used internally by QPainter and + QPaintDevice, and is hidden from application programmers unless + they create their own device type. + + \image paintsystem-core.png + + The main benefit of this approach is that all painting follows the + same painting pipeline making it easy to add support for new + features and providing default implementations for unsupported + ones. + + \section1 Topics + \list + \o \l{Classes for Painting} + \o \l{Paint Devices and Backends} + \o \l{Drawing and Filling} + \o \l{Coordinate System} + \o \l{Reading and Writing Image Files} + \o \l{Styling} + \o \l{Printing with Qt} + \endlist + + \section1 Classes for Painting + + These classes provide support for painting onto a paint device. + + \annotatedlist painting + + Alternatively, Qt provides the QtOpenGL module, offering classes + that makes it easy to use OpenGL in Qt applications. Among others, + the module provides an OpenGL widget class that can be used just + like any other Qt widget, except that it opens an OpenGL display + buffer where the OpenGL API can be used to render the contents. +*/ + + +/*! + \page paintsystem-devices.html + \title Paint Devices and Backends + + \contentspage The Paint System + \nextpage Drawing and Filling + + \section1 Creating a Paint Device + + The QPaintDevice class is the base class of objects that can be + painted, i.e. QPainter can draw on any QPaintDevice + subclass. QPaintDevice's drawing capabilities are currently + implemented by the QWidget, QImage, QPixmap, QGLWidget, + QGLPixelBuffer, QPicture and QPrinter subclasses. + + \image paintsystem-devices.png + + \table 100% + \row \o \bold Widget + + The QWidget class is the base class of all user interface + objects. The widget is the atom of the user interface: it receives + mouse, keyboard and other events from the window system, and + paints a representation of itself on the screen. + + \row \o \bold Image + + The QImage class provides a hardware-independent image + representation which is designed and optimized for I/O, and for + direct pixel access and manipulation. QImage supports several + image formats including monochrome, 8-bit, 32-bit and + alpha-blended images. + + One advantage of using QImage as a paint device is that it is + possible to guarantee the pixel exactness of any drawing operation + in a platform-independent way. Another benefit is that the + painting can be performed in another thread than the current GUI + thread. + + \row \o \bold Pixmap + + The QPixmap class is an off-screen image representation which is + designed and optimized for showing images on screen. Unlike + QImage, the pixel data in a pixmap is internal and is managed by + the underlying window system, i.e. pixels can only be accessed + through QPainter functions or by converting the QPixmap to a + QImage. + + To optimize drawing with QPixmap, Qt provides the QPixmapCache + class which can be used to store temporary pixmaps that are + expensive to generate without using more storage space than the + cache limit. + + Qt also provides the QBitmap convenience class, inheriting + QPixmap. QBitmap guarantees monochrome (1-bit depth) pixmaps, and + is mainly used for creating custom QCursor and QBrush objects, + constructing QRegion objects, and for setting masks for pixmaps + and widgets. + + \row \o \bold {OpenGL Widget} + + As mentioned previously, Qt provides the QtOpenGL module offering + classes that makes it easy to use OpenGL in Qt applications. For + example, the QGLWidget enables the OpenGL API for + rendering. + + But QGLWidget is also a QWidget subclass, and can be used by + QPainter as any other paint device. One huge benefit from this is + that it enables Qt to utilize the high performance of OpenGL for + most drawing operations, such as transformations and pixmap + drawing. + + \row \o \bold {Pixel Buffer} + + The QtOpenGL module also provides the QGLPixelBuffer class which + inherits QPaintDevice directly. + + QGLPixelBuffer encapsulates an OpenGL pbuffer. Rendering into a + pbuffer is normally done using full hardware acceleration which + can be significantly faster than rendering into a QPixmap. + + \row \o \bold {Framebuffer Object} + + The QtOpenGL module also provides the QGLFramebufferObject class + which inherits QPaintDevice directly. + + QGLFramebufferObject encapsulates an OpenGL framebuffer object. + Framebuffer objects can also be used for off-screen rendering, and + offer several advantages over pixel buffers for this purpose. + These are described in the QGLFramebufferObject class documentation. + + \row \o \bold {Picture} + + The QPicture class is a paint device that records and replays + QPainter commands. A picture serializes painter commands to an IO + device in a platform-independent format. QPicture is also + resolution independent, i.e. a QPicture can be displayed on + different devices (for example svg, pdf, ps, printer and screen) + looking the same. + + Qt provides the QPicture::load() and QPicture::save() functions + as well as streaming operators for loading and saving pictures. + + \row \o \bold {Printer} + + The QPrinter class is a paint device that paints on a printer. On + Windows or Mac OS X, QPrinter uses the built-in printer + drivers. On X11, QPrinter generates postscript and sends that to + lpr, lp, or another print program. QPrinter can also print to any + other QPrintEngine object. + + The QPrintEngine class defines an interface for how QPrinter + interacts with a given printing subsystem. The common case when + creating your own print engine, is to derive from both + QPaintEngine and QPrintEngine. + + The output format is by default determined by the platform the + printer is running on, but by explicitly setting the output format + to QPrinter::PdfFormat, QPrinter will generate its output as a PDF + file. + + \row \o \bold {Custom Backends} + + Support for a new backend can be implemented by deriving from the + QPaintDevice class and reimplementing the virtual + QPaintDevice::paintEngine() function to tell QPainter which paint + engine should be used to draw on this particular device. To + actually be able to draw on the device, this paint engine must be + a custom paint engine created by deriving from the QPaintEngine + class. + + \endtable + + \section1 Selecting the Painting Backend + + Since Qt 4.5, it is possible to replace the paint engines and paint + devices used for widgets, pixmaps and the offscreen double buffer. By + default the backends are: + + \table + \row + \o Windows + \o Software Rasterizer + \row + \o X11 + \o X11 + \row + \o Mac OS X + \o CoreGraphics + \row + \o Embedded + \o Software Rasterizer + \endtable + + Passing a command line parameter to the application, such as, + \c{-graphicssystem raster}, specifies that Qt should use the software + rasterizer for this application. The Software rasterizer is fully + supported on all platforms. + + \code + > analogclock -graphicssystem raster + \endcode + + There is also a \c{-graphicssystem opengl} mode that uses OpenGL for + all drawing. Currently, this engine is experimental as it does not draw + everything correctly. + + Qt also supports being configured using \c {-graphicssystem + raster|opengl} in which case all applications will use the + specified graphics system for its graphics. +*/ + +/*! + \page paintsystem-drawing.html + \title Drawing and Filling + + \previouspage Paint Devices and Backends + \contentspage The Paint System + \nextpage Coordinate System + + \section1 Drawing + + QPainter provides highly optimized functions to do most of the + drawing GUI programs require. It can draw everything from simple + graphical primitives (represented by the QPoint, QLine, QRect, + QRegion and QPolygon classes) to complex shapes like vector + paths. In Qt vector paths are represented by the QPainterPath + class. QPainterPath provides a container for painting operations, + enabling graphical shapes to be constructed and reused. + + \table 100% + \row + \o \image paintsystem-painterpath.png + \o \bold QPainterPath + + A painter path is an object composed of lines and curves. For + example, a rectangle is composed by lines and an ellipse is + composed by curves. + + The main advantage of painter paths over normal drawing operations + is that complex shapes only need to be created once; then they can + be drawn many times using only calls to the QPainter::drawPath() + function. + + A QPainterPath object can be used for filling, outlining, and + clipping. To generate fillable outlines for a given painter path, + use the QPainterPathStroker class. + + \endtable + + Lines and outlines are drawn using the QPen class. A pen is + defined by its style (i.e. its line-type), width, brush, how the + endpoints are drawn (cap-style) and how joins between two + connected lines are drawn (join-style). The pen's brush is a + QBrush object used to fill strokes generated with the pen, + i.e. the QBrush class defines the fill pattern. + + QPainter can also draw aligned text and pixmaps. + + When drawing text, the font is specified using the QFont class. Qt + will use the font with the specified attributes, or if no matching + font exists, Qt will use the closest matching installed font. The + attributes of the font that is actually used can be retrieved + using the QFontInfo class. In addition, the QFontMetrics class + provides the font measurements, and the QFontDatabase class + provides information about the fonts available in the underlying + window system. + + Normally, QPainter draws in a "natural" coordinate system, but it + is able to perform view and world transformations using the + QTransform class. For more information, see \l {Coordinate + System}, which also describes the rendering process, i.e. the + relation between the logical representation and the rendered + pixels, and the benefits of anti-aliased painting. + + \table 100% + \row \o + \bold {Anti-Aliased Painting} + + When drawing, the pixel rendering is controlled by the + QPainter::Antialiasing render hint. The QPainter::RenderHint enum + is used to specify flags to QPainter that may or may not be + respected by any given engine. + + The QPainter::Antialiasing value indicates that the engine should + antialias edges of primitives if possible, i.e. smoothing the + edges by using different color intensities. + + \o \image paintsystem-antialiasing.png + + \endtable + + \section1 Filling + + Shapes are filled using the QBrush class. A brush is defined + by its color and its style (i.e. its fill pattern). + + Any color in Qt is represented by the QColor class which supports + the RGB, HSV and CMYK color models. QColor also support + alpha-blended outlining and filling (specifying the transparency + effect), and the class is platform and device independent (the + colors are mapped to hardware using the QColormap class). For more + information, see the QColor class documentation. + + When creating a new widget, it is recommend to use the colors in + the widget's palette rather than hard-coding specific colors. All + widgets in Qt contain a palette and use their palette to draw + themselves. A widget's palette is represented by the QPalette + class which contains color groups for each widget state. + + The available fill patterns are described by the Qt::BrushStyle + enum. These include basic patterns spanning from uniform color to + very sparse pattern, various line combinations, gradient fills and + textures. Qt provides the QGradient class to define custom + gradient fills, while texture patterns are specified using the + QPixmap class. + + \table 100% + \row + \o \image paintsystem-fancygradient.png + \o \bold QGradient + + The QGradient class is used in combination with QBrush to specify + gradient fills. + + \image paintsystem-gradients.png + + Qt currently supports three types of gradient fills: Linear + gradients interpolate colors between start and end points, radial + gradients interpolate colors between a focal point and end points + on a circle surrounding it, and conical gradients interpolate + colors around a center point. + + \endtable +*/ + +/*! + \page paintsystem-images.html + \title Reading and Writing Image Files + + \previouspage Coordinate System + \contentspage The Paint System + \nextpage Styling + + The most common way to read images is through QImage and QPixmap's + constructors, or by calling the QImage::load() and QPixmap::load() + functions. In addition, Qt provides the QImageReader class which + gives more control over the process. Depending on the underlying + support in the image format, the functions provided by the class + can save memory and speed up loading of images. + + Likewise, Qt provides the QImageWriter class which supports + setting format specific options, such as the gamma level, + compression level and quality, prior to storing the image. If you + do not need such options, you can use QImage::save() or + QPixmap::save() instead. + + \table 100% + \row + \o \bold QMovie + + QMovie is a convenience class for displaying animations, using the + QImageReader class internally. Once created, the QMovie class + provides various functions for both running and controlling the + given animation. + + \o \image paintsystem-movie.png + \endtable + + The QImageReader and QImageWriter classes rely on the + QImageIOHandler class which is the common image I/O interface for + all image formats in Qt. QImageIOHandler objects are used + internally by QImageReader and QImageWriter to add support for + different image formats to Qt. + + A list of the supported file formats are available through the + QImageReader::supportedImageFormats() and + QImageWriter::supportedImageFormats() functions. Qt supports + several file formats by default, and in addition new formats can + be added as plugins. The currently supported formats are listed in + the QImageReader and QImageWriter class documentation. + + Qt's plugin mechanism can also be used to write a custom image + format handler. This is done by deriving from the QImageIOHandler + class, and creating a QImageIOPlugin object which is a factory for + creating QImageIOHandler objects. When the plugin is installed, + QImageReader and QImageWriter will automatically load the plugin + and start using it. + + \section1 Rendering SVG files + + \table 100% + \row + \o \image paintsystem-svg.png + \o \bold {SVG Rendering} + + Scalable Vector Graphics (SVG) is a language for describing two-dimensional + graphics and graphical applications in XML. SVG 1.1 is a W3C Recommendation + and forms the core of the current SVG developments in Qt. SVG 1.2 is the + specification currently being developed by the \l{SVG Working Group}, and it + is \l{http://www.w3.org/TR/SVG12/}{available in draft form}. + The \l{Mobile SVG Profiles} (SVG Basic and SVG Tiny) are aimed at + resource-limited devices and are part of the 3GPP platform for third generation + mobile phones. You can read more about SVG at \l{About SVG}. + + Qt supports the \l{SVG 1.2 Tiny Static Features}{static features} of + \l{SVG 1.2 Tiny}. ECMA scripts and DOM manipulation are currently not + supported. + + SVG drawings can be rendered onto any QPaintDevice subclass. This + approach gives developers the flexibility to experiment, in order + to find the best solution for each application. + + The easiest way to render SVG files is to construct a QSvgWidget and + load an SVG file using one of the QSvgWidget::load() functions. + + QSvgRenderer is the class responsible for rendering SVG files for + QSvgWidget, and it can be used directly to provide SVG support for + custom widgets. + To load an SVG file, construct a QSvgRenderer with a file name or the + contents of a file, or call QSvgRenderer::load() on an existing + renderer. If the SVG file has been loaded successfully the + QSvgRenderer::isValid() will return true. + + Once you have loaded the SVG file successfully, you can render it + with the QSvgRenderer::render() function. Note that this scheme allows + you to render SVG files on all paint devices supported by Qt, including + QWidget, QGLWidget, and QImage. See the \l{SVG Viewer Example}{SVG Viewer} + example for more details. + + \endtable +*/ + +/*! + \page paintsystem-styling.html + \title Styling + + \previouspage Reading and Writing Image Files + \contentspage The Paint System + \nextpage Printing with Qt + + Qt's built-in widgets use the QStyle class to perform nearly all + of their drawing. QStyle is an abstract base class that + encapsulates the look and feel of a GUI, and can be used to make + the widgets look exactly like the equivalent native widgets or to + give the widgets a custom look. + + Qt provides a set of QStyle subclasses that emulate the native + look of the different platforms supported by Qt (QWindowsStyle, + QMacStyle, QMotifStyle, etc.). These styles are built into the + QtGui library, other styles can be made available using Qt's + plugin mechansim. + + Most functions for drawing style elements take four arguments: + + \list + \o an enum value specifying which graphical element to draw + \o a QStyleOption object specifying how and where to render that element + \o a QPainter object that should be used to draw the element + \o a QWidget object on which the drawing is performed (optional) + \endlist + + The style gets all the information it needs to render the + graphical element from the QStyleOption class. 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, QStyle can be used to draw on any + paint device (not just widgets), in which case the widget argument + is a zero pointer. + + \image paintsystem-stylepainter.png + + The paint system also provides the QStylePainter class inheriting + from QPainter. QStylePainter is a convenience class for drawing + QStyle elements inside a widget, and extends QPainter with a set + of high-level drawing functions implemented on top of QStyle's + API. The advantage of using QStylePainter is that the parameter + lists get considerably shorter. + + \table 100% + \row + \o \inlineimage paintsystem-icon.png + \o \bold QIcon + + The QIcon class provides scalable icons in different modes and states. + + QIcon can generate pixmaps reflecting an icon's state, mode and + size. These pixmaps are generated from the set of pixmaps + made available to the icon, and are used by Qt widgets to show an + icon representing a particular action. + + The rendering of a QIcon object is handled by the QIconEngine + class. Each icon has a corresponding icon engine that is + responsible for drawing the icon with a requested size, mode and + state. + + \endtable + + For more information about widget styling and appearance, see the + \l{Styles and Style Aware Widgets}. +*/ diff --git a/doc/src/painting-and-printing/printing.qdoc b/doc/src/painting-and-printing/printing.qdoc new file mode 100644 index 0000000000..ccd42eb7f9 --- /dev/null +++ b/doc/src/painting-and-printing/printing.qdoc @@ -0,0 +1,189 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \group printing + \title Printer and Printing APIs + \brief Classes for producing printed output + \ingroup groups +*/ + +/*! + \page printing.html + \title Printing with Qt + \ingroup qt-graphics + + \previouspage Styling + \contentspage The Paint System + + \brief A guide to producing printed output with Qt's paint system and widgets. + + Qt provides extensive cross-platform support for printing. Using the printing + systems on each platform, Qt applications can print to attached printers and + across networks to remote printers. Qt's printing system also enables PostScript + and PDF files to be generated, providing the foundation for basic report + generation facilities. + + \tableofcontents + + \section1 Classes Supporting Printing + + The following classes support the selecting and setting up of printers and + printing output. + + \annotatedlist printing + + \section1 Paint Devices and Printing + + In Qt, printers are represented by QPrinter, a paint device that provides + functionality specific to printing, such as support for multiple pages and + double-sided output. As a result, printing involves using a QPainter to paint + onto a series of pages in the same way that you would paint onto a custom + widget or image. + + \section2 Creating a QPrinter + + Although QPrinter objects can be constructed and set up without requiring user + input, printing is often performed as a result of a request by the user; + for example, when the user selects the \gui{File|Print...} menu item in a GUI + application. In such cases, a newly-constructed QPrinter object is supplied to + a QPrintDialog, allowing the user to specify the printer to use, paper size, and + other printing properties. + + \snippet examples/richtext/orderform/mainwindow.cpp 18 + + It is also possible to set certain default properties by modifying the QPrinter + before it is supplied to the print dialog. For example, applications that + generate batches of reports for printing may set up the QPrinter to + \l{QPrinter::setOutputFileName()}{write to a local file} by default rather than + to a printer. + + \section2 Painting onto a Page + + Once a QPrinter object has been constructed and set up, a QPainter can be used + to perform painting operations on it. We can construct and set up a painter in + the following way: + + \snippet doc/src/snippets/printing-qprinter/object.cpp 0 + + Since the QPrinter starts with a blank page, we only need to call the + \l{QPrinter::}{newPage()} function after drawing each page, except for the + last page. + + The document is sent to the printer, or written to a local file, when we call + \l{QPainter::}{end()}. + + \section2 Coordinate Systems + + QPrinter provides functions that can be used to obtain information about the + dimensions of the paper (the paper rectangle) and the dimensions of the + printable area (the page rectangle). These are given in logical device + coordinates that may differ from the physical coordinates used by the device + itself, indicating that the printer is able to render text and graphics at a + (typically higher) resolution than the user's display. + + Although we do not need to handle the conversion between logical and physical + coordinates ourselves, we still need to apply transformations to painting + operations because the pixel measurements used to draw on screen are often + too small for the higher resolutions of typical printers. + + \table + \row \o \bold{Printer and Painter Coordinate Systems} + + The \l{QPrinter::}{paperRect()} and \l{QPrinter::}{pageRect()} functions + provide information about the size of the paper used for printing and the + area on it that can be painted on. + + The rectangle returned by \l{QPrinter::}{pageRect()} usually lies inside + the rectangle returned by \l{QPrinter::}{paperRect()}. You do not need to + take the positions and sizes of these area into account when using a QPainter + with a QPrinter as the underlying paint device; the origin of the painter's + coordinate system will coincide with the top-left corner of the page + rectangle, and painting operations will be clipped to the bounds of the + drawable part of the page. + + \o \inlineimage printer-rects.png + \endtable + + The paint system automatically uses the correct device metrics when painting + text but, if you need to position text using information obtained from + font metrics, you need to ensure that the print device is specified when + you construct QFontMetrics and QFontMetricsF objects, or ensure that each QFont + used is constructed using the form of the constructor that accepts a + QPaintDevice argument. + + \section1 Printing Widgets + + To print a widget, you can use the QWidget::render() function. As mentioned, + the printer's resolution is usually higher than the screen resolution, so you + will have to scale the painter. You may also want to position the widget on the + page. The following code sample shows how this may look. + + \snippet doc/src/snippets/widgetprinting.cpp 0 + + This will center the widget on the page and scale it so that it fits the page. + + \section1 Printing from Complex Widgets + + Certain widgets, such as QTextEdit and QGraphicsView, display rich content + that is typically managed by instances of other classes, such as QTextDocument + and QGraphicsScene. As a result, it is these content handling classes that + usually provide printing functionality, either via a function that can be used + to perform the complete task, or via a function that accepts an existing + QPainter object. Some widgets provide convenience functions to expose underlying + printing features, avoiding the need to obtain the content handler just to call + a single function. + + The following table shows which class and function are responsible for + printing from a selection of different widgets. For widgets that do not expose + printing functionality directly, the content handling classes containing this + functionality can be obtained via a function in the corresponding widget's API. + + \table + \header \o Widget \o Printing function \o Accepts + \row \o QGraphicsView \o QGraphicsView::render() \o QPainter + \row \o QSvgWidget \o QSvgRenderer::render() \o QPainter + \row \o QTextEdit \o QTextDocument::print() \o QPrinter + \row \o QTextLayout \o QTextLayout::draw() \o QPainter + \row \o QTextLine \o QTextLine::draw() \o QPainter + \endtable + + QTextEdit requires a QPrinter rather than a QPainter because it uses information + about the configured page dimensions in order to insert page breaks at the most + appropriate places in printed documents. +*/ + +/*! + \page pdf-licensing.html + \title Notes about PDF Licensing + \ingroup licensing + \brief Details of restrictions on the use of PDF-related trademarks. + + Please note that Adobe\reg places restrictions on the use of its trademarks + (including logos) in conjunction with PDF; e.g. "Adobe PDF". Please refer + to \l{http://www.adobe.com}{www.adobe.com} for guidelines. +*/ diff --git a/doc/src/snippets/alphachannel.cpp b/doc/src/snippets/alphachannel.cpp new file mode 100644 index 0000000000..d5ec20e60c --- /dev/null +++ b/doc/src/snippets/alphachannel.cpp @@ -0,0 +1,108 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <qapplication.h> +#include <qlabel.h> +#include <qpixmap.h> +#include <qprinter.h> +#include <qpainter.h> +#include <qfile.h> +#include <qdir.h> +#include <qfileinfo.h> +#include <QtGui> +#include <QtCore> + +class MyClass : public QWidget +{ +public: + MyClass(QWidget *parent = 0) : QWidget(parent) { } + +protected: + void paintEvent(QPaintEvent *e) + { + /*QRadialGradient rg(50, 50, 50, 50, 50); + rg.setColorAt(0, QColor::fromRgbF(1, 0, 0, 1)); + rg.setColorAt(1, QColor::fromRgbF(0, 0, 0, 0)); + QPainter pmp(&pm); + pmp.fillRect(0, 0, 100, 100, rg); + pmp.end();*/ + + createImage(); + + QPainter p(this); + p.fillRect(rect(), Qt::white); + + p.drawPixmap(0, 0, pixmap); + + p.drawPixmap(100, 0, channelImage); + } + + void createImage() + { +//! [0] + pixmap = QPixmap(100, 100); + pixmap.fill(Qt::transparent); + + QRadialGradient gradient(50, 50, 50, 50, 50); + gradient.setColorAt(0, QColor::fromRgbF(1, 0, 0, 1)); + gradient.setColorAt(1, QColor::fromRgbF(0, 0, 0, 0)); + QPainter painter(&pixmap); + painter.fillRect(0, 0, 100, 100, gradient); + + channelImage = pixmap.alphaChannel(); + update(); +//! [0] + } + + QPixmap channelImage, pixmap; + QSize sizeHint() const { return QSize(500, 500); } +}; + +int main(int argc, char **argv) +{ + QApplication app(argc, argv); + + MyClass cl; + cl.show(); + QObject::connect(&app, SIGNAL(lastWindowClosed()), &app, SLOT(quit())); + + int ret = app.exec(); + return ret; +} diff --git a/doc/src/snippets/brush/brush.cpp b/doc/src/snippets/brush/brush.cpp new file mode 100644 index 0000000000..57a219242c --- /dev/null +++ b/doc/src/snippets/brush/brush.cpp @@ -0,0 +1,86 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> + +int main() +{ + QWidget anyPaintDevice; + { + // PEN SNIPPET + QPainter painter; + QPen pen(Qt::red, 2); // red solid line, 2 pixels wide + painter.begin(&anyPaintDevice); // paint something + painter.setPen(pen); // set the red, wide pen + painter.drawRect(40,30, 200,100); // draw a rectangle + painter.setPen(Qt::blue); // set blue pen, 0 pixel width + painter.drawLine(40,30, 240,130); // draw a diagonal in rectangle + painter.end(); // painting done + } + + { + // BRUSH SNIPPET + QPainter painter; + QBrush brush(Qt::yellow); // yellow solid pattern + painter.begin(&anyPaintDevice); // paint something + painter.setBrush(brush); // set the yellow brush + painter.setPen(Qt::NoPen); // do not draw outline + painter.drawRect(40,30, 200,100); // draw filled rectangle + painter.setBrush(Qt::NoBrush); // do not fill + painter.setPen(Qt::black); // set black pen, 0 pixel width + painter.drawRect(10,10, 30,20); // draw rectangle outline + painter.end(); // painting done + } + + // LINEAR +//! [0] + QLinearGradient linearGrad(QPointF(100, 100), QPointF(200, 200)); + linearGrad.setColorAt(0, Qt::black); + linearGrad.setColorAt(1, Qt::white); +//! [0] + + // RADIAL +//! [1] + QRadialGradient radialGrad(QPointF(100, 100), 100); + radialGrad.setColorAt(0, Qt::red); + radialGrad.setColorAt(0.5, Qt::blue); + radialGrad.setColorAt(1, Qt::green); +//! [1] +} diff --git a/doc/src/snippets/brush/gradientcreationsnippet.cpp b/doc/src/snippets/brush/gradientcreationsnippet.cpp new file mode 100644 index 0000000000..783c4c249a --- /dev/null +++ b/doc/src/snippets/brush/gradientcreationsnippet.cpp @@ -0,0 +1,62 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> + +int main(int argv, char **args) +{ + QApplication app(argv, args); + +//! [0] + QRadialGradient gradient(50, 50, 50, 50, 50); + gradient.setColorAt(0, QColor::fromRgbF(0, 1, 0, 1)); + gradient.setColorAt(1, QColor::fromRgbF(0, 0, 0, 0)); + + QBrush brush(gradient); +//! [0] + + QWidget widget; + QPalette palette; + palette.setBrush(widget.backgroundRole(), brush); + widget.setPalette(palette); + widget.show(); + + return app.exec(); +} diff --git a/doc/src/snippets/buffer/buffer.cpp b/doc/src/snippets/buffer/buffer.cpp new file mode 100644 index 0000000000..a5e91087cd --- /dev/null +++ b/doc/src/snippets/buffer/buffer.cpp @@ -0,0 +1,124 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QApplication> +#include <QBuffer> +#include <QPalette> + +static void main_snippet() +{ +//! [0] + QBuffer buffer; + char ch; + + buffer.open(QBuffer::ReadWrite); + buffer.write("Qt rocks!"); + buffer.seek(0); + buffer.getChar(&ch); // ch == 'Q' + buffer.getChar(&ch); // ch == 't' + buffer.getChar(&ch); // ch == ' ' + buffer.getChar(&ch); // ch == 'r' +//! [0] +} + +static void write_datastream_snippets() +{ +//! [1] + QByteArray byteArray; + QBuffer buffer(&byteArray); + buffer.open(QIODevice::WriteOnly); + + QDataStream out(&buffer); + out << QApplication::palette(); +//! [1] +} + +static void read_datastream_snippets() +{ + QByteArray byteArray; + +//! [2] + QPalette palette; + QBuffer buffer(&byteArray); + buffer.open(QIODevice::ReadOnly); + + QDataStream in(&buffer); + in >> palette; +//! [2] +} + +static void bytearray_ptr_ctor_snippet() +{ +//! [3] + QByteArray byteArray("abc"); + QBuffer buffer(&byteArray); + buffer.open(QIODevice::WriteOnly); + buffer.seek(3); + buffer.write("def", 3); + buffer.close(); + // byteArray == "abcdef" +//! [3] +} + +static void setBuffer_snippet() +{ +//! [4] + QByteArray byteArray("abc"); + QBuffer buffer; + buffer.setBuffer(&byteArray); + buffer.open(QIODevice::WriteOnly); + buffer.seek(3); + buffer.write("def", 3); + buffer.close(); + // byteArray == "abcdef" +//! [4] +} + +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + + main_snippet(); + bytearray_ptr_ctor_snippet(); + write_datastream_snippets(); + read_datastream_snippets(); + setBuffer_snippet(); + return 0; +} diff --git a/doc/src/snippets/code/doc_src_containers.cpp b/doc/src/snippets/code/doc_src_containers.cpp new file mode 100644 index 0000000000..fa300f916b --- /dev/null +++ b/doc/src/snippets/code/doc_src_containers.cpp @@ -0,0 +1,275 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +class Employee +{ +public: + Employee() {} + Employee(const Employee &other); + + Employee &operator=(const Employee &other); + +private: + QString myName; + QDate myDateOfBirth; +}; +//! [0] + + +//! [1] +QList<QString> list; +list << "A" << "B" << "C" << "D"; + +QListIterator<QString> i(list); +while (i.hasNext()) + qDebug() << i.next(); +//! [1] + + +//! [2] +QListIterator<QString> i(list); +i.toBack(); +while (i.hasPrevious()) + qDebug() << i.previous(); +//! [2] + + +//! [3] +QMutableListIterator<int> i(list); +while (i.hasNext()) { + if (i.next() % 2 != 0) + i.remove(); +} +//! [3] + + +//! [4] +QMutableListIterator<int> i(list); +i.toBack(); +while (i.hasPrevious()) { + if (i.previous() % 2 != 0) + i.remove(); +} +//! [4] + + +//! [5] +QMutableListIterator<int> i(list); +while (i.hasNext()) { + if (i.next() > 128) + i.setValue(128); +} +//! [5] + + +//! [6] +QMutableListIterator<int> i(list); +while (i.hasNext()) + i.next() *= 2; +//! [6] + + +//! [7] +QMap<QString, QString> map; +map.insert("Paris", "France"); +map.insert("Guatemala City", "Guatemala"); +map.insert("Mexico City", "Mexico"); +map.insert("Moscow", "Russia"); +... + +QMutableMapIterator<QString, QString> i(map); +while (i.hasNext()) { + if (i.next().key().endsWith("City")) + i.remove(); +} +//! [7] + + +//! [8] +QMap<int, QWidget *> map; +QHash<int, QWidget *> hash; + +QMapIterator<int, QWidget *> i(map); +while (i.hasNext()) { + i.next(); + hash.insert(i.key(), i.value()); +} +//! [8] + + +//! [9] +QMutableMapIterator<int, QWidget *> i(map); +while (i.findNext(widget)) + i.remove(); +//! [9] + + +//! [10] +QList<QString> list; +list << "A" << "B" << "C" << "D"; + +QList<QString>::iterator i; +for (i = list.begin(); i != list.end(); ++i) + *i = (*i).toLower(); +//! [10] + + +//! [11] +QList<QString> list; +list << "A" << "B" << "C" << "D"; + +QList<QString>::iterator i = list.end(); +while (i != list.begin()) { + --i; + *i = (*i).toLower(); +} +//! [11] + + +//! [12] +QList<QString>::const_iterator i; +for (i = list.constBegin(); i != list.constEnd(); ++i) + qDebug() << *i; +//! [12] + + +//! [13] +QMap<int, int> map; +... +QMap<int, int>::const_iterator i; +for (i = map.constBegin(); i != map.constEnd(); ++i) + qDebug() << i.key() << ":" << i.value(); +//! [13] + + +//! [14] +// RIGHT +const QList<int> sizes = splitter->sizes(); +QList<int>::const_iterator i; +for (i = sizes.begin(); i != sizes.end(); ++i) + ... + +// WRONG +QList<int>::const_iterator i; +for (i = splitter->sizes().begin(); + i != splitter->sizes().end(); ++i) + ... +//! [14] + + +//! [15] +QLinkedList<QString> list; +... +QString str; +foreach (str, list) + qDebug() << str; +//! [15] + + +//! [16] +QLinkedList<QString> list; +... +QLinkedListIterator<QString> i(list); +while (i.hasNext()) + qDebug() << i.next(); +//! [16] + + +//! [17] +QLinkedList<QString> list; +... +foreach (const QString &str, list) + qDebug() << str; +//! [17] + + +//! [18] +QLinkedList<QString> list; +... +foreach (const QString &str, list) { + if (str.isEmpty()) + break; + qDebug() << str; +} +//! [18] + + +//! [19] +QMap<QString, int> map; +... +foreach (const QString &str, map.keys()) + qDebug() << str << ":" << map.value(str); +//! [19] + + +//! [20] +QMultiMap<QString, int> map; +... +foreach (const QString &str, map.uniqueKeys()) { + foreach (int i, map.values(str)) + qDebug() << str << ":" << i; +} +//! [20] + + +//! [21] +forever { + ... +} +//! [21] + + +//! [22] +CONFIG += no_keywords +//! [22] + + +//! [23] +QString onlyLetters(const QString &in) +{ + QString out; + for (int j = 0; j < in.size(); ++j) { + if (in[j].isLetter()) + out += in[j]; + } + return out; +} +//! [23] diff --git a/doc/src/snippets/code/doc_src_coordsys.cpp b/doc/src/snippets/code/doc_src_coordsys.cpp new file mode 100644 index 0000000000..1ebb215941 --- /dev/null +++ b/doc/src/snippets/code/doc_src_coordsys.cpp @@ -0,0 +1,87 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QPainter painter(this); + +painter.setPen(Qt::darkGreen); +painter.drawRect(1, 2, 6, 4); +//! [0] + + +//! [1] +QPainter painter(this); + +painter.setPen(Qt::darkGreen); +painter.drawLine(2, 7, 6, 1); +//! [1] + + +//! [2] +QPainter painter(this); +painter.setRenderHint( + QPainter::Antialiasing); +painter.setPen(Qt::darkGreen); +painter.drawRect(1, 2, 6, 4); +//! [2] + + +//! [3] +QPainter painter(this); +painter.setRenderHint( + QPainter::Antialiasing); +painter.setPen(Qt::darkGreen); +painter.drawLine(2, 7, 6, 1); +//! [3] + + +//! [4] +QPainter painter(this); +painter.setWindow(QRect(-50, -50, 100, 100)); +//! [4] + + +//! [5] +int side = qMin(width(), height()) +int x = (width() - side / 2); +int y = (height() - side / 2); + +painter.setViewport(x, y, side, side); +//! [5] diff --git a/doc/src/snippets/code/doc_src_examples_application.qdoc b/doc/src/snippets/code/doc_src_examples_application.qdoc new file mode 100644 index 0000000000..08e0747695 --- /dev/null +++ b/doc/src/snippets/code/doc_src_examples_application.qdoc @@ -0,0 +1,45 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +application -style=windows +application -style=motif +application -style=cde +//! [0] diff --git a/doc/src/snippets/code/doc_src_examples_arrowpad.cpp b/doc/src/snippets/code/doc_src_examples_arrowpad.cpp new file mode 100644 index 0000000000..c834b9ff26 --- /dev/null +++ b/doc/src/snippets/code/doc_src_examples_arrowpad.cpp @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +qApp->translate("ArrowPad", x) +//! [0] diff --git a/doc/src/snippets/code/doc_src_examples_arrowpad.qdoc b/doc/src/snippets/code/doc_src_examples_arrowpad.qdoc new file mode 100644 index 0000000000..ee3c36784f --- /dev/null +++ b/doc/src/snippets/code/doc_src_examples_arrowpad.qdoc @@ -0,0 +1,54 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [1] +lrelease arrowpad.pro +//! [1] + + +//! [2] +export LANG=fr +setenv LANG fr +//! [2] + + +//! [3] +set LANG=fr +//! [3] diff --git a/doc/src/snippets/code/doc_src_examples_dropsite.qdoc b/doc/src/snippets/code/doc_src_examples_dropsite.qdoc new file mode 100644 index 0000000000..d7bffc0227 --- /dev/null +++ b/doc/src/snippets/code/doc_src_examples_dropsite.qdoc @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +foreach(variable, container) +//! [0] diff --git a/doc/src/snippets/code/doc_src_examples_editabletreemodel.cpp b/doc/src/snippets/code/doc_src_examples_editabletreemodel.cpp new file mode 100644 index 0000000000..a69a7bf772 --- /dev/null +++ b/doc/src/snippets/code/doc_src_examples_editabletreemodel.cpp @@ -0,0 +1,48 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QVariant a = model->index(0, 0, QModelIndex()).data(); +//! [0] + + +//! [1] +QVariant b = model->index(1, 0, QModelIndex()).data(); +//! [1] diff --git a/doc/src/snippets/code/doc_src_examples_hellotr.qdoc b/doc/src/snippets/code/doc_src_examples_hellotr.qdoc new file mode 100644 index 0000000000..9dbcb0af45 --- /dev/null +++ b/doc/src/snippets/code/doc_src_examples_hellotr.qdoc @@ -0,0 +1,71 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +lupdate -verbose hellotr.pro +//! [0] + + +//! [1] +<!DOCTYPE TS><TS> +<context> + <name>QPushButton</name> + <message> + <source>Hello world!</source> + <translation type="unfinished"></translation> + </message> +</context> +</TS> +//! [1] + + +//! [2] +linguist hellotr_la.ts +//! [2] + + +//! [3] +<translation type='unfinished'></translation> +//! [3] + + +//! [4] +<translation>Orbis, te saluto!</translation> +//! [4] diff --git a/doc/src/snippets/code/doc_src_examples_icons.cpp b/doc/src/snippets/code/doc_src_examples_icons.cpp new file mode 100644 index 0000000000..411c49fb8d --- /dev/null +++ b/doc/src/snippets/code/doc_src_examples_icons.cpp @@ -0,0 +1,44 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +if (!condition) + qFatal("ASSERT: "condition" in file ..."); +//! [0] diff --git a/doc/src/snippets/code/doc_src_examples_icons.qdoc b/doc/src/snippets/code/doc_src_examples_icons.qdoc new file mode 100644 index 0000000000..8ca57511f7 --- /dev/null +++ b/doc/src/snippets/code/doc_src_examples_icons.qdoc @@ -0,0 +1,48 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [1] +qmake "CONFIG += debug" icons.pro +//! [1] + + +//! [2] +qmake "CONFIG += release" icons.pro +//! [2] diff --git a/doc/src/snippets/code/doc_src_examples_imageviewer.cpp b/doc/src/snippets/code/doc_src_examples_imageviewer.cpp new file mode 100644 index 0000000000..c86f8ace40 --- /dev/null +++ b/doc/src/snippets/code/doc_src_examples_imageviewer.cpp @@ -0,0 +1,54 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +imageLabel->resize(imageLabel->pixmap()->size()); +//! [0] + + +//! [1] +if (!imageLabel->pixmap()) + qFatal("ASSERT: "imageLabel->pixmap()" in file ..."); +//! [1] + + +//! [4] +scrollBar->setValue(int(factor * scrollBar->value())); +//! [4] diff --git a/doc/src/snippets/code/doc_src_examples_imageviewer.qdoc b/doc/src/snippets/code/doc_src_examples_imageviewer.qdoc new file mode 100644 index 0000000000..1870385de7 --- /dev/null +++ b/doc/src/snippets/code/doc_src_examples_imageviewer.qdoc @@ -0,0 +1,48 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [2] +qmake "CONFIG += debug" foo.pro +//! [2] + + +//! [3] +qmake "CONFIG += release" foo.pro +//! [3] diff --git a/doc/src/snippets/code/doc_src_examples_simpledommodel.cpp b/doc/src/snippets/code/doc_src_examples_simpledommodel.cpp new file mode 100644 index 0000000000..1abcdc21cc --- /dev/null +++ b/doc/src/snippets/code/doc_src_examples_simpledommodel.cpp @@ -0,0 +1,60 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +// file is an open QFile object. +QDomDocument document; +if (document.setContent(&file)) { + + QDomElement documentElement = document.documentElement(); + QString text; + QDomNode node = documentElement.firstChild(); + + while (!node.isNull()) { + if (node.isText()) + text += node.nodeValue(); + else if (node.hasChildNodes()) { + // Examine the node's children and read any text found. + ... + } + node = node.nextSibling(); + } +} +//! [0] diff --git a/doc/src/snippets/code/doc_src_examples_simpletreemodel.qdoc b/doc/src/snippets/code/doc_src_examples_simpletreemodel.qdoc new file mode 100644 index 0000000000..1084d238e7 --- /dev/null +++ b/doc/src/snippets/code/doc_src_examples_simpletreemodel.qdoc @@ -0,0 +1,52 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +Getting Started How to familiarize yourself with Qt Designer + Launching Designer Running the Qt Designer application + The User Interface How to interact with Qt Designer +//! [0] + + +//! [1] +Connection Editing Mode Connecting widgets together with signals and slots + Connecting Objects Making connections in Qt Designer + Editing Connections Changing existing connections +//! [1] diff --git a/doc/src/snippets/code/doc_src_examples_svgalib.qdoc b/doc/src/snippets/code/doc_src_examples_svgalib.qdoc new file mode 100644 index 0000000000..3c34818662 --- /dev/null +++ b/doc/src/snippets/code/doc_src_examples_svgalib.qdoc @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +myApplication -qws -display svgalib +//! [0] diff --git a/doc/src/snippets/code/doc_src_examples_textfinder.pro b/doc/src/snippets/code/doc_src_examples_textfinder.pro new file mode 100644 index 0000000000..cdc2366b57 --- /dev/null +++ b/doc/src/snippets/code/doc_src_examples_textfinder.pro @@ -0,0 +1,46 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#! [0] +CONFIG += uitools +HEADERS = textfinder.h +RESOURCES = textfinder.qrc +SOURCES = textfinder.cpp main.cpp +#! [0] diff --git a/doc/src/snippets/code/doc_src_examples_trollprint.cpp b/doc/src/snippets/code/doc_src_examples_trollprint.cpp new file mode 100644 index 0000000000..f7b8f48f3d --- /dev/null +++ b/doc/src/snippets/code/doc_src_examples_trollprint.cpp @@ -0,0 +1,77 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +twoSidedEnabledRadio = new QRadioButton(tr("Enabled", "two-sided")); +twoSidedDisabledRadio = new QRadioButton(tr("Disabled", "two-sided")); +//! [0] + + +//! [1] +colorsEnabledRadio = new QRadioButton(tr("Enabled", "colors"), colors); +colorsDisabledRadio = new QRadioButton(tr("Disabled", "colors"), colors); +//! [1] + + +//! [2] +/* + TRANSLATOR MainWindow + + In this application the whole application is a MainWindow. + Choose Help|About from the menu bar to see some text + belonging to MainWindow. + + ... +*/ +//! [2] + + +//! [3] +/* + TRANSLATOR ZClientErrorDialog + + Choose Client|Edit to reach the Client Edit dialog, then choose + Client Specification from the drop down list at the top and pick + client Bartel Leendert van der Waerden. Now check the Profile + checkbox and then click the Start Processing button. You should + now see a pop up window with the text "Error: Name too long!". + This window is a ZClientErrorDialog. +*/ +//! [3] diff --git a/doc/src/snippets/code/doc_src_layout.cpp b/doc/src/snippets/code/doc_src_layout.cpp new file mode 100644 index 0000000000..47db36bb3a --- /dev/null +++ b/doc/src/snippets/code/doc_src_layout.cpp @@ -0,0 +1,166 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +#ifndef CARD_H +#define CARD_H + +#include <QtGui> +#include <QList> + +class CardLayout : public QLayout +{ +public: + CardLayout(QWidget *parent, int dist): QLayout(parent, 0, dist) {} + CardLayout(QLayout *parent, int dist): QLayout(parent, dist) {} + CardLayout(int dist): QLayout(dist) {} + ~CardLayout(); + + void addItem(QLayoutItem *item); + QSize sizeHint() const; + QSize minimumSize() const; + QLayoutItem *count() const; + QLayoutItem *itemAt(int) const; + QLayoutItem *takeAt(int); + void setGeometry(const QRect &rect); + +private: + QList<QLayoutItem*> list; +}; +#endif +//! [0] + + +//! [1] +//#include "card.h" +//! [1] + +//! [2] +QLayoutItem *CardLayout::count() const +{ + // QList::size() returns the number of QLayoutItems in the list + return list.size(); +} +//! [2] + +//! [3] +QLayoutItem *CardLayout::itemAt(int idx) const +{ + // QList::value() performs index checking, and returns 0 if we are + // outside the valid range + return list.value(idx); +} + +QLayoutItem *CardLayout::takeAt(int idx) +{ + // QList::take does not do index checking + return idx >= 0 && idx < list.size() ? list.takeAt(idx) : 0; +} +//! [3] + + +//! [4] +void CardLayout::addItem(QLayoutItem *item) +{ + list.append(item); +} +//! [4] + + +//! [5] +CardLayout::~CardLayout() +{ + QLayoutItem *item; + while ((item = takeAt(0))) + delete item; +} +//! [5] + + +//! [6] +void CardLayout::setGeometry(const QRect &r) +{ + QLayout::setGeometry(r); + + if (list.size() == 0) + return; + + int w = r.width() - (list.count() - 1) * spacing(); + int h = r.height() - (list.count() - 1) * spacing(); + int i = 0; + while (i < list.size()) { + QLayoutItem *o = list.at(i); + QRect geom(r.x() + i * spacing(), r.y() + i * spacing(), w, h); + o->setGeometry(geom); + ++i; + } +} +//! [6] + + +//! [7] +QSize CardLayout::sizeHint() const +{ + QSize s(0,0); + int n = list.count(); + if (n > 0) + s = QSize(100,70); //start with a nice default size + int i = 0; + while (i < n) { + QLayoutItem *o = list.at(i); + s = s.expandedTo(o->sizeHint()); + ++i; + } + return s + n*QSize(spacing(), spacing()); +} + +QSize CardLayout::minimumSize() const +{ + QSize s(0,0); + int n = list.count(); + int i = 0; + while (i < n) { + QLayoutItem *o = list.at(i); + s = s.expandedTo(o->minimumSize()); + ++i; + } + return s + n*QSize(spacing(), spacing()); +} +//! [7] diff --git a/doc/src/snippets/code/doc_src_objecttrees.cpp b/doc/src/snippets/code/doc_src_objecttrees.cpp new file mode 100644 index 0000000000..cd92a49eea --- /dev/null +++ b/doc/src/snippets/code/doc_src_objecttrees.cpp @@ -0,0 +1,60 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//![0] +int main() +{ + QWidget window; + QPushButton quit("Quit", &window); + ... +} +//![0] + + +//![1] +int main() +{ + QPushButton quit("Quit"); + QWidget window; + + quit.setParent(&window); + ... +} +//![1] diff --git a/doc/src/snippets/code/doc_src_properties.cpp b/doc/src/snippets/code/doc_src_properties.cpp new file mode 100644 index 0000000000..b5a103db0b --- /dev/null +++ b/doc/src/snippets/code/doc_src_properties.cpp @@ -0,0 +1,132 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +Q_PROPERTY(type name + READ getFunction + [WRITE setFunction] + [RESET resetFunction] + [NOTIFY notifySignal] + [REVISION int] + [DESIGNABLE bool] + [SCRIPTABLE bool] + [STORED bool] + [USER bool] + [CONSTANT] + [FINAL]) +//! [0] + + +//! [1] +Q_PROPERTY(bool focus READ hasFocus) +Q_PROPERTY(bool enabled READ isEnabled WRITE setEnabled) +Q_PROPERTY(QCursor cursor READ cursor WRITE setCursor RESET unsetCursor) +//! [1] + + +//! [2] +Q_PROPERTY(QDate date READ getDate WRITE setDate) +//! [2] + + +//! [3] +QPushButton *button = new QPushButton; +QObject *object = button; + +button->setDown(true); +object->setProperty("down", true); +//! [3] + + +//! [4] +QObject *object = ... +const QMetaObject *metaobject = object->metaObject(); +int count = metaobject->propertyCount(); +for (int i=0; i<count; ++i) { + QMetaProperty metaproperty = metaobject->property(i); + const char *name = metaproperty.name(); + QVariant value = object->property(name); + ... +} +//! [4] + + +//! [5] +class MyClass : public QObject +{ + Q_OBJECT + Q_PROPERTY(Priority priority READ priority WRITE setPriority NOTIFY priorityChanged) + Q_ENUMS(Priority) + +public: + MyClass(QObject *parent = 0); + ~MyClass(); + + enum Priority { High, Low, VeryHigh, VeryLow }; + + void setPriority(Priority priority) + { + m_priority = priority; + emit priorityChanged(priority); + } + Priority priority() const + { return m_priority; } + +signals: + void priorityChanged(Priority); + +private: + Priority m_priority; +}; +//! [5] + + +//! [6] +MyClass *myinstance = new MyClass; +QObject *object = myinstance; + +myinstance->setPriority(MyClass::VeryHigh); +object->setProperty("priority", "VeryHigh"); +//! [6] + + +//! [7] +Q_CLASSINFO("Version", "3.0.0") +//! [7] diff --git a/doc/src/snippets/code/doc_src_qalgorithms.cpp b/doc/src/snippets/code/doc_src_qalgorithms.cpp new file mode 100644 index 0000000000..0438105865 --- /dev/null +++ b/doc/src/snippets/code/doc_src_qalgorithms.cpp @@ -0,0 +1,354 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QStringList list; +list << "one" << "two" << "three"; + +qFill(list.begin(), list.end(), "eleven"); +// list: [ "eleven", "eleven", "eleven" ] +//! [0] + + +//! [1] +qFill(list.begin() + 1, list.end(), "six"); +// list: [ "eleven", "six", "six" ] +//! [1] + + +//! [2] +QChar resolveEntity(const QString &entity) +{ + static const QLatin1String name_table[] = { + "AElig", "Aacute", ..., "zwnj" + }; + static const ushort value_table[] = { + 0x0061, 0x00c1, ..., 0x200c + }; + int N = sizeof(name_table) / sizeof(name_table[0]); + + const QLatin1String *name = qBinaryFind(name_table, name_table + N, + entity); + int index = name - name_table; + if (index == N) + return QChar(); + + return QChar(value_table[index]); +} +//! [2] + + +//! [3] +QChar resolveEntity(const QString &entity) +{ + static QMap<QString, int> entityMap; + + if (!entityMap) { + entityMap.insert("AElig", 0x0061); + entityMap.insert("Aacute", 0x00c1); + ... + entityMap.insert("zwnj", 0x200c); + } + return QChar(entityMap.value(entity)); +} +//! [3] + + +//! [4] +QStringList list; +list << "one" << "two" << "three"; + +QVector<QString> vect1(3); +qCopy(list.begin(), list.end(), vect1.begin()); +// vect: [ "one", "two", "three" ] + +QVector<QString> vect2(8); +qCopy(list.begin(), list.end(), vect2.begin() + 2); +// vect: [ "", "", "one", "two", "three", "", "", "" ] +//! [4] + + +//! [5] +QStringList list; +list << "one" << "two" << "three"; + +QVector<QString> vect(5); +qCopyBackward(list.begin(), list.end(), vect.end()); +// vect: [ "", "", "one", "two", "three" ] +//! [5] + + +//! [6] +QStringList list; +list << "one" << "two" << "three"; + +QVector<QString> vect(3); +vect[0] = "one"; +vect[1] = "two"; +vect[2] = "three"; + +bool ret1 = qEqual(list.begin(), list.end(), vect.begin()); +// ret1 == true + +vect[2] = "seven"; +bool ret2 = qEqual(list.begin(), list.end(), vect.begin()); +// ret2 == false +//! [6] + + +//! [7] +QStringList list; +list << "one" << "two" << "three"; + +qFill(list.begin(), list.end(), "eleven"); +// list: [ "eleven", "eleven", "eleven" ] + +qFill(list.begin() + 1, list.end(), "six"); +// list: [ "eleven", "six", "six" ] +//! [7] + + +//! [8] +QStringList list; +list << "one" << "two" << "three"; + +QStringList::iterator i1 = qFind(list.begin(), list.end(), "two"); +// i1 == list.begin() + 1 + +QStringList::iterator i2 = qFind(list.begin(), list.end(), "seventy"); +// i2 == list.end() +//! [8] + + +//! [9] +QList<int> list; +list << 3 << 3 << 6 << 6 << 6 << 8; + +int countOf6 = 0; +qCount(list.begin(), list.end(), 6, countOf6); +// countOf6 == 3 + +int countOf7 = 0; +qCount(list.begin(), list.end(), 7, countOf7); +// countOf7 == 0 +//! [9] + + +//! [10] +double pi = 3.14; +double e = 2.71; + +qSwap(pi, e); +// pi == 2.71, e == 3.14 +//! [10] + + +//! [11] +QList<int> list; +list << 33 << 12 << 68 << 6 << 12; +qSort(list.begin(), list.end()); +// list: [ 6, 12, 12, 33, 68 ] +//! [11] + + +//! [12] +bool caseInsensitiveLessThan(const QString &s1, const QString &s2) +{ + return s1.toLower() < s2.toLower(); +} + +int doSomething() +{ + QStringList list; + list << "AlPha" << "beTA" << "gamma" << "DELTA"; + qSort(list.begin(), list.end(), caseInsensitiveLessThan); + // list: [ "AlPha", "beTA", "DELTA", "gamma" ] +} +//! [12] + + +//! [13] +QList<int> list; +list << 33 << 12 << 68 << 6 << 12; +qSort(list.begin(), list.end(), qGreater<int>()); +// list: [ 68, 33, 12, 12, 6 ] +//! [13] + + +//! [14] +QStringList list; +list << "AlPha" << "beTA" << "gamma" << "DELTA"; + +QMap<QString, QString> map; +foreach (const QString &str, list) + map.insert(str.toLower(), str); + +list = map.values(); +//! [14] + + +//! [15] +QList<int> list; +list << 33 << 12 << 68 << 6 << 12; +qStableSort(list.begin(), list.end()); +// list: [ 6, 12, 12, 33, 68 ] +//! [15] + + +//! [16] +bool caseInsensitiveLessThan(const QString &s1, const QString &s2) +{ + return s1.toLower() < s2.toLower(); +} + +int doSomething() +{ + QStringList list; + list << "AlPha" << "beTA" << "gamma" << "DELTA"; + qStableSort(list.begin(), list.end(), caseInsensitiveLessThan); + // list: [ "AlPha", "beTA", "DELTA", "gamma" ] +} +//! [16] + + +//! [17] +QList<int> list; +list << 33 << 12 << 68 << 6 << 12; +qStableSort(list.begin(), list.end(), qGreater<int>()); +// list: [ 68, 33, 12, 12, 6 ] +//! [17] + + +//! [18] +QList<int> list; +list << 3 << 3 << 6 << 6 << 6 << 8; + +QList<int>::iterator i = qLowerBound(list.begin(), list.end(), 5); +list.insert(i, 5); +// list: [ 3, 3, 5, 6, 6, 6, 8 ] + +i = qLowerBound(list.begin(), list.end(), 12); +list.insert(i, 12); +// list: [ 3, 3, 5, 6, 6, 6, 8, 12 ] +//! [18] + + +//! [19] +QVector<int> vect; +vect << 3 << 3 << 6 << 6 << 6 << 8; +QVector<int>::iterator begin6 = + qLowerBound(vect.begin(), vect.end(), 6); +QVector<int>::iterator end6 = + qUpperBound(begin6, vect.end(), 6); + +QVector<int>::iterator i = begin6; +while (i != end6) { + *i = 7; + ++i; +} +// vect: [ 3, 3, 7, 7, 7, 8 ] +//! [19] + + +//! [20] +QList<int> list; +list << 3 << 3 << 6 << 6 << 6 << 8; + +QList<int>::iterator i = qUpperBound(list.begin(), list.end(), 5); +list.insert(i, 5); +// list: [ 3, 3, 5, 6, 6, 6, 8 ] + +i = qUpperBound(list.begin(), list.end(), 12); +list.insert(i, 12); +// list: [ 3, 3, 5, 6, 6, 6, 8, 12 ] +//! [20] + + +//! [21] +QVector<int> vect; +vect << 3 << 3 << 6 << 6 << 6 << 8; +QVector<int>::iterator begin6 = + qLowerBound(vect.begin(), vect.end(), 6); +QVector<int>::iterator end6 = + qUpperBound(vect.begin(), vect.end(), 6); + +QVector<int>::iterator i = begin6; +while (i != end6) { + *i = 7; + ++i; +} +// vect: [ 3, 3, 7, 7, 7, 8 ] +//! [21] + + +//! [22] +QVector<int> vect; +vect << 3 << 3 << 6 << 6 << 6 << 8; + +QVector<int>::iterator i = + qBinaryFind(vect.begin(), vect.end(), 6); +// i == vect.begin() + 2 (or 3 or 4) +//! [22] + + +//! [23] +QList<Employee *> list; +list.append(new Employee("Blackpool", "Stephen")); +list.append(new Employee("Twist", "Oliver")); + +qDeleteAll(list.begin(), list.end()); +list.clear(); +//! [23] + + +//! [24] +QList<int> list; +list << 33 << 12 << 68 << 6 << 12; +qSort(list.begin(), list.end(), qLess<int>()); +// list: [ 6, 12, 12, 33, 68 ] +//! [24] + + +//! [25] +QList<int> list; +list << 33 << 12 << 68 << 6 << 12; +qSort(list.begin(), list.end(), qGreater<int>()); +// list: [ 68, 33, 12, 12, 6 ] +//! [25] diff --git a/doc/src/snippets/code/doc_src_qcache.cpp b/doc/src/snippets/code/doc_src_qcache.cpp new file mode 100644 index 0000000000..81fa3cf279 --- /dev/null +++ b/doc/src/snippets/code/doc_src_qcache.cpp @@ -0,0 +1,57 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QCache<int, Employee> cache; +//! [0] + + +//! [1] +Employee *employee = new Employee; +employee->setId(37); +employee->setName("Richard Schmit"); +... +cache.insert(employee->id(), employee); +//! [1] + + +//! [2] +QCache<int, MyDataStructure> cache(5000); +//! [2] diff --git a/doc/src/snippets/code/doc_src_qiterator.cpp b/doc/src/snippets/code/doc_src_qiterator.cpp new file mode 100644 index 0000000000..82b1bd3429 --- /dev/null +++ b/doc/src/snippets/code/doc_src_qiterator.cpp @@ -0,0 +1,420 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QList<float> list; +... +QListIterator<float> i(list); +while (i.hasNext()) + qDebug() << i.next(); +//! [0] + + +//! [1] +QListIterator<float> i(list); +i.toBack(); +while (i.hasPrevious()) + qDebug() << i.previous(); +//! [1] + + +//! [2] +QLinkedList<float> list; +... +QLinkedListIterator<float> i(list); +while (i.hasNext()) + qDebug() << i.next(); +//! [2] + + +//! [3] +QLinkedListIterator<float> i(list); +i.toBack(); +while (i.hasPrevious()) + qDebug() << i.previous(); +//! [3] + + +//! [4] +QVector<float> vector; +... +QVectorIterator<float> i(vector); +while (i.hasNext()) + qDebug() << i.next(); +//! [4] + + +//! [5] +QVectorIterator<float> i(vector); +i.toBack(); +while (i.hasPrevious()) + qDebug() << i.previous(); +//! [5] + + +//! [6] +QSet<QString> set; +... +QSetIterator<QString> i(set); +while (i.hasNext()) + qDebug() << i.next(); +//! [6] + + +//! [7] +QSetIterator<QString> i(set); +i.toBack(); +while (i.hasPrevious()) + qDebug() << i.previous(); +//! [7] + + +//! [8] +QList<float> list; +... +QMutableListIterator<float> i(list); +while (i.hasNext()) + qDebug() << i.next(); +//! [8] + + +//! [9] +QMutableListIterator<float> i(list); +i.toBack(); +while (i.hasPrevious()) + qDebug() << i.previous(); +//! [9] + + +//! [10] +QMutableListIterator<int> i(list); +while (i.hasNext()) { + int val = i.next(); + if (val < 0) { + i.setValue(-val); + } else if (val == 0) { + i.remove(); + } +} +//! [10] + + +//! [11] +QLinkedList<float> list; +... +QMutableLinkedListIterator<float> i(list); +while (i.hasNext()) + qDebug() << i.next(); +//! [11] + + +//! [12] +QMutableLinkedListIterator<float> i(list); +i.toBack(); +while (i.hasPrevious()) + qDebug() << i.previous(); +//! [12] + + +//! [13] +QMutableLinkedListIterator<int> i(list); +while (i.hasNext()) { + int val = i.next(); + if (val < 0) { + i.setValue(-val); + } else if (val == 0) { + i.remove(); + } +} +//! [13] + + +//! [14] +QVector<float> vector; +... +QMutableVectorIterator<float> i(vector); +while (i.hasNext()) + qDebug() << i.next(); +//! [14] + + +//! [15] +QMutableVectorIterator<float> i(vector); +i.toBack(); +while (i.hasPrevious()) + qDebug() << i.previous(); +//! [15] + + +//! [16] +QMutableVectorIterator<int> i(vector); +while (i.hasNext()) { + int val = i.next(); + if (val < 0) { + i.setValue(-val); + } else if (val == 0) { + i.remove(); + } +} +//! [16] + + +//! [17] +QSet<float> set; +... +QMutableSetIterator<float> i(set); +while (i.hasNext()) + qDebug() << i.next(); +//! [17] + + +//! [18] +QMutableSetIterator<float> i(set); +i.toBack(); +while (i.hasPrevious()) + qDebug() << i.previous(); +//! [18] + + +//! [19] +QMutableListIterator<int> i(list); +while (i.hasNext()) { + int val = i.next(); + if (val < -32768 || val > 32767) + i.remove(); +} +//! [19] + + +//! [20] +QMutableLinkedListIterator<int> i(list); +while (i.hasNext()) { + int val = i.next(); + if (val < -32768 || val > 32767) + i.remove(); +} +//! [20] + + +//! [21] +QMutableVectorIterator<int> i(vector); +while (i.hasNext()) { + int val = i.next(); + if (val < -32768 || val > 32767) + i.remove(); +} +//! [21] + + +//! [22] +QMutableSetIterator<int> i(set); +while (i.hasNext()) { + int val = i.next(); + if (val < -32768 || val > 32767) + i.remove(); +} +//! [22] + + +//! [23] +QMutableListIterator<double> i(list); +while (i.hasNext()) { + double val = i.next(); + i.setValue(sqrt(val)); +} +//! [23] + + +//! [24] +QMutableLinkedListIterator<double> i(list); +while (i.hasNext()) { + double val = i.next(); + i.setValue(sqrt(val)); +} +//! [24] + + +//! [25] +QMutableVectorIterator<double> i(list); +while (i.hasNext()) { + double val = i.next(); + i.setValue(sqrt(val)); +} +//! [25] + + +//! [26] +QMap<int, QWidget *> map; +... +QMapIterator<int, QWidget *> i(map); +while (i.hasNext()) { + i.next(); + qDebug() << i.key() << ": " << i.value(); +} +//! [26] + + +//! [27] +QMapIterator<int, QWidget *> i(map); +i.toBack(); +while (i.hasPrevious()) { + i.previous(); + qDebug() << i.key() << ": " << i.value(); +} +//! [27] + + +//! [28] +QMapIterator<int, QWidget *> i(map); +while (i.findNext(widget)) { + qDebug() << "Found widget " << widget << " under key " + << i.key(); +} +//! [28] + + +//! [29] +QHash<int, QWidget *> hash; +... +QHashIterator<int, QWidget *> i(hash); +while (i.hasNext()) { + i.next(); + qDebug() << i.key() << ": " << i.value(); +} +//! [29] + + +//! [30] +QHashIterator<int, QWidget *> i(hash); +i.toBack(); +while (i.hasPrevious()) { + i.previous(); + qDebug() << i.key() << ": " << i.value(); +} +//! [30] + + +//! [31] +QHashIterator<int, QWidget *> i(hash); +while (i.findNext(widget)) { + qDebug() << "Found widget " << widget << " under key " + << i.key(); +} +//! [31] + + +//! [32] +QMap<int, QWidget *> map; +... +QMutableMapIterator<int, QWidget *> i(map); +while (i.hasNext()) { + i.next(); + qDebug() << i.key() << ": " << i.value(); +} +//! [32] + + +//! [33] +QMutableMapIterator<int, QWidget *> i(map); +i.toBack(); +while (i.hasPrevious()) { + i.previous(); + qDebug() << i.key() << ": " << i.value(); +} +//! [33] + + +//! [34] +QMutableMapIterator<int, QWidget *> i(map); +while (i.findNext(widget)) { + qDebug() << "Found widget " << widget << " under key " + << i.key(); +} +//! [34] + + +//! [35] +QMutableMapIterator<QString, QString> i(map); +while (i.hasNext()) { + i.next(); + if (i.key() == i.value()) + i.remove(); +} +//! [35] + + +//! [36] +QHash<int, QWidget *> hash; +... +QMutableHashIterator<QString, QWidget *> i(hash); +while (i.hasNext()) { + i.next(); + qDebug() << i.key() << ": " << i.value(); +} +//! [36] + + +//! [37] +QMutableHashIterator<int, QWidget *> i(hash); +i.toBack(); +while (i.hasPrevious()) { + i.previous(); + qDebug() << i.key() << ": " << i.value(); +} +//! [37] + + +//! [38] +QMutableHashIterator<int, QWidget *> i(hash); +while (i.findNext(widget)) { + qDebug() << "Found widget " << widget << " under key " + << i.key(); +} +//! [38] + + +//! [39] +QMutableHashIterator<QString, QString> i(hash); +while (i.hasNext()) { + i.next(); + if (i.key() == i.value()) + i.remove(); +} +//! [39] diff --git a/doc/src/snippets/code/doc_src_qnamespace.cpp b/doc/src/snippets/code/doc_src_qnamespace.cpp new file mode 100644 index 0000000000..c512862325 --- /dev/null +++ b/doc/src/snippets/code/doc_src_qnamespace.cpp @@ -0,0 +1,59 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [1] +enum CustomEventPriority +{ + // An important event + ImportantEventPriority = Qt::HighEventPriority, + + // A more important event + MoreImportantEventPriority = ImportantEventPriority + 1, + + // A critical event + CriticalEventPriority = 100 * MoreImportantEventPriority, + + // Not that important + StatusEventPriority = Qt::LowEventPriority, + + // These are less important than Status events + IdleProcessingDoneEventPriority = StatusEventPriority - 1 +}; +//! [1] diff --git a/doc/src/snippets/code/doc_src_qnamespace.qdoc b/doc/src/snippets/code/doc_src_qnamespace.qdoc new file mode 100644 index 0000000000..6b5ce6a41d --- /dev/null +++ b/doc/src/snippets/code/doc_src_qnamespace.qdoc @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QObject::connect: Cannot queue arguments of type 'MyType' +//! [0] diff --git a/doc/src/snippets/code/doc_src_qpair.cpp b/doc/src/snippets/code/doc_src_qpair.cpp new file mode 100644 index 0000000000..a9a061e2c7 --- /dev/null +++ b/doc/src/snippets/code/doc_src_qpair.cpp @@ -0,0 +1,55 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QPair<QString, double> pair; +//! [0] + + +//! [1] +pair.first = "pi"; +pair.second = 3.14159265358979323846; +//! [1] + + +//! [2] +QList<QPair<int, double> > list; +list.append(qMakePair(66, 3.14159)); +//! [2] diff --git a/doc/src/snippets/code/doc_src_qplugin.cpp b/doc/src/snippets/code/doc_src_qplugin.cpp new file mode 100644 index 0000000000..fdacc08c3a --- /dev/null +++ b/doc/src/snippets/code/doc_src_qplugin.cpp @@ -0,0 +1,64 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +namespace Foo +{ + struct MyInterface { ... }; +} + +Q_DECLARE_INTERFACE(Foo::MyInterface, "org.examples.MyInterface") +//! [0] + + +//! [1] +Q_EXPORT_PLUGIN2(pnp_extrafilters, ExtraFiltersPlugin) +//! [1] + + +//! [2] +Q_IMPORT_PLUGIN(qjpeg) +//! [2] + + +//! [3] +TEMPLATE = app +QTPLUGIN += qjpeg qgif qmng # image formats +//! [3] diff --git a/doc/src/snippets/code/doc_src_qplugin.pro b/doc/src/snippets/code/doc_src_qplugin.pro new file mode 100644 index 0000000000..f3444e273a --- /dev/null +++ b/doc/src/snippets/code/doc_src_qplugin.pro @@ -0,0 +1,44 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#! [3] +TEMPLATE = app +QTPLUGIN += qjpeg qgif qmng # image formats +#! [3] diff --git a/doc/src/snippets/code/doc_src_qset.cpp b/doc/src/snippets/code/doc_src_qset.cpp new file mode 100644 index 0000000000..4a4953d452 --- /dev/null +++ b/doc/src/snippets/code/doc_src_qset.cpp @@ -0,0 +1,166 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QSet<QString> set; +//! [0] + + +//! [1] +set.insert("one"); +set.insert("three"); +set.insert("seven"); +//! [1] + + +//! [2] +set << "twelve" << "fifteen" << "nineteen"; +//! [2] + + +//! [3] +if (!set.contains("ninety-nine")) + ... +//! [3] + + +//! [4] +QSetIterator<QWidget *> i(set); +while (i.hasNext()) + qDebug() << i.next(); +//! [4] + + +//! [5] +QSet<QWidget *>::const_iterator i = set.constBegin(); +while (i != set.constEnd()) { + qDebug() << *i; + ++i; +} +//! [5] + + +//! [6] +QSet<QString> set; +... +foreach (const QString &value, set) + qDebug() << value; +//! [6] + + +//! [7] +QSet<QString> set; +set.reserve(20000); +for (int i = 0; i < 20000; ++i) + set.insert(values[i]); +//! [7] + + +//! [8] +QSet<QString> set; +set << "January" << "February" << ... << "December"; + +QSet<QString>::iterator i; +for (i = set.begin(); i != set.end(); ++i) + qDebug() << *i; +//! [8] + + +//! [9] +QSet<QString> set; +set << "January" << "February" << ... << "December"; + +QSet<QString>::iterator i = set.begin(); +while (i != set.end()) { + if ((*i).startsWith('J')) { + i = set.erase(i); + } else { + ++i; + } +} +//! [9] + + +//! [10] +QSet<QString> set; +... +QSet<QString>::iterator it = qFind(set.begin(), set.end(), "Jeanette"); +if (it != set.end()) + cout << "Found Jeanette" << endl; +//! [10] + + +//! [11] +QSet<QString> set; +set << "January" << "February" << ... << "December"; + +QSet<QString>::const_iterator i; +for (i = set.begin(); i != set.end(); ++i) + qDebug() << *i; +//! [11] + + +//! [12] +QSet<QString> set; +... +QSet<QString>::iterator it = qFind(set.begin(), set.end(), "Jeanette"); +if (it != set.constEnd()) + cout << "Found Jeanette" << endl; +//! [12] + + +//! [13] +QSet<QString> set; +set << "red" << "green" << "blue" << ... << "black"; + +QList<QString> list = set.toList(); +qSort(list); +//! [13] + + +//! [14] +QStringList list; +list << "Julia" << "Mike" << "Mike" << "Julia" << "Julia"; + +QSet<QString> set = QSet<QString>::fromList(list); +set.contains("Julia"); // returns true +set.contains("Mike"); // returns true +set.size(); // returns 2 +//! [14] diff --git a/doc/src/snippets/code/doc_src_qsignalspy.cpp b/doc/src/snippets/code/doc_src_qsignalspy.cpp new file mode 100644 index 0000000000..12462e2d74 --- /dev/null +++ b/doc/src/snippets/code/doc_src_qsignalspy.cpp @@ -0,0 +1,81 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QCheckBox *box = ...; +QSignalSpy spy(box, SIGNAL(clicked(bool))); + +// do something that triggers the signal +box->animateClick(); + +QCOMPARE(spy.count(), 1); // make sure the signal was emitted exactly one time +QList<QVariant> arguments = spy.takeFirst(); // take the first signal + +QVERIFY(arguments.at(0).toBool() == true); // verify the first argument +//! [0] + + +//! [1] +QSignalSpy spy(myCustomObject, SIGNAL(mySignal(int, QString, double))); + +myCustomObject->doSomething(); // trigger emission of the signal + +QList<QVariant> arguments = spy.takeFirst(); +QVERIFY(arguments.at(0).type() == QVariant::Int); +QVERIFY(arguments.at(1).type() == QVariant::QString); +QVERIFY(arguments.at(2).type() == QVariant::double); +//! [1] + + +//! [2] +qRegisterMetaType<QModelIndex>("QModelIndex"); +QSignalSpy spy(&model, SIGNAL(whatever(QModelIndex))); +//! [2] + + +//! [3] +// get the first argument from the first received signal: +QModelIndex result = qvariant_cast<QModelIndex>(spy.at(0).at(0)); +//! [3] + + +//! [4] +QSignalSpy spy(myPushButton, SIGNAL(clicked(bool))); +//! [4] diff --git a/doc/src/snippets/code/doc_src_qt4-mainwindow.cpp b/doc/src/snippets/code/doc_src_qt4-mainwindow.cpp new file mode 100644 index 0000000000..d0c758e644 --- /dev/null +++ b/doc/src/snippets/code/doc_src_qt4-mainwindow.cpp @@ -0,0 +1,110 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +MainWindow::MainWindow(QWidget *parent) + : QMainWindow(parent) +{ +//! [0] + + +//! [1] +fileToolbar->setAllowedAreas(Qt::TopToolBarArea | Qt::BottomToolBarArea); +addToolBar(Qt::TopToolBarArea, fileToolbar); +//! [1] + + +//! [2] +setCorner(Qt::TopLeftCorner, Qt::LeftDockWidgetArea); +setCorner(Qt::BottomLeftCorner, Qt::LeftDockWidgetArea); +setCorner(Qt::TopRightCorner, Qt::RightDockWidgetArea); +setCorner(Qt::BottomRightCorner, Qt::RightDockWidgetArea); +//! [2] + + +//! [3] +QWidget *centralWidget = new QWidget(this); +setCentralWidget(centralWidget); +//! [3] + + +//! [4] +QPopupMenu *fileMenu = new QPopupMenu(this); +openAction->addTo(fileMenu); +saveAction->addTo(fileMenu); +... +menuBar()->insertItem(tr("&File"), fileMenu); +//! [4] + + +//! [5] +QMenu *fileMenu = menuBar()->addMenu(tr("&File")); +fileMenu->addAction(openAction); +fileMenu->addAction(saveAction); +... +//! [5] + + +//! [6] +QToolBar *fileTools = new QToolBar(this, "file toolbar"); +openAction->addTo(fileTools); +saveAction->addTo(fileTools); +... +//! [6] + + +//! [7] +QToolBar *fileTools = addToolBar(tr("File Tool Bar")); +fileTools->addAction(openAction); +fileTools->addAction(saveAction); +... +//! [7] + + +//! [8] +QDockWidget *dockWidget = new QDockWidget(this); +mainWin->moveDockWidget(dockWidget, Qt::DockLeft); +//! [8] + + +//! [9] +QDockWidget *dockWidget = new QDockWidget(mainWindow); +mainWindow->addDockWidget(Qt::LeftDockWidgetArea, dockWidget); +//! [9] diff --git a/doc/src/snippets/code/doc_src_qt4-styles.cpp b/doc/src/snippets/code/doc_src_qt4-styles.cpp new file mode 100644 index 0000000000..effe3cd561 --- /dev/null +++ b/doc/src/snippets/code/doc_src_qt4-styles.cpp @@ -0,0 +1,82 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +const QStyleOptionFocusRect *focusRectOption = + qstyleoption_cast<const QStyleOptionFocusRect *>(option); +if (focusRectOption) { + ... +} +//! [0] + + +//! [1] +void MyWidget::paintEvent(QPaintEvent *event) +{ + QPainter painter(this); + ... + + QStyleOptionFocusRect option(1); + option.init(this); + option.backgroundColor = palette().color(QPalette::Window); + + style().drawPrimitive(QStyle::PE_FrameFocusRect, &option, &painter, + this); +} +//! [1] + + +//! [2] +void drawControl(ControlElement element, + QPainter *painter, + const QWidget *widget, + const QRect &rect, + const QColorGroup &colorGroup, + SFlags how = Style_Default, + const QStyleOption &option = QStyleOption::Default) const; +//! [2] + + +//! [3] +void drawControl(ControlElement element, + const QStyleOption *option, + QPainter *painter, + const QWidget *widget = 0) const; +//! [3] diff --git a/doc/src/snippets/code/doc_src_qtestevent.cpp b/doc/src/snippets/code/doc_src_qtestevent.cpp new file mode 100644 index 0000000000..fd1c819ac0 --- /dev/null +++ b/doc/src/snippets/code/doc_src_qtestevent.cpp @@ -0,0 +1,51 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QTestEventList events; +events.addKeyClick('a'); +events.addKeyClick(Qt::Key_Backspace); +events.addDelay(200); + +QLineEdit *lineEdit = new QLineEdit(myParent); +... +events.simulate(lineEdit); +events.simulate(lineEdit); +//! [0] diff --git a/doc/src/snippets/code/doc_src_qvarlengtharray.cpp b/doc/src/snippets/code/doc_src_qvarlengtharray.cpp new file mode 100644 index 0000000000..a9383301f5 --- /dev/null +++ b/doc/src/snippets/code/doc_src_qvarlengtharray.cpp @@ -0,0 +1,78 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +int myfunc(int n) +{ + int table[n + 1]; // WRONG + ... + return table[n]; +} +//! [0] + + +//! [1] +int myfunc(int n) +{ + int *table = new int[n + 1]; + ... + int ret = table[n]; + delete[] table; + return ret; +} +//! [1] + + +//! [2] +int myfunc(int n) +{ + QVarLengthArray<int, 1024> array(n + 1); + ... + return array[n]; +} +//! [2] + + +//! [3] +QVarLengthArray<int> array(10); +int *data = array.data(); +for (int i = 0; i < 10; ++i) + data[i] = 2 * i; +//! [3] diff --git a/doc/src/snippets/code/doc_src_resources.cpp b/doc/src/snippets/code/doc_src_resources.cpp new file mode 100644 index 0000000000..b965cbeb29 --- /dev/null +++ b/doc/src/snippets/code/doc_src_resources.cpp @@ -0,0 +1,54 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [4] +QResource::registerResource("/path/to/myresource.rcc"); +//! [4] + + +//! [5] +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + Q_INIT_RESOURCE(graphlib); + ... + return app.exec(); +} +//! [5] diff --git a/doc/src/snippets/code/doc_src_resources.qdoc b/doc/src/snippets/code/doc_src_resources.qdoc new file mode 100644 index 0000000000..0b727da461 --- /dev/null +++ b/doc/src/snippets/code/doc_src_resources.qdoc @@ -0,0 +1,65 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +<file alias="cut-img.png">images/cut.png</file> +//! [0] + + +//! [1] +<qresource prefix="/myresources"> + <file alias="cut-img.png">images/cut.png</file> +</qresource> +//! [1] + + +//! [2] +<qresource> + <file>cut.jpg</file> +</qresource> +<qresource lang="fr"> + <file alias="cut.jpg">cut_fr.jpg</file> +</qresource> +//! [2] + + +//! [3] +rcc -binary myresource.qrc -o myresource.rcc +//! [3] diff --git a/doc/src/snippets/code/doc_src_sql-driver.cpp b/doc/src/snippets/code/doc_src_sql-driver.cpp new file mode 100644 index 0000000000..56e4f9bcdb --- /dev/null +++ b/doc/src/snippets/code/doc_src_sql-driver.cpp @@ -0,0 +1,82 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [2] +QSqlQuery q; +q.exec("call qtestproc (@outval1, @outval2)"); +q.exec("select @outval1, @outval2"); +q.next(); +qDebug() << q.value(0) << q.value(1); // outputs "42" and "43" +//! [2] + + +//! [10] +// STORED_PROC uses the return statement or returns multiple result sets +QSqlQuery query; +query.setForwardOnly(true); +query.exec("{call STORED_PROC}"); +//! [10] + + +//! [24] +db.setHostName("MyServer"); +db.setDatabaseName("C:\\test.gdb"); +//! [24] + + +//! [25] +// connect to database using the Latin-1 character set +db.setConnectOptions("ISC_DPB_LC_CTYPE=Latin1"); +db.open(); +//! [25] + + +//! [26] +QSqlQuery q; +q.exec("execute procedure my_procedure"); +q.next(); +qDebug() << q.value(0); // outputs the first RETURN/OUT value +//! [26] + + +//! [31] +QSqlDatabase: QMYSQL driver not loaded +QSqlDatabase: available drivers: QMYSQL +//! [31] diff --git a/doc/src/snippets/code/doc_src_sql-driver.qdoc b/doc/src/snippets/code/doc_src_sql-driver.qdoc new file mode 100644 index 0000000000..46cd1b3f3e --- /dev/null +++ b/doc/src/snippets/code/doc_src_sql-driver.qdoc @@ -0,0 +1,235 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +-no-sql-<driver> ... Disable SQL <driver> entirely. +-qt-sql-<driver> ... Enable a SQL <driver> in the Qt Library, by default + none are turned on. +-plugin-sql-<driver> Enable SQL <driver> as a plugin to be linked to + at run time. + + Possible values for <driver>: + [ db2 ibase mysql oci odbc psql sqlite sqlite2 tds ] +//! [0] + + +//! [1] +create procedure qtestproc (OUT param1 INT, OUT param2 INT) +BEGIN + set param1 = 42; + set param2 = 43; +END +//! [1] + + +//! [3] +cd $QTDIR/src/plugins/sqldrivers/mysql +qmake "INCLUDEPATH+=/usr/local/include" "LIBS+=-L/usr/local/lib -lmysqlclient_r" mysql.pro +make +//! [3] + + +//! [4] +cd $QTDIR/src/plugins/sqldrivers/mysql +make install +//! [4] + + +//! [5] +cd %QTDIR%\src\plugins\sqldrivers\mysql +qmake "INCLUDEPATH+=C:\MySQL\include" "LIBS+=C:\MYSQL\MySQL Server <version>\lib\opt\libmysql.lib" mysql.pro +nmake +//! [5] + + +//! [6] +cd $QTDIR/src/plugins/sqldrivers/oci +qmake "INCLUDEPATH+=$ORACLE_HOME/rdbms/public $ORACLE_HOME/rdbms/demo" "LIBS+=-L$ORACLE_HOME/lib -lclntsh -lwtc9" oci.pro +make +//! [6] + + +//! [7] +cd $QTDIR/src/plugins/sqldrivers/oci +qmake "INCLUDEPATH+=/usr/include/oracle/10.1.0.3/client/" "LIBS+=-L/usr/lib/oracle/10.1.0.3/client/lib -lclntsh" oci.pro +make +//! [7] + + +//! [8] +set INCLUDE=%INCLUDE%;c:\oracle\oci\include +set LIB=%LIB%;c:\oracle\oci\lib\msvc +cd %QTDIR%\src\plugins\sqldrivers\oci +qmake oci.pro +nmake +//! [8] + + +//! [9] +set PATH=%PATH%;c:\oracle\bin +//! [9] + + +//! [11] +cd $QTDIR/src/plugins/sqldrivers/odbc +qmake "INCLUDEPATH+=/usr/local/unixODBC/include" "LIBS+=-L/usr/local/unixODBC/lib -lodbc" +make +//! [11] + + +//! [12] +cd %QTDIR%\src\plugins\sqldrivers\odbc +qmake odbc.pro +nmake +//! [12] + + +//! [13] +cd $QTDIR/src/plugins/sqldrivers/psql +qmake "INCLUDEPATH+=/usr/include/pgsql" "LIBS+=-L/usr/lib -lpq" psql.pro +make +//! [13] + + +//! [14] +cd $QTDIR/src/plugins/sqldrivers/psql +make install +//! [14] + + +//! [15] +cd %QTDIR%\src\plugins\sqldrivers\psql +qmake "INCLUDEPATH+=C:\psql\include" "LIBS+=C:\psql\lib\ms\libpq.lib" psql.pro +nmake +//! [15] + + +//! [16] +cd $QTDIR/src/plugins/sqldrivers/tds +qmake "INCLUDEPATH=$SYBASE/include" "LIBS=-L$SYBASE/lib -lsybdb" +make +//! [16] + + +//! [17] +cd %QTDIR%\src\plugins\sqldrivers\tds +qmake "LIBS+=NTWDBLIB.LIB" tds.pro +nmake +//! [17] + + +//! [18] +cd $QTDIR/src/plugins/sqldrivers/db2 +qmake "INCLUDEPATH+=$DB2DIR/include" "LIBS+=-L$DB2DIR/lib -ldb2" +make +//! [18] + + +//! [19] +cd $QTDIR/src/plugins/sqldrivers/db2 +make install +//! [19] + + +//! [20] +cd %QTDIR%\src\plugins\sqldrivers\db2 +qmake "INCLUDEPATH+=<DB2 home>/sqllib/include" "LIBS+=<DB2 home>/sqllib/lib/db2cli.lib" +nmake +//! [20] + + +//! [21] +cd $QTDIR/src/plugins/sqldrivers/sqlite +qmake "INCLUDEPATH+=$SQLITE/include" "LIBS+=-L$SQLITE/lib -lsqlite" +make +//! [21] + + +//! [22] +cd $QTDIR/src/plugins/sqldrivers/sqlite +make install +//! [22] + + +//! [23] +cd %QTDIR%\src\plugins\sqldrivers\sqlite +qmake "INCLUDEPATH+=C:\SQLITE\INCLUDE" "LIBS+=C:\SQLITE\LIB\SQLITE3.LIB" sqlite.pro +nmake +//! [23] + + +//! [27] +cd $QTDIR/src/plugins/sqldrivers/ibase +qmake "INCLUDEPATH+=/opt/interbase/include" "LIBS+=-L/opt/interbase/lib" ibase.pro +make +//! [27] + + +//! [28] +cd $QTDIR/src/plugins/sqldrivers/ibase +qmake "INCLUDEPATH+=/opt/interbase/include" "LIBS+=-L/opt/interbase/lib -lfbclient" ibase.pro +make +//! [28] + + +//! [29] +cd %QTDIR%\src\plugins\sqldrivers\ibase +qmake "INCLUDEPATH+=C:\interbase\include" ibase.pro +nmake +//! [29] + + +//! [30] +cd %QTDIR%\src\plugins\sqldrivers\ibase +qmake "INCLUDEPATH+=C:\interbase\include" "LIBS+=-lfbclient" ibase.pro +nmake +//! [30] + + +//! [32] +configure -I /usr/include/oracle/10.1.0.3/client -L /usr/lib/oracle/10.1.0.3/client/lib -R /usr/lib/oracle/10.1.0.3/client/lib -lclntsh -lnnz10 +make +//! [32] + +//! [33] +cd $QTDIR/src/plugins/sqldrivers/oci +qmake "INCLUDEPATH+=/usr/include/oracle/10.1.0.3/client" "LIBS+=-L/usr/lib/oracle/10.1.0.3/client/lib -Wl,-rpath,/usr/lib/oracle/10.1.0.3/client/lib -lclntsh -lnnz10" oci.pro +make +//! [33] diff --git a/doc/src/snippets/code/doc_src_styles.cpp b/doc/src/snippets/code/doc_src_styles.cpp new file mode 100644 index 0000000000..a2a6fa9694 --- /dev/null +++ b/doc/src/snippets/code/doc_src_styles.cpp @@ -0,0 +1,134 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] + opt.initFrom(q); + if (down) + opt.state |= QStyle::State_Sunken; + if (tristate && noChange) + opt.state |= QStyle::State_NoChange; + else + opt.state |= checked ? QStyle::State_On : + QStyle::State_Off; + if (q->testAttribute(Qt::WA_Hover) && q->underMouse()) { + if (hovering) + opt.state |= QStyle::State_MouseOver; + else + opt.state &= ~QStyle::State_MouseOver; + } + opt.text = text; + opt.icon = icon; + opt.iconSize = q->iconSize(); +//! [0] + + +//! [1] + state = QStyle::State_None; + if (widget->isEnabled()) + state |= QStyle::State_Enabled; + if (widget->hasFocus()) + state |= QStyle::State_HasFocus; + if (widget->window()->testAttribute(Qt::WA_KeyboardFocusChange)) + state |= QStyle::State_KeyboardFocusChange; + if (widget->underMouse()) + state |= QStyle::State_MouseOver; + if (widget->window()->isActiveWindow()) + state |= QStyle::State_Active; +#ifdef Q_WS_MAC + extern bool qt_mac_can_clickThrough(const QWidget *w); //qwidget_mac.cpp + if (!(state & QStyle::State_Active) && !qt_mac_can_clickThrough(widget)) + state &= ~QStyle::State_Enabled; +#endif +#ifdef QT_KEYPAD_NAVIGATION + if (widget->hasEditFocus()) + state |= QStyle::State_HasEditFocus; +#endif + + direction = widget->layoutDirection(); + rect = widget->rect(); + palette = widget->palette(); + fontMetrics = widget->fontMetrics(); +//! [1] + + +//! [2] + QStylePainter p(this); + QStyleOptionButton opt = d->getStyleOption(); + p.drawControl(QStyle::CE_CheckBox, opt); +//! [2] + + +//! [3] + QStyleOptionButton subopt = *btn; + subopt.rect = subElementRect(SE_CheckBoxIndicator, btn, widget); + drawPrimitive(PE_IndicatorCheckBox, &subopt, p, widget); + subopt.rect = subElementRect(SE_CheckBoxContents, btn, widget); + drawControl(CE_CheckBoxLabel, &subopt, p, widget); + + if (btn->state & State_HasFocus) { + QStyleOptionFocusRect fropt; + fropt.QStyleOption::operator=(*btn); + fropt.rect = subElementRect(SE_CheckBoxFocusRect, btn, widget); + drawPrimitive(PE_FrameFocusRect, &fropt, p, widget); + } +//! [3] + + +//! [4] + const QStyleOptionButton *btn = qstyleoption_cast<const QStyleOptionButton *>(opt); + uint alignment = visualAlignment(btn->direction, Qt::AlignLeft | Qt::AlignVCenter); + + if (!styleHint(SH_UnderlineShortcut, btn, widget)) + alignment |= Qt::TextHideMnemonic; + QPixmap pix; + QRect textRect = btn->rect; + if (!btn->icon.isNull()) { + pix = btn->icon.pixmap(btn->iconSize, btn->state & State_Enabled ? QIcon::Normal : QIcon::Disabled); + drawItemPixmap(p, btn->rect, alignment, pix); + if (btn->direction == Qt::RightToLeft) + textRect.setRight(textRect.right() - btn->iconSize.width() - 4); + else + textRect.setLeft(textRect.left() + btn->iconSize.width() + 4); + } + if (!btn->text.isEmpty()){ + drawItemText(p, textRect, alignment | Qt::TextShowMnemonic, + btn->palette, btn->state & State_Enabled, btn->text, QPalette::WindowText); + } +//! [4] diff --git a/doc/src/snippets/code/doc_src_stylesheet.cpp b/doc/src/snippets/code/doc_src_stylesheet.cpp new file mode 100644 index 0000000000..3faaf2d037 --- /dev/null +++ b/doc/src/snippets/code/doc_src_stylesheet.cpp @@ -0,0 +1,140 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [21] +qApp->setStyleSheet("QPushButton { color: white }"); +//! [21] + + +//! [22] +myPushButton->setStyleSheet("* { color: blue }"); +//! [22] + + +//! [23] +myPushButton->setStyleSheet("color: blue"); +//! [23] + + +//! [24] +qApp->setStyleSheet("QGroupBox { color: red; } "); +//! [24] + +//! [25] +qApp->setStyleSheet("QGroupBox, QGroupBox * { color: red; }"); +//! [25] + + +//! [26] +class MyPushButton : public QPushButton { + // ... +} + +// ... +qApp->setStyleSheet("MyPushButton { background: yellow; }"); +//! [26] + + +//! [27] +namespace ns { + class MyPushButton : public QPushButton { + // ... + } +} + +// ... +qApp->setStyleSheet("ns--MyPushButton { background: yellow; }"); +//! [27] + + +//! [32] +void CustomWidget::paintEvent(QPaintEvent *) +{ + QStyleOption opt; + opt.init(this); + QPainter p(this); + style()->drawPrimitive(QStyle::PE_Widget, &opt, &p, this); +} +//! [32] + + +//! [88] +qApp->setStyleSheet("QLineEdit { background-color: yellow }"); +//! [88] + + +//! [89] +myDialog->setStyleSheet("QLineEdit { background-color: yellow }"); +//! [89] + + +//! [90] +myDialog->setStyleSheet("QLineEdit#nameEdit { background-color: yellow }"); +//! [90] + + +//! [91] +nameEdit->setStyleSheet("background-color: yellow"); +//! [91] + + +//! [92] +nameEdit->setStyleSheet("color: blue; background-color: yellow"); +//! [92] + + +//! [93] +nameEdit->setStyleSheet("color: blue;" + "background-color: yellow;" + "selection-color: yellow;" + "selection-background-color: blue;"); +//! [93] + + +//! [95] +QLineEdit *nameEdit = new QLineEdit(this); +nameEdit->setProperty("mandatoryField", true); + +QLineEdit *emailEdit = new QLineEdit(this); +emailEdit->setProperty("mandatoryField", true); + +QSpinBox *ageSpinBox = new QSpinBox(this); +ageSpinBox->setProperty("mandatoryField", true); +//! [95] diff --git a/doc/src/snippets/code/doc_src_stylesheet.qdoc b/doc/src/snippets/code/doc_src_stylesheet.qdoc new file mode 100644 index 0000000000..99b31c9387 --- /dev/null +++ b/doc/src/snippets/code/doc_src_stylesheet.qdoc @@ -0,0 +1,1866 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QLineEdit { background: yellow } +QCheckBox { color: red } +//! [0] + + +//! [1] +QPushButton { color: red } +//! [1] + + +//! [2] +QPushButton, QLineEdit, QComboBox { color: red } +//! [2] + + +//! [3] +QPushButton { color: red } +QLineEdit { color: red } +QComboBox { color: red } +//! [3] + + +//! [4] +QPushButton { color: red; background-color: white } +//! [4] + + +//! [5] +QComboBox::drop-down { image: url(dropdown.png) } +//! [5] + + +//! [6] +QComboBox { + margin-right: 20px; +} +QComboBox::drop-down { + subcontrol-origin: margin; +} +//! [6] + + +//! [7] +QComboBox::down-arrow { + image: url(down_arrow.png); +} +QComboBox::down-arrow:pressed { + position: relative; + top: 1px; left: 1px; +} +//! [7] + + +//! [8] +QPushButton:hover { color: white } +//! [8] + + +//! [9] +QRadioButton:!hover { color: red } +//! [9] + + +//! [10] +QCheckBox:hover:checked { color: white } +//! [10] + + +//! [11] +QPushButton:hover:!pressed { color: blue; } +//! [11] + + +//! [12] +QCheckBox:hover, QCheckBox:checked { color: white } +//! [12] + + +//! [13] +QComboBox::drop-down:hover { image: url(dropdown_bright.png) } +//! [13] + + +//! [14] +QPushButton#okButton { color: gray } +QPushButton { color: red } +//! [14] + + +//! [15] +QPushButton:hover { color: white } +QPushButton { color: red } +//! [15] + + +//! [16] +QPushButton:hover { color: white } +QPushButton:enabled { color: red } +//! [16] + + +//! [17] +QPushButton:enabled { color: red } +QPushButton:hover { color: white } +//! [17] + + +//! [18] +QPushButton:hover:enabled { color: white } +QPushButton:enabled { color: red } +//! [18] + + +//! [19] +QPushButton { color: red } +QAbstractButton { color: gray } +//! [19] + + +//! [20] +* {} /* a=0 b=0 c=0 -> specificity = 0 */ +LI {} /* a=0 b=0 c=1 -> specificity = 1 */ +UL LI {} /* a=0 b=0 c=2 -> specificity = 2 */ +UL OL+LI {} /* a=0 b=0 c=3 -> specificity = 3 */ +H1 + *[REL=up]{} /* a=0 b=1 c=1 -> specificity = 11 */ +UL OL LI.red {} /* a=0 b=1 c=3 -> specificity = 13 */ +LI.red.level {} /* a=0 b=2 c=1 -> specificity = 21 */ +#x34y {} /* a=1 b=0 c=0 -> specificity = 100 */ +//! [20] + + +//! [28] +MyLabel { qproperty-pixmap: url(pixmap.png); } +MyGroupBox { qproperty-titleColor: rgb(100, 200, 100); } +QPushButton { qproperty-iconSize: 20px 20px; } +//! [28] + + +//! [30] +QPushButton { background-color: red; border: none; } +//! [30] + + +//! [31] +QToolButton { background-color: red; border: none; } +//! [31] + + +//! [33] +QTreeView { + alternate-background-color: blue; + background: yellow; +} +//! [33] + + +//! [34] +QTextEdit { background: yellow } +//! [34] + + +//! [35] +QLabel { + background-image: url(dense6pattern.png); + background-repeat: repeat-xy; +} +//! [35] + + +//! [36] +QLabel { background-color: yellow } +QLineEdit { background-color: rgb(255, 0, 0) } +//! [36] + + +//! [37] +QFrame { background-image: url(:/images/hydro.png) } +//! [37] + + +//! [38] +QFrame { + background: white url(:/images/ring.png); + background-repeat: repeat-y; + background-position: left; +} +//! [38] + + +//! [39] +QFrame { + background: url(:/images/footer.png); + background-position: bottom left; +} +//! [39] + + +//! [40] +QTextEdit { + background-image: url("leaves.png"); + background-attachment: fixed; +} +//! [40] + + +//! [41] +QFrame { + background-image: url(:/images/header.png); + background-position: top left; + background-origin: content; + background-clip: padding; +} +//! [41] + + +//! [42] +QFrame { + background-image: url(:/images/header.png); + background-position: top left; + background-origin: content; +} +//! [42] + + +//! [43] +QLineEdit { border: 1px solid white } +//! [43] + + +//! [44] +QLineEdit { + border-width: 1px; + border-style: solid; + border-color: white; +} +//! [44] + + +//! [45] +QLineEdit { + border-width: 1px; + border-style: solid; + border-radius: 4px; +} +//! [45] + + +//! [46] +QLineEdit { + border-width: 1px; + border-style: solid; + border-color: blue; +} +//! [46] + + +//! [47] +QLineEdit { + border-width: 2px; + border-style: solid; + border-color: darkblue; +} +//! [47] + + +//! [48] +QSpinBox::down-button { bottom: 2px } +//! [48] + + +//! [49] +* { button-layout: 2 } +//! [49] + + +//! [50] +QPushButton { color: red } +//! [50] + + +//! [51] +QDialogButtonBox { dialogbuttonbox-buttons-have-icons: 1; } +//! [51] + + +//! [52] +* { etch-disabled-text: 1 } +//! [52] + + +//! [53] +QCheckBox { font: bold italic large "Times New Roman" } +//! [53] + + +//! [54] +QCheckBox { font-family: "New Century Schoolbook" } +//! [54] + + +//! [55] +QTextEdit { font-size: 12px } +//! [55] + + +//! [56] +QTextEdit { font-style: italic } +//! [56] + + +//! [57] +* { gridline-color: gray } +//! [57] + + +//! [58] +QSpinBox::down-button { height: 10px } +//! [58] + + +//! [59] +/* implicitly sets the size of down-button to the size of spindown.png */ +QSpinBox::down-button { image: url(:/images/spindown.png) } +//! [59] + + +//! [60] +QSpinBox::down-button { left: 2px } +//! [60] + + +//! [61] +* { lineedit-password-character: 9679 } +//! [61] + + +//! [62] +QLineEdit { margin: 2px } +//! [62] + + +//! [63] +QSpinBox { max-height: 24px } +//! [63] + + +//! [64] +QComboBox { max-width: 72px } +//! [64] + + +//! [65] +QMessageBox { messagebox-text-interaction-flags: 5 } +//! [65] + + +//! [66] +QComboBox { min-height: 24px } +//! [66] + + +//! [67] +QComboBox { min-width: 72px } +//! [67] + + +//! [68] +QToolTip { opacity: 223 } +//! [68] + + +//! [69] +QLineEdit { padding: 3px } +//! [69] + + +//! [70] +QSpinBox::down-button { right: 2px } +//! [70] + + +//! [71] +QTextEdit { selection-background-color: darkblue } +//! [71] + + +//! [72] +QTextEdit { selection-color: white } +//! [72] + + +//! [73] +* { show-decoration-selected: 1 } +//! [73] + + +//! [74] +QMenuBar { spacing: 10 } +//! [74] + + +//! [75] +QSpinBox::up-button { + image: url(:/images/spinup.png); + subcontrol-origin: content; + subcontrol-position: right top; +} +//! [75] + + +//! [76] +QSpinBox::down-button { + image: url(:/images/spindown.png); + subcontrol-origin: padding; + subcontrol-position: right bottom; +} +//! [76] + + +//! [77] +QPushButton { + text-align: left; +} +//! [77] + + +//! [78] +QSpinBox::up-button { top: 2px } +//! [78] + + +//! [79] +QSpinBox::up-button { width: 12px } +//! [79] + + +//! [80] +QTextEdit { background-position: bottom center } +//! [80] + + +//! [81] +QDialog { etch-disabled-text: 1 } +//! [81] + + +//! [82] +QLabel { border-color: red } /* red red red red */ +QLabel { border-color: red blue } /* red blue red blue */ +QLabel { border-color: red blue green } /* red blue green blue */ +QLabel { border-color: red blue green yellow } /* red blue green yellow */ +//! [82] + + +//! [83] +QLabel { border-width: 1px } /* 1px 1px 1px 1px */ +QLabel { border-width: 1px 2px } /* 1px 2px 1px 2px */ +QLabel { border-width: 1px 2px 3px } /* 1px 2px 3px 2px */ +QLabel { border-width: 1px 2px 3px 4px } /* 1px 2px 3px 4px */ +//! [83] + + +//! [84] +QLabel { border-color: red } /* opaque red */ +QLabel { border-color: #FF0000 } /* opaque red */ +QLabel { border-color: rgba(255, 0, 0, 75%) } /* 75% opaque red */ +QLabel { border-color: rgb(255, 0, 0) } /* opaque red */ +QLabel { border-color: rgb(100%, 0%, 0%) } /* opaque red */ +QLabel { border-color: hsv(60, 255, 255) } /* opaque yellow */ +QLabel { border-color: hsva(240, 255, 255, 75%) } /* 75% blue */ +//! [84] + + +//! [85] +/* linear gradient from white to green */ +QTextEdit { + background: qlineargradient(x1:0, y1:0, x2:1, y2:1, + stop:0 white, stop: 0.4 gray, stop:1 green) +} + +/* linear gradient from white to green */ +QTextEdit { + background: qlineargradient(x1:0, y1:0, x2:1, y2:1, + stop:0 white, stop: 0.4 rgba(10, 20, 30, 40), stop:1 rgb(0, 200, 230, 200)) +} + + +/* conical gradient from white to green */ +QTextEdit { + background: qconicalgradient(cx:0.5, cy:0.5, angle:30, + stop:0 white, stop:1 #00FF00) +} + +/* radial gradient from white to green */ +QTextEdit { + background: qradialgradient(cx:0, cy:0, radius: 1, + fx:0.5, fy:0.5, stop:0 white, stop:1 green) +} +//! [85] + + +//! [86] +* { + file-icon: url(file.png), + url(file_selected.png) selected; + } + +QMessageBox { + dialogbuttonbox-buttons-have-icons: true; + dialog-ok-icon: url(ok.svg); + dialog-cancel-icon: url(cancel.png), url(grayed_cancel.png) disabled; +} +//! [86] + + +//! [87] +QPushButton { color: palette(dark); } +//! [87] + + +//! [94] +*[mandatoryField="true"] { background-color: yellow } +//! [94] + + +//! [96] +QPushButton#evilButton { background-color: red } +//! [96] + + +//! [97] +QPushButton#evilButton { + background-color: red; + border-style: outset; + border-width: 2px; + border-color: beige; +} +//! [97] + + +//! [98] +QPushButton#evilButton { + background-color: red; + border-style: outset; + border-width: 2px; + border-radius: 10px; + border-color: beige; + font: bold 14px; + min-width: 10em; + padding: 6px; +} +//! [98] + + +//! [99] +QPushButton#evilButton { + background-color: red; + border-style: outset; + border-width: 2px; + border-radius: 10px; + border-color: beige; + font: bold 14px; + min-width: 10em; + padding: 6px; +} +QPushButton#evilButton:pressed { + background-color: rgb(224, 0, 0); + border-style: inset; +} +//! [99] + + +//! [100] +QPushButton#evilButton::menu-indicator { + image: url(myindicator.png); +} +//! [100] + + +//! [101] +QPushButton::menu-indicator { + image: url(myindicator.png); + subcontrol-position: right center; + subcontrol-origin: padding; + left: -2px; +} +//! [101] + + +//! [102] +QLineEdit { color: red } +//! [102] + + +//! [103] +QLineEdit { color: red } +QLineEdit[readOnly="true"] { color: gray } +//! [103] + + +//! [104] +QLineEdit { color: red } +QLineEdit[readOnly="true"] { color: gray } +#registrationDialog QLineEdit { color: brown } +//! [104] + + +//! [105] +QLineEdit { color: red } +QLineEdit[readOnly="true"] { color: gray } +QDialog QLineEdit { color: brown } +//! [105] + + +//! [106] +QTextEdit, QListView { + background-color: white; + background-image: url(draft.png); + background-attachment: scroll; +} +//! [106] + + +//! [107] +QTextEdit, QListView { + background-color: white; + background-image: url(draft.png); + background-attachment: fixed; +} +//! [107] + + +//! [108] +QCheckBox { + spacing: 5px; +} + +QCheckBox::indicator { + width: 13px; + height: 13px; +} + +QCheckBox::indicator:unchecked { + image: url(:/images/checkbox_unchecked.png); +} + +QCheckBox::indicator:unchecked:hover { + image: url(:/images/checkbox_unchecked_hover.png); +} + +QCheckBox::indicator:unchecked:pressed { + image: url(:/images/checkbox_unchecked_pressed.png); +} + +QCheckBox::indicator:checked { + image: url(:/images/checkbox_checked.png); +} + +QCheckBox::indicator:checked:hover { + image: url(:/images/checkbox_checked_hover.png); +} + +QCheckBox::indicator:checked:pressed { + image: url(:/images/checkbox_checked_pressed.png); +} + +QCheckBox::indicator:indeterminate:hover { + image: url(:/images/checkbox_indeterminate_hover.png); +} + +QCheckBox::indicator:indeterminate:pressed { + image: url(:/images/checkbox_indeterminate_pressed.png); +} +//! [108] + + +//! [109] +QComboBox { + border: 1px solid gray; + border-radius: 3px; + padding: 1px 18px 1px 3px; + min-width: 6em; +} + +QComboBox:editable { + background: white; +} + +QComboBox:!editable, QComboBox::drop-down:editable { + background: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1, + stop: 0 #E1E1E1, stop: 0.4 #DDDDDD, + stop: 0.5 #D8D8D8, stop: 1.0 #D3D3D3); +} + +/* QComboBox gets the "on" state when the popup is open */ +QComboBox:!editable:on, QComboBox::drop-down:editable:on { + background: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1, + stop: 0 #D3D3D3, stop: 0.4 #D8D8D8, + stop: 0.5 #DDDDDD, stop: 1.0 #E1E1E1); +} + +QComboBox:on { /* shift the text when the popup opens */ + padding-top: 3px; + padding-left: 4px; +} + +QComboBox::drop-down { + subcontrol-origin: padding; + subcontrol-position: top right; + width: 15px; + + border-left-width: 1px; + border-left-color: darkgray; + border-left-style: solid; /* just a single line */ + border-top-right-radius: 3px; /* same radius as the QComboBox */ + border-bottom-right-radius: 3px; +} + +QComboBox::down-arrow { + image: url(/usr/share/icons/crystalsvg/16x16/actions/1downarrow.png); +} + +QComboBox::down-arrow:on { /* shift the arrow when popup is open */ + top: 1px; + left: 1px; +} +//! [109] + + +//! [110] +QComboBox QAbstractItemView { + border: 2px solid darkgray; + selection-background-color: lightgray; +} +//! [110] + + +//! [111] +QDockWidget { + border: 1px solid lightgray; + titlebar-close-icon: url(close.png); + titlebar-normal-icon: url(undock.png); +} + +QDockWidget::title { + text-align: left; /* align the text to the left */ + background: lightgray; + padding-left: 5px; +} + +QDockWidget::close-button, QDockWidget::float-button { + border: 1px solid transparent; + background: darkgray; + padding: 0px; +} + +QDockWidget::close-button:hover, QDockWidget::float-button:hover { + background: gray; +} + +QDockWidget::close-button:pressed, QDockWidget::float-button:pressed { + padding: 1px -1px -1px 1px; +} +//! [111] + + +//! [112] +QDockWidget { + border: 1px solid lightgray; + titlebar-close-icon: url(close.png); + titlebar-normal-icon: url(float.png); +} + +QDockWidget::title { + text-align: left; + background: lightgray; + padding-left: 35px; +} + +QDockWidget::close-button, QDockWidget::float-button { + background: darkgray; + padding: 0px; + icon-size: 14px; /* maximum icon size */ +} + +QDockWidget::close-button:hover, QDockWidget::float-button:hover { + background: gray; +} + +QDockWidget::close-button:pressed, QDockWidget::float-button:pressed { + padding: 1px -1px -1px 1px; +} + +QDockWidget::close-button { + subcontrol-position: top left; + subcontrol-origin: margin; + position: absolute; + top: 0px; left: 0px; bottom: 0px; + width: 14px; +} + +QDockWidget::float-button { + subcontrol-position: top left; + subcontrol-origin: margin; + position: absolute; + top: 0px; left: 16px; bottom: 0px; + width: 14px; +} +//! [112] + + +//! [113] +QFrame, QLabel, QToolTip { + border: 2px solid green; + border-radius: 4px; + padding: 2px; + background-image: url(images/welcome.png); +} +//! [113] + + +//! [114] +QGroupBox { + background-color: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1, + stop: 0 #E0E0E0, stop: 1 #FFFFFF); + border: 2px solid gray; + border-radius: 5px; + margin-top: 1ex; /* leave space at the top for the title */ +} + +QGroupBox::title { + subcontrol-origin: margin; + subcontrol-position: top center; /* position at the top center */ + padding: 0 3px; + background-color: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1, + stop: 0 #FFOECE, stop: 1 #FFFFFF); +} +//! [114] + + +//! [115] +QGroupBox::indicator { + width: 13px; + height: 13px; +} + +QGroupBox::indicator:unchecked { + image: url(:/images/checkbox_unchecked.png); +} + +/* proceed with styling just like QCheckBox */ +//! [115] + + +//! [116] +QHeaderView::section { + background-color: qlineargradient(x1:0, y1:0, x2:0, y2:1, + stop:0 #616161, stop: 0.5 #505050, + stop: 0.6 #434343, stop:1 #656565); + color: white; + padding-left: 4px; + border: 1px solid #6c6c6c; +} + +QHeaderView::section:checked +{ + background-color: red; +} + +/* style the sort indicator */ +QHeaderView::down-arrow { + image: url(down_arrow.png); +} + +QHeaderView::up-arrow { + image: url(up_arrow.png); +} +//! [116] + + +//! [117] +QLineEdit { + border: 2px solid gray; + border-radius: 10px; + padding: 0 8px; + background: yellow; + selection-background-color: darkgray; +} +//! [117] + + +//! [118] +QLineEdit[echoMode="2"] { + lineedit-password-character: 9679; +} +//! [118] + + +//! [119] +QLineEdit:read-only { + background: lightblue; +//! [119] + + +//! [120] +QListView { + alternate-background-color: yellow; +} +//! [120] + + +//! [121] +QListView { + show-decoration-selected: 1; /* make the selection span the entire width of the view */ +} + +QListView::item:alternate { + background: #EEEEEE; +} + +QListView::item:selected { + border: 1px solid #6a6ea9; +} + +QListView::item:selected:!active { + background: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1, + stop: 0 #ABAFE5, stop: 1 #8588B2); +} + +QListView::item:selected:active { + background: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1, + stop: 0 #6a6ea9, stop: 1 #888dd9); +} + +QListView::item:hover { + background: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1, + stop: 0 #FAFBFE, stop: 1 #DCDEF1); +} +//! [121] + + +//! [122] +QMainWindow::separator { + background: yellow; + width: 10px; /* when vertical */ + height: 10px; /* when horizontal */ +} + +QMainWindow::separator:hover { + background: red; +} +//! [122] + + +//! [123] +QMenu { + background-color: #ABABAB; /* sets background of the menu */ + border: 1px solid black; +} + +QMenu::item { + /* sets background of menu item. set this to something non-transparent + if you want menu color and menu item color to be different */ + background-color: transparent; +} + +QMenu::item:selected { /* when user selects item using mouse or keyboard */ + background-color: #654321; +} +//! [123] + + +//! [124] +QMenu { + background-color: white; + margin: 2px; /* some spacing around the menu */ +} + +QMenu::item { + padding: 2px 25px 2px 20px; + border: 1px solid transparent; /* reserve space for selection border */ +} + +QMenu::item:selected { + border-color: darkblue; + background: rgba(100, 100, 100, 150); +} + +QMenu::icon:checked { /* appearance of a 'checked' icon */ + background: gray; + border: 1px inset gray; + position: absolute; + top: 1px; + right: 1px; + bottom: 1px; + left: 1px; +} + +QMenu::separator { + height: 2px; + background: lightblue; + margin-left: 10px; + margin-right: 5px; +} + +QMenu::indicator { + width: 13px; + height: 13px; +} + +/* non-exclusive indicator = check box style indicator (see QActionGroup::setExclusive) */ +QMenu::indicator:non-exclusive:unchecked { + image: url(:/images/checkbox_unchecked.png); +} + +QMenu::indicator:non-exclusive:unchecked:selected { + image: url(:/images/checkbox_unchecked_hover.png); +} + +QMenu::indicator:non-exclusive:checked { + image: url(:/images/checkbox_checked.png); +} + +QMenu::indicator:non-exclusive:checked:selected { + image: url(:/images/checkbox_checked_hover.png); +} + +/* exclusive indicator = radio button style indicator (see QActionGroup::setExclusive) */ +QMenu::indicator:exclusive:unchecked { + image: url(:/images/radiobutton_unchecked.png); +} + +QMenu::indicator:exclusive:unchecked:selected { + image: url(:/images/radiobutton_unchecked_hover.png); +} + +QMenu::indicator:exclusive:checked { + image: url(:/images/radiobutton_checked.png); +} + +QMenu::indicator:exclusive:checked:selected { + image: url(:/images/radiobutton_checked_hover.png); +} + +//! [124] + + +//! [125] +QMenuBar { + background-color: qlineargradient(x1:0, y1:0, x2:0, y2:1, + stop:0 lightgray, stop:1 darkgray); +} + +QMenuBar::item { + spacing: 3px; /* spacing between menu bar items */ + padding: 1px 4px; + background: transparent; + border-radius: 4px; +} + +QMenuBar::item:selected { /* when selected using mouse or keyboard */ + background: #a8a8a8; +} + +QMenuBar::item:pressed { + background: #888888; +} +//! [125] + + +//! [126] +QProgressBar { + border: 2px solid grey; + border-radius: 5px; +} + +QProgressBar::chunk { + background-color: #05B8CC; + width: 20px; +} +//! [126] + + +//! [127] +QProgressBar { + border: 2px solid grey; + border-radius: 5px; + text-align: center; +} +//! [127] + + +//! [128] +QProgressBar::chunk { + background-color: #CD96CD; + width: 10px; + margin: 0.5px; +} +//! [128] + + +//! [129] +QPushButton { + border: 2px solid #8f8f91; + border-radius: 6px; + background-color: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1, + stop: 0 #f6f7fa, stop: 1 #dadbde); + min-width: 80px; +} + +QPushButton:pressed { + background-color: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1, + stop: 0 #dadbde, stop: 1 #f6f7fa); +} + +QPushButton:flat { + border: none; /* no border for a flat push button */ +} + +QPushButton:default { + border-color: navy; /* make the default button prominent */ +} +//! [129] + + +//! [130] +QPushButton:open { /* when the button has its menu open */ + background-color: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1, + stop: 0 #dadbde, stop: 1 #f6f7fa); +} + +QPushButton::menu-indicator { + image: url(menu_indicator.png); + subcontrol-origin: padding; + subcontrol-position: bottom right; +} + +QPushButton::menu-indicator:pressed, QPushButton::menu-indicator:open { + position: relative; + top: 2px; left: 2px; /* shift the arrow by 2 px */ +} +//! [130] + + +//! [131] +QRadioButton::indicator { + width: 13px; + height: 13px; +} + +QRadioButton::indicator::unchecked { + image: url(:/images/radiobutton_unchecked.png); +} + +QRadioButton::indicator:unchecked:hover { + image: url(:/images/radiobutton_unchecked_hover.png); +} + +QRadioButton::indicator:unchecked:pressed { + image: url(:/images/radiobutton_unchecked_pressed.png); +} + +QRadioButton::indicator::checked { + image: url(:/images/radiobutton_checked.png); +} + +QRadioButton::indicator:checked:hover { + image: url(:/images/radiobutton_checked_hover.png); +} + +QRadioButton::indicator:checked:pressed { + image: url(:/images/radiobutton_checked_pressed.png); +} +//! [131] + + +//! [132] +QScrollBar:horizontal { + border: 2px solid grey; + background: #32CC99; + height: 15px; + margin: 0px 20px 0 20px; +} +//! [132] + + +//! [133] +QScrollBar::handle:horizontal { + background: white; + min-width: 20px; +} +//! [133] + + +//! [134] +QScrollBar::add-line:horizontal { + border: 2px solid grey; + background: #32CC99; + width: 20px; + subcontrol-position: right; + subcontrol-origin: margin; +} + +QScrollBar::sub-line:horizontal { + border: 2px solid grey; + background: #32CC99; + width: 20px; + subcontrol-position: left; + subcontrol-origin: margin; +} +//! [134] + + +//! [135] +QScrollBar:left-arrow:horizontal, QScrollBar::right-arrow:horizontal { + border: 2px solid grey; + width: 3px; + height: 3px; + background: white; +} + +QScrollBar::add-page:horizontal, QScrollBar::sub-page:horizontal { + background: none; +} +//! [135] + + +//! [136] +QScrollBar:horizontal { + border: 2px solid green; + background: cyan; + height: 15px; + margin: 0px 40px 0 0px; +} + +QScrollBar::handle:horizontal { + background: gray; + min-width: 20px; +} + +QScrollBar::add-line:horizontal { + background: blue; + width: 16px; + subcontrol-position: right; + subcontrol-origin: margin; + border: 2px solid black; +} + +QScrollBar::sub-line:horizontal { + background: magenta; + width: 16px; + subcontrol-position: top right; + subcontrol-origin: margin; + border: 2px solid black; + position: absolute; + right: 20px; +} + +QScrollBar:left-arrow:horizontal, QScrollBar::right-arrow:horizontal { + width: 3px; + height: 3px; + background: pink; +} + +QScrollBar::add-page:horizontal, QScrollBar::sub-page:horizontal { + background: none; +} + +//! [136] + + +//! [137] + QScrollBar:vertical { + border: 2px solid grey; + background: #32CC99; + width: 15px; + margin: 22px 0 22px 0; + } + QScrollBar::handle:vertical { + background: white; + min-height: 20px; + } + QScrollBar::add-line:vertical { + border: 2px solid grey; + background: #32CC99; + height: 20px; + subcontrol-position: bottom; + subcontrol-origin: margin; + } + + QScrollBar::sub-line:vertical { + border: 2px solid grey; + background: #32CC99; + height: 20px; + subcontrol-position: top; + subcontrol-origin: margin; + } + QScrollBar::up-arrow:vertical, QScrollBar::down-arrow:vertical { + border: 2px solid grey; + width: 3px; + height: 3px; + background: white; + } + + QScrollBar::add-page:vertical, QScrollBar::sub-page:vertical { + background: none; + } +//! [137] + + +//! [138] +QSizeGrip { + image: url(:/images/sizegrip.png); + width: 16px; + height: 16px; +} +//! [138] + + +//! [139] +QSlider::groove:horizontal { + border: 1px solid #999999; + height: 8px; /* the groove expands to the size of the slider by default. by giving it a height, it has a fixed size */ + background: qlineargradient(x1:0, y1:0, x2:0, y2:1, stop:0 #B1B1B1, stop:1 #c4c4c4); + margin: 2px 0; +} + +QSlider::handle:horizontal { + background: qlineargradient(x1:0, y1:0, x2:1, y2:1, stop:0 #b4b4b4, stop:1 #8f8f8f); + border: 1px solid #5c5c5c; + width: 18px; + margin: -2px 0; /* handle is placed by default on the contents rect of the groove. Expand outside the groove */ + border-radius: 3px; +} +//! [139] + + +//! [140] +QSlider::groove:vertical { + background: red; + position: absolute; /* absolutely position 4px from the left and right of the widget. setting margins on the widget should work too... */ + left: 4px; right: 4px; +} + +QSlider::handle:vertical { + height: 10px; + background: green; + margin: 0 -4px; /* expand outside the groove */ +} + +QSlider::add-page:vertical { + background: white; +} + +QSlider::sub-page:vertical { + background: pink; +} +//! [140] + + +//! [141] +QSpinBox { + padding-right: 15px; /* make room for the arrows */ + border-image: url(:/images/frame.png) 4; + border-width: 3; +} + +QSpinBox::up-button { + subcontrol-origin: border; + subcontrol-position: top right; /* position at the top right corner */ + + width: 16px; /* 16 + 2*1px border-width = 15px padding + 3px parent border */ + border-image: url(:/images/spinup.png) 1; + border-width: 1px; +} + +QSpinBox::up-button:hover { + border-image: url(:/images/spinup_hover.png) 1; +} + +QSpinBox::up-button:pressed { + border-image: url(:/images/spinup_pressed.png) 1; +} + +QSpinBox::up-arrow { + image: url(:/images/up_arrow.png); + width: 7px; + height: 7px; +} + +QSpinBox::up-arrow:disabled, QSpinBox::up-arrow:off { /* off state when value is max */ + image: url(:/images/up_arrow_disabled.png); +} + +QSpinBox::down-button { + subcontrol-origin: border; + subcontrol-position: bottom right; /* position at bottom right corner */ + + width: 16px; + border-image: url(:/images/spindown.png) 1; + border-width: 1px; + border-top-width: 0; +} + +QSpinBox::down-button:hover { + border-image: url(:/images/spindown_hover.png) 1; +} + +QSpinBox::down-button:pressed { + border-image: url(:/images/spindown_pressed.png) 1; +} + +QSpinBox::down-arrow { + image: url(:/images/down_arrow.png); + width: 7px; + height: 7px; +} + +QSpinBox::down-arrow:disabled, +QSpinBox::down-arrow:off { /* off state when value in min */ + image: url(:/images/down_arrow_disabled.png); +} + +//! [141] + + +//! [142] +QSplitter::handle { + image: url(images/splitter.png); +} + +QSplitter::handle:horizontal { + width: 2px; +} + +QSplitter::handle:vertical { + height: 2px; +} + +QSplitter::handle:pressed { + url(images/splitter_pressed.png); +} + +//! [142] + + +//! [143] +QStatusBar { + background: brown; +} + +QStatusBar::item { + border: 1px solid red; + border-radius: 3px; +} +//! [143] + + +//! [144] +QStatusBar QLabel { + border: 3px solid white; +} +//! [144] + + +//! [145] +QTabWidget::pane { /* The tab widget frame */ + border-top: 2px solid #C2C7CB; +} + +QTabWidget::tab-bar { + left: 5px; /* move to the right by 5px */ +} + +/* Style the tab using the tab sub-control. Note that + it reads QTabBar _not_ QTabWidget */ +QTabBar::tab { + background: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1, + stop: 0 #E1E1E1, stop: 0.4 #DDDDDD, + stop: 0.5 #D8D8D8, stop: 1.0 #D3D3D3); + border: 2px solid #C4C4C3; + border-bottom-color: #C2C7CB; /* same as the pane color */ + border-top-left-radius: 4px; + border-top-right-radius: 4px; + min-width: 8ex; + padding: 2px; +} + +QTabBar::tab:selected, QTabBar::tab:hover { + background: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1, + stop: 0 #fafafa, stop: 0.4 #f4f4f4, + stop: 0.5 #e7e7e7, stop: 1.0 #fafafa); +} + +QTabBar::tab:selected { + border-color: #9B9B9B; + border-bottom-color: #C2C7CB; /* same as pane color */ +} + +QTabBar::tab:!selected { + margin-top: 2px; /* make non-selected tabs look smaller */ +} +//! [145] + + +//! [146] +QTabWidget::pane { /* The tab widget frame */ + border-top: 2px solid #C2C7CB; +} + +QTabWidget::tab-bar { + left: 5px; /* move to the right by 5px */ +} + +/* Style the tab using the tab sub-control. Note that + it reads QTabBar _not_ QTabWidget */ +QTabBar::tab { + background: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1, + stop: 0 #E1E1E1, stop: 0.4 #DDDDDD, + stop: 0.5 #D8D8D8, stop: 1.0 #D3D3D3); + border: 2px solid #C4C4C3; + border-bottom-color: #C2C7CB; /* same as the pane color */ + border-top-left-radius: 4px; + border-top-right-radius: 4px; + min-width: 8ex; + padding: 2px; +} + +QTabBar::tab:selected, QTabBar::tab:hover { + background: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1, + stop: 0 #fafafa, stop: 0.4 #f4f4f4, + stop: 0.5 #e7e7e7, stop: 1.0 #fafafa); +} + +QTabBar::tab:selected { + border-color: #9B9B9B; + border-bottom-color: #C2C7CB; /* same as pane color */ +} + +QTabBar::tab:!selected { + margin-top: 2px; /* make non-selected tabs look smaller */ +} + +/* make use of negative margins for overlapping tabs */ +QTabBar::tab:selected { + /* expand/overlap to the left and right by 4px */ + margin-left: -4px; + margin-right: -4px; +} + +QTabBar::tab:first:selected { + margin-left: 0; /* the first selected tab has nothing to overlap with on the left */ +} + +QTabBar::tab:last:selected { + margin-right: 0; /* the last selected tab has nothing to overlap with on the right */ +} + +QTabBar::tab:only-one { + margin: 0; /* if there is only one tab, we don't want overlapping margins */ +} +//! [146] + + +//! [147] +QTabWidget::pane { /* The tab widget frame */ + border-top: 2px solid #C2C7CB; + position: absolute; + top: -0.5em; +} + +QTabWidget::tab-bar { + alignment: center; +} + +/* Style the tab using the tab sub-control. Note that + it reads QTabBar _not_ QTabWidget */ +QTabBar::tab { + background: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1, + stop: 0 #E1E1E1, stop: 0.4 #DDDDDD, + stop: 0.5 #D8D8D8, stop: 1.0 #D3D3D3); + border: 2px solid #C4C4C3; + border-bottom-color: #C2C7CB; /* same as the pane color */ + border-top-left-radius: 4px; + border-top-right-radius: 4px; + min-width: 8ex; + padding: 2px; +} + +QTabBar::tab:selected, QTabBar::tab:hover { + background: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1, + stop: 0 #fafafa, stop: 0.4 #f4f4f4, + stop: 0.5 #e7e7e7, stop: 1.0 #fafafa); +} + +QTabBar::tab:selected { + border-color: #9B9B9B; + border-bottom-color: #C2C7CB; /* same as pane color */ +} +//! [147] + + +//! [148] +QTabBar::tear { + image: url(tear_indicator.png); +} + +QTabBar::scroller { /* the width of the scroll buttons */ + width: 20px; +} + +QTabBar QToolButton { /* the scroll buttons are tool buttons */ + border-image: url(scrollbutton.png) 2; + border-width: 2px; +} + +QTabBar QToolButton::right-arrow { /* the arrow mark in the tool buttons */ + image: url(rightarrow.png); +} + +QTabBar QToolButton::left-arrow { + image: url(leftarrow.png); +} +//! [148] + + +//! [149] +QTableView { + selection-background-color: qlineargradient(x1: 0, y1: 0, x2: 0.5, y2: 0.5, + stop: 0 #FF92BB, stop: 1 white); +} +//! [149] + + +//! [150] +QTableView QTableCornerButton::section { + background: red; + border: 2px outset red; +} +//! [150] + + +//! [151] +QToolBar { + background: red; + spacing: 3px; /* spacing between items in the tool bar */ +} + +QToolBar::handle { + image: url(handle.png); +} +//! [151] + + +//! [152] +QToolBox::tab { + background: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1, + stop: 0 #E1E1E1, stop: 0.4 #DDDDDD, + stop: 0.5 #D8D8D8, stop: 1.0 #D3D3D3); + border-radius: 5px; + color: darkgray; +} + +QToolBox::tab:selected { /* italicize selected tabs */ + font: italic; + color: white; +} +//! [152] + + +//! [153] +QToolButton { /* all types of tool button */ + border: 2px solid #8f8f91; + border-radius: 6px; + background-color: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1, + stop: 0 #f6f7fa, stop: 1 #dadbde); +} + +QToolButton[popupMode="1"] { /* only for MenuButtonPopup */ + padding-right: 20px; /* make way for the popup button */ +} + +QToolButton:pressed { + background-color: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1, + stop: 0 #dadbde, stop: 1 #f6f7fa); +} + +/* the subcontrols below are used only in the MenuButtonPopup mode */ +QToolButton::menu-button { + border: 2px solid gray; + border-top-right-radius: 6px; + border-bottom-right-radius: 6px; + /* 16px width + 4px for border = 20px allocated above */ + width: 16px; +} + +QToolButton::menu-arrow { + image: url(downarrow.png); +} + +QToolButton::menu-arrow:open { + top: 1px; left: 1px; /* shift it a bit */ +} +//! [153] + + +//! [154] +QToolTip { + border: 2px solid darkkhaki; + padding: 5px; + border-radius: 3px; + opacity: 200; +} +//! [154] + + +//! [155] +QTreeView { + alternate-background-color: yellow; +} +//! [155] + + +//! [156] +QTreeView { + show-decoration-selected: 1; +} + +QTreeView::item { + border: 1px solid #d9d9d9; + border-top-color: transparent; + border-bottom-color: transparent; +} + +QTreeView::item:hover { + background: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1, stop: 0 #e7effd, stop: 1 #cbdaf1); + border: 1px solid #bfcde4; +} + +QTreeView::item:selected { + border: 1px solid #567dbc; +} + +QTreeView::item:selected:active{ + background: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1, stop: 0 #6ea1f1, stop: 1 #567dbc); +} + +QTreeView::item:selected:!active { + background: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1, stop: 0 #6b9be8, stop: 1 #577fbf); +} +//! [156] + + +//! [157] +QTreeView::branch { + background: palette(base); +} + +QTreeView::branch:has-siblings:!adjoins-item { + background: cyan; +} + +QTreeView::branch:has-siblings:adjoins-item { + background: red; +} + +QTreeView::branch:!has-children:!has-siblings:adjoins-item { + background: blue; +} + +QTreeView::branch:closed:has-children:has-siblings { + background: pink; +} + +QTreeView::branch:has-children:!has-siblings:closed { + background: gray; +} + +QTreeView::branch:open:has-children:has-siblings { + background: magenta; +} + +QTreeView::branch:open:has-children:!has-siblings { + background: green; +} + +//! [157] + + +//! [158] +QTreeView::branch:has-siblings:!adjoins-item { + border-image: url(vline.png) 0; +} + +QTreeView::branch:has-siblings:adjoins-item { + border-image: url(branch-more.png) 0; +} + +QTreeView::branch:!has-children:!has-siblings:adjoins-item { + border-image: url(branch-end.png) 0; +} + +QTreeView::branch:has-children:!has-siblings:closed, +QTreeView::branch:closed:has-children:has-siblings { + border-image: none; + image: url(branch-closed.png); +} + +QTreeView::branch:open:has-children:!has-siblings, +QTreeView::branch:open:has-children:has-siblings { + border-image: none; + image: url(branch-open.png); +} +//! [158] + +//! [159] +QTabBar::close-button { + image: url(close.png) + subcontrol-position: left; +} +QTabBar::close-button:hover { + image: url(close-hover.png) +} + +//! [159] diff --git a/doc/src/snippets/code/src.gui.text.qtextdocumentwriter.cpp b/doc/src/snippets/code/src.gui.text.qtextdocumentwriter.cpp new file mode 100644 index 0000000000..d7b982758b --- /dev/null +++ b/doc/src/snippets/code/src.gui.text.qtextdocumentwriter.cpp @@ -0,0 +1,45 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] + QTextDocumentWriter writer; + writer.setFormat("odf"); // same as writer.setFormat("ODF"); +//! [0] + diff --git a/doc/src/snippets/code/src.qdbus.qdbuspendingcall.cpp b/doc/src/snippets/code/src.qdbus.qdbuspendingcall.cpp new file mode 100644 index 0000000000..623c526f7b --- /dev/null +++ b/doc/src/snippets/code/src.qdbus.qdbuspendingcall.cpp @@ -0,0 +1,65 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +{ +//! [0] + QDBusPendingCall async = iface->asyncCall("RemoteMethod", value1, value2); + QDBusPendingCallWatcher *watcher = new QDBusPendingCallWatcher(async, this); + + QObject::connect(watcher, SIGNAL(finished(QDBusPendingCallWatcher*)), + this, SLOT(callFinishedSlot(QDBusPendingCallWatcher*))); +//! [0] + +} + +//! [1] +void MyClass::callFinishedSlot(QDBusPendingCallWatcher *call) +{ + QDBusPendingReply<QString, QByteArray> reply = *call; + if (reply.isError()) { + showError(); + } else { + QString text = reply.argumentAt<0>(); + QByteArray data = reply.argumentAt<1>(); + showReply(text, data); + } + call->deleteLater(); +} +//! [1] diff --git a/doc/src/snippets/code/src.qdbus.qdbuspendingreply.cpp b/doc/src/snippets/code/src.qdbus.qdbuspendingreply.cpp new file mode 100644 index 0000000000..31e240ad35 --- /dev/null +++ b/doc/src/snippets/code/src.qdbus.qdbuspendingreply.cpp @@ -0,0 +1,63 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +{ +//! [0] + QDBusPendingReply<QString> reply = interface->asyncCall("RemoteMethod"); + reply.waitForFinished(); + if (reply.isError()) + // call failed. Show an error condition. + showError(reply.error()); + else + // use the returned value + useValue(reply.value()); +//! [0] + +//! [2] + QDBusPendingReply<bool, QString> reply = interface->asyncCall("RemoteMethod"); + reply.waitForFinished(); + if (!reply.isError()) { + if (reply.argumentAt<0>()) + showSuccess(reply.argumentAt<1>()); + else + showFailure(reply.argumentAt<1>()); + } +//! [2] +} diff --git a/doc/src/snippets/code/src_corelib_codecs_qtextcodec.cpp b/doc/src/snippets/code/src_corelib_codecs_qtextcodec.cpp new file mode 100644 index 0000000000..698c0b652e --- /dev/null +++ b/doc/src/snippets/code/src_corelib_codecs_qtextcodec.cpp @@ -0,0 +1,75 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QByteArray encodedString = "..."; +QTextCodec *codec = QTextCodec::codecForName("KOI8-R"); +QString string = codec->toUnicode(encodedString); +//! [0] + + +//! [1] +QString string = "..."; +QTextCodec *codec = QTextCodec::codecForName("KOI8-R"); +QByteArray encodedString = codec->fromUnicode(string); +//! [1] + + +//! [2] +QTextCodec *codec = QTextCodec::codecForName("Shift-JIS"); +QTextDecoder *decoder = codec->makeDecoder(); + +QString string; +while (new_data_available()) { + QByteArray chunk = get_new_data(); + string += decoder->toUnicode(chunk); +} +delete decoder; +//! [2] + + +//! [3] +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + QTextCodec::setCodecForTr(QTextCodec::codecForName("eucKR")); + ... +} +//! [3] diff --git a/doc/src/snippets/code/src_corelib_codecs_qtextcodecplugin.cpp b/doc/src/snippets/code/src_corelib_codecs_qtextcodecplugin.cpp new file mode 100644 index 0000000000..684884f400 --- /dev/null +++ b/doc/src/snippets/code/src_corelib_codecs_qtextcodecplugin.cpp @@ -0,0 +1,56 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QList<QByteArray> MyCodecPlugin::names() const +{ + return QList<QByteArray> << "IBM01140" << "hp15-tw"; +} + +QTextCodec *MyCodecPlugin::createForName(const QByteArray &name) +{ + if (name == "IBM01140") { + return new Ibm01140Codec; + } else if (name == "hp15-tw") { + return new Hp15TwCodec; + } + return 0; +} +//! [0] diff --git a/doc/src/snippets/code/src_corelib_concurrent_qfuture.cpp b/doc/src/snippets/code/src_corelib_concurrent_qfuture.cpp new file mode 100644 index 0000000000..7e106bfb9c --- /dev/null +++ b/doc/src/snippets/code/src_corelib_concurrent_qfuture.cpp @@ -0,0 +1,64 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QFuture<QString> future = ...; + +QFuture<QString>::const_iterator i; +for (i = future.constBegin(); i != future.constEnd(); ++i) + cout << *i << endl; +//! [0] + + +//! [1] +QFuture<QString> future; +... +QFutureIterator<QString> i(future); +while (i.hasNext()) + qDebug() << i.next(); +//! [1] + + +//! [2] +QFutureIterator<QString> i(future); +i.toBack(); +while (i.hasPrevious()) + qDebug() << i.previous(); +//! [2] diff --git a/doc/src/snippets/code/src_corelib_concurrent_qfuturesynchronizer.cpp b/doc/src/snippets/code/src_corelib_concurrent_qfuturesynchronizer.cpp new file mode 100644 index 0000000000..291e2f4f4e --- /dev/null +++ b/doc/src/snippets/code/src_corelib_concurrent_qfuturesynchronizer.cpp @@ -0,0 +1,53 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +void someFunction() +{ + QFutureSynchronizer<void> synchronizer; + + ... + + synchronizer.addFuture(QtConcurrent::run(anotherFunction)); + synchronizer.addFuture(QtConcurrent::map(list, mapFunction)); + + return; // QFutureSynchronizer waits for all futures to finish +} +//! [0] diff --git a/doc/src/snippets/code/src_corelib_concurrent_qfuturewatcher.cpp b/doc/src/snippets/code/src_corelib_concurrent_qfuturewatcher.cpp new file mode 100644 index 0000000000..9f12e936fc --- /dev/null +++ b/doc/src/snippets/code/src_corelib_concurrent_qfuturewatcher.cpp @@ -0,0 +1,50 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +// Instantiate the objects and connect to the finished signal. +MyClass myObject; +QFutureWatcher<int> watcher; +connect(&watcher, SIGNAL(finished()), &myObject, SLOT(handleFinished())); + +// Start the computation. +QFuture<int> future = QtConcurrent::run(...); +watcher.setFuture(future); +//! [0] diff --git a/doc/src/snippets/code/src_corelib_concurrent_qtconcurrentexception.cpp b/doc/src/snippets/code/src_corelib_concurrent_qtconcurrentexception.cpp new file mode 100644 index 0000000000..85f3551b62 --- /dev/null +++ b/doc/src/snippets/code/src_corelib_concurrent_qtconcurrentexception.cpp @@ -0,0 +1,75 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] + +class MyException : public QtConcurrent::Exception +{ +public: + void raise() const { throw *this; } + Exception *clone() const { return new MyException(*this); } +}; + +//! [0] + + +//! [1] + +try { + QtConcurrent::blockingMap(list, throwFunction); // throwFunction throws MyException +} catch (MyException &e) { + // handle exception +} + +//! [1] + + +//! [2] + +void MyException::raise() const { throw *this; } + +//! [2] + + +//! [3] + +MyException *MyException::clone() const { return new MyException(*this); } + +//! [3] diff --git a/doc/src/snippets/code/src_corelib_concurrent_qtconcurrentfilter.cpp b/doc/src/snippets/code/src_corelib_concurrent_qtconcurrentfilter.cpp new file mode 100644 index 0000000000..d18f1e5165 --- /dev/null +++ b/doc/src/snippets/code/src_corelib_concurrent_qtconcurrentfilter.cpp @@ -0,0 +1,171 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +bool function(const T &t); +//! [0] + + +//! [1] +bool allLowerCase(const QString &string) +{ + return string.lowered() == string; +} + +QStringList strings = ...; +QFuture<QString> lowerCaseStrings = QtConcurrent::filtered(strings, allLowerCase); +//! [1] + + +//! [2] +QStringList strings = ...; +QFuture<void> future = QtConcurrent::filter(strings, allLowerCase); +//! [2] + + +//! [3] +V function(T &result, const U &intermediate) +//! [3] + + +//! [4] +void addToDictionary(QSet<QString> &dictionary, const QString &string) +{ + dictionary.insert(string); +} + +QStringList strings = ...; +QFuture<QSet<QString> > dictionary = QtConcurrent::filteredReduced(strings, allLowerCase, addToDictionary); +//! [4] + + +//! [5] +QStringList strings = ...; +QFuture<QString> lowerCaseStrings = QtConcurrent::filtered(strings.constBegin(), strings.constEnd(), allLowerCase); + +// filter in-place only works on non-const iterators +QFuture<void> future = QtConcurrent::filter(strings.begin(), strings.end(), allLowerCase); + +QFuture<QSet<QString> > dictionary = QtConcurrent::filteredReduced(strings.constBegin(), strings.constEnd(), allLowerCase, addToDictionary); +//! [5] + + +//! [6] +QStringList strings = ...; + +// each call blocks until the entire operation is finished +QStringList lowerCaseStrings = QtConcurrent::blockingFiltered(strings, allLowerCase); + + +QtConcurrent::blockingFilter(strings, allLowerCase); + +QSet<QString> dictionary = QtConcurrent::blockingFilteredReduced(strings, allLowerCase, addToDictionary); +//! [6] + + +//! [7] +// keep only images with an alpha channel +QList<QImage> images = ...; +QFuture<void> alphaImages = QtConcurrent::filter(strings, &QImage::hasAlphaChannel); + +// keep only gray scale images +QList<QImage> images = ...; +QFuture<QImage> grayscaleImages = QtConcurrent::filtered(images, &QImage::isGrayscale); + +// create a set of all printable characters +QList<QChar> characters = ...; +QFuture<QSet<QChar> > set = QtConcurrent::filteredReduced(characters, &QChar::isPrint, &QSet<QChar>::insert); +//! [7] + + +//! [8] +// can mix normal functions and member functions with QtConcurrent::filteredReduced() + +// create a dictionary of all lower cased strings +extern bool allLowerCase(const QString &string); +QStringList strings = ...; +QFuture<QSet<int> > averageWordLength = QtConcurrent::filteredReduced(strings, allLowerCase, QSet<QString>::insert); + +// create a collage of all gray scale images +extern void addToCollage(QImage &collage, const QImage &grayscaleImage); +QList<QImage> images = ...; +QFuture<QImage> collage = QtConcurrent::filteredReduced(images, &QImage::isGrayscale, addToCollage); +//! [8] + + +//! [9] +bool QString::contains(const QRegExp ®exp) const; +//! [9] + + +//! [10] +boost::bind(&QString::contains, QRegExp("^\\S+$")); // matches strings without whitespace +//! [10] + + +//! [11] +bool contains(const QString &string) +//! [11] + + +//! [12] +QStringList strings = ...; +boost::bind(static_cast<bool(QString::*)(const QRegExp&)>( &QString::contains ), QRegExp("..." )); +//! [12] + +//! [13] +struct StartsWith +{ + StartsWith(const QString &string) + : m_string(string) { } + + typedef bool result_type; + + bool operator()(const QString &testString) + { + return testString.startsWith(m_string); + } + + QString m_string; +}; + +QList<QString> strings = ...; +QFuture<QString> fooString = QtConcurrent::filtered(images, StartsWith(QLatin1String("Foo"))); +//! [13] diff --git a/doc/src/snippets/code/src_corelib_concurrent_qtconcurrentmap.cpp b/doc/src/snippets/code/src_corelib_concurrent_qtconcurrentmap.cpp new file mode 100644 index 0000000000..c48ce1e6ae --- /dev/null +++ b/doc/src/snippets/code/src_corelib_concurrent_qtconcurrentmap.cpp @@ -0,0 +1,184 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +U function(const T &t); +//! [0] + + +//! [1] +QImage scaled(const QImage &image) +{ + return image.scaled(100, 100); +} + +QList<QImage> images = ...; +QFuture<QImage> thumbnails = QtConcurrent::mapped(images, scaled); +//! [1] + + +//! [2] +U function(T &t); +//! [2] + + +//! [3] +void scale(QImage &image) +{ + image = image.scaled(100, 100); +} + +QList<QImage> images = ...; +QFuture<void> future = QtConcurrent::map(images, scale); +//! [3] + + +//! [4] +V function(T &result, const U &intermediate) +//! [4] + + +//! [5] +void addToCollage(QImage &collage, const QImage &thumbnail) +{ + QPainter p(&collage); + static QPoint offset = QPoint(0, 0); + p.drawImage(offset, thumbnail); + offset += ...; +} + +QList<QImage> images = ...; +QFuture<QImage> collage = QtConcurrent::mappedReduced(images, scaled, addToCollage); +//! [5] + + +//! [6] +QList<QImage> images = ...; + +QFuture<QImage> thumbnails = QtConcurrent::mapped(images.constBegin(), images.constEnd(), scaled); + +// map in-place only works on non-const iterators +QFuture<void> future = QtConcurrent::map(images.begin(), images.end(), scale); + +QFuture<QImage> collage = QtConcurrent::mappedReduced(images.constBegin(), images.constEnd(), scaled, addToCollage); +//! [6] + + +//! [7] +QList<QImage> images = ...; + +// each call blocks until the entire operation is finished +QList<QImage> future = QtConcurrent::blockingMapped(images, scaled); + +QtConcurrent::blockingMap(images, scale); + +QImage collage = QtConcurrent::blockingMappedReduced(images, scaled, addToCollage); +//! [7] + + +//! [8] +// squeeze all strings in a QStringList +QStringList strings = ...; +QFuture<void> squeezedStrings = QtConcurrent::map(strings, &QString::squeeze); + +// swap the rgb values of all pixels on a list of images +QList<QImage> images = ...; +QFuture<QImage> bgrImages = QtConcurrent::mapped(images, &QImage::rgbSwapped); + +// create a set of the lengths of all strings in a list +QStringList strings = ...; +QFuture<QSet<int> > wordLengths = QtConcurrent::mappedReduced(string, &QString::length, &QSet<int>::insert); +//! [8] + + +//! [9] +// can mix normal functions and member functions with QtConcurrent::mappedReduced() + +// compute the average length of a list of strings +extern void computeAverage(int &average, int length); +QStringList strings = ...; +QFuture<int> averageWordLength = QtConcurrent::mappedReduced(strings, &QString::length, computeAverage); + +// create a set of the color distribution of all images in a list +extern int colorDistribution(const QImage &string); +QList<QImage> images = ...; +QFuture<QSet<int> > totalColorDistribution = QtConcurrent::mappedReduced(images, colorDistribution, QSet<int>::insert); +//! [9] + + +//! [10] +QImage QImage::scaledToWidth(int width, Qt::TransformationMode) const; +//! [10] + + +//! [11] +boost::bind(&QImage::scaledToWidth, 100, Qt::SmoothTransformation) +//! [11] + + +//! [12] +QImage scaledToWith(const QImage &image) +//! [12] + + +//! [13] +QList<QImage> images = ...; +QFuture<QImage> thumbnails = QtConcurrent::mapped(images, boost::bind(&QImage::scaledToWidth, 100 Qt::SmoothTransformation)); +//! [13] + +//! [14] +struct Scaled +{ + Scaled(int size) + : m_size(size) { } + + typedef QImage result_type; + + QImage operator()(const QImage &image) + { + return image.scaled(m_size, m_size); + } + + int m_size; +}; + +QList<QImage> images = ...; +QFuture<QImage> thumbnails = QtConcurrent::mapped(images, Scaled(100)); +//! [14] diff --git a/doc/src/snippets/code/src_corelib_concurrent_qtconcurrentrun.cpp b/doc/src/snippets/code/src_corelib_concurrent_qtconcurrentrun.cpp new file mode 100644 index 0000000000..11f5163f50 --- /dev/null +++ b/doc/src/snippets/code/src_corelib_concurrent_qtconcurrentrun.cpp @@ -0,0 +1,98 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +extern void aFunction(); +QFuture<void> future = QtConcurrent::run(aFunction); +//! [0] + + +//! [1] +extern void aFunctionWithArguments(int arg1, double arg2, const QString &string); + +int integer = ...; +double floatingPoint = ...; +QString string = ...; + +QFuture<void> future = QtConcurrent::run(aFunctionWithArguments, integer, floatingPoint, string); +//! [1] + + +//! [2] +extern QString functionReturningAString(); +QFuture<QString> future = QtConcurrent::run(functionReturningAString); +... +QString result = future.result(); +//! [2] + + +//! [3] +extern QString someFunction(const QByteArray &input); + +QByteArray bytearray = ...; + +QFuture<QString> future = QtConcurrent::run(someFunction, bytearray); +... +QString result = future.result(); +//! [3] + +//! [4] +// call 'QList<QByteArray> QByteArray::split(char sep) const' in a separate thread +QByteArray bytearray = "hello world"; +QFuture<QList<QByteArray> > future = QtConcurrent::run(bytearray, &QByteArray::split), ','); +... +QList<QByteArray> result = future.result(); +//! [4] + +//! [5] +// call 'void QImage::invertPixels(InvertMode mode)' in a separate thread +QImage image = ...; +QFuture<void> future = QtConcurrent::run(image, &QImage::invertPixels, QImage::InvertRgba); +... +future.waitForFinished(); +// At this point, the pixels in 'image' have been inverted +//! [5] + + +//! [6] +void someFunction(int arg1, double arg2); +QFuture<void> future = QtConcurrent::run(boost::bind(someFunction, 1, 2.0)); +... +//! [6] diff --git a/doc/src/snippets/code/src_corelib_concurrent_qthreadpool.cpp b/doc/src/snippets/code/src_corelib_concurrent_qthreadpool.cpp new file mode 100644 index 0000000000..6262cb1a11 --- /dev/null +++ b/doc/src/snippets/code/src_corelib_concurrent_qthreadpool.cpp @@ -0,0 +1,53 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +class HelloWorldTask : public QRunnable +{ + void run() + { + qDebug() << "Hello world from thread" << QThread::currentThread(); + } +} + +HelloWorldTask *hello = new HelloWorldTask(); +// QThreadPool takes ownership and deletes 'hello' automatically +QThreadPool::globalInstance()->start(hello); +//! [0] diff --git a/doc/src/snippets/code/src_corelib_global_qglobal.cpp b/doc/src/snippets/code/src_corelib_global_qglobal.cpp new file mode 100644 index 0000000000..c79a714192 --- /dev/null +++ b/doc/src/snippets/code/src_corelib_global_qglobal.cpp @@ -0,0 +1,557 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +label->setAlignment(Qt::AlignLeft | Qt::AlignTop); +//! [0] + + +//! [1] +class MyClass +{ +public: + enum Option { + NoOptions = 0x0, + ShowTabs = 0x1, + ShowAll = 0x2, + SqueezeBlank = 0x4 + }; + Q_DECLARE_FLAGS(Options, Option) + ... +}; + +Q_DECLARE_OPERATORS_FOR_FLAGS(MyClass::Options) +//! [1] + +//! [meta-object flags] +Q_FLAGS(Options) +//! [meta-object flags] + +//! [2] +typedef QFlags<Enum> Flags; +//! [2] + + +//! [3] +int myValue = 10; +int minValue = 2; +int maxValue = 6; + +int boundedValue = qBound(minValue, myValue, maxValue); +// boundedValue == 6 +//! [3] + + +//! [4] +if (!driver()->isOpen() || driver()->isOpenError()) { + qWarning("QSqlQuery::exec: database not open"); + return false; +} +//! [4] + + +//! [5] +qint64 value = Q_INT64_C(932838457459459); +//! [5] + + +//! [6] +quint64 value = Q_UINT64_C(932838457459459); +//! [6] + + +//! [7] +void myMsgHandler(QtMsgType, const char *); +//! [7] + + +//! [8] +qint64 value = Q_INT64_C(932838457459459); +//! [8] + + +//! [9] +quint64 value = Q_UINT64_C(932838457459459); +//! [9] + + +//! [10] +int absoluteValue; +int myValue = -4; + +absoluteValue = qAbs(myValue); +// absoluteValue == 4 +//! [10] + + +//! [11] +qreal valueA = 2.3; +qreal valueB = 2.7; + +int roundedValueA = qRound(valueA); +// roundedValueA = 2 +int roundedValueB = qRound(valueB); +// roundedValueB = 3 +//! [11] + + +//! [12] +qreal valueA = 42949672960.3; +qreal valueB = 42949672960.7; + +int roundedValueA = qRound(valueA); +// roundedValueA = 42949672960 +int roundedValueB = qRound(valueB); +// roundedValueB = 42949672961 +//! [12] + + +//! [13] +int myValue = 6; +int yourValue = 4; + +int minValue = qMin(myValue, yourValue); +// minValue == yourValue +//! [13] + + +//! [14] +int myValue = 6; +int yourValue = 4; + +int maxValue = qMax(myValue, yourValue); +// maxValue == myValue +//! [14] + + +//! [15] +int myValue = 10; +int minValue = 2; +int maxValue = 6; + +int boundedValue = qBound(minValue, myValue, maxValue); +// boundedValue == 6 +//! [15] + + +//! [16] +#if QT_VERSION >= 0x040100 + QIcon icon = style()->standardIcon(QStyle::SP_TrashIcon); +#else + QPixmap pixmap = style()->standardPixmap(QStyle::SP_TrashIcon); + QIcon icon(pixmap); +#endif +//! [16] + + +//! [17] +// File: div.cpp + +#include <QtGlobal> + +int divide(int a, int b) +{ + Q_ASSERT(b != 0); + return a / b; +} +//! [17] + + +//! [18] +ASSERT: "b == 0" in file div.cpp, line 7 +//! [18] + + +//! [19] +// File: div.cpp + +#include <QtGlobal> + +int divide(int a, int b) +{ + Q_ASSERT_X(b != 0, "divide", "division by zero"); + return a / b; +} +//! [19] + + +//! [20] +ASSERT failure in divide: "division by zero", file div.cpp, line 7 +//! [20] + + +//! [21] +int *a; + +Q_CHECK_PTR(a = new int[80]); // WRONG! + +a = new (nothrow) int[80]; // Right +Q_CHECK_PTR(a); +//! [21] + + +//! [22] +template<typename TInputType> +const TInputType &myMin(const TInputType &value1, const TInputType &value2) +{ + qDebug() << Q_FUNC_INFO << "was called with value1:" << value1 << "value2:" << value2; + + if(value1 < value2) + return value1; + else + return value2; +} +//! [22] + + +//! [23] +#include <qapplication.h> +#include <stdio.h> +#include <stdlib.h> + +void myMessageOutput(QtMsgType type, const char *msg) +{ + switch (type) { + case QtDebugMsg: + fprintf(stderr, "Debug: %s\n", msg); + break; + case QtWarningMsg: + fprintf(stderr, "Warning: %s\n", msg); + break; + case QtCriticalMsg: + fprintf(stderr, "Critical: %s\n", msg); + break; + case QtFatalMsg: + fprintf(stderr, "Fatal: %s\n", msg); + abort(); + } +} + +int main(int argc, char **argv) +{ + qInstallMsgHandler(myMessageOutput); + QApplication app(argc, argv); + ... + return app.exec(); +} +//! [23] + + +//! [24] +qDebug("Items in list: %d", myList.size()); +//! [24] + + +//! [25] +qDebug() << "Brush:" << myQBrush << "Other value:" << i; +//! [25] + + +//! [26] +void f(int c) +{ + if (c > 200) + qWarning("f: bad argument, c == %d", c); +} +//! [26] + + +//! [27] +qWarning() << "Brush:" << myQBrush << "Other value:" +<< i; +//! [27] + + +//! [28] +void load(const QString &fileName) +{ + QFile file(fileName); + if (!file.exists()) + qCritical("File '%s' does not exist!", qPrintable(fileName)); +} +//! [28] + + +//! [29] +qCritical() << "Brush:" << myQBrush << "Other +value:" << i; +//! [29] + + +//! [30] +int divide(int a, int b) +{ + if (b == 0) // program error + qFatal("divide: cannot divide by zero"); + return a / b; +} +//! [30] + + +//! [31] +forever { + ... +} +//! [31] + + +//! [32] +CONFIG += no_keywords +//! [32] + + +//! [33] +CONFIG += no_keywords +//! [33] + + +//! [34] +QString FriendlyConversation::greeting(int type) +{ +static const char *greeting_strings[] = { + QT_TR_NOOP("Hello"), + QT_TR_NOOP("Goodbye") +}; +return tr(greeting_strings[type]); +} +//! [34] + + +//! [35] +static const char *greeting_strings[] = { + QT_TRANSLATE_NOOP("FriendlyConversation", "Hello"), + QT_TRANSLATE_NOOP("FriendlyConversation", "Goodbye") +}; + +QString FriendlyConversation::greeting(int type) +{ + return tr(greeting_strings[type]); +} + +QString global_greeting(int type) +{ + return qApp->translate("FriendlyConversation", + greeting_strings[type]); +} +//! [35] + + +//! [36] + +static { const char *source; const char *comment; } greeting_strings[] = +{ + QT_TRANSLATE_NOOP3("FriendlyConversation", "Hello", + "A really friendly hello"), + QT_TRANSLATE_NOOP3("FriendlyConversation", "Goodbye", + "A really friendly goodbye") +}; + +QString FriendlyConversation::greeting(int type) +{ + return tr(greeting_strings[type].source, + greeting_strings[type].comment); +} + +QString global_greeting(int type) +{ + return qApp->translate("FriendlyConversation", + greeting_strings[type].source, + greeting_strings[type].comment); +} +//! [36] + + +//! [qttrid] + //% "%n fooish bar(s) found.\n" + //% "Do you want to continue?" + QString text = qtTrId("qtn_foo_bar", n); +//! [qttrid] + + +//! [qttrid_noop] +static const char * const ids[] = { + //% "This is the first text." + QT_TRID_NOOP("qtn_1st_text"), + //% "This is the second text." + QT_TRID_NOOP("qtn_2nd_text"), + 0 +}; + +void TheClass::addLabels() +{ + for (int i = 0; ids[i]; ++i) + new QLabel(qtTrId(ids[i]), this); +} +//! [qttrid_noop] + + +//! [37] +qWarning("%s: %s", qPrintable(key), qPrintable(value)); +//! [37] + + +//! [38] +struct Point2D +{ + int x; + int y; +}; + +Q_DECLARE_TYPEINFO(Point2D, Q_PRIMITIVE_TYPE); +//! [38] + + +//! [39] +class Point2D +{ +public: + Point2D() { data = new int[2]; } + Point2D(const Point2D &other) { ... } + ~Point2D() { delete[] data; } + + Point2D &operator=(const Point2D &other) { ... } + + int x() const { return data[0]; } + int y() const { return data[1]; } + +private: + int *data; +}; + +Q_DECLARE_TYPEINFO(Point2D, Q_MOVABLE_TYPE); +//! [39] + + +//! [40] +#if Q_BYTE_ORDER == Q_BIG_ENDIAN +... +#endif + +or + +#if Q_BYTE_ORDER == Q_LITTLE_ENDIAN +... +#endif + +//! [40] + + +//! [41] + +#if Q_BYTE_ORDER == Q_LITTLE_ENDIAN +... +#endif + +//! [41] + + +//! [42] +#if Q_BYTE_ORDER == Q_BIG_ENDIAN +... +#endif + +//! [42] + +//! [begin namespace macro] +namespace QT_NAMESPACE { +//! [begin namespace macro] + +//! [end namespace macro] +} +//! [end namespace macro] + +//! [43] +class MyClass : public QObject +{ + + private: + Q_DISABLE_COPY(MyClass) +}; + +//! [43] + +//! [44] +class MyClass : public QObject +{ + + private: + MyClass(const MyClass &); + MyClass &operator=(const MyClass &); +}; +//! [44] + +//! [45] + QWidget w = QWidget(); +//! [45] + +//! [46] + // Instead of comparing with 0.0 + qFuzzyCompare(0.0,1.0e-200); // This will return false + // Compare adding 1 to both values will fix the problem + qFuzzyCompare(1 + 0.0, 1 + 1.0e-200); // This will return true +//! [46] + +//! [47] +CApaApplication *myApplicationFactory(); +//! [47] + +//! [qlikely] + // the condition inside the "if" will be successful most of the times + for (int i = 1; i <= 365; i++) { + if (Q_LIKELY(isWorkingDay(i))) { + ... + } + ... + } +//! [qlikely] + +//! [qunlikely] +bool readConfiguration(const QFile &file) +{ + // We expect to be asked to read an existing file + if (Q_UNLIKELY(!file.exists())) { + qWarning() << "File not found"; + return false; + } + + ... + return true; +} +//! [qunlikely] diff --git a/doc/src/snippets/code/src_corelib_io_qabstractfileengine.cpp b/doc/src/snippets/code/src_corelib_io_qabstractfileengine.cpp new file mode 100644 index 0000000000..74ef79fa87 --- /dev/null +++ b/doc/src/snippets/code/src_corelib_io_qabstractfileengine.cpp @@ -0,0 +1,120 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +class ZipEngineHandler : public QAbstractFileEngineHandler +{ +public: + QAbstractFileEngine *create(const QString &fileName) const; +}; + +QAbstractFileEngine *ZipEngineHandler::create(const QString &fileName) const +{ + // ZipEngineHandler returns a ZipEngine for all .zip files + return fileName.toLower().endsWith(".zip") ? new ZipEngine(fileName) : 0; +} + +int main(int argc, char **argv) +{ + QApplication app(argc, argv); + + ZipEngineHandler engine; + + MainWindow window; + window.show(); + + return app.exec(); +} +//! [0] + + +//! [1] +QAbstractSocketEngine *ZipEngineHandler::create(const QString &fileName) const +{ + // ZipEngineHandler returns a ZipEngine for all .zip files + return fileName.toLower().endsWith(".zip") ? new ZipEngine(fileName) : 0; +} +//! [1] + + +//! [2] +QAbstractFileEngineIterator * +CustomFileEngine::beginEntryList(QDir::Filters filters, const QStringList &filterNames) +{ + return new CustomFileEngineIterator(filters, filterNames); +} +//! [2] + + +//! [3] +class CustomIterator : public QAbstractFileEngineIterator +{ +public: + CustomIterator(const QStringList &nameFilters, QDir::Filters filters) + : QAbstractFileEngineIterator(nameFilters, filters), index(0) + { + // In a real iterator, these entries are fetched from the + // file system based on the value of path(). + entries << "entry1" << "entry2" << "entry3"; + } + + bool hasNext() const + { + return index < entries.size() - 1; + } + + QString next() + { + if (!hasNext()) + return QString(); + ++index; + return currentFilePath(); + } + + QString currentFileName() + { + return entries.at(index); + } + +private: + QStringList entries; + int index; +}; +//! [3] diff --git a/doc/src/snippets/code/src_corelib_io_qdatastream.cpp b/doc/src/snippets/code/src_corelib_io_qdatastream.cpp new file mode 100644 index 0000000000..cd9632c885 --- /dev/null +++ b/doc/src/snippets/code/src_corelib_io_qdatastream.cpp @@ -0,0 +1,121 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +void wrapInFunction() +{ + +//! [0] +QFile file("file.dat"); +file.open(QIODevice::WriteOnly); +QDataStream out(&file); // we will serialize the data into the file +out << QString("the answer is"); // serialize a string +out << (qint32)42; // serialize an integer +//! [0] + + +//! [1] +QFile file("file.dat"); +file.open(QIODevice::ReadOnly); +QDataStream in(&file); // read the data serialized from the file +QString str; +qint32 a; +in >> str >> a; // extract "the answer is" and 42 +//! [1] + + +//! [2] +stream.setVersion(QDataStream::Qt_4_0); +//! [2] + + +//! [3] +QFile file("file.xxx"); +file.open(QIODevice::WriteOnly); +QDataStream out(&file); + +// Write a header with a "magic number" and a version +out << (quint32)0xA0B0C0D0; +out << (qint32)123; + +out.setVersion(QDataStream::Qt_4_0); + +// Write the data +out << lots_of_interesting_data; +//! [3] + + +//! [4] +QFile file("file.xxx"); +file.open(QIODevice::ReadOnly); +QDataStream in(&file); + +// Read and check the header +quint32 magic; +in >> magic; +if (magic != 0xA0B0C0D0) + return XXX_BAD_FILE_FORMAT; + +// Read the version +qint32 version; +in >> version; +if (version < 100) + return XXX_BAD_FILE_TOO_OLD; +if (version > 123) + return XXX_BAD_FILE_TOO_NEW; + +if (version <= 110) + in.setVersion(QDataStream::Qt_3_2); +else + in.setVersion(QDataStream::Qt_4_0); + +// Read the data +in >> lots_of_interesting_data; +if (version >= 120) + in >> data_new_in_XXX_version_1_2; +in >> other_interesting_data; +//! [4] + + +//! [5] +QDataStream out(file); +out.setVersion(QDataStream::Qt_4_0); +//! [5] + +} diff --git a/doc/src/snippets/code/src_corelib_io_qdir.cpp b/doc/src/snippets/code/src_corelib_io_qdir.cpp new file mode 100644 index 0000000000..51262f711c --- /dev/null +++ b/doc/src/snippets/code/src_corelib_io_qdir.cpp @@ -0,0 +1,175 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + + +void wrapInFunction() +{ + +//! [0] +QDir("/home/user/Documents") +QDir("C:/Documents and Settings") +//! [0] + + +//! [1] +QDir("images/landscape.png") +//! [1] + + +//! [2] +QDir("Documents/Letters/Applications").dirName() // "Applications" +QDir().dirName() // "." +//! [2] + + +//! [3] +QDir directory("Documents/Letters"); +QString path = directory.filePath("contents.txt"); +QString absolutePath = directory.absoluteFilePath("contents.txt"); +//! [3] + + +//! [4] +QDir dir("example"); +if (!dir.exists()) + qWarning("Cannot find the example directory"); +//! [4] + + +//! [5] +QDir dir = QDir::root(); // "/" +if (!dir.cd("tmp")) { // "/tmp" + qWarning("Cannot find the \"/tmp\" directory"); +} else { + QFile file(dir.filePath("ex1.txt")); // "/tmp/ex1.txt" + if (!file.open(QIODevice::ReadWrite)) + qWarning("Cannot create the file %s", file.name()); +} +//! [5] + + +//! [6] +QString bin = "/local/bin"; // where /local/bin is a symlink to /usr/bin +QDir binDir(bin); +QString canonicalBin = binDir.canonicalPath(); +// canonicalBin now equals "/usr/bin" + +QString ls = "/local/bin/ls"; // where ls is the executable "ls" +QDir lsDir(ls); +QString canonicalLs = lsDir.canonicalPath(); +// canonicalLS now equals "/usr/bin/ls". +//! [6] + + +//! [7] +QDir dir("/home/bob"); +QString s; + +s = dir.relativeFilePath("images/file.jpg"); // s is "images/file.jpg" +s = dir.relativeFilePath("/home/mary/file.txt"); // s is "../mary/file.txt" +//! [7] + + +//! [8] +QDir::setSearchPaths("icons", QStringList(QDir::homePath() + "/images")); +QDir::setSearchPaths("docs", QStringList(":/embeddedDocuments")); +... +QPixmap pixmap("icons:undo.png"); // will look for undo.png in QDir::homePath() + "/images" +QFile file("docs:design.odf"); // will look in the :/embeddedDocuments resource path +//! [8] + + +//! [9] +QDir dir("/tmp/root_link"); +dir = dir.canonicalPath(); +if (dir.isRoot()) + qWarning("It is a root link"); +//! [9] + + +//! [10] +// The current directory is "/usr/local" +QDir d1("/usr/local/bin"); +QDir d2("bin"); +if (d1 == d2) + qDebug("They're the same"); +//! [10] + + +//! [11] +// The current directory is "/usr/local" +QDir d1("/usr/local/bin"); +d1.setFilter(QDir::Executable); +QDir d2("bin"); +if (d1 != d2) + qDebug("They differ"); +//! [11] + + +//! [12] +C:/Documents and Settings/Username +//! [12] + + +//! [13] +Q_INIT_RESOURCE(myapp); +//! [13] + + +//! [14] +inline void initMyResource() { Q_INIT_RESOURCE(myapp); } + +namespace MyNamespace +{ + ... + + void myFunction() + { + initMyResource(); + } +} +//! [14] + + +//! [15] +Q_CLEANUP_RESOURCE(myapp); +//! [15] + +} diff --git a/doc/src/snippets/code/src_corelib_io_qdiriterator.cpp b/doc/src/snippets/code/src_corelib_io_qdiriterator.cpp new file mode 100644 index 0000000000..e7a93d4021 --- /dev/null +++ b/doc/src/snippets/code/src_corelib_io_qdiriterator.cpp @@ -0,0 +1,52 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QDirIterator it("/etc", QDirIterator::Subdirectories); +while (it.hasNext()) { + qDebug() << it.next(); + + // /etc/. + // /etc/.. + // /etc/X11 + // /etc/X11/fs + // ... +} +//! [0] diff --git a/doc/src/snippets/code/src_corelib_io_qfile.cpp b/doc/src/snippets/code/src_corelib_io_qfile.cpp new file mode 100644 index 0000000000..158971e9ca --- /dev/null +++ b/doc/src/snippets/code/src_corelib_io_qfile.cpp @@ -0,0 +1,75 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QFile file; +QDir::setCurrent("/tmp"); +file.setFileName("readme.txt"); +QDir::setCurrent("/home"); +file.open(QIODevice::ReadOnly); // opens "/home/readme.txt" under Unix +//! [0] + + +//! [1] +QByteArray myEncoderFunc(const QString &fileName); +//! [1] + + +//! [2] +QString myDecoderFunc(const QByteArray &localFileName); +//! [2] + + +//! [3] +#include <stdio.h> + +void printError(const char* msg) +{ + QFile file; + file.open(stderr, QIODevice::WriteOnly); + file.write(msg, qstrlen(msg)); // write to stderr + file.close(); +} +//! [3] + + +//! [4] +CONFIG += console +//! [4] diff --git a/doc/src/snippets/code/src_corelib_io_qfileinfo.cpp b/doc/src/snippets/code/src_corelib_io_qfileinfo.cpp new file mode 100644 index 0000000000..85e00052f7 --- /dev/null +++ b/doc/src/snippets/code/src_corelib_io_qfileinfo.cpp @@ -0,0 +1,146 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + + +//![newstuff] + QFileInfo fi("c:/temp/foo"); => fi.absoluteFilePath() => "C:/temp/foo" +//![newstuff] + +//! [0] +#ifdef Q_OS_UNIX + +QFileInfo info1("/home/bob/bin/untabify"); +info1.isSymLink(); // returns true +info1.absoluteFilePath(); // returns "/home/bob/bin/untabify" +info1.size(); // returns 56201 +info1.symLinkTarget(); // returns "/opt/pretty++/bin/untabify" + +QFileInfo info2(info1.symLinkTarget()); +info2.isSymLink(); // returns false +info2.absoluteFilePath(); // returns "/opt/pretty++/bin/untabify" +info2.size(); // returns 56201 + +#endif +//! [0] + + +//! [1] +#ifdef Q_OS_WIN + +QFileInfo info1("C:\\Documents and Settings\\Bob\\untabify.lnk"); +info1.isSymLink(); // returns true +info1.absoluteFilePath(); // returns "C:/Documents and Settings/Bob/untabify.lnk" +info1.size(); // returns 743 +info1.symLinkTarget(); // returns "C:/Pretty++/untabify" + +QFileInfo info2(info1.symLinkTarget()); +info2.isSymLink(); // returns false +info2.absoluteFilePath(); // returns "C:/Pretty++/untabify" +info2.size(); // returns 63942 + +#endif +//! [1] + + +//! [2] +QString absolute = "/local/bin"; +QString relative = "local/bin"; +QFileInfo absFile(absolute); +QFileInfo relFile(relative); + +QDir::setCurrent(QDir::rootPath()); +// absFile and relFile now point to the same file + +QDir::setCurrent("/tmp"); +// absFile now points to "/local/bin", +// while relFile points to "/tmp/local/bin" +//! [2] + + +//! [3] +QFileInfo fi("/tmp/archive.tar.gz"); +QString name = fi.fileName(); // name = "archive.tar.gz" +//! [3] + + +//! [4] +QFileInfo fi("/Applications/Safari.app"); +QString bundle = fi.bundleName(); // name = "Safari" +//! [4] + + +//! [5] +QFileInfo fi("/tmp/archive.tar.gz"); +QString base = fi.baseName(); // base = "archive" +//! [5] + + +//! [6] +QFileInfo fi("/tmp/archive.tar.gz"); +QString base = fi.completeBaseName(); // base = "archive.tar" +//! [6] + + +//! [7] +QFileInfo fi("/tmp/archive.tar.gz"); +QString ext = fi.completeSuffix(); // ext = "tar.gz" +//! [7] + + +//! [8] +QFileInfo fi("/tmp/archive.tar.gz"); +QString ext = fi.suffix(); // ext = "gz" +//! [8] + + +//! [9] +QFileInfo info(fileName); +if (info.isSymLink()) + fileName = info.symLinkTarget(); +//! [9] + + +//! [10] +QFileInfo fi("/tmp/archive.tar.gz"); +if (fi.permission(QFile::WriteUser | QFile::ReadGroup)) + qWarning("I can change the file; my group can read the file"); +if (fi.permission(QFile::WriteGroup | QFile::WriteOther)) + qWarning("The group or others can change the file"); +//! [10] diff --git a/doc/src/snippets/code/src_corelib_io_qiodevice.cpp b/doc/src/snippets/code/src_corelib_io_qiodevice.cpp new file mode 100644 index 0000000000..1e2a976c77 --- /dev/null +++ b/doc/src/snippets/code/src_corelib_io_qiodevice.cpp @@ -0,0 +1,99 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QProcess gzip; +gzip.start("gzip", QStringList() << "-c"); +if (!gzip.waitForStarted()) + return false; + +gzip.write("uncompressed data"); + +QByteArray compressed; +while (gzip.waitForReadyRead()) + compressed += gzip.readAll(); +//! [0] + + +//! [1] +qint64 CustomDevice::bytesAvailable() const +{ + return buffer.size() + QIODevice::bytesAvailable(); +} +//! [1] + + +//! [2] +QFile file("box.txt"); +if (file.open(QFile::ReadOnly)) { + char buf[1024]; + qint64 lineLength = file.readLine(buf, sizeof(buf)); + if (lineLength != -1) { + // the line is available in buf + } +} +//! [2] + + +//! [3] +bool CustomDevice::canReadLine() const +{ + return buffer.contains('\n') || QIODevice::canReadLine(); +} +//! [3] + + +//! [4] +bool isExeFile(QFile *file) +{ + char buf[2]; + if (file->peek(buf, sizeof(buf)) == sizeof(buf)) + return (buf[0] == 'M' && buf[1] == 'Z'); + return false; +} +//! [4] + + +//! [5] +bool isExeFile(QFile *file) +{ + return file->peek(2) == "MZ"; +} +//! [5] diff --git a/doc/src/snippets/code/src_corelib_io_qprocess.cpp b/doc/src/snippets/code/src_corelib_io_qprocess.cpp new file mode 100644 index 0000000000..64fb17a7c7 --- /dev/null +++ b/doc/src/snippets/code/src_corelib_io_qprocess.cpp @@ -0,0 +1,134 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + + +void wrapInFunction() +{ + +//! [0] +QProcess builder; +builder.setProcessChannelMode(QProcess::MergedChannels); +builder.start("make", QStringList() << "-j2"); + +if (!builder.waitForFinished()) + qDebug() << "Make failed:" << builder.errorString(); +else + qDebug() << "Make output:" << builder.readAll(); +//! [0] + + +//! [1] +QProcess more; +more.start("more"); +more.write("Text to display"); +more.closeWriteChannel(); +// QProcess will emit readyRead() once "more" starts printing +//! [1] + + +//! [2] +command1 | command2 +//! [2] + + +//! [3] +QProcess process1; +QProcess process2; + +process1.setStandardOutputProcess(&process2); + +process1.start("command1"); +process2.start("command2"); +//! [3] + + +//! [4] +class SandboxProcess : public QProcess +{ + ... + protected: + void setupChildProcess(); + ... +}; + +void SandboxProcess::setupChildProcess() +{ + // Drop all privileges in the child process, and enter + // a chroot jail. +#if defined Q_OS_UNIX + ::setgroups(0, 0); + ::chroot("/etc/safe"); + ::chdir("/"); + ::setgid(safeGid); + ::setuid(safeUid); + ::umask(0); +#endif +} + +//! [4] + + +//! [5] +QProcess process; +process.start("del /s *.txt"); +// same as process.start("del", QStringList() << "/s" << "*.txt"); +... +//! [5] + + +//! [6] +QProcess process; +process.start("dir \"My Documents\""); +//! [6] + + +//! [7] +QProcess process; +process.start("dir \"\"\"My Documents\"\"\""); +//! [7] + + +//! [8] +QStringList environment = QProcess::systemEnvironment(); +// environment = {"PATH=/usr/bin:/usr/local/bin", +// "USER=greg", "HOME=/home/greg"} +//! [8] + +} diff --git a/doc/src/snippets/code/src_corelib_io_qsettings.cpp b/doc/src/snippets/code/src_corelib_io_qsettings.cpp new file mode 100644 index 0000000000..5abb0e368c --- /dev/null +++ b/doc/src/snippets/code/src_corelib_io_qsettings.cpp @@ -0,0 +1,316 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QSettings settings("MySoft", "Star Runner"); +QColor color = settings.value("DataPump/bgcolor").value<QColor>(); +//! [0] + + +//! [1] +QSettings settings("MySoft", "Star Runner"); +QColor color = palette().background().color(); +settings.setValue("DataPump/bgcolor", color); +//! [1] + + +//! [2] +QSettings settings("/home/petra/misc/myapp.ini", + QSettings::IniFormat); +//! [2] + + +//! [3] +QSettings settings("/Users/petra/misc/myapp.plist", + QSettings::NativeFormat); +//! [3] + + +//! [4] +QSettings settings("HKEY_CURRENT_USER\\Software\\Microsoft\\Office", + QSettings::NativeFormat); +//! [4] + + +//! [5] +settings.setValue("11.0/Outlook/Security/DontTrustInstalledFiles", 0); +//! [5] + + +//! [6] +settings.setValue("HKEY_CURRENT_USER\\MySoft\\Star Runner\\Galaxy", "Milkyway"); +settings.setValue("HKEY_CURRENT_USER\\MySoft\\Star Runner\\Galaxy\\Sun", "OurStar"); +settings.value("HKEY_CURRENT_USER\\MySoft\\Star Runner\\Galaxy\\Default"); // returns "Milkyway" +//! [6] + + +//! [7] +#ifdef Q_WS_MAC + QSettings settings("grenoullelogique.fr", "Squash"); +#else + QSettings settings("Grenoulle Logique", "Squash"); +#endif +//! [7] + + +//! [8] +pos = @Point(100 100) +//! [8] + + +//! [9] +windir = C:\Windows +//! [9] + + +//! [10] +QSettings settings("Moose Tech", "Facturo-Pro"); +//! [10] + + +//! [11] +QSettings settings("Moose Soft", "Facturo-Pro"); +//! [11] + + +//! [12] +QCoreApplication::setOrganizationName("Moose Soft"); +QCoreApplication::setApplicationName("Facturo-Pro"); +QSettings settings; +//! [12] + + +//! [13] +settings.beginGroup("mainwindow"); +settings.setValue("size", win->size()); +settings.setValue("fullScreen", win->isFullScreen()); +settings.endGroup(); + +settings.beginGroup("outputpanel"); +settings.setValue("visible", panel->isVisible()); +settings.endGroup(); +//! [13] + + +//! [14] +settings.beginGroup("alpha"); +// settings.group() == "alpha" + +settings.beginGroup("beta"); +// settings.group() == "alpha/beta" + +settings.endGroup(); +// settings.group() == "alpha" + +settings.endGroup(); +// settings.group() == "" +//! [14] + + +//! [15] +struct Login { + QString userName; + QString password; +}; +QList<Login> logins; +... + +QSettings settings; +int size = settings.beginReadArray("logins"); +for (int i = 0; i < size; ++i) { + settings.setArrayIndex(i); + Login login; + login.userName = settings.value("userName").toString(); + login.password = settings.value("password").toString(); + logins.append(login); +} +settings.endArray(); +//! [15] + + +//! [16] +struct Login { + QString userName; + QString password; +}; +QList<Login> logins; +... + +QSettings settings; +settings.beginWriteArray("logins"); +for (int i = 0; i < logins.size(); ++i) { + settings.setArrayIndex(i); + settings.setValue("userName", list.at(i).userName); + settings.setValue("password", list.at(i).password); +} +settings.endArray(); +//! [16] + + +//! [17] +QSettings settings; +settings.setValue("fridge/color", Qt::white); +settings.setValue("fridge/size", QSize(32, 96)); +settings.setValue("sofa", true); +settings.setValue("tv", false); + +QStringList keys = settings.allKeys(); +// keys: ["fridge/color", "fridge/size", "sofa", "tv"] +//! [17] + + +//! [18] +settings.beginGroup("fridge"); +keys = settings.allKeys(); +// keys: ["color", "size"] +//! [18] + + +//! [19] +QSettings settings; +settings.setValue("fridge/color", Qt::white); +settings.setValue("fridge/size", QSize(32, 96)); +settings.setValue("sofa", true); +settings.setValue("tv", false); + +QStringList keys = settings.childKeys(); +// keys: ["sofa", "tv"] +//! [19] + + +//! [20] +settings.beginGroup("fridge"); +keys = settings.childKeys(); +// keys: ["color", "size"] +//! [20] + + +//! [21] +QSettings settings; +settings.setValue("fridge/color", Qt::white); +settings.setValue("fridge/size", QSize(32, 96)); +settings.setValue("sofa", true); +settings.setValue("tv", false); + +QStringList groups = settings.childGroups(); +// group: ["fridge"] +//! [21] + + +//! [22] +settings.beginGroup("fridge"); +groups = settings.childGroups(); +// groups: [] +//! [22] + + +//! [23] +QSettings settings; +settings.setValue("interval", 30); +settings.value("interval").toInt(); // returns 30 + +settings.setValue("interval", 6.55); +settings.value("interval").toDouble(); // returns 6.55 +//! [23] + + +//! [24] +QSettings settings; +settings.setValue("ape"); +settings.setValue("monkey", 1); +settings.setValue("monkey/sea", 2); +settings.setValue("monkey/doe", 4); + +settings.remove("monkey"); +QStringList keys = settings.allKeys(); +// keys: ["ape"] +//! [24] + + +//! [25] +QSettings settings; +settings.setValue("ape"); +settings.setValue("monkey", 1); +settings.setValue("monkey/sea", 2); +settings.setValue("monkey/doe", 4); + +settings.beginGroup("monkey"); +settings.remove(""); +settings.endGroup(); + +QStringList keys = settings.allKeys(); +// keys: ["ape"] +//! [25] + + +//! [26] +QSettings settings; +settings.setValue("animal/snake", 58); +settings.value("animal/snake", 1024).toInt(); // returns 58 +settings.value("animal/zebra", 1024).toInt(); // returns 1024 +settings.value("animal/zebra").toInt(); // returns 0 +//! [26] + + +//! [27] +bool myReadFunc(QIODevice &device, QSettings::SettingsMap &map); +//! [27] + + +//! [28] +bool myWriteFunc(QIODevice &device, const QSettings::SettingsMap &map); +//! [28] + + +//! [29] +bool readXmlFile(QIODevice &device, QSettings::SettingsMap &map); +bool writeXmlFile(QIODevice &device, const QSettings::SettingsMap &map); + +int main(int argc, char *argv[]) +{ + const QSettings::Format XmlFormat = + QSettings::registerFormat("xml", readXmlFile, writeXmlFile); + + QSettings settings(XmlFormat, QSettings::UserScope, "MySoft", + "Star Runner"); + + ... +} +//! [29] diff --git a/doc/src/snippets/code/src_corelib_io_qtemporaryfile.cpp b/doc/src/snippets/code/src_corelib_io_qtemporaryfile.cpp new file mode 100644 index 0000000000..1fb1ccd77d --- /dev/null +++ b/doc/src/snippets/code/src_corelib_io_qtemporaryfile.cpp @@ -0,0 +1,53 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +{ +//! [0] + // Within a function/method... + + QTemporaryFile file; + if (file.open()) { + // file.fileName() returns the unique file name + } + + // The QTemporaryFile destructor removes the temporary file + // as it goes out of scope. +//! [0] +} diff --git a/doc/src/snippets/code/src_corelib_io_qtextstream.cpp b/doc/src/snippets/code/src_corelib_io_qtextstream.cpp new file mode 100644 index 0000000000..b3483a9b10 --- /dev/null +++ b/doc/src/snippets/code/src_corelib_io_qtextstream.cpp @@ -0,0 +1,129 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QFile data("output.txt"); +if (data.open(QFile::WriteOnly | QFile::Truncate)) { + QTextStream out(&data); + out << "Result: " << qSetFieldWidth(10) << left << 3.14 << 2.7; + // writes "Result: 3.14 2.7 " +} +//! [0] + + +//! [1] +QTextStream stream(stdin); +QString line; +do { + line = stream.readLine(); +} while (!line.isNull()); +//! [1] + + +//! [2] +QTextStream in("0x50 0x20"); +int firstNumber, secondNumber; + +in >> firstNumber; // firstNumber == 80 +in >> dec >> secondNumber; // secondNumber == 0 + +char ch; +in >> ch; // ch == 'x' +//! [2] + + +//! [3] +int main(int argc, char *argv[]) +{ + // read numeric arguments (123, 0x20, 4.5...) + for (int i = 1; i < argc; ++i) { + int number; + QTextStream in(argv[i]); + in >> number; + ... + } +} +//! [3] + + +//! [4] +QString str; +QTextStream in(stdin); +in >> str; +//! [4] + + +//! [5] +QString s; +QTextStream out(&s); +out.setFieldWidth(10); +out.setFieldAlignment(QTextStream::AlignCenter); +out.setPadChar('-'); +out << "Qt" << "rocks!"; +//! [5] + + +//! [6] +----Qt------rocks!-- +//! [6] + + +//! [7] +QTextStream in(file); +QChar ch1, ch2, ch3; +in >> ch1 >> ch2 >> ch3; +//! [7] + + +//! [8] +QTextStream out(stdout); +out << "Qt rocks!" << endl; +//! [8] + + +//! [9] +stream << '\n' << flush; +//! [9] + + +//! [10] +QTextStream out(&file); +out.setCodec("UTF-8"); +//! [10] diff --git a/doc/src/snippets/code/src_corelib_io_qurl.cpp b/doc/src/snippets/code/src_corelib_io_qurl.cpp new file mode 100644 index 0000000000..18f36da9f4 --- /dev/null +++ b/doc/src/snippets/code/src_corelib_io_qurl.cpp @@ -0,0 +1,87 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QUrl url("http://www.example.com/List of holidays.xml"); +// url.toEncoded() == "http://www.example.com/List%20of%20holidays.xml" +//! [0] + + +//! [1] +QUrl url = QUrl::fromEncoded("http://qt.nokia.com/List%20of%20holidays.xml"); +//! [1] + + +//! [2] +bool checkUrl(const QUrl &url) { + if (!url.isValid()) { + qDebug(QString("Invalid URL: %1").arg(url.toString())); + return false; + } + + return true; +} +//! [2] + + +//! [3] +QFtp ftp; +ftp.connectToHost(url.host(), url.port(21)); +//! [3] + + +//! [4] +http://www.example.com/cgi-bin/drawgraph.cgi?type-pie/color-green +//! [4] + + +//! [5] +QUrl baseUrl("http://qt.nokia.com/support"); +QUrl relativeUrl("../products/solutions"); +qDebug(baseUrl.resolved(relativeUrl).toString()); +// prints "http://qt.nokia.com/products/solutions" +//! [5] + + +//! [6] +QByteArray ba = QUrl::toPercentEncoding("{a fishy string?}", "{}", "s"); +qDebug(ba.constData()); +// prints "{a fi%73hy %73tring%3F}" +//! [6] diff --git a/doc/src/snippets/code/src_corelib_kernel_qabstracteventdispatcher.cpp b/doc/src/snippets/code/src_corelib_kernel_qabstracteventdispatcher.cpp new file mode 100644 index 0000000000..8f0a5c7ec8 --- /dev/null +++ b/doc/src/snippets/code/src_corelib_kernel_qabstracteventdispatcher.cpp @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +bool myEventFilter(void *message); +//! [0] diff --git a/doc/src/snippets/code/src_corelib_kernel_qabstractitemmodel.cpp b/doc/src/snippets/code/src_corelib_kernel_qabstractitemmodel.cpp new file mode 100644 index 0000000000..cf40f9a05a --- /dev/null +++ b/doc/src/snippets/code/src_corelib_kernel_qabstractitemmodel.cpp @@ -0,0 +1,123 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +beginInsertRows(parent, 2, 4); +//! [0] + + +//! [1] +beginInsertRows(parent, 4, 5); +//! [1] + + +//! [2] +beginRemoveRows(parent, 2, 3); +//! [2] + + +//! [3] +beginInsertColumns(parent, 4, 6); +//! [3] + + +//! [4] +beginInsertColumns(parent, 6, 8); +//! [4] + + +//! [5] +beginRemoveColumns(parent, 4, 6); +//! [5] + + +//! [6] +beginMoveRows(sourceParent, 2, 4, destinationParent, 2); +//! [6] + + +//! [7] +beginMoveRows(sourceParent, 2, 4, destinationParent, 6); +//! [7] + + +//! [8] +beginMoveRows(parent, 2, 2, parent, 0); +//! [8] + + +//! [9] +beginMoveRows(parent, 2, 2, parent, 4); +//! [9] + + +//! [10] +class CustomDataProxy : public QSortFilterProxyModel +{ + Q_OBJECT +public: + CustomDataProxy(QObject *parent) + : QSortFilterProxyModel(parent) + { + } + + ... + + QVariant data(const QModelIndex &index, int role) + { + if (role != Qt::BackgroundRole) + return QSortFilterProxyModel::data(index, role); + + if (m_customData.contains(index.row())) + return m_customData.value(index.row()); + return QSortFilterProxyModel::data(index, role); + } + +private slots: + void resetInternalData() + { + m_customData.clear(); + } + +private: + QHash<int, QVariant> m_customData; +}; +//! [10] + diff --git a/doc/src/snippets/code/src_corelib_kernel_qcoreapplication.cpp b/doc/src/snippets/code/src_corelib_kernel_qcoreapplication.cpp new file mode 100644 index 0000000000..0e6c16f6de --- /dev/null +++ b/doc/src/snippets/code/src_corelib_kernel_qcoreapplication.cpp @@ -0,0 +1,126 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QMouseEvent event(QEvent::MouseButtonPress, pos, 0, 0, 0); +QApplication::sendEvent(mainWindow, &event); +//! [0] + + +//! [1] +QPushButton *quitButton = new QPushButton("Quit"); +connect(quitButton, SIGNAL(clicked()), &app, SLOT(quit())); +//! [1] + + +//! [2] +foreach (const QString &path, app.libraryPaths()) + do_something(path); +//! [2] + + +//! [3] +bool myEventFilter(void *message, long *result); +//! [3] + + +//! [4] +static int *global_ptr = 0; + +static void cleanup_ptr() +{ + delete [] global_ptr; + global_ptr = 0; +} + +void init_ptr() +{ + global_ptr = new int[100]; // allocate data + qAddPostRoutine(cleanup_ptr); // delete later +} +//! [4] + + +//! [5] +class MyPrivateInitStuff : public QObject +{ +public: + static MyPrivateInitStuff *initStuff(QObject *parent) + { + if (!p) + p = new MyPrivateInitStuff(parent); + return p; + } + + ~MyPrivateInitStuff() + { + // cleanup goes here + } + +private: + MyPrivateInitStuff(QObject *parent) + : QObject(parent) + { + // initialization goes here + } + + MyPrivateInitStuff *p; +}; +//! [5] + + +//! [6] +static inline QString tr(const char *sourceText, + const char *comment = 0); +static inline QString trUtf8(const char *sourceText, + const char *comment = 0); +//! [6] + + +//! [7] +class MyMfcView : public CView +{ + Q_DECLARE_TR_FUNCTIONS(MyMfcView) + +public: + MyMfcView(); + ... +}; +//! [7] diff --git a/doc/src/snippets/code/src_corelib_kernel_qmetaobject.cpp b/doc/src/snippets/code/src_corelib_kernel_qmetaobject.cpp new file mode 100644 index 0000000000..86bad5e825 --- /dev/null +++ b/doc/src/snippets/code/src_corelib_kernel_qmetaobject.cpp @@ -0,0 +1,136 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + + +void wrapInFunction() +{ + +//! [0] +class MyClass : public QObject +{ + Q_OBJECT + Q_CLASSINFO("author", "Sabrina Schweinsteiger") + Q_CLASSINFO("url", "http://doc.moosesoft.co.uk/1.0/") + +public: + ... +}; +//! [0] + + +//! [1] +QByteArray normType = QMetaObject::normalizedType(" int const *"); +// normType is now "const int*" +//! [1] + + +//! [2] +QMetaObject::invokeMethod(pushButton, "animateClick", + Qt::QueuedConnection); +//! [2] + + +//! [3] +QMetaObject::invokeMethod: Unable to handle unregistered datatype 'MyType' +//! [3] + + +//! [4] +QString retVal; +QMetaObject::invokeMethod(obj, "compute", Qt::DirectConnection, + Q_RETURN_ARG(QString, retVal), + Q_ARG(QString, "sqrt"), + Q_ARG(int, 42), + Q_ARG(double, 9.7)); +//! [4] + + +//! [5] +class MyClass +{ + Q_OBJECT + Q_CLASSINFO("author", "Sabrina Schweinsteiger") + Q_CLASSINFO("url", "http://doc.moosesoft.co.uk/1.0/") + +public: + ... +}; +//! [5] + + +//! [propertyCount] +const QMetaObject* metaObject = obj->metaObject(); +QStringList properties; +for(int i = metaObject->propertyOffset(); i < metaObject->propertyCount(); ++i) + properties << QString::fromLatin1(metaObject->property(i).name()); +//! [propertyCount] + + +//! [methodCount] +const QMetaObject* metaObject = obj->metaObject(); +QStringList methods; +for(int i = metaObject->methodOffset(); i < metaObject->methodCount(); ++i) + methods << QString::fromLatin1(metaObject->method(i).signature()); +//! [methodCount] + +//! [6] +int methodIndex = pushButton->metaObject()->indexOfMethod("animateClick()"); +QMetaMethod method = metaObject->method(methodIndex); +method.invoke(pushButton, Qt::QueuedConnection); +//! [6] + +//! [7] +QMetaMethod::invoke: Unable to handle unregistered datatype 'MyType' +//! [7] + +//! [8] +QString retVal; +QByteArray normalizedSignature = QMetaObject::normalizedSignature("compute(QString, int, double)"); +int methodIndex = obj->metaObject()->indexOfMethod(normalizedSignature); +QMetaMethod method = metaObject->method(methodIndex); +method.invoke(obj, + Qt::DirectConnection, + Q_RETURN_ARG(QString, retVal), + Q_ARG(QString, "sqrt"), + Q_ARG(int, 42), + Q_ARG(double, 9.7)); +//! [8] + +} diff --git a/doc/src/snippets/code/src_corelib_kernel_qmetatype.cpp b/doc/src/snippets/code/src_corelib_kernel_qmetatype.cpp new file mode 100644 index 0000000000..35e6feb523 --- /dev/null +++ b/doc/src/snippets/code/src_corelib_kernel_qmetatype.cpp @@ -0,0 +1,114 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +struct MyStruct +{ + int i; + ... +}; + +Q_DECLARE_METATYPE(MyStruct) +//! [0] + + +//! [1] +namespace MyNamespace +{ + ... +} + +Q_DECLARE_METATYPE(MyNamespace::MyStruct) +//! [1] + + +//! [2] +MyStruct s; +QVariant var; +var.setValue(s); // copy s into the variant + +... + +// retrieve the value +MyStruct s2 = var.value<MyStruct>(); +//! [2] + + +//! [3] +int id = QMetaType::type("MyClass"); +if (id == 0) { + void *myClassPtr = QMetaType::construct(id); + ... + QMetaType::destroy(id, myClassPtr); + myClassPtr = 0; +} +//! [3] + + +//! [4] +qRegisterMetaType<MyClass>("MyClass"); +//! [4] + + +//! [5] +qRegisterMetaTypeStreamOperators<MyClass>("MyClass"); +//! [5] + + +//! [6] +QDataStream &operator<<(QDataStream &out, const MyClass &myObj); +QDataStream &operator>>(QDataStream &in, MyClass &myObj); +//! [6] + + +//! [7] +int id = qRegisterMetaType<MyStruct>(); +//! [7] + + +//! [8] +int id = qMetaTypeId<QString>(); // id is now QMetaType::QString +id = qMetaTypeId<MyStruct>(); // compile error if MyStruct not declared +//! [8] + +//! [9] +typedef QString CustomString; +qRegisterMetaType<CustomString>("CustomString"); +//! [9] diff --git a/doc/src/snippets/code/src_corelib_kernel_qmimedata.cpp b/doc/src/snippets/code/src_corelib_kernel_qmimedata.cpp new file mode 100644 index 0000000000..fcfc662f45 --- /dev/null +++ b/doc/src/snippets/code/src_corelib_kernel_qmimedata.cpp @@ -0,0 +1,108 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +void MyWidget::dragEnterEvent(QDragEnterEvent *event) +{ + if (event->mimeData()->hasUrls()) + event->acceptProposedAction(); +} + +void MyWidget::dropEvent(QDropEvent *event) +{ + if (event->mimeData()->hasUrls()) { + foreach (QUrl url, event->mimeData()->urls()) { + ... + } + } +} +//! [0] + + +//! [1] +QByteArray csvData = ...; + +QMimeData *mimeData = new QMimeData; +mimeData->setData("text/csv", csvData); +//! [1] + + +//! [2] +void MyWidget::dropEvent(QDropEvent *event) +{ + const MyMimeData *myData = + qobject_cast<const MyMimeData *>(event->mimeData()); + if (myData) { + // access myData's data directly (not through QMimeData's API) + } +} +//! [2] + + +//! [3] +application/x-qt-windows-mime;value="<custom type>" +//! [3] + + +//! [4] +application/x-qt-windows-mime;value="FileGroupDescriptor" +application/x-qt-windows-mime;value="FileContents" +//! [4] + + +//! [5] +if (event->mimeData()->hasImage()) { + QImage image = qvariant_cast<QImage>(event->mimeData()->imageData()); + ... +} +//! [5] + + +//! [6] +mimeData->setImageData(QImage("beautifulfjord.png")); +//! [6] + + +//! [7] +if (event->mimeData()->hasColor()) { + QColor color = qvariant_cast<QColor>(event->mimeData()->colorData()); + ... +} +//! [7] diff --git a/doc/src/snippets/code/src_corelib_kernel_qobject.cpp b/doc/src/snippets/code/src_corelib_kernel_qobject.cpp new file mode 100644 index 0000000000..afb9460983 --- /dev/null +++ b/doc/src/snippets/code/src_corelib_kernel_qobject.cpp @@ -0,0 +1,448 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QLineEdit *lineEdit = static_cast<QLineEdit *>( + qt_find_obj_child(myWidget, "QLineEdit", "my line edit")); +if (lineEdit) + lineEdit->setText("Default"); +//! [0] + + +//! [1] +QObject *obj = new QPushButton; +obj->metaObject()->className(); // returns "QPushButton" + +QPushButton::staticMetaObject.className(); // returns "QPushButton" +//! [1] + + +//! [2] +QPushButton::staticMetaObject.className(); // returns "QPushButton" + +QObject *obj = new QPushButton; +obj->metaObject()->className(); // returns "QPushButton" +//! [2] + + +//! [3] +QObject *obj = new QTimer; // QTimer inherits QObject + +QTimer *timer = qobject_cast<QTimer *>(obj); +// timer == (QObject *)obj + +QAbstractButton *button = qobject_cast<QAbstractButton *>(obj); +// button == 0 +//! [3] + + +//! [4] +QTimer *timer = new QTimer; // QTimer inherits QObject +timer->inherits("QTimer"); // returns true +timer->inherits("QObject"); // returns true +timer->inherits("QAbstractButton"); // returns false + +// QVBoxLayout inherits QObject and QLayoutItem +QVBoxLayout *layout = new QVBoxLayout; +layout->inherits("QObject"); // returns true +layout->inherits("QLayoutItem"); // returns true (even though QLayoutItem is not a QObject) +//! [4] + + +//! [5] +qDebug("MyClass::setPrecision(): (%s) invalid precision %f", + qPrintable(objectName()), newPrecision); +//! [5] + + +//! [6] +class MainWindow : public QMainWindow +{ +public: + MainWindow(); + +protected: + bool eventFilter(QObject *obj, QEvent *ev); + +private: + QTextEdit *textEdit; +}; + +MainWindow::MainWindow() +{ + textEdit = new QTextEdit; + setCentralWidget(textEdit); + + textEdit->installEventFilter(this); +} + +bool MainWindow::eventFilter(QObject *obj, QEvent *event) +{ + if (obj == textEdit) { + if (event->type() == QEvent::KeyPress) { + QKeyEvent *keyEvent = static_cast<QKeyEvent*>(event); + qDebug() << "Ate key press" << keyEvent->key(); + return true; + } else { + return false; + } + } else { + // pass the event on to the parent class + return QMainWindow::eventFilter(obj, event); + } +} +//! [6] + + +//! [7] +myObject->moveToThread(QApplication::instance()->thread()); +//! [7] + + +//! [8] +class MyObject : public QObject +{ + Q_OBJECT + +public: + MyObject(QObject *parent = 0); + +protected: + void timerEvent(QTimerEvent *event); +}; + +MyObject::MyObject(QObject *parent) + : QObject(parent) +{ + startTimer(50); // 50-millisecond timer + startTimer(1000); // 1-second timer + startTimer(60000); // 1-minute timer +} + +void MyObject::timerEvent(QTimerEvent *event) +{ + qDebug() << "Timer ID:" << event->timerId(); +} +//! [8] + + +//! [9] +QList<QObject *> list = window()->queryList("QAbstractButton")); +foreach (QObject *obj, list) + static_cast<QAbstractButton *>(obj)->setEnabled(false); +//! [9] + + +//! [10] +QPushButton *button = parentWidget->findChild<QPushButton *>("button1"); +//! [10] + + +//! [11] +QListWidget *list = parentWidget->findChild<QListWidget *>(); +//! [11] + + +//! [12] +QList<QWidget *> widgets = parentWidget.findChildren<QWidget *>("widgetname"); +//! [12] + + +//! [13] +QList<QPushButton *> allPButtons = parentWidget.findChildren<QPushButton *>(); +//! [13] + + +//! [14] +monitoredObj->installEventFilter(filterObj); +//! [14] + + +//! [15] +class KeyPressEater : public QObject +{ + Q_OBJECT + ... + +protected: + bool eventFilter(QObject *obj, QEvent *event); +}; + +bool KeyPressEater::eventFilter(QObject *obj, QEvent *event) +{ + if (event->type() == QEvent::KeyPress) { + QKeyEvent *keyEvent = static_cast<QKeyEvent *>(event); + qDebug("Ate key press %d", keyEvent->key()); + return true; + } else { + // standard event processing + return QObject::eventFilter(obj, event); + } +} +//! [15] + + +//! [16] +KeyPressEater *keyPressEater = new KeyPressEater(this); +QPushButton *pushButton = new QPushButton(this); +QListView *listView = new QListView(this); + +pushButton->installEventFilter(keyPressEater); +listView->installEventFilter(keyPressEater); +//! [16] + + +//! [17] +MyWindow::MyWindow() +{ + QLabel *senderLabel = new QLabel(tr("Name:")); + QLabel *recipientLabel = new QLabel(tr("Name:", "recipient")); +//! [17] +} + + +//! [18] +int n = messages.count(); +showMessage(tr("%n message(s) saved", "", n)); +//! [18] + + +//! [19] +n == 1 ? tr("%n message saved") : tr("%n messages saved") +//! [19] + + +//! [20] +label->setText(tr("F\374r \310lise")); +//! [20] + + +//! [21] +if (receivers(SIGNAL(valueChanged(QByteArray))) > 0) { + QByteArray data; + get_the_value(&data); // expensive operation + emit valueChanged(data); +} +//! [21] + + +//! [22] +QLabel *label = new QLabel; +QScrollBar *scrollBar = new QScrollBar; +QObject::connect(scrollBar, SIGNAL(valueChanged(int)), + label, SLOT(setNum(int))); +//! [22] + + +//! [23] +// WRONG +QObject::connect(scrollBar, SIGNAL(valueChanged(int value)), + label, SLOT(setNum(int value))); +//! [23] + + +//! [24] +class MyWidget : public QWidget +{ + Q_OBJECT + +public: + MyWidget(); + +signals: + void buttonClicked(); + +private: + QPushButton *myButton; +}; + +MyWidget::MyWidget() +{ + myButton = new QPushButton(this); + connect(myButton, SIGNAL(clicked()), + this, SIGNAL(buttonClicked())); +} +//! [24] + + +//! [25] +QObject::connect: Cannot queue arguments of type 'MyType' +(Make sure 'MyType' is registered using qRegisterMetaType().) +//! [25] + + +//! [26] +disconnect(myObject, 0, 0, 0); +//! [26] + + +//! [27] +myObject->disconnect(); +//! [27] + + +//! [28] +disconnect(myObject, SIGNAL(mySignal()), 0, 0); +//! [28] + + +//! [29] +myObject->disconnect(SIGNAL(mySignal())); +//! [29] + + +//! [30] +disconnect(myObject, 0, myReceiver, 0); +//! [30] + + +//! [31] +myObject->disconnect(myReceiver); +//! [31] + + +//! [32] +if (QLatin1String(signal) == SIGNAL(valueChanged(int))) { + // signal is valueChanged(int) +} +//! [32] + + +//! [33] +void on_<object name>_<signal name>(<signal parameters>); +//! [33] + + +//! [34] +void on_button1_clicked(); +//! [34] + + +//! [35] +class MyClass : public QObject +{ + Q_OBJECT + Q_CLASSINFO("Author", "Pierre Gendron") + Q_CLASSINFO("URL", "http://www.my-organization.qc.ca") + +public: + ... +}; +//! [35] + + +//! [36] +Q_PROPERTY(type name + READ getFunction + [WRITE setFunction] + [RESET resetFunction] + [NOTIFY notifySignal] + [DESIGNABLE bool] + [SCRIPTABLE bool] + [STORED bool] + [USER bool] + [CONSTANT] + [FINAL]) +//! [36] + + +//! [37] +Q_PROPERTY(QString title READ title WRITE setTitle USER true) +//! [37] + + +//! [38] +class MyClass : public QObject +{ + Q_OBJECT + Q_ENUMS(Priority) + +public: + MyClass(QObject *parent = 0); + ~MyClass(); + + enum Priority { High, Low, VeryHigh, VeryLow }; + void setPriority(Priority priority); + Priority priority() const; +}; +//! [38] + + +//! [39a] +class QLibrary : public QObject +{ + ... + Q_FLAGS(LoadHint LoadHints) + ... +//! [39a] + +//! [39b] + ... +public: + enum LoadHint { + ResolveAllSymbolsHint = 0x01, + ExportExternalSymbolsHint = 0x02, + LoadArchiveMemberHint = 0x04 + }; + Q_DECLARE_FLAGS(LoadHints, LoadHint) + ... +//! [39b] + + +//! [40] +//: This name refers to a host name. +hostNameLabel->setText(tr("Name:")); + +/*: This text refers to a C++ code example. */ +QString example = tr("Example"); +//! [40] + +//! [meta data] +//: This is a comment for the translator. +//= qtn_foo_bar +//~ loc-layout_id foo_dialog +//~ loc-blank False +//~ magic-stuff This might mean something magic. +QString text = MyMagicClass::tr("Sim sala bim."); +//! [meta data] + +//! [explicit tr context] +QString text = QScrollBar::tr("Page up"); +//! [explicit tr context] diff --git a/doc/src/snippets/code/src_corelib_kernel_qsystemsemaphore.cpp b/doc/src/snippets/code/src_corelib_kernel_qsystemsemaphore.cpp new file mode 100644 index 0000000000..1f5c5acda4 --- /dev/null +++ b/doc/src/snippets/code/src_corelib_kernel_qsystemsemaphore.cpp @@ -0,0 +1,61 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QSystemSemaphore sem("market", 3, QSystemSemaphore::Create); + // resources available == 3 +sem.acquire(); // resources available == 2 +sem.acquire(); // resources available == 1 +sem.acquire(); // resources available == 0 +sem.release(); // resources available == 1 +sem.release(2); // resources available == 3 +//! [0] + + +//! [1] +QSystemSemaphore sem("market", 5, QSystemSemaphore::Create); +sem.acquire(5); // acquire all 5 resources +sem.release(5); // release the 5 resources +//! [1] + + +//! [2] +sem.release(10); // "create" 10 new resources +//! [2] diff --git a/doc/src/snippets/code/src_corelib_kernel_qtimer.cpp b/doc/src/snippets/code/src_corelib_kernel_qtimer.cpp new file mode 100644 index 0000000000..ef06fd84b2 --- /dev/null +++ b/doc/src/snippets/code/src_corelib_kernel_qtimer.cpp @@ -0,0 +1,52 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +#include <QApplication> +#include <QTimer> + +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + QTimer::singleShot(600000, &app, SLOT(quit())); + ... + return app.exec(); +} +//! [0] diff --git a/doc/src/snippets/code/src_corelib_kernel_qvariant.cpp b/doc/src/snippets/code/src_corelib_kernel_qvariant.cpp new file mode 100644 index 0000000000..8b1bcbf41d --- /dev/null +++ b/doc/src/snippets/code/src_corelib_kernel_qvariant.cpp @@ -0,0 +1,136 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QDataStream out(...); +QVariant v(123); // The variant now contains an int +int x = v.toInt(); // x = 123 +out << v; // Writes a type tag and an int to out +v = QVariant("hello"); // The variant now contains a QByteArray +v = QVariant(tr("hello")); // The variant now contains a QString +int y = v.toInt(); // y = 0 since v cannot be converted to an int +QString s = v.toString(); // s = tr("hello") (see QObject::tr()) +out << v; // Writes a type tag and a QString to out +... +QDataStream in(...); // (opening the previously written stream) +in >> v; // Reads an Int variant +int z = v.toInt(); // z = 123 +qDebug("Type is %s", // prints "Type is int" + v.typeName()); +v = v.toInt() + 100; // The variant now hold the value 223 +v = QVariant(QStringList()); +//! [0] + + +//! [1] +QVariant x, y(QString()), z(QString("")); +x.convert(QVariant::Int); +// x.isNull() == true +// y.isNull() == true, z.isNull() == false +//! [1] + + +//! [2] +QVariant variant; +... +QColor color = variant.value<QColor>(); +//! [2] + + +//! [3] +QColor color = palette().background().color(); +QVariant variant = color; +//! [3] + + +//! [4] +QVariant v; + +v.setValue(5); +int i = v.toInt(); // i is now 5 +QString s = v.toString() // s is now "5" + +MyCustomStruct c; +v.setValue(c); + +... + +MyCustomStruct c2 = v.value<MyCustomStruct>(); +//! [4] + + +//! [5] +QVariant v; + +MyCustomStruct c; +if (v.canConvert<MyCustomStruct>()) + c = v.value<MyCustomStruct>(); + +v = 7; +int i = v.value<int>(); // same as v.toInt() +QString s = v.value<QString>(); // same as v.toString(), s is now "7" +MyCustomStruct c2 = v.value<MyCustomStruct>(); // conversion failed, c2 is empty +//! [5] + + +//! [6] +QVariant v = 42; + +v.canConvert<int>(); // returns true +v.canConvert<QString>(); // returns true + +MyCustomStruct s; +v.setValue(s); + +v.canConvert<int>(); // returns false +v.canConvert<MyCustomStruct>(); // returns true +//! [6] + + +//! [7] +MyCustomStruct s; +return QVariant::fromValue(s); +//! [7] + + +//! [8] +QObject *object = getObjectFromSomewhere(); +QVariant data = QVariant::fromValue(object); +//! [8] diff --git a/doc/src/snippets/code/src_corelib_plugin_qlibrary.cpp b/doc/src/snippets/code/src_corelib_plugin_qlibrary.cpp new file mode 100644 index 0000000000..8943e92475 --- /dev/null +++ b/doc/src/snippets/code/src_corelib_plugin_qlibrary.cpp @@ -0,0 +1,84 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QLibrary myLib("mylib"); +typedef void (*MyPrototype)(); +MyPrototype myFunction = (MyPrototype) myLib.resolve("mysymbol"); +if (myFunction) + myFunction(); +//! [0] + + +//! [1] +typedef void (*MyPrototype)(); +MyPrototype myFunction = + (MyPrototype) QLibrary::resolve("mylib", "mysymbol"); +if (myFunction) + myFunction(); +//! [1] + + +//! [2] +typedef int (*AvgFunction)(int, int); + +AvgFunction avg = (AvgFunction) library->resolve("avg"); +if (avg) + return avg(5, 8); +else + return -1; +//! [2] + + +//! [3] +extern "C" MY_EXPORT int avg(int a, int b) +{ + return (a + b) / 2; +} +//! [3] + + +//! [4] +#ifdef Q_WS_WIN +#define MY_EXPORT __declspec(dllexport) +#else +#define MY_EXPORT +#endif +//! [4] diff --git a/doc/src/snippets/code/src_corelib_plugin_quuid.cpp b/doc/src/snippets/code/src_corelib_plugin_quuid.cpp new file mode 100644 index 0000000000..88cdb54515 --- /dev/null +++ b/doc/src/snippets/code/src_corelib_plugin_quuid.cpp @@ -0,0 +1,44 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +// {67C8770B-44F1-410A-AB9A-F9B5446F13EE} +QUuid IID_MyInterface(0x67c8770b, 0x44f1, 0x410a, 0xab, 0x9a, 0xf9, 0xb5, 0x44, 0x6f, 0x13, 0xee) +//! [0] diff --git a/doc/src/snippets/code/src_corelib_statemachine_qstatemachine.cpp b/doc/src/snippets/code/src_corelib_statemachine_qstatemachine.cpp new file mode 100644 index 0000000000..9909b1b6e2 --- /dev/null +++ b/doc/src/snippets/code/src_corelib_statemachine_qstatemachine.cpp @@ -0,0 +1,55 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [simple state machine] +QPushButton button; + +QStateMachine machine; +QState *s1 = new QState(); +s1->assignProperty(&button, "text", "Click me"); + +QFinalState *s2 = new QFinalState(); +s1->addTransition(&button, SIGNAL(clicked()), s2); + +machine.addState(s1); +machine.addState(s2); +machine.setInitialState(s1); +machine.start(); +//! [simple state machine] diff --git a/doc/src/snippets/code/src_corelib_thread_qatomic.cpp b/doc/src/snippets/code/src_corelib_thread_qatomic.cpp new file mode 100644 index 0000000000..a70c187b7d --- /dev/null +++ b/doc/src/snippets/code/src_corelib_thread_qatomic.cpp @@ -0,0 +1,98 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +MySharedType &MySharedType::operator=(const MySharedType &other) +{ + (void) other.data->atomicInt.ref(); + if (!data->atomicInt.deref()) { + // The last reference has been released + delete d; + } + d = other.d; + return *this; +} +//! [0] + + +//! [1] +if (currentValue == expectedValue) { + currentValue = newValue; + return true; +} +return false; +//! [1] + + +//! [2] +int originalValue = currentValue; +currentValue = newValue; +return originalValue; +//! [2] + + +//! [3] +int originalValue = currentValue; +currentValue += valueToAdd; +return originalValue; +//! [3] + + +//! [4] +if (currentValue == expectedValue) { + currentValue = newValue; + return true; +} +return false; +//! [4] + + +//! [5] +T *originalValue = currentValue; +currentValue = newValue; +return originalValue; +//! [5] + + +//! [6] +T *originalValue = currentValue; +currentValue += valueToAdd; +return originalValue; +//! [6] diff --git a/doc/src/snippets/code/src_corelib_thread_qmutex.cpp b/doc/src/snippets/code/src_corelib_thread_qmutex.cpp new file mode 100644 index 0000000000..7800a4da2d --- /dev/null +++ b/doc/src/snippets/code/src_corelib_thread_qmutex.cpp @@ -0,0 +1,193 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +int number = 6; + +void method1() +{ + number *= 5; + number /= 4; +} + +void method2() +{ + number *= 3; + number /= 2; +} +//! [0] + + +//! [1] +// method1() +number *= 5; // number is now 30 +number /= 4; // number is now 7 + +// method2() +number *= 3; // number is now 21 +number /= 2; // number is now 10 +//! [1] + + +//! [2] +// Thread 1 calls method1() +number *= 5; // number is now 30 + +// Thread 2 calls method2(). +// +// Most likely Thread 1 has been put to sleep by the operating +// system to allow Thread 2 to run. +number *= 3; // number is now 90 +number /= 2; // number is now 45 + +// Thread 1 finishes executing. +number /= 4; // number is now 11, instead of 10 +//! [2] + + +//! [3] +QMutex mutex; +int number = 6; + +void method1() +{ + mutex.lock(); + number *= 5; + number /= 4; + mutex.unlock(); +} + +void method2() +{ + mutex.lock(); + number *= 3; + number /= 2; + mutex.unlock(); +} +//! [3] + + +//! [4] +int complexFunction(int flag) +{ + mutex.lock(); + + int retVal = 0; + + switch (flag) { + case 0: + case 1: + mutex.unlock(); + return moreComplexFunction(flag); + case 2: + { + int status = anotherFunction(); + if (status < 0) { + mutex.unlock(); + return -2; + } + retVal = status + flag; + } + break; + default: + if (flag > 10) { + mutex.unlock(); + return -1; + } + break; + } + + mutex.unlock(); + return retVal; +} +//! [4] + + +//! [5] +int complexFunction(int flag) +{ + QMutexLocker locker(&mutex); + + int retVal = 0; + + switch (flag) { + case 0: + case 1: + return moreComplexFunction(flag); + case 2: + { + int status = anotherFunction(); + if (status < 0) + return -2; + retVal = status + flag; + } + break; + default: + if (flag > 10) + return -1; + break; + } + + return retVal; +} +//! [5] + + +//! [6] +class SignalWaiter +{ +private: + QMutexLocker locker; + +public: + SignalWaiter(QMutex *mutex) + : locker(mutex) + { + } + + void waitForSignal() + { + ... + while (!signalled) + waitCondition.wait(locker.mutex()); + ... + } +}; +//! [6] diff --git a/doc/src/snippets/code/src_corelib_thread_qmutexpool.cpp b/doc/src/snippets/code/src_corelib_thread_qmutexpool.cpp new file mode 100644 index 0000000000..5163fe54f8 --- /dev/null +++ b/doc/src/snippets/code/src_corelib_thread_qmutexpool.cpp @@ -0,0 +1,61 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +class Number { +public: + Number(double n) : num (n) { } + + void setNumber(double n) { num = n; } + double number() const { return num; } + +private: + double num; +}; +//! [0] + + +//! [1] +void calcSquare(Number *num) +{ + QMutexLocker locker(mutexpool.get(num)); + num.setNumber(num.number() * num.number()); +} +//! [1] diff --git a/doc/src/snippets/code/src_corelib_thread_qreadwritelock.cpp b/doc/src/snippets/code/src_corelib_thread_qreadwritelock.cpp new file mode 100644 index 0000000000..9b325a785d --- /dev/null +++ b/doc/src/snippets/code/src_corelib_thread_qreadwritelock.cpp @@ -0,0 +1,109 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QReadWriteLock lock; + +void ReaderThread::run() +{ + ... + lock.lockForRead(); + read_file(); + lock.unlock(); + ... +} + +void WriterThread::run() +{ + ... + lock.lockForWrite(); + write_file(); + lock.unlock(); + ... +} +//! [0] + + +//! [1] +QReadWriteLock lock; + +QByteArray readData() +{ + QReadLocker locker(&lock); + ... + return data; +} +//! [1] + + +//! [2] +QReadWriteLock lock; + +QByteArray readData() +{ + lock.lockForRead(); + ... + lock.unlock(); + return data; +} +//! [2] + + +//! [3] +QReadWriteLock lock; + +void writeData(const QByteArray &data) +{ + QWriteLocker locker(&lock); + ... +} +//! [3] + + +//! [4] +QReadWriteLock lock; + +void writeData(const QByteArray &data) +{ + lock.lockForWrite(); + ... + lock.unlock(); +} +//! [4] diff --git a/doc/src/snippets/code/src_corelib_thread_qsemaphore.cpp b/doc/src/snippets/code/src_corelib_thread_qsemaphore.cpp new file mode 100644 index 0000000000..72a15dee2c --- /dev/null +++ b/doc/src/snippets/code/src_corelib_thread_qsemaphore.cpp @@ -0,0 +1,73 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QSemaphore sem(5); // sem.available() == 5 + +sem.acquire(3); // sem.available() == 2 +sem.acquire(2); // sem.available() == 0 +sem.release(5); // sem.available() == 5 +sem.release(5); // sem.available() == 10 + +sem.tryAcquire(1); // sem.available() == 9, returns true +sem.tryAcquire(250); // sem.available() == 9, returns false +//! [0] + + +//! [1] +QSemaphore sem(5); // a semaphore that guards 5 resources +sem.acquire(5); // acquire all 5 resources +sem.release(5); // release the 5 resources +sem.release(10); // "create" 10 new resources +//! [1] + + +//! [2] +QSemaphore sem(5); // sem.available() == 5 +sem.tryAcquire(250); // sem.available() == 5, returns false +sem.tryAcquire(3); // sem.available() == 2, returns true +//! [2] + + +//! [3] +QSemaphore sem(5); // sem.available() == 5 +sem.tryAcquire(250, 1000); // sem.available() == 5, waits 1000 milliseconds and returns false +sem.tryAcquire(3, 30000); // sem.available() == 2, returns true without waiting +//! [3] diff --git a/doc/src/snippets/code/src_corelib_thread_qthread.cpp b/doc/src/snippets/code/src_corelib_thread_qthread.cpp new file mode 100644 index 0000000000..2b2422f7de --- /dev/null +++ b/doc/src/snippets/code/src_corelib_thread_qthread.cpp @@ -0,0 +1,56 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +class MyThread : public QThread +{ +public: + void run(); +}; + +void MyThread::run() +{ + QTcpSocket socket; + // connect QTcpSocket's signals somewhere meaningful + ... + socket.connectToHost(hostName, portNumber); + exec(); +} +//! [0] diff --git a/doc/src/snippets/code/src_corelib_thread_qwaitcondition_unix.cpp b/doc/src/snippets/code/src_corelib_thread_qwaitcondition_unix.cpp new file mode 100644 index 0000000000..49574cb36d --- /dev/null +++ b/doc/src/snippets/code/src_corelib_thread_qwaitcondition_unix.cpp @@ -0,0 +1,89 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +forever { + mutex.lock(); + keyPressed.wait(&mutex); + do_something(); + mutex.unlock(); +} +//! [0] + + +//! [1] +forever { + getchar(); + keyPressed.wakeAll(); +} +//! [1] + + +//! [2] +forever { + mutex.lock(); + keyPressed.wait(&mutex); + ++count; + mutex.unlock(); + + do_something(); + + mutex.lock(); + --count; + mutex.unlock(); +} +//! [2] + + +//! [3] +forever { + getchar(); + + mutex.lock(); + // Sleep until there are no busy worker threads + while (count > 0) { + mutex.unlock(); + sleep(1); + mutex.lock(); + } + keyPressed.wakeAll(); + mutex.unlock(); +} +//! [3] diff --git a/doc/src/snippets/code/src_corelib_tools_qbitarray.cpp b/doc/src/snippets/code/src_corelib_tools_qbitarray.cpp new file mode 100644 index 0000000000..11621dcf92 --- /dev/null +++ b/doc/src/snippets/code/src_corelib_tools_qbitarray.cpp @@ -0,0 +1,176 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QBitArray ba(200); +//! [0] + + +//! [1] +QBitArray ba; +ba.resize(3); +ba[0] = true; +ba[1] = false; +ba[2] = true; +//! [1] + + +//! [2] +QBitArray ba(3); +ba.setBit(0, true); +ba.setBit(1, false); +ba.setBit(2, true); +//! [2] + + +//! [3] +QBitArray x(5); +x.setBit(3, true); +// x: [ 0, 0, 0, 1, 0 ] + +QBitArray y(5); +y.setBit(4, true); +// y: [ 0, 0, 0, 0, 1 ] + +x |= y; +// x: [ 0, 0, 0, 1, 1 ] +//! [3] + + +//! [4] +QBitArray().isNull(); // returns true +QBitArray().isEmpty(); // returns true + +QBitArray(0).isNull(); // returns false +QBitArray(0).isEmpty(); // returns true + +QBitArray(3).isNull(); // returns false +QBitArray(3).isEmpty(); // returns false +//! [4] + + +//! [5] +QBitArray().isNull(); // returns true +QBitArray(0).isNull(); // returns false +QBitArray(3).isNull(); // returns false +//! [5] + + +//! [6] +QBitArray ba(8); +ba.fill(true); +// ba: [ 1, 1, 1, 1, 1, 1, 1, 1 ] + +ba.fill(false, 2); +// ba: [ 0, 0 ] +//! [6] + + +//! [7] +QBitArray a(3); +a[0] = false; +a[1] = true; +a[2] = a[0] ^ a[1]; +//! [7] + + +//! [8] +QBitArray a(3); +QBitArray b(2); +a[0] = 1; a[1] = 0; a[2] = 1; // a: [ 1, 0, 1 ] +b[0] = 1; b[1] = 0; // b: [ 1, 1 ] +a &= b; // a: [ 1, 0, 0 ] +//! [8] + + +//! [9] +QBitArray a(3); +QBitArray b(2); +a[0] = 1; a[1] = 0; a[2] = 1; // a: [ 1, 0, 1 ] +b[0] = 1; b[1] = 0; // b: [ 1, 1 ] +a |= b; // a: [ 1, 1, 1 ] +//! [9] + + +//! [10] +QBitArray a(3); +QBitArray b(2); +a[0] = 1; a[1] = 0; a[2] = 1; // a: [ 1, 0, 1 ] +b[0] = 1; b[1] = 0; // b: [ 1, 1 ] +a ^= b; // a: [ 0, 1, 1 ] +//! [10] + + +//! [11] +QBitArray a(3); +QBitArray b; +a[0] = 1; a[1] = 0; a[2] = 1; // a: [ 1, 0, 1 ] +b = ~a; // b: [ 0, 1, 0 ] +//! [11] + + +//! [12] +QBitArray a(3); +QBitArray b(2); +QBitArray c; +a[0] = 1; a[1] = 0; a[2] = 1; // a: [ 1, 0, 1 ] +b[0] = 1; b[1] = 0; // b: [ 1, 1 ] +c = a & b; // c: [ 1, 0, 0 ] +//! [12] + + +//! [13] +QBitArray a(3); +QBitArray b(2); +QBitArray c; +a[0] = 1; a[1] = 0; a[2] = 1; // a: [ 1, 0, 1 ] +b[0] = 1; b[1] = 0; // b: [ 1, 1 ] +c = a | b; // c: [ 1, 1, 1 ] +//! [13] + + +//! [14] +QBitArray a(3); +QBitArray b(2); +QBitArray c; +a[0] = 1; a[1] = 0; a[2] = 1; // a: [ 1, 0, 1 ] +b[0] = 1; b[1] = 0; // b: [ 1, 1 ] +c = a ^ b; // c: [ 0, 1, 1 ] +//! [14] diff --git a/doc/src/snippets/code/src_corelib_tools_qbytearray.cpp b/doc/src/snippets/code/src_corelib_tools_qbytearray.cpp new file mode 100644 index 0000000000..4f3d8dda91 --- /dev/null +++ b/doc/src/snippets/code/src_corelib_tools_qbytearray.cpp @@ -0,0 +1,421 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + + +void wrapInFunction() +{ + +//! [0] +QByteArray ba("Hello"); +//! [0] + + +//! [1] +QByteArray ba; +ba.resize(5); +ba[0] = 0x3c; +ba[1] = 0xb8; +ba[2] = 0x64; +ba[3] = 0x18; +ba[4] = 0xca; +//! [1] + + +//! [2] +for (int i = 0; i < ba.size(); ++i) { + if (ba.at(i) >= 'a' && ba.at(i) <= 'f') + cout << "Found character in range [a-f]" << endl; +} +//! [2] + + +//! [3] +QByteArray x("and"); +x.prepend("rock "); // x == "rock and" +x.append(" roll"); // x == "rock and roll" +x.replace(5, 3, "&"); // x == "rock & roll" +//! [3] + + +//! [4] +QByteArray ba("We must be <b>bold</b>, very <b>bold</b>"); +int j = 0; +while ((j = ba.indexOf("<b>", j)) != -1) { + cout << "Found <b> tag at index position " << j << endl; + ++j; +} +//! [4] + + +//! [5] +QByteArray().isNull(); // returns true +QByteArray().isEmpty(); // returns true + +QByteArray("").isNull(); // returns false +QByteArray("").isEmpty(); // returns true + +QByteArray("abc").isNull(); // returns false +QByteArray("abc").isEmpty(); // returns false +//! [5] + + +//! [6] +QByteArray ba("Hello"); +int n = ba.size(); // n == 5 +ba.data()[0]; // returns 'H' +ba.data()[4]; // returns 'o' +ba.data()[5]; // returns '\0' +//! [6] + + +//! [7] +QByteArray().isEmpty(); // returns true +QByteArray("").isEmpty(); // returns true +QByteArray("abc").isEmpty(); // returns false +//! [7] + + +//! [8] +QByteArray ba("Hello world"); +char *data = ba.data(); +while (*data) { + cout << "[" << *data << "]" << endl; + ++data; +} +//! [8] + + +//! [9] +QByteArray ba; +for (int i = 0; i < 10; ++i) + ba[i] = 'A' + i; +// ba == "ABCDEFGHIJ" +//! [9] + + +//! [10] +QByteArray ba("Stockholm"); +ba.truncate(5); // ba == "Stock" +//! [10] + + +//! [11] +QByteArray ba("STARTTLS\r\n"); +ba.chop(2); // ba == "STARTTLS" +//! [11] + + +//! [12] +QByteArray x("free"); +QByteArray y("dom"); +x += y; +// x == "freedom" +//! [12] + + +//! [13] +QByteArray().isNull(); // returns true +QByteArray("").isNull(); // returns false +QByteArray("abc").isNull(); // returns false +//! [13] + + +//! [14] +QByteArray ba("Istambul"); +ba.fill('o'); +// ba == "oooooooo" + +ba.fill('X', 2); +// ba == "XX" +//! [14] + + +//! [15] +QByteArray x("ship"); +QByteArray y("air"); +x.prepend(y); +// x == "airship" +//! [15] + + +//! [16] +QByteArray x("free"); +QByteArray y("dom"); +x.append(y); +// x == "freedom" +//! [16] + + +//! [17] +QByteArray ba("Meal"); +ba.insert(1, QByteArray("ontr")); +// ba == "Montreal" +//! [17] + + +//! [18] +QByteArray ba("Montreal"); +ba.remove(1, 4); +// ba == "Meal" +//! [18] + + +//! [19] +QByteArray x("Say yes!"); +QByteArray y("no"); +x.replace(4, 3, y); +// x == "Say no!" +//! [19] + + +//! [20] +QByteArray ba("colour behaviour flavour neighbour"); +ba.replace(QByteArray("ou"), QByteArray("o")); +// ba == "color behavior flavor neighbor" +//! [20] + + +//! [21] +QByteArray x("sticky question"); +QByteArray y("sti"); +x.indexOf(y); // returns 0 +x.indexOf(y, 1); // returns 10 +x.indexOf(y, 10); // returns 10 +x.indexOf(y, 11); // returns -1 +//! [21] + + +//! [22] +QByteArray ba("ABCBA"); +ba.indexOf("B"); // returns 1 +ba.indexOf("B", 1); // returns 1 +ba.indexOf("B", 2); // returns 3 +ba.indexOf("X"); // returns -1 +//! [22] + + +//! [23] +QByteArray x("crazy azimuths"); +QByteArray y("az"); +x.lastIndexOf(y); // returns 6 +x.lastIndexOf(y, 6); // returns 6 +x.lastIndexOf(y, 5); // returns 2 +x.lastIndexOf(y, 1); // returns -1 +//! [23] + + +//! [24] +QByteArray ba("ABCBA"); +ba.lastIndexOf("B"); // returns 3 +ba.lastIndexOf("B", 3); // returns 3 +ba.lastIndexOf("B", 2); // returns 1 +ba.lastIndexOf("X"); // returns -1 +//! [24] + + +//! [25] +QByteArray url("ftp://ftp.qt.nokia.com/"); +if (url.startsWith("ftp:")) + ... +//! [25] + + +//! [26] +QByteArray url("http://qt.nokia.com/index.html"); +if (url.endsWith(".html")) + ... +//! [26] + + +//! [27] +QByteArray x("Pineapple"); +QByteArray y = x.left(4); +// y == "Pine" +//! [27] + + +//! [28] +QByteArray x("Pineapple"); +QByteArray y = x.right(5); +// y == "apple" +//! [28] + + +//! [29] +QByteArray x("Five pineapples"); +QByteArray y = x.mid(5, 4); // y == "pine" +QByteArray z = x.mid(5); // z == "pineapples" +//! [29] + + +//! [30] +QByteArray x("Qt by NOKIA"); +QByteArray y = x.toLower(); +// y == "qt by nokia" +//! [30] + + +//! [31] +QByteArray x("Qt by NOKIA"); +QByteArray y = x.toUpper(); +// y == "QT BY NOKIA" +//! [31] + + +//! [32] +QByteArray ba(" lots\t of\nwhitespace\r\n "); +ba = ba.simplified(); +// ba == "lots of whitespace"; +//! [32] + + +//! [33] +QByteArray ba(" lots\t of\nwhitespace\r\n "); +ba = ba.trimmed(); +// ba == "lots\t of\nwhitespace"; +//! [33] + + +//! [34] +QByteArray x("apple"); +QByteArray y = x.leftJustified(8, '.'); // y == "apple..." +//! [34] + + +//! [35] +QByteArray x("apple"); +QByteArray y = x.rightJustified(8, '.'); // y == "...apple" +//! [35] + + +//! [36] +QByteArray str("FF"); +bool ok; +int hex = str.toInt(&ok, 16); // hex == 255, ok == true +int dec = str.toInt(&ok, 10); // dec == 0, ok == false +//! [36] + + +//! [37] +QByteArray str("FF"); +bool ok; +long hex = str.toLong(&ok, 16); // hex == 255, ok == true +long dec = str.toLong(&ok, 10); // dec == 0, ok == false +//! [37] + + +//! [38] +QByteArray string("1234.56"); +double a = string.toDouble(); // a == 1234.56 +//! [38] + + +//! [39] +QByteArray text("Qt is great!"); +text.toBase64(); // returns "UXQgaXMgZ3JlYXQh" +//! [39] + + +//! [40] +QByteArray ba; +int n = 63; +ba.setNum(n); // ba == "63" +ba.setNum(n, 16); // ba == "3f" +//! [40] + + +//! [41] +int n = 63; +QByteArray::number(n); // returns "63" +QByteArray::number(n, 16); // returns "3f" +QByteArray::number(n, 16).toUpper(); // returns "3F" +//! [41] + + +//! [42] +QByteArray ba = QByteArray::number(12.3456, 'E', 3); +// ba == 1.235E+01 +//! [42] + + +//! [43] + static const char mydata[] = { + 0x00, 0x00, 0x03, 0x84, 0x78, 0x9c, 0x3b, 0x76, + 0xec, 0x18, 0xc3, 0x31, 0x0a, 0xf1, 0xcc, 0x99, + ... + 0x6d, 0x5b +}; + +QByteArray data = QByteArray::fromRawData(mydata, sizeof(mydata)); +QDataStream in(&data, QIODevice::ReadOnly); +... +//! [43] + + +//! [44] +QByteArray text = QByteArray::fromBase64("UXQgaXMgZ3JlYXQh"); +text.data(); // returns "Qt is great!" +//! [44] + + +//! [45] +QByteArray text = QByteArray::fromHex("517420697320677265617421"); +text.data(); // returns "Qt is great!" +//! [45] + +//! [46] +QString tmp = "test"; +QByteArray text = tmp.toLocal8Bit(); +char *data = new char[text.size()] +strcpy(data, text.data()); +delete [] data; +//! [46] + +//! [47] +QString tmp = "test"; +QByteArray text = tmp.toLocal8Bit(); +char *data = new char[text.size() + 1] +strcpy(data, text.data()); +delete [] data; +//! [47] + +} + + diff --git a/doc/src/snippets/code/src_corelib_tools_qdatetime.cpp b/doc/src/snippets/code/src_corelib_tools_qdatetime.cpp new file mode 100644 index 0000000000..3c53394a3b --- /dev/null +++ b/doc/src/snippets/code/src_corelib_tools_qdatetime.cpp @@ -0,0 +1,146 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QDate d1(1995, 5, 17); // May 17, 1995 +QDate d2(1995, 5, 20); // May 20, 1995 +d1.daysTo(d2); // returns 3 +d2.daysTo(d1); // returns -3 +//! [0] + + +//! [1] +QDate date = QDate::fromString("1MM12car2003", "d'MM'MMcaryyyy"); +// date is 1 December 2003 +//! [1] + + +//! [2] +QDate date = QDate::fromString("130", "Md"); // invalid +//! [2] + + +//! [3] +QDate::fromString("1.30", "M.d"); // January 30 1900 +QDate::fromString("20000110", "yyyyMMdd"); // January 10, 2000 +QDate::fromString("20000110", "yyyyMd"); // January 10, 2000 +//! [3] + + +//! [4] +QDate::isValid(2002, 5, 17); // true +QDate::isValid(2002, 2, 30); // false (Feb 30 does not exist) +QDate::isValid(2004, 2, 29); // true (2004 is a leap year) +QDate::isValid(2000, 2, 29); // true (2000 is a leap year) +QDate::isValid(2006, 2, 29); // false (2006 is not a leap year) +QDate::isValid(2100, 2, 29); // false (2100 is not a leap year) +QDate::isValid(1202, 6, 6); // true (even though 1202 is pre-Gregorian) +//! [4] + + +//! [5] +QTime n(14, 0, 0); // n == 14:00:00 +QTime t; +t = n.addSecs(70); // t == 14:01:10 +t = n.addSecs(-70); // t == 13:58:50 +t = n.addSecs(10 * 60 * 60 + 5); // t == 00:00:05 +t = n.addSecs(-15 * 60 * 60); // t == 23:00:00 +//! [5] + + +//! [6] +QTime time = QTime::fromString("1mm12car00", "m'mm'hcarss"); +// time is 12:01.00 +//! [6] + + +//! [7] +QTime time = QTime::fromString("00:710", "hh:ms"); // invalid +//! [7] + + +//! [8] +QTime time = QTime::fromString("1.30", "m.s"); +// time is 00:01:30.000 +//! [8] + + +//! [9] +QTime::isValid(21, 10, 30); // returns true +QTime::isValid(22, 5, 62); // returns false +//! [9] + + +//! [10] +QTime t; +t.start(); +some_lengthy_task(); +qDebug("Time elapsed: %d ms", t.elapsed()); +//! [10] + + +//! [11] +QDateTime now = QDateTime::currentDateTime(); +QDateTime xmas(QDate(now.date().year(), 12, 25), QTime(0, 0)); +qDebug("There are %d seconds to Christmas", now.secsTo(xmas)); +//! [11] + + +//! [12] +QTime time1 = QTime::fromString("131", "HHh"); +// time1 is 13:00:00 +QTime time1 = QTime::fromString("1apA", "1amAM"); +// time1 is 01:00:00 + +QDateTime dateTime2 = QDateTime::fromString("M1d1y9800:01:02", + "'M'M'd'd'y'yyhh:mm:ss"); +// dateTime is 1 January 1998 00:01:02 +//! [12] + + +//! [13] +QDateTime dateTime = QDateTime::fromString("130", "Mm"); // invalid +//! [13] + + +//! [14] +QDateTime dateTime = QDateTime::fromString("1.30.1", "M.d.s"); +// dateTime is January 30 in 1900 at 00:00:01. +//! [14] diff --git a/doc/src/snippets/code/src_corelib_tools_qeasingcurve.cpp b/doc/src/snippets/code/src_corelib_tools_qeasingcurve.cpp new file mode 100644 index 0000000000..59ae1b551c --- /dev/null +++ b/doc/src/snippets/code/src_corelib_tools_qeasingcurve.cpp @@ -0,0 +1,44 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +qreal myEasingFunction(qreal progress); +//! [0] + diff --git a/doc/src/snippets/code/src_corelib_tools_qhash.cpp b/doc/src/snippets/code/src_corelib_tools_qhash.cpp new file mode 100644 index 0000000000..a6bedb957e --- /dev/null +++ b/doc/src/snippets/code/src_corelib_tools_qhash.cpp @@ -0,0 +1,299 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QHash<QString, int> hash; +//! [0] + + +//! [1] +hash["one"] = 1; +hash["three"] = 3; +hash["seven"] = 7; +//! [1] + + +//! [2] +hash.insert("twelve", 12); +//! [2] + + +//! [3] +int num1 = hash["thirteen"]; +int num2 = hash.value("thirteen"); +//! [3] + + +//! [4] +int timeout = 30; +if (hash.contains("TIMEOUT")) + timeout = hash.value("TIMEOUT"); +//! [4] + + +//! [5] +int timeout = hash.value("TIMEOUT", 30); +//! [5] + + +//! [6] +// WRONG +QHash<int, QWidget *> hash; +... +for (int i = 0; i < 1000; ++i) { + if (hash[i] == okButton) + cout << "Found button at index " << i << endl; +} +//! [6] + + +//! [7] +QHashIterator<QString, int> i(hash); +while (i.hasNext()) { + i.next(); + cout << i.key() << ": " << i.value() << endl; +} +//! [7] + + +//! [8] +QHash<QString, int>::const_iterator i = hash.constBegin(); +while (i != hash.constEnd()) { + cout << i.key() << ": " << i.value() << endl; + ++i; +} +//! [8] + + +//! [9] +hash.insert("plenty", 100); +hash.insert("plenty", 2000); +// hash.value("plenty") == 2000 +//! [9] + + +//! [10] +QList<int> values = hash.values("plenty"); +for (int i = 0; i < values.size(); ++i) + cout << values.at(i) << endl; +//! [10] + + +//! [11] +QHash<QString, int>::iterator i = hash.find("plenty"); +while (i != hash.end() && i.key() == "plenty") { + cout << i.value() << endl; + ++i; +} +//! [11] + + +//! [12] +QHash<QString, int> hash; +... +foreach (int value, hash) + cout << value << endl; +//! [12] + + +//! [13] +#ifndef EMPLOYEE_H +#define EMPLOYEE_H + +class Employee +{ +public: + Employee() {} + Employee(const QString &name, const QDate &dateOfBirth); + ... + +private: + QString myName; + QDate myDateOfBirth; +}; + +inline bool operator==(const Employee &e1, const Employee &e2) +{ + return e1.name() == e2.name() + && e1.dateOfBirth() == e2.dateOfBirth(); +} + +inline uint qHash(const Employee &key) +{ + return qHash(key.name()) ^ key.dateOfBirth().day(); +} + +#endif // EMPLOYEE_H +//! [13] + + +//! [14] +QHash<QString, int> hash; +hash.reserve(20000); +for (int i = 0; i < 20000; ++i) + hash.insert(keys[i], values[i]); +//! [14] + + +//! [15] +QHash<QObject *, int> objectHash; +... +QHash<QObject *, int>::iterator i = objectHash.find(obj); +while (i != objectHash.end() && i.key() == obj) { + if (i.value() == 0) { + i = objectHash.erase(i); + } else { + ++i; + } +} +//! [15] + + +//! [16] +QHash<QString, int> hash; +... +QHash<QString, int>::const_iterator i = hash.find("HDR"); +while (i != hash.end() && i.key() == "HDR") { + cout << i.value() << endl; + ++i; +} +//! [16] + + +//! [17] +QHash<QString, int> hash; +hash.insert("January", 1); +hash.insert("February", 2); +... +hash.insert("December", 12); + +QHash<QString, int>::iterator i; +for (i = hash.begin(); i != hash.end(); ++i) + cout << i.key() << ": " << i.value() << endl; +//! [17] + + +//! [18] +QHash<QString, int>::iterator i; +for (i = hash.begin(); i != hash.end(); ++i) + i.value() += 2; +//! [18] + + +//! [19] +QHash<QString, int>::iterator i = hash.begin(); +while (i != hash.end()) { + if (i.key().startsWith("_")) + i = hash.erase(i); + else + ++i; +} +//! [19] + + +//! [20] +QHash<QString, int>::iterator i = hash.begin(); +while (i != hash.end()) { + QHash<QString, int>::iterator prev = i; + ++i; + if (prev.key().startsWith("_")) + hash.erase(prev); +} +//! [20] + + +//! [21] +// WRONG +while (i != hash.end()) { + if (i.key().startsWith("_")) + hash.erase(i); + ++i; +} +//! [21] + + +//! [22] +if (i.key() == "Hello") + i.value() = "Bonjour"; +//! [22] + + +//! [23] +QHash<QString, int> hash; +hash.insert("January", 1); +hash.insert("February", 2); +... +hash.insert("December", 12); + +QHash<QString, int>::const_iterator i; +for (i = hash.constBegin(); i != hash.constEnd(); ++i) + cout << i.key() << ": " << i.value() << endl; +//! [23] + + +//! [24] +QMultiHash<QString, int> hash1, hash2, hash3; + +hash1.insert("plenty", 100); +hash1.insert("plenty", 2000); +// hash1.size() == 2 + +hash2.insert("plenty", 5000); +// hash2.size() == 1 + +hash3 = hash1 + hash2; +// hash3.size() == 3 +//! [24] + + +//! [25] +QList<int> values = hash.values("plenty"); +for (int i = 0; i < values.size(); ++i) + cout << values.at(i) << endl; +//! [25] + + +//! [26] +QMultiHash<QString, int>::iterator i = hash.find("plenty"); +while (i != hash.end() && i.key() == "plenty") { + cout << i.value() << endl; + ++i; +} +//! [26] diff --git a/doc/src/snippets/code/src_corelib_tools_qlinkedlist.cpp b/doc/src/snippets/code/src_corelib_tools_qlinkedlist.cpp new file mode 100644 index 0000000000..2bfafc81b4 --- /dev/null +++ b/doc/src/snippets/code/src_corelib_tools_qlinkedlist.cpp @@ -0,0 +1,204 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QLinkedList<int> integerList; +QLinkedList<QTime> timeList; +//! [0] + + +//! [1] +QLinkedList<QString> list; +list << "one" << "two" << "three"; +// list: ["one", "two", "three"] +//! [1] + + +//! [2] +QLinkedList<QWidget *> list; +... +while (!list.isEmpty()) + delete list.takeFirst(); +//! [2] + + +//! [3] +QLinkedList<QString> list; +list.append("one"); +list.append("two"); +list.append("three"); +// list: ["one", "two", "three"] +//! [3] + + +//! [4] +QLinkedList<QString> list; +list.prepend("one"); +list.prepend("two"); +list.prepend("three"); +// list: ["three", "two", "one"] +//! [4] + + +//! [5] +QList<QString> list; +list << "sun" << "cloud" << "sun" << "rain"; +list.removeAll("sun"); +// list: ["cloud", "rain"] +//! [5] + + +//! [6] +QList<QString> list; +list << "sun" << "cloud" << "sun" << "rain"; +list.removeOne("sun"); +// list: ["cloud", "sun", "rain"] +//! [6] + + +//! [7] +QLinkedList<QString> list; +list.append("January"); +list.append("February"); +... +list.append("December"); + +QLinkedList<QString>::iterator i; +for (i = list.begin(); i != list.end(); ++i) + cout << *i << endl; +//! [7] + + +//! [8] +QLinkedList<QString> list; +... +QLinkedList<QString>::iterator it = qFind(list.begin(), + list.end(), "Joel"); +if (it != list.end()) + cout << "Found Joel" << endl; +//! [8] + + +//! [9] +QLinkedList<int>::iterator i; +for (i = list.begin(); i != list.end(); ++i) + *i += 2; +//! [9] + + +//! [10] +QLinkedList<QString> list; +... +QLinkedList<QString>::iterator i = list.begin(); +while (i != list.end()) { + if ((*i).startsWith("_")) + i = list.erase(i); + else + ++i; +} +//! [10] + + +//! [11] +QLinkedList<QString>::iterator i = list.begin(); +while (i != list.end()) { + QLinkedList<QString>::iterator previous = i; + ++i; + if ((*previous).startsWith("_")) + list.erase(previous); +} +//! [11] + + +//! [12] +// WRONG +while (i != list.end()) { + if ((*i).startsWith("_")) + list.erase(i); + ++i; +} +//! [12] + + +//! [13] +if (*it == "Hello") + *it = "Bonjour"; +//! [13] + + +//! [14] +QLinkedList<QString> list; +list.append("January"); +list.append("February"); +... +list.append("December"); + +QLinkedList<QString>::const_iterator i; +for (i = list.constBegin(); i != list.constEnd(); ++i) + cout << *i << endl; +//! [14] + + +//! [15] +QLinkedList<QString> list; +... +QLinkedList<QString>::iterator it = qFind(list.constBegin(), + list.constEnd(), "Joel"); +if (it != list.constEnd()) + cout << "Found Joel" << endl; +//! [15] + + +//! [16] +std::list<double> stdlist; +list.push_back(1.2); +list.push_back(0.5); +list.push_back(3.14); + +QLinkedList<double> list = QLinkedList<double>::fromStdList(stdlist); +//! [16] + + +//! [17] +QLinkedList<double> list; +list << 1.2 << 0.5 << 3.14; + +std::list<double> stdlist = list.toStdList(); +//! [17] diff --git a/doc/src/snippets/code/src_corelib_tools_qlistdata.cpp b/doc/src/snippets/code/src_corelib_tools_qlistdata.cpp new file mode 100644 index 0000000000..f580ba1940 --- /dev/null +++ b/doc/src/snippets/code/src_corelib_tools_qlistdata.cpp @@ -0,0 +1,267 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QList<int> integerList; +QList<QDate> dateList; +//! [0] + + +//! [1] +QList<QString> list; +list << "one" << "two" << "three"; +// list: ["one", "two", "three"] +//! [1] + + +//! [2] +if (list[0] == "Bob") + list[0] = "Robert"; +//! [2] + + +//! [3] +for (int i = 0; i < list.size(); ++i) { + if (list.at(i) == "Jane") + cout << "Found Jane at position " << i << endl; +} +//! [3] + + +//! [4] +QList<QWidget *> list; +... +while (!list.isEmpty()) + delete list.takeFirst(); +//! [4] + + +//! [5] +int i = list.indexOf("Jane"); +if (i != -1) + cout << "First occurrence of Jane is at position " << i << endl; +//! [5] + + +//! [6] +QList<QString> list; +list.append("one"); +list.append("two"); +list.append("three"); +// list: ["one", "two", "three"] +//! [6] + + +//! [7] +QList<QString> list; +list.prepend("one"); +list.prepend("two"); +list.prepend("three"); +// list: ["three", "two", "one"] +//! [7] + + +//! [8] +QList<QString> list; +list << "alpha" << "beta" << "delta"; +list.insert(2, "gamma"); +// list: ["alpha", "beta", "gamma", "delta"] +//! [8] + + +//! [9] +QList<QString> list; +list << "sun" << "cloud" << "sun" << "rain"; +list.removeAll("sun"); +// list: ["cloud", "rain"] +//! [9] + + +//! [10] +QList<QString> list; +list << "sun" << "cloud" << "sun" << "rain"; +list.removeOne("sun"); +// list: ["cloud", ,"sun", "rain"] +//! [10] + + +//! [11] +QList<QString> list; +list << "A" << "B" << "C" << "D" << "E" << "F"; +list.move(1, 4); +// list: ["A", "C", "D", "E", "B", "F"] +//! [11] + + +//! [12] +QList<QString> list; +list << "A" << "B" << "C" << "D" << "E" << "F"; +list.swap(1, 4); +// list: ["A", "E", "C", "D", "B", "F"] +//! [12] + + +//! [13] +QList<QString> list; +list << "A" << "B" << "C" << "B" << "A"; +list.indexOf("B"); // returns 1 +list.indexOf("B", 1); // returns 1 +list.indexOf("B", 2); // returns 3 +list.indexOf("X"); // returns -1 +//! [13] + + +//! [14] +QList<QString> list; +list << "A" << "B" << "C" << "B" << "A"; +list.lastIndexOf("B"); // returns 3 +list.lastIndexOf("B", 3); // returns 3 +list.lastIndexOf("B", 2); // returns 1 +list.lastIndexOf("X"); // returns -1 +//! [14] + + +//! [15] +QList<QString> list; +list.append("January"); +list.append("February"); +... +list.append("December"); + +QList<QString>::iterator i; +for (i = list.begin(); i != list.end(); ++i) + cout << *i << endl; +//! [15] + + +//! [16] +QList<int>::iterator i; +for (i = list.begin(); i != list.end(); ++i) + *i += 2; +//! [16] + + +//! [17] +QList<QWidget *> list; +... +qDeleteAll(list.begin(), list.end()); +//! [17] + + +//! [18] +if (*it == "Hello") + *it = "Bonjour"; +//! [18] + + +//! [19] +QList<QString> list; +list.append("January"); +list.append("February"); +... +list.append("December"); + +QList<QString>::const_iterator i; +for (i = list.constBegin(); i != list.constEnd(); ++i) + cout << *i << endl; +//! [19] + + +//! [20] +QList<QWidget *> list; +... +qDeleteAll(list.constBegin(), list.constEnd()); +//! [20] + + +//! [21] +QVector<double> vect; +vect << 20.0 << 30.0 << 40.0 << 50.0; + +QList<double> list = QVector<T>::fromVector(vect); +// list: [20.0, 30.0, 40.0, 50.0] +//! [21] + + +//! [22] +QStringList list; +list << "Sven" << "Kim" << "Ola"; + +QVector<QString> vect = list.toVector(); +// vect: ["Sven", "Kim", "Ola"] +//! [22] + + +//! [23] +QSet<int> set; +set << 20 << 30 << 40 << ... << 70; + +QList<int> list = QList<int>::fromSet(set); +qSort(list); +//! [23] + + +//! [24] +QStringList list; +list << "Julia" << "Mike" << "Mike" << "Julia" << "Julia"; + +QSet<QString> set = list.toSet(); +set.contains("Julia"); // returns true +set.contains("Mike"); // returns true +set.size(); // returns 2 +//! [24] + + +//! [25] +std::list<double> stdlist; +list.push_back(1.2); +list.push_back(0.5); +list.push_back(3.14); + +QList<double> list = QList<double>::fromStdList(stdlist); +//! [25] + + +//! [26] +QList<double> list; +list << 1.2 << 0.5 << 3.14; + +std::list<double> stdlist = list.toStdList(); +//! [26] diff --git a/doc/src/snippets/code/src_corelib_tools_qlocale.cpp b/doc/src/snippets/code/src_corelib_tools_qlocale.cpp new file mode 100644 index 0000000000..674b6f6313 --- /dev/null +++ b/doc/src/snippets/code/src_corelib_tools_qlocale.cpp @@ -0,0 +1,95 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QLocale egyptian(QLocale::Arabic, QLocale::Egypt); +QString s1 = egyptian.toString(1.571429E+07, 'e'); +QString s2 = egyptian.toString(10); + +double d = egyptian.toDouble(s1); +int i = egyptian.toInt(s2); +//! [0] + + +//! [1] +QLocale::setDefault(QLocale(QLocale::Hebrew, QLocale::Israel)); +QLocale hebrew; // Constructs a default QLocale +QString s1 = hebrew.toString(15714.3, 'e'); + +bool ok; +double d; + +QLocale::setDefault(QLocale::C); +d = QString("1234,56").toDouble(&ok); // ok == false +d = QString("1234.56").toDouble(&ok); // ok == true, d == 1234.56 + +QLocale::setDefault(QLocale::German); +d = QString("1234,56").toDouble(&ok); // ok == true, d == 1234.56 +d = QString("1234.56").toDouble(&ok); // ok == true, d == 1234.56 + +QLocale::setDefault(QLocale(QLocale::English, QLocale::UnitedStates)); +str = QString("%1 %L2 %L3") + .arg(12345).arg(12345).arg(12345, 0, 16); +// str == "12345 12,345 3039" +//! [1] + + +//! [2] +QLocale korean("ko"); +QLocale swiss("de_CH"); +//! [2] + + +//! [3] +bool ok; +double d; + +QLocale c(QLocale::C); +d = c.toDouble( "1234.56", &ok ); // ok == true, d == 1234.56 +d = c.toDouble( "1,234.56", &ok ); // ok == true, d == 1234.56 +d = c.toDouble( "1234,56", &ok ); // ok == false + +QLocale german(QLocale::German); +d = german.toDouble( "1234,56", &ok ); // ok == true, d == 1234.56 +d = german.toDouble( "1.234,56", &ok ); // ok == true, d == 1234.56 +d = german.toDouble( "1234.56", &ok ); // ok == false + +d = german.toDouble( "1.234", &ok ); // ok == true, d == 1234.0 +//! [3] diff --git a/doc/src/snippets/code/src_corelib_tools_qmap.cpp b/doc/src/snippets/code/src_corelib_tools_qmap.cpp new file mode 100644 index 0000000000..13715435f1 --- /dev/null +++ b/doc/src/snippets/code/src_corelib_tools_qmap.cpp @@ -0,0 +1,313 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QMap<QString, int> map; +//! [0] + + +//! [1] +map["one"] = 1; +map["three"] = 3; +map["seven"] = 7; +//! [1] + + +//! [2] +map.insert("twelve", 12); +//! [2] + + +//! [3] +int num1 = map["thirteen"]; +int num2 = map.value("thirteen"); +//! [3] + + +//! [4] +int timeout = 30; +if (map.contains("TIMEOUT")) + timeout = map.value("TIMEOUT"); +//! [4] + + +//! [5] +int timeout = map.value("TIMEOUT", 30); +//! [5] + + +//! [6] +// WRONG +QMap<int, QWidget *> map; +... +for (int i = 0; i < 1000; ++i) { + if (map[i] == okButton) + cout << "Found button at index " << i << endl; +} +//! [6] + + +//! [7] +QMapIterator<QString, int> i(map); +while (i.hasNext()) { + i.next(); + cout << i.key() << ": " << i.value() << endl; +} +//! [7] + + +//! [8] +QMap<QString, int>::const_iterator i = map.constBegin(); +while (i != map.constEnd()) { + cout << i.key() << ": " << i.value() << endl; + ++i; +} +//! [8] + + +//! [9] +map.insert("plenty", 100); +map.insert("plenty", 2000); +// map.value("plenty") == 2000 +//! [9] + + +//! [10] +QList<int> values = map.values("plenty"); +for (int i = 0; i < values.size(); ++i) + cout << values.at(i) << endl; +//! [10] + + +//! [11] +QMap<QString, int>::iterator i = map.find("plenty"); +while (i != map.end() && i.key() == "plenty") { + cout << i.value() << endl; + ++i; +} +//! [11] + + +//! [12] +QMap<QString, int> map; +... +foreach (int value, map) + cout << value << endl; +//! [12] + + +//! [13] +#ifndef EMPLOYEE_H +#define EMPLOYEE_H + +class Employee +{ +public: + Employee() {} + Employee(const QString &name, const QDate &dateOfBirth); + ... + +private: + QString myName; + QDate myDateOfBirth; +}; + +inline bool operator<(const Employee &e1, const Employee &e2) +{ + if (e1.name() != e2.name()) + return e1.name() < e2.name(); + return e1.dateOfBirth() < e2.dateOfBirth(); +} + +#endif // EMPLOYEE_H +//! [13] + + +//! [14] +QMap<QString, int> map; +... +QMap<QString, int>::const_iterator i = map.find("HDR"); +while (i != map.end() && i.key() == "HDR") { + cout << i.value() << endl; + ++i; +} +//! [14] + + +//! [15] +QMap<int, QString> map; +map.insert(1, "one"); +map.insert(5, "five"); +map.insert(10, "ten"); + +map.lowerBound(0); // returns iterator to (1, "one") +map.lowerBound(1); // returns iterator to (1, "one") +map.lowerBound(2); // returns iterator to (5, "five") +map.lowerBound(10); // returns iterator to (10, "ten") +map.lowerBound(999); // returns end() +//! [15] + + +//! [16] +QMap<QString, int> map; +... +QMap<QString, int>::const_iterator i = map.lowerBound("HDR"); +QMap<QString, int>::const_iterator upperBound = map.upperBound("HDR"); +while (i != upperBound) { + cout << i.value() << endl; + ++i; +} +//! [16] + + +//! [17] +QMap<int, QString> map; +map.insert(1, "one"); +map.insert(5, "five"); +map.insert(10, "ten"); + +map.upperBound(0); // returns iterator to (1, "one") +map.upperBound(1); // returns iterator to (5, "five") +map.upperBound(2); // returns iterator to (5, "five") +map.upperBound(10); // returns end() +map.upperBound(999); // returns end() +//! [17] + + +//! [18] +QMap<QString, int> map; +map.insert("January", 1); +map.insert("February", 2); +... +map.insert("December", 12); + +QMap<QString, int>::iterator i; +for (i = map.begin(); i != map.end(); ++i) + cout << i.key() << ": " << i.value() << endl; +//! [18] + + +//! [19] +QMap<QString, int>::iterator i; +for (i = map.begin(); i != map.end(); ++i) + i.value() += 2; +//! [19] + + +//! [20] +QMap<QString, int>::iterator i = map.begin(); +while (i != map.end()) { + if (i.key().startsWith("_")) + i = map.erase(i); + else + ++i; +} +//! [20] + + +//! [21] +QMap<QString, int>::iterator i = map.begin(); +while (i != map.end()) { + QMap<QString, int>::iterator prev = i; + ++i; + if (prev.key().startsWith("_")) + map.erase(prev); +} +//! [21] + + +//! [22] +// WRONG +while (i != map.end()) { + if (i.key().startsWith("_")) + map.erase(i); + ++i; +} +//! [22] + + +//! [23] +if (i.key() == "Hello") + i.value() = "Bonjour"; +//! [23] + + +//! [24] +QMap<QString, int> map; +map.insert("January", 1); +map.insert("February", 2); +... +map.insert("December", 12); + +QMap<QString, int>::const_iterator i; +for (i = map.constBegin(); i != map.constEnd(); ++i) + cout << i.key() << ": " << i.value() << endl; +//! [24] + + +//! [25] +QMultiMap<QString, int> map1, map2, map3; + +map1.insert("plenty", 100); +map1.insert("plenty", 2000); +// map1.size() == 2 + +map2.insert("plenty", 5000); +// map2.size() == 1 + +map3 = map1 + map2; +// map3.size() == 3 +//! [25] + + +//! [26] +QList<int> values = map.values("plenty"); +for (int i = 0; i < values.size(); ++i) + cout << values.at(i) << endl; +//! [26] + + +//! [27] +QMultiMap<QString, int>::iterator i = map.find("plenty"); +while (i != map.end() && i.key() == "plenty") { + cout << i.value() << endl; + ++i; +} +//! [27] diff --git a/doc/src/snippets/code/src_corelib_tools_qpoint.cpp b/doc/src/snippets/code/src_corelib_tools_qpoint.cpp new file mode 100644 index 0000000000..f5c6ec996c --- /dev/null +++ b/doc/src/snippets/code/src_corelib_tools_qpoint.cpp @@ -0,0 +1,149 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QPoint p; + +p.setX(p.x() + 1); +p += QPoint(1, 0); +p.rx()++; +//! [0] + + +//! [1] +QPoint p(1, 2); +p.rx()--; // p becomes (0, 2) +//! [1] + + +//! [2] +QPoint p(1, 2); +p.ry()++; // p becomes (1, 3) +//! [2] + + +//! [3] +QPoint p( 3, 7); +QPoint q(-1, 4); +p += q; // p becomes (2, 11) +//! [3] + + +//! [4] +QPoint p( 3, 7); +QPoint q(-1, 4); +p -= q; // p becomes (4, 3) +//! [4] + + +//! [5] +QPoint p(-1, 4); +p *= 2.5; // p becomes (-3, 10) +//! [5] + + +//! [6] +QPoint p(-3, 10); +p /= 2.5; // p becomes (-1, 4) +//! [6] + + +//! [7] +QPoint oldPosition; + +MyWidget::mouseMoveEvent(QMouseEvent *event) +{ + QPoint point = event->pos() - oldPosition; + if (point.manhattanLength() > 3) + // the mouse has moved more than 3 pixels since the oldPosition +} +//! [7] + + +//! [8] +double trueLength = sqrt(pow(x(), 2) + pow(y(), 2)); +//! [8] + + +//! [9] +QPointF p; + +p.setX(p.x() + 1.0); +p += QPointF(1.0, 0.0); +p.rx()++; +//! [9] + + +//! [10] + QPointF p(1.1, 2.5); + p.rx()--; // p becomes (0.1, 2.5) +//! [10] + + +//! [11] +QPointF p(1.1, 2.5); +p.ry()++; // p becomes (1.1, 3.5) +//! [11] + + +//! [12] +QPointF p( 3.1, 7.1); +QPointF q(-1.0, 4.1); +p += q; // p becomes (2.1, 11.2) +//! [12] + + +//! [13] +QPointF p( 3.1, 7.1); +QPointF q(-1.0, 4.1); +p -= q; // p becomes (4.1, 3.0) +//! [13] + + +//! [14] +QPointF p(-1.1, 4.1); +p *= 2.5; // p becomes (-2.75, 10.25) +//! [14] + + +//! [15] +QPointF p(-2.75, 10.25); +p /= 2.5; // p becomes (-1.1, 4.1) +//! [15] diff --git a/doc/src/snippets/code/src_corelib_tools_qqueue.cpp b/doc/src/snippets/code/src_corelib_tools_qqueue.cpp new file mode 100644 index 0000000000..6b5509aa1a --- /dev/null +++ b/doc/src/snippets/code/src_corelib_tools_qqueue.cpp @@ -0,0 +1,48 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QQueue<int> queue; +queue.enqueue(1); +queue.enqueue(2); +queue.enqueue(3); +while (!queue.isEmpty()) + cout << queue.dequeue() << endl; +//! [0] diff --git a/doc/src/snippets/code/src_corelib_tools_qrect.cpp b/doc/src/snippets/code/src_corelib_tools_qrect.cpp new file mode 100644 index 0000000000..3a3d0deec0 --- /dev/null +++ b/doc/src/snippets/code/src_corelib_tools_qrect.cpp @@ -0,0 +1,50 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QRect r1(100, 200, 11, 16); +QRect r2(QPoint(100, 200), QSize(11, 16)); +//! [0] + + +//! [1] +QRectF r1(100, 200, 11, 16); +QRectF r2(QPoint(100, 200), QSize(11, 16)); +//! [1] diff --git a/doc/src/snippets/code/src_corelib_tools_qregexp.cpp b/doc/src/snippets/code/src_corelib_tools_qregexp.cpp new file mode 100644 index 0000000000..ccb6382723 --- /dev/null +++ b/doc/src/snippets/code/src_corelib_tools_qregexp.cpp @@ -0,0 +1,224 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QRegExp rx("(\\d+)"); +QString str = "Offsets: 12 14 99 231 7"; +QStringList list; +int pos = 0; + +while ((pos = rx.indexIn(str, pos)) != -1) { + list << rx.cap(1); + pos += rx.matchedLength(); +} +// list: ["12", "14", "99", "231", "7"] +//! [0] + + +//! [1] +QRegExp rx("*.txt"); +rx.setPatternSyntax(QRegExp::Wildcard); +rx.exactMatch("README.txt"); // returns true +rx.exactMatch("welcome.txt.bak"); // returns false +//! [1] + + +//! [2] +QRegExp rx("ro+m"); +rx.setMinimal(true); +//! [2] + + +//! [3] +QRegExp mark("\\b" // word boundary + "[Mm]ark" // the word we want to match + ); +//! [3] + + +//! [4] +QRegExp rx("^\\d\\d?$"); // match integers 0 to 99 +rx.indexIn("123"); // returns -1 (no match) +rx.indexIn("-6"); // returns -1 (no match) +rx.indexIn("6"); // returns 0 (matched as position 0) +//! [4] + + +//! [5] +QRegExp rx("^\\S+$"); // match strings without whitespace +rx.indexIn("Hello world"); // returns -1 (no match) +rx.indexIn("This_is-OK"); // returns 0 (matched at position 0) +//! [5] + + +//! [6] +QRegExp rx("\\b(mail|letter|correspondence)\\b"); +rx.indexIn("I sent you an email"); // returns -1 (no match) +rx.indexIn("Please write the letter"); // returns 17 +//! [6] + + +//! [7] +QString captured = rx.cap(1); // captured == "letter" +//! [7] + + +//! [8] +QRegExp rx("&(?!amp;)"); // match ampersands but not & +QString line1 = "This & that"; +line1.replace(rx, "&"); +// line1 == "This & that" +QString line2 = "His & hers & theirs"; +line2.replace(rx, "&"); +// line2 == "His & hers & theirs" +//! [8] + + +//! [9] +QString str = "One Eric another Eirik, and an Ericsson. " + "How many Eiriks, Eric?"; +QRegExp rx("\\b(Eric|Eirik)\\b"); // match Eric or Eirik +int pos = 0; // where we are in the string +int count = 0; // how many Eric and Eirik's we've counted +while (pos >= 0) { + pos = rx.indexIn(str, pos); + if (pos >= 0) { + ++pos; // move along in str + ++count; // count our Eric or Eirik + } +} +//! [9] + + +//! [10] +str = "Nokia Corporation\tqt.nokia.com\tNorway"; +QString company, web, country; +rx.setPattern("^([^\t]+)\t([^\t]+)\t([^\t]+)$"); +if (rx.indexIn(str) != -1) { + company = rx.cap(1); + web = rx.cap(2); + country = rx.cap(3); +} +//! [10] + + +//! [11] +QStringList field = str.split("\t"); +//! [11] + + +//! [12] +QRegExp rx("*.html"); +rx.setPatternSyntax(QRegExp::Wildcard); +rx.exactMatch("index.html"); // returns true +rx.exactMatch("default.htm"); // returns false +rx.exactMatch("readme.txt"); // returns false +//! [12] + + +//! [13] +QString str = "offsets: 1.23 .50 71.00 6.00"; +QRegExp rx("\\d*\\.\\d+"); // primitive floating point matching +int count = 0; +int pos = 0; +while ((pos = rx.indexIn(str, pos)) != -1) { + ++count; + pos += rx.matchedLength(); +} +// pos will be 9, 14, 18 and finally 24; count will end up as 4 +//! [13] + + +//! [14] +QRegExp rx("(\\d+)(\\s*)(cm|inch(es)?)"); +int pos = rx.indexIn("Length: 36 inches"); +QStringList list = rx.capturedTexts(); +// list is now ("36 inches", "36", " ", "inches", "es") +//! [14] + + +//! [15] +QRegExp rx("(\\d+)(?:\\s*)(cm|inch(?:es)?)"); +int pos = rx.indexIn("Length: 36 inches"); +QStringList list = rx.capturedTexts(); +// list is now ("36 inches", "36", "inches") +//! [15] + + +//! [16] +QStringList list = rx.capturedTexts(); +QStringList::iterator it = list.begin(); +while (it != list.end()) { + myProcessing(*it); + ++it; +} +//! [16] + + +//! [17] +QRegExp rxlen("(\\d+)(?:\\s*)(cm|inch)"); +int pos = rxlen.indexIn("Length: 189cm"); +if (pos > -1) { + QString value = rxlen.cap(1); // "189" + QString unit = rxlen.cap(2); // "cm" + // ... +} +//! [17] + + +//! [18] +QRegExp rx("/([a-z]+)/([a-z]+)"); +rx.indexIn("Output /dev/null"); // returns 7 (position of /dev/null) +rx.pos(0); // returns 7 (position of /dev/null) +rx.pos(1); // returns 8 (position of dev) +rx.pos(2); // returns 12 (position of null) +//! [18] + + +//! [19] +s1 = QRegExp::escape("bingo"); // s1 == "bingo" +s2 = QRegExp::escape("f(x)"); // s2 == "f\\(x\\)" +//! [19] + + +//! [20] +QRegExp rx("(" + QRegExp::escape(name) + + "|" + QRegExp::escape(alias) + ")"); +//! [20] diff --git a/doc/src/snippets/code/src_corelib_tools_qscopedpointer.cpp b/doc/src/snippets/code/src_corelib_tools_qscopedpointer.cpp new file mode 100644 index 0000000000..be28d56eb2 --- /dev/null +++ b/doc/src/snippets/code/src_corelib_tools_qscopedpointer.cpp @@ -0,0 +1,138 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +void myFunction(bool useSubClass) +{ + MyClass *p = useSubClass ? new MyClass() : new MySubClass; + QIODevice *device = handsOverOwnership(); + + if (m_value > 3) { + delete p; + delete device; + return; + } + + try { + process(device); + } + catch (...) { + delete p; + delete device; + throw; + } + + delete p; + delete device; +} +//! [0] + +//! [1] +void myFunction(bool useSubClass) +{ + // assuming that MyClass has a virtual destructor + QScopedPointer<MyClass> p(useSubClass ? new MyClass() : new MySubClass); + QScopedPointer<QIODevice> device(handsOverOwnership()); + + if (m_value > 3) + return; + + process(device); +} +//! [1] + +//! [2] + const QWidget *const p = new QWidget(); + // is equivalent to: + const QScopedPointer<const QWidget> p(new QWidget()); + + QWidget *const p = new QWidget(); + // is equivalent to: + const QScopedPointer<QWidget> p(new QWidget()); + + const QWidget *p = new QWidget(); + // is equivalent to: + QScopedPointer<const QWidget> p(new QWidget()); +//! [2] + +//! [3] +if (scopedPointer) { + ... +} +//! [3] + +//! [4] +class MyPrivateClass; // forward declare MyPrivateClass + +class MyClass +{ +private: + QScopedPointer<MyPrivateClass> privatePtr; // QScopedPointer to forward declared class + +public: + MyClass(); // OK + inline ~MyClass() {} // VIOLATION - Destructor must not be inline + +private: + Q_DISABLE_COPY(MyClass) // OK - copy constructor and assignment operators + // are now disabled, so the compiler won't implicitely + // generate them. +}; +//! [4] + +//! [5] +// this QScopedPointer deletes its data using the delete[] operator: +QScopedPointer<int, QScopedPointerArrayDeleter<int> > arrayPointer(new int[42]); + +// this QScopedPointer frees its data using free(): +QScopedPointer<int, QScopedPointerPodDeleter> podPointer(reinterpret_cast<int *>(malloc(42))); + +// this struct calls "myCustomDeallocator" to delete the pointer +struct ScopedPointerCustomDeleter +{ + static inline void cleanup(MyCustomClass *pointer) + { + myCustomDeallocator(pointer); + } +}; + +// QScopedPointer using a custom deleter: +QScopedPointer<MyCustomClass, ScopedPointerCustomDeleter> customPointer(new MyCustomClass); +//! [5] diff --git a/doc/src/snippets/code/src_corelib_tools_qsize.cpp b/doc/src/snippets/code/src_corelib_tools_qsize.cpp new file mode 100644 index 0000000000..701627eb20 --- /dev/null +++ b/doc/src/snippets/code/src_corelib_tools_qsize.cpp @@ -0,0 +1,136 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QSize t1(10, 12); +t1.scale(60, 60, Qt::IgnoreAspectRatio); +// t1 is (60, 60) + +QSize t2(10, 12); +t2.scale(60, 60, Qt::KeepAspectRatio); +// t2 is (50, 60) + +QSize t3(10, 12); +t3.scale(60, 60, Qt::KeepAspectRatioByExpanding); +// t3 is (60, 72) +//! [0] + + +//! [1] +QSize size(100, 10); +size.rwidth() += 20; + +// size becomes (120,10) +//! [1] + + +//! [2] +QSize size(100, 10); +size.rheight() += 5; + +// size becomes (100,15) +//! [2] + + +//! [3] +QSize s( 3, 7); +QSize r(-1, 4); +s += r; + +// s becomes (2,11) +//! [3] + + +//! [4] +QSize s( 3, 7); +QSize r(-1, 4); +s -= r; + +// s becomes (4,3) +//! [4] + + +//! [5] +QSizeF t1(10, 12); +t1.scale(60, 60, Qt::IgnoreAspectRatio); +// t1 is (60, 60) + +QSizeF t2(10, 12); +t2.scale(60, 60, Qt::KeepAspectRatio); +// t2 is (50, 60) + +QSizeF t3(10, 12); +t3.scale(60, 60, Qt::KeepAspectRatioByExpanding); +// t3 is (60, 72) +//! [5] + + +//! [6] +QSizeF size(100.3, 10); +size.rwidth() += 20.5; + + // size becomes (120.8,10) +//! [6] + + +//! [7] +QSizeF size(100, 10.2); +size.rheight() += 5.5; + +// size becomes (100,15.7) +//! [7] + + +//! [8] +QSizeF s( 3, 7); +QSizeF r(-1, 4); +s += r; + +// s becomes (2,11) +//! [8] + + +//! [9] +QSizeF s( 3, 7); +QSizeF r(-1, 4); +s -= r; + +// s becomes (4,3) +//! [9] diff --git a/doc/src/snippets/code/src_corelib_tools_qstring.cpp b/doc/src/snippets/code/src_corelib_tools_qstring.cpp new file mode 100644 index 0000000000..0cd1801beb --- /dev/null +++ b/doc/src/snippets/code/src_corelib_tools_qstring.cpp @@ -0,0 +1,87 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +DEFINES += QT_NO_CAST_FROM_ASCII \ + QT_NO_CAST_TO_ASCII +//! [0] + + +//! [1] +QString url = QLatin1String("http://www.unicode.org/"); +//! [1] + + +//! [2] +double d = 12.34; +QString str = QString("delta: %1").arg(d, 0, 'E', 3); +// str == "delta: 1.234E+01" +//! [2] + + +//! [3] +if (str == "auto" || str == "extern" + || str == "static" || str == "register") { + ... +} +//! [3] + + +//! [4] +if (str == QString("auto") || str == QString("extern") + || str == QString("static") || str == QString("register")) { + ... +} +//! [4] + + +//! [5] +if (str == QLatin1String("auto") + || str == QLatin1String("extern") + || str == QLatin1String("static") + || str == QLatin1String("register") { + ... +} +//! [5] + + +//! [6] +QLabel *label = new QLabel(QLatin1String("MOD"), this); +//! [6] diff --git a/doc/src/snippets/code/src_corelib_tools_qtimeline.cpp b/doc/src/snippets/code/src_corelib_tools_qtimeline.cpp new file mode 100644 index 0000000000..3374995bb2 --- /dev/null +++ b/doc/src/snippets/code/src_corelib_tools_qtimeline.cpp @@ -0,0 +1,55 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +... +progressBar = new QProgressBar(this); +progressBar->setRange(0, 100); + +// Construct a 1-second timeline with a frame range of 0 - 100 +QTimeLine *timeLine = new QTimeLine(1000, this); +timeLine->setFrameRange(0, 100); +connect(timeLine, SIGNAL(frameChanged(int)), progressBar, SLOT(setValue(int))); + +// Clicking the push button will start the progress bar animation +pushButton = new QPushButton(tr("Start animation"), this); +connect(pushButton, SIGNAL(clicked()), timeLine, SLOT(start())); +... +//! [0] diff --git a/doc/src/snippets/code/src_corelib_tools_qvector.cpp b/doc/src/snippets/code/src_corelib_tools_qvector.cpp new file mode 100644 index 0000000000..fc46d913d3 --- /dev/null +++ b/doc/src/snippets/code/src_corelib_tools_qvector.cpp @@ -0,0 +1,183 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QVector<int> integerVector; +QVector<QString> stringVector; +//! [0] + + +//! [1] +QVector<QString> vector(200); +//! [1] + + +//! [2] +QVector<QString> vector(200, "Pass"); +//! [2] + + +//! [3] +if (vector[0] == "Liz") + vector[0] = "Elizabeth"; +//! [3] + + +//! [4] +for (int i = 0; i < vector.size(); ++i) { + if (vector.at(i) == "Alfonso") + cout << "Found Alfonso at position " << i << endl; +} +//! [4] + + +//! [5] +int i = vector.indexOf("Harumi"); +if (i != -1) + cout << "First occurrence of Harumi is at position " << i << endl; +//! [5] + + +//! [6] +QVector<int> vector(10); +int *data = vector.data(); +for (int i = 0; i < 10; ++i) + data[i] = 2 * i; +//! [6] + + +//! [7] +QVector<QString> vector(0); +vector.append("one"); +vector.append("two"); +vector.append("three"); +// vector: ["one", "two", "three"] +//! [7] + + +//! [8] +QVector<QString> vector; +vector.prepend("one"); +vector.prepend("two"); +vector.prepend("three"); +// vector: ["three", "two", "one"] +//! [8] + + +//! [9] +QVector<QString> vector; +vector << "alpha" << "beta" << "delta"; +vector.insert(2, "gamma"); +// vector: ["alpha", "beta", "gamma", "delta"] +//! [9] + + +//! [10] +QVector<double> vector; +vector << 2.718 << 1.442 << 0.4342; +vector.insert(1, 3, 9.9); +// vector: [2.718, 9.9, 9.9, 9.9, 1.442, 0.4342] +//! [10] + + +//! [11] +QVector<QString> vector(3); +vector.fill("Yes"); +// vector: ["Yes", "Yes", "Yes"] + +vector.fill("oh", 5); +// vector: ["oh", "oh", "oh", "oh", "oh"] +//! [11] + + +//! [12] +QVector<QString> vector; +vector << "A" << "B" << "C" << "B" << "A"; +vector.indexOf("B"); // returns 1 +vector.indexOf("B", 1); // returns 1 +vector.indexOf("B", 2); // returns 3 +vector.indexOf("X"); // returns -1 +//! [12] + + +//! [13] +QList<QString> vector; +vector << "A" << "B" << "C" << "B" << "A"; +vector.lastIndexOf("B"); // returns 3 +vector.lastIndexOf("B", 3); // returns 3 +vector.lastIndexOf("B", 2); // returns 1 +vector.lastIndexOf("X"); // returns -1 +//! [13] + + +//! [14] +QVector<double> vect; +vect << "red" << "green" << "blue" << "black"; + +QList<double> list = vect.toList(); +// list: ["red", "green", "blue", "black"] +//! [14] + + +//! [15] +QStringList list; +list << "Sven" << "Kim" << "Ola"; + +QVector<QString> vect = QVector<QString>::fromList(list); +// vect: ["Sven", "Kim", "Ola"] +//! [15] + + +//! [16] +std::vector<double> stdvector; +vector.push_back(1.2); +vector.push_back(0.5); +vector.push_back(3.14); + +QVector<double> vector = QVector<double>::fromStdVector(stdvector); +//! [16] + + +//! [17] +QVector<double> vector; +vector << 1.2 << 0.5 << 3.14; + +std::vector<double> stdvector = vector.toStdVector(); +//! [17] diff --git a/doc/src/snippets/code/src_corelib_xml_qxmlstream.cpp b/doc/src/snippets/code/src_corelib_xml_qxmlstream.cpp new file mode 100644 index 0000000000..fe08cea4c9 --- /dev/null +++ b/doc/src/snippets/code/src_corelib_xml_qxmlstream.cpp @@ -0,0 +1,67 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] + QXmlStreamReader xml; + ... + while (!xml.atEnd()) { + xml.readNext(); + ... // do processing + } + if (xml.hasError()) { + ... // do error handling + } +//! [0] + + +//! [1] + writeStartElement(qualifiedName); + writeCharacters(text); + writeEndElement(); +//! [1] + + +//! [2] + writeStartElement(namespaceUri, name); + writeCharacters(text); + writeEndElement(); +//! [2] + + diff --git a/doc/src/snippets/code/src_gui_accessible_qaccessible.cpp b/doc/src/snippets/code/src_gui_accessible_qaccessible.cpp new file mode 100644 index 0000000000..84eb1cd1ac --- /dev/null +++ b/doc/src/snippets/code/src_gui_accessible_qaccessible.cpp @@ -0,0 +1,52 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QAccessibleInterface *child = 0; +int targetChild = object->navigate(Accessible::Child, 1, &child); +if (child) { + // ... + delete child; +} +//! [0] + +//! [1] +typedef QAccessibleInterface* myFactoryFunction(const QString &key, QObject *); +//! [1] diff --git a/doc/src/snippets/code/src_gui_dialogs_qabstractprintdialog.cpp b/doc/src/snippets/code/src_gui_dialogs_qabstractprintdialog.cpp new file mode 100644 index 0000000000..bc5d296e07 --- /dev/null +++ b/doc/src/snippets/code/src_gui_dialogs_qabstractprintdialog.cpp @@ -0,0 +1,46 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QPrintDialog printDialog(printer, parent); +if (printDialog.exec() == QDialog::Accepted) { + // print ... +} +//! [0] diff --git a/doc/src/snippets/code/src_gui_dialogs_qfiledialog.cpp b/doc/src/snippets/code/src_gui_dialogs_qfiledialog.cpp new file mode 100644 index 0000000000..ef14632437 --- /dev/null +++ b/doc/src/snippets/code/src_gui_dialogs_qfiledialog.cpp @@ -0,0 +1,131 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +fileName = QFileDialog::getOpenFileName(this, + tr("Open Image"), "/home/jana", tr("Image Files (*.png *.jpg *.bmp)")); +//! [0] + + +//! [1] +"Images (*.png *.xpm *.jpg);;Text files (*.txt);;XML files (*.xml)" +//! [1] + + +//! [2] +QFileDialog dialog(this); +dialog.setFileMode(QFileDialog::AnyFile); +//! [2] + + +//! [3] +dialog.setNameFilter(tr("Images (*.png *.xpm *.jpg)")); +//! [3] + + +//! [4] +dialog.setViewMode(QFileDialog::Detail); +//! [4] + + +//! [5] +QStringList fileNames; +if (dialog.exec()) + fileNames = dialog.selectedFiles(); +//! [5] + + +//! [6] +dialog.setNameFilter("All C++ files (*.cpp *.cc *.C *.cxx *.c++)"); +dialog.setNameFilter("*.cpp *.cc *.C *.cxx *.c++"); +//! [6] + + +//! [7] +QStringList filters; +filters << "Image files (*.png *.xpm *.jpg)" + << "Text files (*.txt)" + << "Any files (*)"; + +QFileDialog dialog(this); +dialog.setNameFilters(filters); +dialog.exec(); +//! [7] + + +//! [8] +QString fileName = QFileDialog::getOpenFileName(this, tr("Open File"), + "/home", + tr("Images (*.png *.xpm *.jpg)")); +//! [8] + + +//! [9] +QStringList files = QFileDialog::getOpenFileNames( + this, + "Select one or more files to open", + "/home", + "Images (*.png *.xpm *.jpg)"); +//! [9] + + +//! [10] +QStringList list = files; +QStringList::Iterator it = list.begin(); +while(it != list.end()) { + myProcessing(*it); + ++it; +} +//! [10] + + +//! [11] +QString fileName = QFileDialog::getSaveFileName(this, tr("Save File"), + "/home/jana/untitled.png", + tr("Images (*.png *.xpm *.jpg)")); +//! [11] + + +//! [12] +QString dir = QFileDialog::getExistingDirectory(this, tr("Open Directory"), + "/home", + QFileDialog::ShowDirsOnly + | QFileDialog::DontResolveSymlinks); +//! [12] diff --git a/doc/src/snippets/code/src_gui_dialogs_qfontdialog.cpp b/doc/src/snippets/code/src_gui_dialogs_qfontdialog.cpp new file mode 100644 index 0000000000..ef906d7e7e --- /dev/null +++ b/doc/src/snippets/code/src_gui_dialogs_qfontdialog.cpp @@ -0,0 +1,85 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +bool ok; +QFont font = QFontDialog::getFont( + &ok, QFont("Helvetica [Cronyx]", 10), this); +if (ok) { + // the user clicked OK and font is set to the font the user selected +} else { + // the user canceled the dialog; font is set to the initial + // value, in this case Helvetica [Cronyx], 10 +} +//! [0] + + +//! [1] +myWidget.setFont(QFontDialog::getFont(0, myWidget.font())); +//! [1] + + +//! [2] +bool ok; +QFont font = QFontDialog::getFont(&ok, QFont("Times", 12), this); +if (ok) { + // font is set to the font the user selected +} else { + // the user canceled the dialog; font is set to the initial + // value, in this case Times, 12. +} +//! [2] + + +//! [3] +myWidget.setFont(QFontDialog::getFont(0, myWidget.font())); +//! [3] + + +//! [4] +bool ok; +QFont font = QFontDialog::getFont(&ok, this); +if (ok) { + // font is set to the font the user selected +} else { + // the user canceled the dialog; font is set to the default + // application font, QApplication::font() +} +//! [4] diff --git a/doc/src/snippets/code/src_gui_dialogs_qmessagebox.cpp b/doc/src/snippets/code/src_gui_dialogs_qmessagebox.cpp new file mode 100644 index 0000000000..7db6e264ae --- /dev/null +++ b/doc/src/snippets/code/src_gui_dialogs_qmessagebox.cpp @@ -0,0 +1,148 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +int ret = QMessageBox::warning(this, tr("My Application"), + tr("The document has been modified.\n" + "Do you want to save your changes?"), + QMessageBox::Save | QMessageBox::Discard + | QMessageBox::Cancel, + QMessageBox::Save); +//! [0] + + +//! [1] +QMessageBox msgBox; +msgBox.setStandardButtons(QMessageBox::Yes | QMessageBox::No); +switch (msgBox.exec()) { +case QMessageBox::Yes: + // yes was clicked + break; +case QMessageBox::No: + // no was clicked + break; +default: + // should never be reached + break; +} +//! [1] + + +//! [2] +QMessageBox msgBox; +QPushButton *connectButton = msgBox.addButton(tr("Connect"), QMessageBox::ActionRole); +QPushButton *abortButton = msgBox.addButton(QMessageBox::Abort); + +msgBox.exec(); + +if (msgBox.clickedButton() == connectButton) { + // connect +} else if (msgBox.clickedButton() == abortButton) { + // abort +} +//! [2] + + +//! [3] +QMessageBox messageBox(this); +QAbstractButton *disconnectButton = + messageBox.addButton(tr("Disconnect"), QMessageBox::ActionRole); +... +messageBox.exec(); +if (messageBox.clickedButton() == disconnectButton) { + ... +} +//! [3] + + +//! [4] +#include <QApplication> +#include <QMessageBox> + +int main(int argc, char *argv[]) +{ + QT_REQUIRE_VERSION(argc, argv, "4.0.2") + + QApplication app(argc, argv); + ... + return app.exec(); +} +//! [4] + +//! [5] +QMessageBox msgBox; +msgBox.setText("The document has been modified."); +msgBox.exec(); +//! [5] + +//! [6] +QMessageBox msgBox; +msgBox.setText("The document has been modified."); +msgBox.setInformativeText("Do you want to save your changes?"); +msgBox.setStandardButtons(QMessageBox::Save | QMessageBox::Discard | QMessageBox::Cancel); +msgBox.setDefaultButton(QMessageBox::Save); +int ret = msgBox.exec(); +//! [6] + +//! [7] +switch (ret) { + case QMessageBox::Save: + // Save was clicked + break; + case QMessageBox::Discard: + // Don't Save was clicked + break; + case QMessageBox::Cancel: + // Cancel was clicked + break; + default: + // should never be reached + break; +} +//! [7] + +//! [9] +QMessageBox msgBox(this); +msgBox.setText(tr("The document has been modified.\n" + "Do you want to save your changes?")); +msgBox.setStandardButtons(QMessageBox::Save | QMessageBox::Discard + | QMessageBox::Cancel); +msgBox.setDefaultButton(QMessageBox::Save); +//! [9] diff --git a/doc/src/snippets/code/src_gui_dialogs_qwizard.cpp b/doc/src/snippets/code/src_gui_dialogs_qwizard.cpp new file mode 100644 index 0000000000..0a8c033a26 --- /dev/null +++ b/doc/src/snippets/code/src_gui_dialogs_qwizard.cpp @@ -0,0 +1,80 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +int LicenseWizard::nextId() const +{ + switch (currentId()) { + case Page_Intro: + if (field("intro.evaluate").toBool()) { + return Page_Evaluate; + } else { + return Page_Register; + } + case Page_Evaluate: + return Page_Conclusion; + case Page_Register: + if (field("register.upgradeKey").toString().isEmpty()) { + return Page_Details; + } else { + return Page_Conclusion; + } + case Page_Details: + return Page_Conclusion; + case Page_Conclusion: + default: + return -1; + } +} +//! [0] + + +//! [1] +MyWizard::MyWizard(QWidget *parent) + : QWizard(parent) +{ + ... + QList<QWizard::WizardButton> layout; + layout << QWizard::Stretch << QWizard::BackButton << QWizard::CancelButton + << QWizard::NextButton << QWizard::FinishButton; + setButtonLayout(layout); + ... +} +//! [1] diff --git a/doc/src/snippets/code/src_gui_effects_qgraphicseffect.cpp b/doc/src/snippets/code/src_gui_effects_qgraphicseffect.cpp new file mode 100644 index 0000000000..1fa1717fd6 --- /dev/null +++ b/doc/src/snippets/code/src_gui_effects_qgraphicseffect.cpp @@ -0,0 +1,83 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +MyGraphicsOpacityEffect::draw(QPainter *painter) +{ + // Fully opaque; draw directly without going through a pixmap. + if (qFuzzyCompare(m_opacity, 1)) { + drawSource(painter); + return; + } + ... +} +//! [0] + +//! [1] +MyGraphicsEffect::draw(QPainter *painter) +{ + ... + QPoint offset; + if (sourceIsPixmap()) { + // No point in drawing in device coordinates (pixmap will be scaled anyways). + const QPixmap pixmap = sourcePixmap(Qt::LogicalCoordinates, &offset); + ... + painter->drawPixmap(offset, pixmap); + } else { + // Draw pixmap in device coordinates to avoid pixmap scaling; + const QPixmap pixmap = sourcePixmap(Qt::DeviceCoordinates, &offset); + painter->setWorldTransform(QTransform()); + ... + painter->drawPixmap(offset, pixmap); + } + ... +} +//! [1] + +//! [2] +... +QLinearGradient alphaGradient(rect.topLeft(), rect.bottomLeft()); +alphaGradient.setColorAt(0.0, Qt::transparent); +alphaGradient.setColorAt(0.5, Qt::black); +alphaGradient.setColorAt(1.0, Qt::transparent); +QGraphicsOpacityEffect *effect = new QGraphicsOpacityEffect; +effect->setOpacityMask(alphaGradient); +... +//! [2] diff --git a/doc/src/snippets/code/src_gui_embedded_qcopchannel_qws.cpp b/doc/src/snippets/code/src_gui_embedded_qcopchannel_qws.cpp new file mode 100644 index 0000000000..38d17e8033 --- /dev/null +++ b/doc/src/snippets/code/src_gui_embedded_qcopchannel_qws.cpp @@ -0,0 +1,66 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +void MyClass::receive(const QString &message, const QByteArray &data) +{ + QDataStream in(data); + if (message == "execute(QString,QString)") { + QString cmd; + QString arg; + in >> cmd >> arg; + ... + } else if (message == "delete(QString)") { + QString fileName; + in >> fileName; + ... + } else { + ... + } +} +//! [0] + + +//! [1] +QByteArray data; +QDataStream out(&data, QIODevice::WriteOnly); +out << QString("cat") << QString("file.txt"); +QCopChannel::send("System/Shell", "execute(QString,QString)", data); +//! [1] diff --git a/doc/src/snippets/code/src_gui_embedded_qmouse_qws.cpp b/doc/src/snippets/code/src_gui_embedded_qmouse_qws.cpp new file mode 100644 index 0000000000..31db87037a --- /dev/null +++ b/doc/src/snippets/code/src_gui_embedded_qmouse_qws.cpp @@ -0,0 +1,44 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +s*Xs = a*Xd + b*Yd + c +s*Ys = d*Xd + e*Yd + f +//! [0] diff --git a/doc/src/snippets/code/src_gui_embedded_qmousetslib_qws.cpp b/doc/src/snippets/code/src_gui_embedded_qmousetslib_qws.cpp new file mode 100644 index 0000000000..dc5a77300f --- /dev/null +++ b/doc/src/snippets/code/src_gui_embedded_qmousetslib_qws.cpp @@ -0,0 +1,49 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +configure -L <path to tslib library> -I <path to tslib headers> +//! [0] + + +//! [1] +module_raw input +module linear +//! [1] diff --git a/doc/src/snippets/code/src_gui_embedded_qscreen_qws.cpp b/doc/src/snippets/code/src_gui_embedded_qscreen_qws.cpp new file mode 100644 index 0000000000..cb902e5ed4 --- /dev/null +++ b/doc/src/snippets/code/src_gui_embedded_qscreen_qws.cpp @@ -0,0 +1,48 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +[screen driver][:driver specific options][:display number] +//! [0] + + +//! [1] +Mach64:/dev/fb1:2 +//! [1] diff --git a/doc/src/snippets/code/src_gui_embedded_qtransportauth_qws.cpp b/doc/src/snippets/code/src_gui_embedded_qtransportauth_qws.cpp new file mode 100644 index 0000000000..0d5294be08 --- /dev/null +++ b/doc/src/snippets/code/src_gui_embedded_qtransportauth_qws.cpp @@ -0,0 +1,87 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + + +void wrapInFunction() +{ + +//! [0] +QTransportAuth::Data *conData; +QTransportAuth *a = QTransportAuth::getInstance(); + +conData = a->connectTransport( + QTransportAuth::Trusted | QTransportAuth::UnixStreamSock, + socketDescriptor ); +//! [0] + + +//! [1] +// mySocket can be any QIODevice subclass +AuthDevice *ad = a->recvBuf( d, mySocket ); + +// proxy in the auth device where the socket would have gone +connect( ad, SIGNAL(readyRead()), this, SLOT(mySocketReadyRead())); +//! [1] + + +//! [2] +AuthDevice *ad = a->authBuf( d, mySocket ); + +ad->write( someData ); +//! [2] + + +//! [3] +policyCheck( QTransportAuth::Data &, const QString & ) +//! [3] + + +//! [4] +QTransportAuth::Result r = d.status & QTransportAuth::ErrMask; +qWarning( "error: %s", QTransportAuth::errorStrings[r] ); +//! [4] + + +//! [5] +MD5(K XOR opad, MD5(K XOR ipad, text)) +//! [5] + +} + diff --git a/doc/src/snippets/code/src_gui_embedded_qwindowsystem_qws.cpp b/doc/src/snippets/code/src_gui_embedded_qwindowsystem_qws.cpp new file mode 100644 index 0000000000..defa56a9e2 --- /dev/null +++ b/doc/src/snippets/code/src_gui_embedded_qwindowsystem_qws.cpp @@ -0,0 +1,85 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +bool MyScreenSaver::save( int level ) +{ + switch ( level ) { + case 0: + if ( dim_enabled ) { + // dim the screen + } + return true; + case 1: + if ( screenoff_enabled ) { + // turn off the screen + } + return true; + case 2: + if ( suspend_enabled ) { + // suspend + } + return true; + default: + return false; + } +} + +... + +int timings[4]; +timings[0] = 5000; // dim after 5 seconds +timings[1] = 10000; // light off after 15 seconds +timings[2] = 45000; // suspend after 60 seconds +timings[3] = 0; +QWSServer::setScreenSaverIntervals( timings ); + +// ignore the key/mouse event that turns on the screen +int blocklevel = 1; +if ( !screenoff_enabled ) { + // screenoff is disabled, ignore the key/mouse event that wakes from suspend + blocklevel = 2; + if ( !suspend_enabled ) { + // suspend is disabled, never ignore events + blocklevel = -1; + } +} +QWSServer::setScreenSaverBlockLevel( blocklevel ); +//! [0] diff --git a/doc/src/snippets/code/src_gui_graphicsview_qgraphicsgridlayout.cpp b/doc/src/snippets/code/src_gui_graphicsview_qgraphicsgridlayout.cpp new file mode 100644 index 0000000000..fb4178bda0 --- /dev/null +++ b/doc/src/snippets/code/src_gui_graphicsview_qgraphicsgridlayout.cpp @@ -0,0 +1,53 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QGraphicsScene scene; +QGraphicsWidget *textEdit = scene.addWidget(new QTextEdit); +QGraphicsWidget *pushButton = scene.addWidget(new QPushButton); + +QGraphicsGridLayout *layout = new QGraphicsGridLayout; +layout->addItem(textEdit, 0, 0); +layout->addItem(pushButton, 0, 1); + +QGraphicsWidget *form = new QGraphicsWidget; +form->setLayout(layout); +scene.addItem(form); +//! [0] diff --git a/doc/src/snippets/code/src_gui_graphicsview_qgraphicsitem.cpp b/doc/src/snippets/code/src_gui_graphicsview_qgraphicsitem.cpp new file mode 100644 index 0000000000..c4cf674995 --- /dev/null +++ b/doc/src/snippets/code/src_gui_graphicsview_qgraphicsitem.cpp @@ -0,0 +1,278 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +class SimpleItem : public QGraphicsItem +{ +public: + QRectF boundingRect() const + { + qreal penWidth = 1; + return QRectF(-10 - penWidth / 2, -10 - penWidth / 2, + 20 + penWidth, 20 + penWidth); + } + + void paint(QPainter *painter, const QStyleOptionGraphicsItem *option, + QWidget *widget) + { + painter->drawRoundedRect(-10, -10, 20, 20, 5, 5); + } +}; +//! [0] + + +//! [1] +class CustomItem : public QGraphicsItem +{ + ... + enum { Type = UserType + 1 }; + + int type() const + { + // Enable the use of qgraphicsitem_cast with this item. + return Type; + } + ... +}; +//! [1] + + +//! [2] +item->setCursor(Qt::IBeamCursor); +//! [2] + + +//! [3] +item->setCursor(Qt::IBeamCursor); +//! [3] + + +//! [4] +QGraphicsRectItem rect; +rect.setPos(100, 100); + +rect.sceneTransform().map(QPointF(0, 0)); +// returns QPointF(100, 100); + +rect.sceneTransform().inverted().map(QPointF(100, 100)); +// returns QPointF(0, 0); +//! [4] + + +//! [5] +QGraphicsRectItem rect; +rect.setPos(100, 100); + +rect.deviceTransform(view->viewportTransform()).map(QPointF(0, 0)); +// returns the item's (0, 0) point in view's viewport coordinates + +rect.deviceTransform(view->viewportTransform()).inverted().map(QPointF(100, 100)); +// returns view's viewport's (100, 100) coordinate in item coordinates +//! [5] + + +//! [6] +// Rotate an item 45 degrees around (0, 0). +item->rotate(45); + +// Rotate an item 45 degrees around (x, y). +item->setTransform(QTransform().translate(x, y).rotate(45).translate(-x, -y)); +//! [6] + + +//! [7] +// Scale an item by 3x2 from its origin +item->scale(3, 2); + +// Scale an item by 3x2 from (x, y) +item->setTransform(QTransform().translate(x, y).scale(3, 2).translate(-x, -y)); +//! [7] + + +//! [8] +QRectF CircleItem::boundingRect() const +{ + qreal penWidth = 1; + return QRectF(-radius - penWidth / 2, -radius - penWidth / 2, + diameter + penWidth, diameter + penWidth); +} +//! [8] + + +//! [9] +QPainterPath RoundItem::shape() const +{ + QPainterPath path; + path.addEllipse(boundingRect()); + return path; +} +//! [9] + + +//! [10] +void RoundRectItem::paint(QPainter *painter, + const QStyleOptionGraphicsItem *option, + QWidget *widget) +{ + painter->drawRoundedRect(-10, -10, 20, 20, 5, 5); +} +//! [10] + + +//! [11] +static const int ObjectName = 0; + +QGraphicsItem *item = scene.itemAt(100, 50); +if (item->data(ObjectName).toString().isEmpty()) { + if (qgraphicsitem_cast<ButtonItem *>(item)) + item->setData(ObjectName, "Button"); +} +//! [11] + + +//! [12] +QGraphicsScene scene; +QGraphicsEllipseItem *ellipse = scene.addEllipse(QRectF(-10, -10, 20, 20)); +QGraphicsLineItem *line = scene.addLine(QLineF(-10, -10, 20, 20)); + +line->installSceneEventFilter(ellipse); +// line's events are filtered by ellipse's sceneEventFilter() function. + +ellipse->installSceneEventFilter(line); +// ellipse's events are filtered by line's sceneEventFilter() function. +//! [12] + + +//! [13] +void CustomItem::contextMenuEvent(QGraphicsSceneContextMenuEvent *event) +{ + QMenu menu; + QAction *removeAction = menu.addAction("Remove"); + QAction *markAction = menu.addAction("Mark"); + QAction *selectedAction = menu.exec(event->screenPos()); + // ... +} +//! [13] + + +//! [14] +CustomItem::CustomItem() +{ + setAcceptDrops(true); + ... +} + +void CustomItem::dragEnterEvent(QGraphicsSceneDragDropEvent *event) +{ + event->setAccepted(event->mimeData()->hasFormat("text/plain")); +} +//! [14] + + +//! [15] +QVariant Component::itemChange(GraphicsItemChange change, const QVariant &value) +{ + if (change == ItemPositionChange && scene()) { + // value is the new position. + QPointF newPos = value.toPointF(); + QRectF rect = scene()->sceneRect(); + if (!rect.contains(newPos)) { + // Keep the item inside the scene rect. + newPos.setX(qMin(rect.right(), qMax(newPos.x(), rect.left()))); + newPos.setY(qMin(rect.bottom(), qMax(newPos.y(), rect.top()))); + return newPos; + } + } + return QGraphicsItem::itemChange(change, value); +} +//! [15] + + +//! [16] +void CircleItem::setRadius(qreal newRadius) +{ + if (radius != newRadius) { + prepareGeometryChange(); + radius = newRadius; + } +} +//! [16] + + +//! [17] +// Group all selected items together +QGraphicsItemGroup *group = scene->createItemGroup(scene->selecteditems()); + +// Destroy the group, and delete the group item +scene->destroyItemGroup(group); +//! [17] + + +//! [QGraphicsItem type] +class CustomItem : public QGraphicsItem +{ + ... + enum { Type = UserType + 1 }; + + int type() const + { + // Enable the use of qgraphicsitem_cast with this item. + return Type; + } + ... +}; +//! [QGraphicsItem type] + +//! [18] +class QGraphicsPathItem : public QAbstractGraphicsShapeItem +{ + public: + enum { Type = 2 }; + int type() const { return Type; } + ... +}; +//! [18] + +//! [19] +QTransform xform = item->deviceTransform(view->viewportTransform()); +QRect deviceRect = xform.mapRect(rect).toAlignedRect(); +view->viewport()->scroll(dx, dy, deviceRect); +//! [19] + diff --git a/doc/src/snippets/code/src_gui_graphicsview_qgraphicslinearlayout.cpp b/doc/src/snippets/code/src_gui_graphicsview_qgraphicslinearlayout.cpp new file mode 100644 index 0000000000..492827a9d1 --- /dev/null +++ b/doc/src/snippets/code/src_gui_graphicsview_qgraphicslinearlayout.cpp @@ -0,0 +1,53 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QGraphicsScene scene; +QGraphicsWidget *textEdit = scene.addWidget(new QTextEdit); +QGraphicsWidget *pushButton = scene.addWidget(new QPushButton); + +QGraphicsLinearLayout *layout = new QGraphicsLinearLayout; +layout->addItem(textEdit); +layout->addItem(pushButton); + +QGraphicsWidget *form = new QGraphicsWidget; +form->setLayout(layout); +scene.addItem(form); +//! [0] diff --git a/doc/src/snippets/code/src_gui_graphicsview_qgraphicsproxywidget.cpp b/doc/src/snippets/code/src_gui_graphicsview_qgraphicsproxywidget.cpp new file mode 100644 index 0000000000..470b1505da --- /dev/null +++ b/doc/src/snippets/code/src_gui_graphicsview_qgraphicsproxywidget.cpp @@ -0,0 +1,87 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +int main(int argc, char **argv) +{ + QApplication app(argc, argv); + + QTabWidget *tabWidget = new QTabWidget; + + QGraphicsScene scene; + QGraphicsProxyWidget *proxy = scene.addWidget(tabWidget); + + QGraphicsView view(&scene); + view.show(); + + return app.exec(); +} +//! [0] + +//! [1] +QGroupBox *groupBox = new QGroupBox("Contact Details"); +QLabel *numberLabel = new QLabel("Telephone number"); +QLineEdit *numberEdit = new QLineEdit; + +QFormLayout *layout = new QFormLayout; +layout->addRow(numberLabel, numberEdit); +groupBox->setLayout(layout); + +QGraphicsScene scene; +QGraphicsProxyWidget *proxy = scene.addWidget(groupBox); + +QGraphicsView view(&scene); +view.show(); +//! [1] + +//! [2] +QGraphicsScene scene; + +QLineEdit *edit = new QLineEdit; +QGraphicsProxyWidget *proxy = scene.addWidget(edit); + +edit->isVisible(); // returns true +proxy->isVisible(); // also returns true + +edit->hide(); + +edit->isVisible(); // returns false +proxy->isVisible(); // also returns false +//! [2] diff --git a/doc/src/snippets/code/src_gui_graphicsview_qgraphicsscene.cpp b/doc/src/snippets/code/src_gui_graphicsview_qgraphicsscene.cpp new file mode 100644 index 0000000000..383a8efbb7 --- /dev/null +++ b/doc/src/snippets/code/src_gui_graphicsview_qgraphicsscene.cpp @@ -0,0 +1,122 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QGraphicsScene scene; +scene.addText("Hello, world!"); + +QGraphicsView view(&scene); +view.show(); +//! [0] + + +//! [1] +QGraphicsScene scene; +scene.addItem(... +... +QPrinter printer(QPrinter::HighResolution); +printer.setPaperSize(QPrinter::A4); + +QPainter painter(&printer); +scene.render(&painter); +//! [1] + + +//! [2] +QSizeF segmentSize = sceneRect().size() / pow(2, depth - 1); +//! [2] + + +//! [3] +QGraphicsScene scene; +QGraphicsView view(&scene); +view.show(); + +// a blue background +scene.setBackgroundBrush(Qt::blue); + +// a gradient background +QRadialGradient gradient(0, 0, 10); +gradient.setSpread(QGradient::RepeatSpread); +scene.setBackgroundBrush(gradient); +//! [3] + + +//! [4] +QGraphicsScene scene; +QGraphicsView view(&scene); +view.show(); + +// a white semi-transparent foreground +scene.setForegroundBrush(QColor(255, 255, 255, 127)); + +// a grid foreground +scene.setForegroundBrush(QBrush(Qt::lightGray, Qt::CrossPattern)); +//! [4] + + +//! [5] +QRectF TileScene::rectForTile(int x, int y) const +{ + // Return the rectangle for the tile at position (x, y). + return QRectF(x * tileWidth, y * tileHeight, tileWidth, tileHeight); +} + +void TileScene::setTile(int x, int y, const QPixmap &pixmap) +{ + // Sets or replaces the tile at position (x, y) with pixmap. + if (x >= 0 && x < numTilesH && y >= 0 && y < numTilesV) { + tiles[y][x] = pixmap; + invalidate(rectForTile(x, y), BackgroundLayer); + } +} + +void TileScene::drawBackground(QPainter *painter, const QRectF &exposed) +{ + // Draws all tiles that intersect the exposed area. + for (int y = 0; y < numTilesV; ++y) { + for (int x = 0; x < numTilesH; ++x) { + QRectF rect = rectForTile(x, y); + if (exposed.intersects(rect)) + painter->drawPixmap(rect.topLeft(), tiles[y][x]); + } + } +} +//! [5] diff --git a/doc/src/snippets/code/src_gui_graphicsview_qgraphicssceneevent.cpp b/doc/src/snippets/code/src_gui_graphicsview_qgraphicssceneevent.cpp new file mode 100644 index 0000000000..9ad042bc82 --- /dev/null +++ b/doc/src/snippets/code/src_gui_graphicsview_qgraphicssceneevent.cpp @@ -0,0 +1,45 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] + +setDropAction(proposedAction()); + +//! [0] diff --git a/doc/src/snippets/code/src_gui_graphicsview_qgraphicsview.cpp b/doc/src/snippets/code/src_gui_graphicsview_qgraphicsview.cpp new file mode 100644 index 0000000000..0fffc4be40 --- /dev/null +++ b/doc/src/snippets/code/src_gui_graphicsview_qgraphicsview.cpp @@ -0,0 +1,132 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QGraphicsScene scene; +scene.addText("Hello, world!"); + +QGraphicsView view(&scene); +view.show(); +//! [0] + + +//! [1] +QGraphicsScene scene; +scene.addRect(QRectF(-10, -10, 20, 20)); + +QGraphicsView view(&scene); +view.setRenderHints(QPainter::Antialiasing | QPainter::SmoothPixmapTransform); +view.show(); +//! [1] + + +//! [2] +QGraphicsView view; +view.setBackgroundBrush(QImage(":/images/backgroundtile.png")); +view.setCacheMode(QGraphicsView::CacheBackground); +//! [2] + + +//! [3] +QGraphicsScene scene; +scene.addText("GraphicsView rotated clockwise"); + +QGraphicsView view(&scene); +view.rotate(90); // the text is rendered with a 90 degree clockwise rotation +view.show(); +//! [3] + + +//! [4] +QGraphicsScene scene; +scene.addItem(... +... + +QGraphicsView view(&scene); +view.show(); +... + +QPrinter printer(QPrinter::HighResolution); +printer.setPageSize(QPrinter::A4); +QPainter painter(&printer); + +// print, fitting the viewport contents into a full page +view.render(&painter); + +// print the upper half of the viewport into the lower. +// half of the page. +QRect viewport = view.viewport()->rect(); +view.render(&painter, + QRectF(0, printer.height() / 2, + printer.width(), printer.height() / 2), + viewport.adjusted(0, 0, 0, -viewport.height() / 2)); + +//! [4] + + +//! [5] +void CustomView::mousePressEvent(QMouseEvent *event) +{ + qDebug() << "There are" << items(event->pos()).size() + << "items at position" << mapToScene(event->pos()); +} +//! [5] + + +//! [6] +void CustomView::mousePressEvent(QMouseEvent *event) +{ + if (QGraphicsItem *item = itemAt(event->pos())) { + qDebug() << "You clicked on item" << item; + } else { + qDebug() << "You didn't click on an item."; + } +} +//! [6] + + +//! [7] +QGraphicsScene scene; +scene.addText("GraphicsView rotated clockwise"); + +QGraphicsView view(&scene); +view.rotate(90); // the text is rendered with a 90 degree clockwise rotation +view.show(); +//! [7] diff --git a/doc/src/snippets/code/src_gui_graphicsview_qgraphicswidget.cpp b/doc/src/snippets/code/src_gui_graphicsview_qgraphicswidget.cpp new file mode 100644 index 0000000000..aed1787984 --- /dev/null +++ b/doc/src/snippets/code/src_gui_graphicsview_qgraphicswidget.cpp @@ -0,0 +1,66 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +void MyGroupBoxWidget::initStyleOption(QStyleOption *option) const +{ + QGraphicsWidget::initStyleOption(option); + if (QStyleOptionGroupBox *box = qstyleoption_cast<QStyleOptionGroupBox *>(option)) { + // Add group box specific state. + box->flat = isFlat(); + ... + } +} +//! [0] + + +//! [1] +setTabOrder(a, b); // a to b +setTabOrder(b, c); // a to b to c +setTabOrder(c, d); // a to b to c to d +//! [1] + + +//! [2] +// WRONG +setTabOrder(c, d); // c to d +setTabOrder(a, b); // a to b AND c to d +setTabOrder(b, c); // a to b to c, but not c to d +//! [2] diff --git a/doc/src/snippets/code/src_gui_image_qbitmap.cpp b/doc/src/snippets/code/src_gui_image_qbitmap.cpp new file mode 100644 index 0000000000..7b388433b5 --- /dev/null +++ b/doc/src/snippets/code/src_gui_image_qbitmap.cpp @@ -0,0 +1,44 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +uchar arrow_bits[] = { 0x3f, 0x1f, 0x0f, 0x1f, 0x3b, 0x71, 0xe0, 0xc0 }; +QBitmap bm(8, 8, arrow_bits, true); +//! [0] diff --git a/doc/src/snippets/code/src_gui_image_qicon.cpp b/doc/src/snippets/code/src_gui_image_qicon.cpp new file mode 100644 index 0000000000..cf6469eaae --- /dev/null +++ b/doc/src/snippets/code/src_gui_image_qicon.cpp @@ -0,0 +1,71 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QToolButton *button = new QToolButton; +button->setIcon(QIcon("open.xpm")); +//! [0] + + +//! [1] +button->setIcon(QIcon()); +//! [1] + + +//! [2] +void MyWidget::drawIcon(QPainter *painter, QPoint pos) +{ + QPixmap pixmap = icon.pixmap(QSize(22, 22), + isEnabled() ? QIcon::Normal + : QIcon::Disabled, + isChecked() ? QIcon::On + : QIcon::Off); + painter->drawPixmap(pos, pixmap); +} +//! [2] + +//! [3] + QIcon undoicon = QIcon::fromTheme("edit-undo"); +//! [3] + +//! [4] + QIcon undoicon = QIcon::fromTheme("edit-undo", QIcon(":/undo.png")); +//! [4] + diff --git a/doc/src/snippets/code/src_gui_image_qimage.cpp b/doc/src/snippets/code/src_gui_image_qimage.cpp new file mode 100644 index 0000000000..cbfdf14cc1 --- /dev/null +++ b/doc/src/snippets/code/src_gui_image_qimage.cpp @@ -0,0 +1,82 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QImage image(3, 3, QImage::Format_RGB32); +QRgb value; + +value = qRgb(189, 149, 39); // 0xffbd9527 +image.setPixel(1, 1, value); + +value = qRgb(122, 163, 39); // 0xff7aa327 +image.setPixel(0, 1, value); +image.setPixel(1, 0, value); + +value = qRgb(237, 187, 51); // 0xffedba31 +image.setPixel(2, 1, value); +//! [0] + + +//! [1] +QImage image(3, 3, QImage::Format_Indexed8); +QRgb value; + +value = qRgb(122, 163, 39); // 0xff7aa327 +image.setColor(0, value); + +value = qRgb(237, 187, 51); // 0xffedba31 +image.setColor(1, value); + +value = qRgb(189, 149, 39); // 0xffbd9527 +image.setColor(2, value); + +image.setPixel(0, 1, 0); +image.setPixel(1, 0, 0); +image.setPixel(1, 1, 2); +image.setPixel(2, 1, 1); +//! [1] + + +//! [2] +static const char * const start_xpm[] = { + "16 15 8 1", + "a c #cec6bd", +.... +//! [2] diff --git a/doc/src/snippets/code/src_gui_image_qimagereader.cpp b/doc/src/snippets/code/src_gui_image_qimagereader.cpp new file mode 100644 index 0000000000..f4c64c165f --- /dev/null +++ b/doc/src/snippets/code/src_gui_image_qimagereader.cpp @@ -0,0 +1,66 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QImageReader reader; +reader.setFormat("png"); // same as reader.setFormat("PNG"); +//! [0] + + +//! [1] +QImageReader reader("image.png"); +// reader.format() == "png" +//! [1] + + +//! [2] +QImage icon(64, 64, QImage::Format_RGB32); +QImageReader reader("icon_64x64.bmp"); +if (reader.read(&icon)) { + // Display icon +} +//! [2] + + +//! [3] +QImageReader reader(":/image.png"); +if (reader.supportsOption(QImageIOHandler::Size)) + qDebug() << "Size:" << reader.size(); +//! [3] diff --git a/doc/src/snippets/code/src_gui_image_qimagewriter.cpp b/doc/src/snippets/code/src_gui_image_qimagewriter.cpp new file mode 100644 index 0000000000..e44442ba7e --- /dev/null +++ b/doc/src/snippets/code/src_gui_image_qimagewriter.cpp @@ -0,0 +1,59 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QImageWriter writer; +writer.setFormat("png"); // same as writer.setFormat("PNG"); +//! [0] + + +//! [1] +QImage image("some/image.jpeg"); +QImageWriter writer("images/outimage.png", "png"); +writer.setText("Author", "John Smith"); +writer.write(image); +//! [1] + + +//! [2] +QImageWriter writer(fileName); +if (writer.supportsOption(QImageIOHandler::Description)) + writer.setText("Author", "John Smith"); +//! [2] diff --git a/doc/src/snippets/code/src_gui_image_qmovie.cpp b/doc/src/snippets/code/src_gui_image_qmovie.cpp new file mode 100644 index 0000000000..4efbac52b9 --- /dev/null +++ b/doc/src/snippets/code/src_gui_image_qmovie.cpp @@ -0,0 +1,53 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QLabel label; +QMovie *movie = new QMovie("animations/fire.gif"); + +label.setMovie(movie); +movie->start(); +//! [0] + + +//! [1] +QMovie movie("racecar.gif"); +movie.setSpeed(200); // 2x speed +//! [1] diff --git a/doc/src/snippets/code/src_gui_image_qpixmap.cpp b/doc/src/snippets/code/src_gui_image_qpixmap.cpp new file mode 100644 index 0000000000..11e021201d --- /dev/null +++ b/doc/src/snippets/code/src_gui_image_qpixmap.cpp @@ -0,0 +1,58 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +static const char * const start_xpm[]={ + "16 15 8 1", + "a c #cec6bd", +.... +//! [0] + + +//! [1] +QPixmap myPixmap; +myPixmap->setMask(myPixmap->createHeuristicMask()); +//! [1] + +//! [2] +QPixmap pixmap("background.png"); +QRegion exposed; +pixmap.scroll(10, 10, pixmap.rect(), &exposed); +//! [2] diff --git a/doc/src/snippets/code/src_gui_image_qpixmapcache.cpp b/doc/src/snippets/code/src_gui_image_qpixmapcache.cpp new file mode 100644 index 0000000000..08973b851d --- /dev/null +++ b/doc/src/snippets/code/src_gui_image_qpixmapcache.cpp @@ -0,0 +1,61 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QPixmap* pp; +QPixmap p; +if ((pp=QPixmapCache::find("my_big_image", pm))) { + p = *pp; +} else { + p.load("bigimage.png"); + QPixmapCache::insert("my_big_image", new QPixmap(p)); +} +painter->drawPixmap(0, 0, p); +//! [0] + + +//! [1] +QPixmap pm; +if (!QPixmapCache::find("my_big_image", &pm)) { + pm.load("bigimage.png"); + QPixmapCache::insert("my_big_image", pm); +} +painter->drawPixmap(0, 0, pm); +//! [1] diff --git a/doc/src/snippets/code/src_gui_image_qpixmapfilter.cpp b/doc/src/snippets/code/src_gui_image_qpixmapfilter.cpp new file mode 100644 index 0000000000..2d9c78f579 --- /dev/null +++ b/doc/src/snippets/code/src_gui_image_qpixmapfilter.cpp @@ -0,0 +1,62 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QPixmapColorizeFilter *myFilter = new QPixmapColorFilter; +myFilter->setColor(QColor(128, 0, 0)); +myFilter->draw(painter, QPoint(0, 0), originalPixmap); +//! [0] + +//! [1] +QPixmapConvolutionFilter *myFilter = new QPixmapConvolutionFilter; +qreal kernel[] = { + 0.0,-1.0, 0.0, + -1.0, 5.0,-1.0, + 0.0,-1.0, 0.0 + }; +myFilter->setConvolutionKernel(kernel, 3, 3); +myFilter->draw(painter, QPoint(0, 0), originalPixmap); +//! [1] + +//! [2] +QPixmapDropShadowFilter *myFilter = new QPixmapDropShadowFilter; +myFilter->draw(painter, QPoint(0, 0), originalPixmap); +//! [2] + diff --git a/doc/src/snippets/code/src_gui_itemviews_qabstractitemview.cpp b/doc/src/snippets/code/src_gui_itemviews_qabstractitemview.cpp new file mode 100644 index 0000000000..75ada3acd2 --- /dev/null +++ b/doc/src/snippets/code/src_gui_itemviews_qabstractitemview.cpp @@ -0,0 +1,58 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +void MyView::resizeEvent(QResizeEvent *event) { + horizontalScrollBar()->setRange(0, realWidth - width()); + ... +} +//! [0] + +//! [1] +setIndexWidget(index, new QLineEdit); +... +setIndexWidget(index, new QTextEdit); +//! [1] + +//! [2] +QItemSelectionModel *m = view->selectionModel(); +view->setModel(new model); +delete m; +//! [2] diff --git a/doc/src/snippets/code/src_gui_itemviews_qdatawidgetmapper.cpp b/doc/src/snippets/code/src_gui_itemviews_qdatawidgetmapper.cpp new file mode 100644 index 0000000000..a3b90e2c1e --- /dev/null +++ b/doc/src/snippets/code/src_gui_itemviews_qdatawidgetmapper.cpp @@ -0,0 +1,63 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QDataWidgetMapper *mapper = new QDataWidgetMapper; +mapper->setModel(model); +mapper->addMapping(mySpinBox, 0); +mapper->addMapping(myLineEdit, 1); +mapper->addMapping(myCountryChooser, 2); +mapper->toFirst(); +//! [0] + + +//! [1] +QDataWidgetMapper *mapper = new QDataWidgetMapper(); +mapper->setModel(myModel); +mapper->addMapping(nameLineEdit, 0); +mapper->addMapping(ageSpinBox, 1); +//! [1] + + +//! [2] +QDataWidgetMapper *mapper = new QDataWidgetMapper(); +connect(myTableView->selectionModel(), SIGNAL(currentRowChanged(QModelIndex,QModelIndex)), + mapper, SLOT(setCurrentModelIndex(QModelIndex))); +//! [2] diff --git a/doc/src/snippets/code/src_gui_itemviews_qitemeditorfactory.cpp b/doc/src/snippets/code/src_gui_itemviews_qitemeditorfactory.cpp new file mode 100644 index 0000000000..bef6711da0 --- /dev/null +++ b/doc/src/snippets/code/src_gui_itemviews_qitemeditorfactory.cpp @@ -0,0 +1,63 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +Q_PROPERTY(QColor color READ color WRITE setColor USER true) +//! [0] + + +//! [1] +QItemEditorCreator<MyEditor> *itemCreator = + new QItemEditorCreator<MyEditor>("myProperty"); + +QItemEditorFactory *factory = new QItemEditorFactory; +//! [1] + + +//! [2] +QItemEditorFactory *editorFactory = new QItemEditorFactory; +QItemEditorCreatorBase *creator = new QStandardItemEditorCreator<MyFancyDateTimeEdit>(); +editorFactory->registerEditor(QVariant::DateType, creator); +//! [2] + + +//! [3] +Q_PROPERTY(QColor color READ color WRITE setColor USER true) +//! [3] diff --git a/doc/src/snippets/code/src_gui_itemviews_qitemselectionmodel.cpp b/doc/src/snippets/code/src_gui_itemviews_qitemselectionmodel.cpp new file mode 100644 index 0000000000..1277506cd0 --- /dev/null +++ b/doc/src/snippets/code/src_gui_itemviews_qitemselectionmodel.cpp @@ -0,0 +1,50 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QItemSelection *selection = new QItemSelection(topLeft, bottomRight); +//! [0] + + +//! [1] +QItemSelection *selection = new QItemSelection(); +... +selection->select(topLeft, bottomRight); +//! [1] diff --git a/doc/src/snippets/code/src_gui_itemviews_qstandarditemmodel.cpp b/doc/src/snippets/code/src_gui_itemviews_qstandarditemmodel.cpp new file mode 100644 index 0000000000..6005179843 --- /dev/null +++ b/doc/src/snippets/code/src_gui_itemviews_qstandarditemmodel.cpp @@ -0,0 +1,82 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QStandardItemModel model(4, 4); +for (int row = 0; row < 4; ++row) { + for (int column = 0; column < 4; ++column) { + QStandardItem *item = new QStandardItem(QString("row %0, column %1").arg(row).arg(column)); + model.setItem(row, column, item); + } +} +//! [0] + + +//! [1] +QStandardItemModel model; +QStandardItem *parentItem = model.invisibleRootItem(); +for (int i = 0; i < 4; ++i) { + QStandardItem *item = new QStandardItem(QString("item %0").arg(i)); + parentItem->appendRow(item); + parentItem = item; +} +//! [1] + + +//! [2] +QTreeView *treeView = new QTreeView(this); +treeView->setModel(myStandardItemModel); +connect(treeView, SIGNAL(clicked(QModelIndex)), + this, SLOT(clicked(QModelIndex))); +//! [2] + + +//! [3] +void MyWidget::clicked(const QModelIndex &index) +{ + QStandardItem *item = myStandardItemModel->itemFromIndex(index); + // Do stuff with the item ... +} +//! [3] + + +//! [4] +treeView->scrollTo(item->index()); +//! [4] diff --git a/doc/src/snippets/code/src_gui_itemviews_qtablewidget.cpp b/doc/src/snippets/code/src_gui_itemviews_qtablewidget.cpp new file mode 100644 index 0000000000..4035ca8e13 --- /dev/null +++ b/doc/src/snippets/code/src_gui_itemviews_qtablewidget.cpp @@ -0,0 +1,45 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +setCellWidget(index, new QLineEdit); +... +setCellWidget(index, new QTextEdit); +//! [0] diff --git a/doc/src/snippets/code/src_gui_itemviews_qtreewidget.cpp b/doc/src/snippets/code/src_gui_itemviews_qtreewidget.cpp new file mode 100644 index 0000000000..4f5bc37d36 --- /dev/null +++ b/doc/src/snippets/code/src_gui_itemviews_qtreewidget.cpp @@ -0,0 +1,48 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QTreeWidget *treeWidget = new QTreeWidget(); +treeWidget->setColumnCount(1); +QList<QTreeWidgetItem *> items; +for (int i = 0; i < 10; ++i) + items.append(new QTreeWidgetItem((QTreeWidget*)0, QStringList(QString("item: %1").arg(i)))); +treeWidget->insertTopLevelItems(0, items); +//! [0] diff --git a/doc/src/snippets/code/src_gui_kernel_qaction.cpp b/doc/src/snippets/code/src_gui_kernel_qaction.cpp new file mode 100644 index 0000000000..bfc613b36e --- /dev/null +++ b/doc/src/snippets/code/src_gui_kernel_qaction.cpp @@ -0,0 +1,49 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QApplication app(argc, argv); +app.setAttribute(Qt::AA_DontShowIconsInMenus); // Icons are *no longer shown* in menus +// ... +QAction *myAction = new QAction(); +// ... +myAction->setIcon(SomeIcon); +myAction->setIconVisibleInMenu(true); // Icon *will* be shown in menus for *this* action. +//! [0] diff --git a/doc/src/snippets/code/src_gui_kernel_qapplication.cpp b/doc/src/snippets/code/src_gui_kernel_qapplication.cpp new file mode 100644 index 0000000000..bb0cdde200 --- /dev/null +++ b/doc/src/snippets/code/src_gui_kernel_qapplication.cpp @@ -0,0 +1,183 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +int main(int argc, char **argv) +{ +#ifdef Q_WS_X11 + bool useGUI = getenv("DISPLAY") != 0; +#else + bool useGUI = true; +#endif + QApplication app(argc, argv, useGUI); + + if (useGUI) { + // start GUI version + ... + } else { + // start non-GUI version + ... + } + return app.exec(); +} +//! [0] + + +//! [1] +QApplication::setStyle(new QWindowsStyle); +//! [1] + + +//! [2] +int main(int argc, char *argv[]) +{ + QApplication::setColorSpec(QApplication::ManyColor); + QApplication app(argc, argv); + ... + return app.exec(); +} +//! [2] + + +//! [3] +QSize MyWidget::sizeHint() const +{ + return QSize(80, 25).expandedTo(QApplication::globalStrut()); +} +//! [3] + + +//! [4] +void showAllHiddenTopLevelWidgets() +{ + foreach (QWidget *widget, QApplication::topLevelWidgets()) { + if (widget->isHidden()) + widget->show(); + } +} +//! [4] + + +//! [5] +void updateAllWidgets() +{ + foreach (QWidget *widget, QApplication::allWidgets()) + widget->update(); +} +//! [5] + + +//! [6] +int main(int argc, char *argv[]) +{ + QApplication::setDesktopSettingsAware(false); + QApplication app(argc, argv); + ... + return app.exec(); +} +//! [6] + + +//! [7] +if ((startPos - currentPos).manhattanLength() >= + QApplication::startDragDistance()) + startTheDrag(); +//! [7] + + +//! [8] +void MyApplication::commitData(QSessionManager& manager) +{ + if (manager.allowsInteraction()) { + int ret = QMessageBox::warning( + mainWindow, + tr("My Application"), + tr("Save changes to document?"), + QMessageBox::Save | QMessageBox::Discard | QMessageBox::Cancel); + + switch (ret) { + case QMessageBox::Save: + manager.release(); + if (!saveDocument()) + manager.cancel(); + break; + case QMessageBox::Discard: + break; + case QMessageBox::Cancel: + default: + manager.cancel(); + } + } else { + // we did not get permission to interact, then + // do something reasonable instead + } +} +//! [8] + + +//! [9] +appname -session id +//! [9] + + +//! [10] +foreach (const QString &command, mySession.restartCommand()) + do_something(command); +//! [10] + + +//! [11] +foreach (const QString &command, mySession.discardCommand()) + do_something(command); +//! [11] + + +//! [12] +QWidget *widget = qApp->widgetAt(x, y); +if (widget) + widget = widget->window(); +//! [12] + + +//! [13] +QWidget *widget = qApp->widgetAt(point); +if (widget) + widget = widget->window(); +//! [13] diff --git a/doc/src/snippets/code/src_gui_kernel_qapplication_x11.cpp b/doc/src/snippets/code/src_gui_kernel_qapplication_x11.cpp new file mode 100644 index 0000000000..a73f65de62 --- /dev/null +++ b/doc/src/snippets/code/src_gui_kernel_qapplication_x11.cpp @@ -0,0 +1,45 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QApplication::setOverrideCursor(QCursor(Qt::WaitCursor)); +calculateHugeMandelbrot(); // lunch time... +QApplication::restoreOverrideCursor(); +//! [0] diff --git a/doc/src/snippets/code/src_gui_kernel_qclipboard.cpp b/doc/src/snippets/code/src_gui_kernel_qclipboard.cpp new file mode 100644 index 0000000000..dd052d790b --- /dev/null +++ b/doc/src/snippets/code/src_gui_kernel_qclipboard.cpp @@ -0,0 +1,53 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QClipboard *clipboard = QApplication::clipboard(); +QString originalText = clipboard->text(); +... +clipboard->setText(newText); +//! [0] + + +//! [1] +QMimeData *data = new QMimeData; +data->setImageData(image); +clipboard->setMimeData(data, mode); +//! [1] diff --git a/doc/src/snippets/code/src_gui_kernel_qevent.cpp b/doc/src/snippets/code/src_gui_kernel_qevent.cpp new file mode 100644 index 0000000000..d0627b2b44 --- /dev/null +++ b/doc/src/snippets/code/src_gui_kernel_qevent.cpp @@ -0,0 +1,54 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +void MyWidget::wheelEvent(QWheelEvent *event) +{ + int numDegrees = event->delta() / 8; + int numSteps = numDegrees / 15; + + if (event->orientation() == Qt::Horizontal) { + scrollHorizontally(numSteps); + } else { + scrollVertically(numSteps); + } + event->accept(); +} +//! [0] diff --git a/doc/src/snippets/code/src_gui_kernel_qformlayout.cpp b/doc/src/snippets/code/src_gui_kernel_qformlayout.cpp new file mode 100644 index 0000000000..94e6b1bd90 --- /dev/null +++ b/doc/src/snippets/code/src_gui_kernel_qformlayout.cpp @@ -0,0 +1,76 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QFormLayout *formLayout = new QFormLayout; +formLayout->addRow(tr("&Name:"), nameLineEdit); +formLayout->addRow(tr("&Email:"), emailLineEdit); +formLayout->addRow(tr("&Age:"), ageSpinBox); +setLayout(formLayout); +//! [0] + + +//! [1] +nameLabel = new QLabel(tr("&Name:")); +nameLabel->setBuddy(nameLineEdit); + +emailLabel = new QLabel(tr("&Name:")); +emailLabel->setBuddy(emailLineEdit); + +ageLabel = new QLabel(tr("&Name:")); +ageLabel->setBuddy(ageSpinBox); + +QGridLayout *gridLayout = new QGridLayout; +gridLayout->addWidget(nameLabel, 0, 0); +gridLayout->addWidget(nameLineEdit, 0, 1); +gridLayout->addWidget(emailLabel, 1, 0); +gridLayout->addWidget(emailLineEdit, 1, 1); +gridLayout->addWidget(ageLabel, 2, 0); +gridLayout->addWidget(ageSpinBox, 2, 1); +setLayout(gridLayout); +//! [1] + + +//! [2] +formLayout->setRowWrapPolicy(QFormLayout::DontWrapRows); +formLayout->setFieldGrowthPolicy(QFormLayout::FieldsStayAtSizeHint); +formLayout->setFormAlignment(Qt::AlignHCenter | Qt::AlignTop); +formLayout->setLabelAlignment(Qt::AlignLeft); +//! [2] diff --git a/doc/src/snippets/code/src_gui_kernel_qkeysequence.cpp b/doc/src/snippets/code/src_gui_kernel_qkeysequence.cpp new file mode 100644 index 0000000000..1672dc7e85 --- /dev/null +++ b/doc/src/snippets/code/src_gui_kernel_qkeysequence.cpp @@ -0,0 +1,59 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QKeySequence(QKeySequence::Print); +QKeySequence(tr("Ctrl+P")); +QKeySequence(tr("Ctrl+p")); +QKeySequence(Qt::CTRL + Qt::Key_P); +//! [0] + + +//! [1] +QKeySequence(tr("Ctrl+X, Ctrl+C")); +QKeySequence(Qt::CTRL + Qt::Key_X, Qt::CTRL + Qt::Key_C); +//! [1] + + +//! [2] +QMenu *file = new QMenu(this); +file->addAction(tr("&Open..."), this, SLOT(open()), + QKeySequence(tr("Ctrl+O", "File|Open"))); +//! [2] diff --git a/doc/src/snippets/code/src_gui_kernel_qlayout.cpp b/doc/src/snippets/code/src_gui_kernel_qlayout.cpp new file mode 100644 index 0000000000..35da7cd89e --- /dev/null +++ b/doc/src/snippets/code/src_gui_kernel_qlayout.cpp @@ -0,0 +1,67 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +static void paintLayout(QPainter *painter, QLayoutItem *item) +{ + QLayout *layout = item->layout(); + if (layout) { + for (int i = 0; i < layout->count(); ++i) + paintLayout(painter, layout->itemAt(i)); + } + painter->drawRect(item->geometry()); +} + +void MyWidget::paintEvent(QPaintEvent *) +{ + QPainter painter(this); + if (layout()) + paintLayout(&painter, layout()); +} +//! [0] + + +//! [1] +QLayoutItem *child; +while ((child = layout->takeAt(0)) != 0) { + ... + delete child; +} +//! [1] diff --git a/doc/src/snippets/code/src_gui_kernel_qlayoutitem.cpp b/doc/src/snippets/code/src_gui_kernel_qlayoutitem.cpp new file mode 100644 index 0000000000..306b822bdf --- /dev/null +++ b/doc/src/snippets/code/src_gui_kernel_qlayoutitem.cpp @@ -0,0 +1,53 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +int MyLayout::heightForWidth(int w) const +{ + if (cache_dirty || cached_width != w) { + // not all C++ compilers support "mutable" + MyLayout *that = (MyLayout*)this; + int h = calculateHeightForWidth(w); + that->cached_hfw = h; + return h; + } + return cached_hfw; +} +//! [0] diff --git a/doc/src/snippets/code/src_gui_kernel_qshortcut.cpp b/doc/src/snippets/code/src_gui_kernel_qshortcut.cpp new file mode 100644 index 0000000000..16bdda8799 --- /dev/null +++ b/doc/src/snippets/code/src_gui_kernel_qshortcut.cpp @@ -0,0 +1,55 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +shortcut = new QShortcut(QKeySequence(tr("Ctrl+O", "File|Open")), + parent); +//! [0] + + +//! [1] +setKey(0); // no signal emitted +setKey(QKeySequence()); // no signal emitted +setKey(0x3b1); // Greek letter alpha +setKey(Qt::Key_D); // 'd', e.g. to delete +setKey('q'); // 'q', e.g. to quit +setKey(Qt::CTRL + Qt::Key_P); // Ctrl+P, e.g. to print document +setKey("Ctrl+P"); // Ctrl+P, e.g. to print document +//! [1] diff --git a/doc/src/snippets/code/src_gui_kernel_qshortcutmap.cpp b/doc/src/snippets/code/src_gui_kernel_qshortcutmap.cpp new file mode 100644 index 0000000000..db8edb46f3 --- /dev/null +++ b/doc/src/snippets/code/src_gui_kernel_qshortcutmap.cpp @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +key = QKeySequence(); +//! [0] diff --git a/doc/src/snippets/code/src_gui_kernel_qsound.cpp b/doc/src/snippets/code/src_gui_kernel_qsound.cpp new file mode 100644 index 0000000000..ebaeead9cb --- /dev/null +++ b/doc/src/snippets/code/src_gui_kernel_qsound.cpp @@ -0,0 +1,49 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QSound::play("mysounds/bells.wav"); +//! [0] + + +//! [1] +QSound bells("mysounds/bells.wav"); +bells.play(); +//! [1] diff --git a/doc/src/snippets/code/src_gui_kernel_qwidget.cpp b/doc/src/snippets/code/src_gui_kernel_qwidget.cpp new file mode 100644 index 0000000000..d142d56a1a --- /dev/null +++ b/doc/src/snippets/code/src_gui_kernel_qwidget.cpp @@ -0,0 +1,137 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +w->setWindowState(w->windowState() ^ Qt::WindowFullScreen); +//! [0] + + +//! [1] +w->setWindowState(w->windowState() & ~Qt::WindowMinimized | Qt::WindowActive); +//! [1] + + +//! [2] +width = baseSize().width() + i * sizeIncrement().width(); +height = baseSize().height() + j * sizeIncrement().height(); +//! [2] + + +//! [3] +aWidget->window()->setWindowTitle("New Window Title"); +//! [3] + + +//! [4] +QFont font("Helvetica", 12, QFont::Bold); +setFont(font); +//! [4] + + +//! [5] +QFont font; +font.setBold(false); +setFont(font); +//! [5] + + +//! [6] +setCursor(Qt::IBeamCursor); +//! [6] + + +//! [7] +QPixmap pixmap(widget->size()); +widget->render(&pixmap); +//! [7] + + +//! [8] +QPainter painter(this); +... +painter.end(); +myWidget->render(this); +//! [8] + + +//! [9] +setTabOrder(a, b); // a to b +setTabOrder(b, c); // a to b to c +setTabOrder(c, d); // a to b to c to d +//! [9] + + +//! [10] +// WRONG +setTabOrder(c, d); // c to d +setTabOrder(a, b); // a to b AND c to d +setTabOrder(b, c); // a to b to c, but not c to d +//! [10] + + +//! [11] +void MyWidget::closeEvent(QCloseEvent *event) +{ + QSettings settings("MyCompany", "MyApp"); + settings.setValue("geometry", saveGeometry()); + QWidget::closeEvent(event); +} +//! [11] + + +//! [12] +QSettings settings("MyCompany", "MyApp"); +myWidget->restoreGeometry(settings.value("myWidget/geometry").toByteArray()); +//! [12] + + +//! [13] +setUpdatesEnabled(false); +bigVisualChanges(); +setUpdatesEnabled(true); +//! [13] + + +//! [14] +... +extern void qt_x11_set_global_double_buffer(bool); +qt_x11_set_global_double_buffer(false); +... +//! [14] diff --git a/doc/src/snippets/code/src_gui_painting_qbrush.cpp b/doc/src/snippets/code/src_gui_painting_qbrush.cpp new file mode 100644 index 0000000000..c2ce61ea35 --- /dev/null +++ b/doc/src/snippets/code/src_gui_painting_qbrush.cpp @@ -0,0 +1,51 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QPainter painter(this); + +painter.setBrush(Qt::cyan); +painter.setPen(Qt::darkCyan); +painter.drawRect(0, 0, 100,100); + +painter.setBrush(Qt::NoBrush); +painter.setPen(Qt::darkGreen); +painter.drawRect(40, 40, 100, 100); +//! [0] diff --git a/doc/src/snippets/code/src_gui_painting_qcolor.cpp b/doc/src/snippets/code/src_gui_painting_qcolor.cpp new file mode 100644 index 0000000000..31434f2d96 --- /dev/null +++ b/doc/src/snippets/code/src_gui_painting_qcolor.cpp @@ -0,0 +1,49 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +// Specify semi-transparent red +painter.setBrush(QColor(255, 0, 0, 127)); +painter.drawRect(0, 0, width()/2, height()); + +// Specify semi-transparent blue +painter.setBrush(QColor(0, 0, 255, 127)); +painter.drawRect(0, 0, width(), height()/2); +//! [0] diff --git a/doc/src/snippets/code/src_gui_painting_qdrawutil.cpp b/doc/src/snippets/code/src_gui_painting_qdrawutil.cpp new file mode 100644 index 0000000000..6822d818ae --- /dev/null +++ b/doc/src/snippets/code/src_gui_painting_qdrawutil.cpp @@ -0,0 +1,98 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QFrame frame: +frame.setFrameStyle(QFrame::HLine | QFrame::Sunken); +//! [0] + + +//! [1] +QFrame frame: +frame.setFrameStyle(QFrame::Box | QFrame::Raised); +//! [1] + + +//! [2] +QFrame frame: +frame.setFrameStyle( QFrame::Panel | QFrame::Sunken); +//! [2] + + +//! [3] +QFrame frame: +frame.setFrameStyle(QFrame::WinPanel | QFrame::Raised); +//! [3] + + +//! [4] +QFrame frame: +frame.setFrameStyle(QFrame::Box | QFrame::Plain); +//! [4] + + +//! [5] +QFrame frame: +frame.setFrameStyle(QFrame::HLine | QFrame::Sunken); +//! [5] + + +//! [6] +QFrame frame: +frame.setFrameStyle(QFrame::Box | QFrame::Raised); +//! [6] + + +//! [7] +QFrame frame: +frame.setFrameStyle( QFrame::Panel | QFrame::Sunken); +//! [7] + + +//! [8] +QFrame frame: +frame.setFrameStyle(QFrame::WinPanel | QFrame::Raised); +//! [8] + + +//! [9] +QFrame frame: +frame.setFrameStyle(QFrame::Box | QFrame::Plain); +//! [9] diff --git a/doc/src/snippets/code/src_gui_painting_qmatrix.cpp b/doc/src/snippets/code/src_gui_painting_qmatrix.cpp new file mode 100644 index 0000000000..63dfd6d493 --- /dev/null +++ b/doc/src/snippets/code/src_gui_painting_qmatrix.cpp @@ -0,0 +1,62 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +x' = m11*x + m21*y + dx +y' = m22*y + m12*x + dy +//! [0] + + +//! [1] +x' = m11*x + m21*y + dx +y' = m22*y + m12*x + dy +//! [1] + + +//! [2] +x' = m11*x + m21*y + dx +y' = m22*y + m12*x + dy +//! [2] + + +//! [3] +x' = m11*x + m21*y + dx +y' = m22*y + m12*x + dy +//! [3] diff --git a/doc/src/snippets/code/src_gui_painting_qpainter.cpp b/doc/src/snippets/code/src_gui_painting_qpainter.cpp new file mode 100644 index 0000000000..da566ed43a --- /dev/null +++ b/doc/src/snippets/code/src_gui_painting_qpainter.cpp @@ -0,0 +1,259 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +void SimpleExampleWidget::paintEvent(QPaintEvent *) +{ + QPainter painter(this); + painter.setPen(Qt::blue); + painter.setFont(QFont("Arial", 30)); + painter.drawText(rect(), Qt::AlignCenter, "Qt"); +} +//! [0] + + +//! [1] +void MyWidget::paintEvent(QPaintEvent *) +{ + QPainter p; + p.begin(this); + p.drawLine(...); // drawing code + p.end(); +} +//! [1] + + +//! [2] +void MyWidget::paintEvent(QPaintEvent *) +{ + QPainter p(this); + p.drawLine(...); // drawing code +} +//! [2] + + +//! [3] +painter->begin(0); // impossible - paint device cannot be 0 + +QPixmap image(0, 0); +painter->begin(&image); // impossible - image.isNull() == true; + +painter->begin(myWidget); +painter2->begin(myWidget); // impossible - only one painter at a time +//! [3] + + +//! [4] +void QPainter::rotate(qreal angle) +{ + QMatrix matrix; + matrix.rotate(angle); + setWorldMatrix(matrix, true); +} +//! [4] + + +//! [5] +QPainterPath path; +path.moveTo(20, 80); +path.lineTo(20, 30); +path.cubicTo(80, 0, 50, 50, 80, 80); + +QPainter painter(this); +painter.drawPath(path); +//! [5] + + +//! [6] +QLineF line(10.0, 80.0, 90.0, 20.0); + +QPainter(this); +painter.drawLine(line); +//! [6] + + +//! [7] +QRectF rectangle(10.0, 20.0, 80.0, 60.0); + +QPainter painter(this); +painter.drawRect(rectangle); +//! [7] + + +//! [8] +QRectF rectangle(10.0, 20.0, 80.0, 60.0); + +QPainter painter(this); +painter.drawRoundedRect(rectangle, 20.0, 15.0); +//! [8] + + +//! [9] +QRectF rectangle(10.0, 20.0, 80.0, 60.0); + +QPainter painter(this); +painter.drawEllipse(rectangle); +//! [9] + + +//! [10] +QRectF rectangle(10.0, 20.0, 80.0, 60.0); +int startAngle = 30 * 16; +int spanAngle = 120 * 16; + +QPainter painter(this); +painter.drawArc(rectangle, startAngle, spanAngle); +//! [10] + + +//! [11] +QRectF rectangle(10.0, 20.0, 80.0, 60.0); +int startAngle = 30 * 16; +int spanAngle = 120 * 16; + +QPainter painter(this); +painter.drawPie(rectangle, startAngle, spanAngle); +//! [11] + + +//! [12] +QRectF rectangle(10.0, 20.0, 80.0, 60.0); +int startAngle = 30 * 16; +int spanAngle = 120 * 16; + +QPainter painter(this); +painter.drawChord(rect, startAngle, spanAngle); +//! [12] + + +//! [13] +static const QPointF points[3] = { + QPointF(10.0, 80.0), + QPointF(20.0, 10.0), + QPointF(80.0, 30.0), +}; + +QPainter painter(this); +painter.drawPolyline(points, 3); +//! [13] + + +//! [14] +static const QPointF points[4] = { + QPointF(10.0, 80.0), + QPointF(20.0, 10.0), + QPointF(80.0, 30.0), + QPointF(90.0, 70.0) +}; + +QPainter painter(this); +painter.drawPolygon(points, 4); +//! [14] + + +//! [15] +static const QPointF points[4] = { + QPointF(10.0, 80.0), + QPointF(20.0, 10.0), + QPointF(80.0, 30.0), + QPointF(90.0, 70.0) +}; + +QPainter painter(this); +painter.drawConvexPolygon(points, 4); +//! [15] + + +//! [16] +QRectF target(10.0, 20.0, 80.0, 60.0); +QRectF source(0.0, 0.0, 70.0, 40.0); +QPixmap pixmap(":myPixmap.png"); + +QPainter(this); +painter.drawPixmap(target, image, source); +//! [16] + + +//! [17] +QPainter painter(this); +painter.drawText(rect, Qt::AlignCenter, tr("Qt by\nNokia")); +//! [17] + + +//! [18] +QPicture picture; +QPointF point(10.0, 20.0) +picture.load("drawing.pic"); + +QPainter painter(this); +painter.drawPicture(0, 0, picture); +//! [18] + + +//! [19] +fillRect(rectangle, background()). +//! [19] + + +//! [20] +QRectF target(10.0, 20.0, 80.0, 60.0); +QRectF source(0.0, 0.0, 70.0, 40.0); +QImage image(":/images/myImage.png"); + +QPainter painter(this); +painter.drawImage(target, image, source); +//! [20] + + +//! [21] +QPainter painter(this); +painter.fillRect(0, 0, 128, 128, Qt::green); +painter.beginNativePainting(); + +glEnable(GL_SCISSOR_TEST); +glScissor(0, 0, 64, 64); + +glClearColor(1, 0, 0, 1); +glClear(GL_COLOR_BUFFER_BIT); + +glDisable(GL_SCISSOR_TEST); + +painter.endNativePainting(); +//! [21] diff --git a/doc/src/snippets/code/src_gui_painting_qpainterpath.cpp b/doc/src/snippets/code/src_gui_painting_qpainterpath.cpp new file mode 100644 index 0000000000..b2a9dcf5c7 --- /dev/null +++ b/doc/src/snippets/code/src_gui_painting_qpainterpath.cpp @@ -0,0 +1,149 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QPainterPath path; +path.addRect(20, 20, 60, 60); + +path.moveTo(0, 0); +path.cubicTo(99, 0, 50, 50, 99, 99); +path.cubicTo(0, 99, 50, 50, 0, 0); + +QPainter painter(this); +painter.fillRect(0, 0, 100, 100, Qt::white); +painter.setPen(QPen(QColor(79, 106, 25), 1, Qt::SolidLine, + Qt::FlatCap, Qt::MiterJoin)); +painter.setBrush(QColor(122, 163, 39)); + +painter.drawPath(path); +//! [0] + + +//! [1] +QLinearGradient myGradient; +QPen myPen; + +QPainterPath myPath; +myPath.cubicTo(c1, c2, endPoint); + +QPainter painter(this); +painter.setBrush(myGradient); +painter.setPen(myPen); +painter.drawPath(myPath); +//! [1] + + +//! [2] +QLinearGradient myGradient; +QPen myPen; + +QPointF center, startPoint; + +QPainterPath myPath; +myPath.moveTo(center); +myPath.arcTo(boundingRect, startAngle, + sweepLength); + +QPainter painter(this); +painter.setBrush(myGradient); +painter.setPen(myPen); +painter.drawPath(myPath); +//! [2] + + +//! [3] +QLinearGradient myGradient; +QPen myPen; +QRectF myRectangle; + +QPainterPath myPath; +myPath.addRect(myRectangle); + +QPainter painter(this); +painter.setBrush(myGradient); +painter.setPen(myPen); +painter.drawPath(myPath); +//! [3] + + +//! [4] +QLinearGradient myGradient; +QPen myPen; +QPolygonF myPolygon; + +QPainterPath myPath; +myPath.addPolygon(myPolygon); + +QPainter painter(this); +painter.setBrush(myGradient); +painter.setPen(myPen); +painter.drawPath(myPath); +//! [4] + + +//! [5] +QLinearGradient myGradient; +QPen myPen; +QRectF boundingRectangle; + +QPainterPath myPath; +myPath.addEllipse(boundingRectangle); + +QPainter painter(this); +painter.setBrush(myGradient); +painter.setPen(myPen); +painter.drawPath(myPath); +//! [5] + + +//! [6] +QLinearGradient myGradient; +QPen myPen; +QFont myFont; +QPointF baseline(x, y); + +QPainterPath myPath; +myPath.addText(baseline, myFont, tr("Qt")); + +QPainter painter(this); +painter.setBrush(myGradient); +painter.setPen(myPen); +painter.drawPath(myPath); +//! [6] diff --git a/doc/src/snippets/code/src_gui_painting_qpen.cpp b/doc/src/snippets/code/src_gui_painting_qpen.cpp new file mode 100644 index 0000000000..8674516fbc --- /dev/null +++ b/doc/src/snippets/code/src_gui_painting_qpen.cpp @@ -0,0 +1,81 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QPainter painter(this); +QPen pen(Qt::green, 3, Qt::DashDotLine, Qt::RoundCap, Qt::RoundJoin); +painter.setPen(pen); +//! [0] + + +//! [1] +QPainter painter(this); +QPen pen; // creates a default pen + +pen.setStyle(Qt::DashDotLine); +pen.setWidth(3); +pen.setBrush(Qt::green); +pen.setCapStyle(Qt::RoundCap); +pen.setJoinStyle(Qt::RoundJoin); + +painter.setPen(pen); +//! [1] + + +//! [2] +QPen pen; +QVector<qreal> dashes; +qreal space = 4; + +dashes << 1 << space << 3 << space << 9 << space + << 27 << space << 9 << space; + +pen.setDashPattern(dashes); +//! [2] + + +//! [3] +QPen pen; +QVector<qreal> dashes; +qreal space = 4; +dashes << 1 << space << 3 << space << 9 << space + << 27 << space << 9 << space; +pen.setDashPattern(dashes); +//! [3] diff --git a/doc/src/snippets/code/src_gui_painting_qregion.cpp b/doc/src/snippets/code/src_gui_painting_qregion.cpp new file mode 100644 index 0000000000..660138d461 --- /dev/null +++ b/doc/src/snippets/code/src_gui_painting_qregion.cpp @@ -0,0 +1,53 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +void MyWidget::paintEvent(QPaintEvent *) +{ + QRegion r1(QRect(100, 100, 200, 80), // r1: elliptic region + QRegion::Ellipse); + QRegion r2(QRect(100, 120, 90, 30)); // r2: rectangular region + QRegion r3 = r1.intersected(r2); // r3: intersection + + QPainter painter(this); + painter.setClipRegion(r3); + ... // paint clipped graphics +} +//! [0] diff --git a/doc/src/snippets/code/src_gui_painting_qregion_unix.cpp b/doc/src/snippets/code/src_gui_painting_qregion_unix.cpp new file mode 100644 index 0000000000..2eddeea506 --- /dev/null +++ b/doc/src/snippets/code/src_gui_painting_qregion_unix.cpp @@ -0,0 +1,54 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QRegion r1(10, 10, 20, 20); +r1.isEmpty(); // false + +QRegion r3; +r3.isEmpty(); // true + +QRegion r2(40, 40, 20, 20); +r3 = r1.intersected(r2); // r3: intersection of r1 and r2 +r3.isEmpty(); // true + +r3 = r1.united(r2); // r3: union of r1 and r2 +r3.isEmpty(); // false +//! [0] diff --git a/doc/src/snippets/code/src_gui_painting_qtransform.cpp b/doc/src/snippets/code/src_gui_painting_qtransform.cpp new file mode 100644 index 0000000000..24b1a359e1 --- /dev/null +++ b/doc/src/snippets/code/src_gui_painting_qtransform.cpp @@ -0,0 +1,82 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +x' = m11*x + m21*y + dx +y' = m22*y + m12*x + dy +if (is not affine) { + w' = m13*x + m23*y + m33 + x' /= w' + y' /= w' +} +//! [0] + + +//! [1] +x' = m11*x + m21*y + dx +y' = m22*y + m12*x + dy +if (is not affine) { + w' = m13*x + m23*y + m33 + x' /= w' + y' /= w' +} +//! [1] + + +//! [2] +x' = m11*x + m21*y + dx +y' = m22*y + m12*x + dy +if (is not affine) { + w' = m13*x + m23*y + m33 + x' /= w' + y' /= w' +} +//! [2] + + +//! [3] +x' = m11*x + m21*y + dx +y' = m22*y + m12*x + dy +if (is not affine) { + w' = m13*x + m23*y + m33 + x' /= w' + y' /= w' +} +//! [3] diff --git a/doc/src/snippets/code/src_gui_qproxystyle.cpp b/doc/src/snippets/code/src_gui_qproxystyle.cpp new file mode 100644 index 0000000000..b4cd0b65d0 --- /dev/null +++ b/doc/src/snippets/code/src_gui_qproxystyle.cpp @@ -0,0 +1,85 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +class MyProxyStyle : public QProxyStyle +{ +public: + + int styleHint(StyleHint hint, const QStyleOption *option = 0, + const QWidget *widget = 0, QStyleHintReturn *returnData = 0) const + { + if (hint == QStyle::SH_UnderlineShortcut) + return 1; + return QProxyStyle::styleHint(hint, option, widget, returnData); + } +}; + +//! [0] + +//! [1] +#include "textedit.h" +#include <QApplication> +#include <QProxyStyle> + +class MyProxyStyle : public QProxyStyle +{ + public: + int styleHint(StyleHint hint, const QStyleOption *option = 0, + const QWidget *widget = 0, QStyleHintReturn *returnData = 0) const + { + if (hint == QStyle::SH_UnderlineShortcut) + return 0; + return QProxyStyle::styleHint(hint, option, widget, returnData); + } +}; + +int main(int argc, char **argv) +{ + Q_INIT_RESOURCE(textedit); + + QApplication a(argc, argv); + a.setStyle(new MyProxyStyle); + TextEdit mw; + mw.resize(700, 800); + mw.show(); + //... +} +//! [1] diff --git a/doc/src/snippets/code/src_gui_styles_qstyle.cpp b/doc/src/snippets/code/src_gui_styles_qstyle.cpp new file mode 100644 index 0000000000..40fb230c02 --- /dev/null +++ b/doc/src/snippets/code/src_gui_styles_qstyle.cpp @@ -0,0 +1,48 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +./myapplication -style motif +//! [0] + + +//! [1] +./myapplication -style custom +//! [1] diff --git a/doc/src/snippets/code/src_gui_styles_qstyleoption.cpp b/doc/src/snippets/code/src_gui_styles_qstyleoption.cpp new file mode 100644 index 0000000000..ba65d3f5ea --- /dev/null +++ b/doc/src/snippets/code/src_gui_styles_qstyleoption.cpp @@ -0,0 +1,54 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +int MyStyle::styleHint(StyleHint stylehint, const QStyleOption *opt, + const QWidget *widget, QStyleHintReturn* returnData) const; +{ + if (stylehint == SH_RubberBand_Mask) { + const QStyleHintReturnMask *maskReturn = + qstyleoption_cast<const QStyleHintReturnMask *>(hint); + if (maskReturn) { + ... + } + } + ... +} +//! [0] diff --git a/doc/src/snippets/code/src_gui_text_qfont.cpp b/doc/src/snippets/code/src_gui_text_qfont.cpp new file mode 100644 index 0000000000..5694d6aab0 --- /dev/null +++ b/doc/src/snippets/code/src_gui_text_qfont.cpp @@ -0,0 +1,67 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QFont serifFont("Times", 10, QFont::Bold); +QFont sansFont("Helvetica [Cronyx]", 12); +//! [0] + + +//! [1] +QFont f("Helvetica"); +//! [1] + + +//! [2] +QFont f("Helvetica [Cronyx]"); +//! [2] + + +//! [3] +QFontInfo info(f1); +QString family = info.family(); +//! [3] + + +//! [4] +QFontMetrics fm(f1); +int textWidthInPixels = fm.width("How many pixels wide is this text?"); +int textHeightInPixels = fm.height(); +//! [4] diff --git a/doc/src/snippets/code/src_gui_text_qfontmetrics.cpp b/doc/src/snippets/code/src_gui_text_qfontmetrics.cpp new file mode 100644 index 0000000000..3be333d22a --- /dev/null +++ b/doc/src/snippets/code/src_gui_text_qfontmetrics.cpp @@ -0,0 +1,54 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QFont font("times", 24); +QFontMetrics fm(font); +int pixelsWide = fm.width("What's the width of this text?"); +int pixelsHigh = fm.height(); +//! [0] + + +//! [1] +QFont font("times", 24); +QFontMetricsF fm(font); +qreal pixelsWide = fm.width("What's the width of this text?"); +qreal pixelsHigh = fm.height(); +//! [1] diff --git a/doc/src/snippets/code/src_gui_text_qsyntaxhighlighter.cpp b/doc/src/snippets/code/src_gui_text_qsyntaxhighlighter.cpp new file mode 100644 index 0000000000..a273f333a5 --- /dev/null +++ b/doc/src/snippets/code/src_gui_text_qsyntaxhighlighter.cpp @@ -0,0 +1,126 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QTextEdit *editor = new QTextEdit; +MyHighlighter *highlighter = new MyHighlighter(editor->document()); +//! [0] + + +//! [1] +void MyHighlighter::highlightBlock(const QString &text) +{ + QTextCharFormat myClassFormat; + myClassFormat.setFontWeight(QFont::Bold); + myClassFormat.setForeground(Qt::darkMagenta); + QString pattern = "\\bMy[A-Za-z]+\\b"; + + QRegExp expression(pattern); + int index = text.indexOf(expression); + while (index >= 0) { + int length = expression.matchedLength(); + setFormat(index, length, myClassFormat); + index = text.indexOf(expression, index + length); + } +} +//! [1] + + +//! [2] +QTextCharFormat multiLineCommentFormat; +multiLineCommentFormat.setForeground(Qt::red); + +QRegExp startExpression("/\\*"); +QRegExp endExpression("\\*/"); + +setCurrentBlockState(0); + +int startIndex = 0; +if (previousBlockState() != 1) + startIndex = text.indexOf(startExpression); + +while (startIndex >= 0) { + int endIndex = text.indexOf(endExpression, startIndex); + int commentLength; + if (endIndex == -1) { + setCurrentBlockState(1); + commentLength = text.length() - startIndex; + } else { + commentLength = endIndex - startIndex + + endExpression.matchedLength(); + } + setFormat(startIndex, commentLength, multiLineCommentFormat); + startIndex = text.indexOf(startExpression, + startIndex + commentLength); +} +//! [2] + + +//! [3] +void MyHighlighter::highlightBlock(const QString &text) +{ + QTextCharFormat myClassFormat; + myClassFormat.setFontWeight(QFont::Bold); + myClassFormat.setForeground(Qt::darkMagenta); + QString pattern = "\\bMy[A-Za-z]+\\b"; + + QRegExp expression(pattern); + int index = text.indexOf(expression); + while (index >= 0) { + int length = expression.matchedLength(); + setFormat(index, length, myClassFormat); + index = text.indexOf(expression, index + length); + } + } +//! [3] + + +//! [4] +struct ParenthesisInfo +{ + QChar char; + int position; +}; + +struct BlockData : public QTextBlockUserData +{ + QVector<ParenthesisInfo> parentheses; +}; +//! [4] diff --git a/doc/src/snippets/code/src_gui_text_qtextcursor.cpp b/doc/src/snippets/code/src_gui_text_qtextcursor.cpp new file mode 100644 index 0000000000..9e99c4b676 --- /dev/null +++ b/doc/src/snippets/code/src_gui_text_qtextcursor.cpp @@ -0,0 +1,80 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +cursor.clearSelection(); +cursor.movePosition(QTextCursor::NextWord, QTextCursor::KeepAnchor); +cursor.insertText("Hello World"); +//! [0] + + +//! [1] +QImage img = ... +textDocument->addResource(QTextDocument::ImageResource, QUrl("myimage"), img); +cursor.insertImage("myimage"); +//! [1] + + +//! [2] +QTextCursor cursor(textDocument); +cursor.beginEditBlock(); +cursor.insertText("Hello"); +cursor.insertText("World"); +cursor.endEditBlock(); + +textDocument->undo(); +//! [2] + + +//! [3] +QTextCursor cursor(textDocument); +cursor.beginEditBlock(); +cursor.insertText("Hello"); +cursor.insertText("World"); +cursor.endEditBlock(); + +... + +cursor.joinPreviousEditBlock(); +cursor.insertText("Hey"); +cursor.endEditBlock(); + +textDocument->undo(); +//! [3] diff --git a/doc/src/snippets/code/src_gui_text_qtextdocument.cpp b/doc/src/snippets/code/src_gui_text_qtextdocument.cpp new file mode 100644 index 0000000000..775cc0fcd1 --- /dev/null +++ b/doc/src/snippets/code/src_gui_text_qtextdocument.cpp @@ -0,0 +1,50 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QString plain = "#include <QtCore>" +QString html = Qt::escape(plain); +// html == "#include <QtCore>" +//! [0] + + +//! [1] +<html><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"></head><body>... +//! [1] diff --git a/doc/src/snippets/code/src_gui_text_qtextlayout.cpp b/doc/src/snippets/code/src_gui_text_qtextlayout.cpp new file mode 100644 index 0000000000..feb5219c1a --- /dev/null +++ b/doc/src/snippets/code/src_gui_text_qtextlayout.cpp @@ -0,0 +1,62 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +int leading = fontMetrics.leading(); +qreal height = 0; +textLayout.beginLayout(); +while (1) { + QTextLine line = textLayout.createLine(); + if (!line.isValid()) + break; + + line.setLineWidth(lineWidth); + height += leading; + line.setPosition(QPointF(0, height)); + height += line.height(); +} +textLayout.endLayout(); +//! [0] + + +//! [1] +QPainter painter(this); +textLayout.draw(&painter, QPoint(0, 0)); +//! [1] diff --git a/doc/src/snippets/code/src_gui_util_qcompleter.cpp b/doc/src/snippets/code/src_gui_util_qcompleter.cpp new file mode 100644 index 0000000000..bfc1b54cbd --- /dev/null +++ b/doc/src/snippets/code/src_gui_util_qcompleter.cpp @@ -0,0 +1,63 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QStringList wordList; +wordList << "alpha" << "omega" << "omicron" << "zeta"; + +QLineEdit *lineEdit = new QLineEdit(this); + +QCompleter *completer = new QCompleter(wordList, this); +completer->setCaseSensitivity(Qt::CaseInsensitive); +lineEdit->setCompleter(completer); +//! [0] + + +//! [1] +QCompleter *completer = new QCompleter(this); +completer->setModel(new QDirModel(completer)); +lineEdit->setCompleter(completer); +//! [1] + + +//! [2] +for (int i = 0; completer->setCurrentRow(i); i++) + qDebug() << completer->currentCompletion() << " is match number " << i; +//! [2] diff --git a/doc/src/snippets/code/src_gui_util_qdesktopservices.cpp b/doc/src/snippets/code/src_gui_util_qdesktopservices.cpp new file mode 100644 index 0000000000..c878b71b6c --- /dev/null +++ b/doc/src/snippets/code/src_gui_util_qdesktopservices.cpp @@ -0,0 +1,60 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +class MyHelpHandler : public QObject +{ + Q_OBJECT +public: + ... +public slots: + void showHelp(const QUrl &url); +}; + +QDesktopServices::setUrlHandler("help", helpInstance, "showHelp"); +//! [0] + +//! [1] +mailto:user@foo.com?subject=Test&body=Just a test +//! [1] + +//! [2] +QDesktopServices::openUrl(QUrl("file:///C:/Documents and Settings/All Users/Desktop", QUrl::TolerantMode)); +//! [2] diff --git a/doc/src/snippets/code/src_gui_util_qundostack.cpp b/doc/src/snippets/code/src_gui_util_qundostack.cpp new file mode 100644 index 0000000000..2eccd71015 --- /dev/null +++ b/doc/src/snippets/code/src_gui_util_qundostack.cpp @@ -0,0 +1,109 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +class AppendText : public QUndoCommand +{ +public: + AppendText(QString *doc, const QString &text) + : m_document(doc), m_text(text) { setText("append text"); } + virtual void undo() + { m_document->chop(m_text.length()); } + virtual void redo() + { m_document->append(m_text); } +private: + QString *m_document; + QString m_text; +}; +//! [0] + + +//! [1] +MyCommand *command1 = new MyCommand(); +stack->push(command1); +MyCommand *command2 = new MyCommand(); +stack->push(command2); + +stack->undo(); + +MyCommand *command3 = new MyCommand(); +stack->push(command3); // command2 gets deleted +//! [1] + + +//! [2] +QUndoCommand *insertRed = new QUndoCommand(); // an empty command +insertRed->setText("insert red text"); + +new InsertText(document, idx, text, insertRed); // becomes child of insertRed +new SetColor(document, idx, text.length(), Qt::red, insertRed); + +stack.push(insertRed); +//! [2] + + +//! [3] +bool AppendText::mergeWith(const QUndoCommand *other) +{ + if (other->id() != id()) // make sure other is also an AppendText command + return false; + m_text += static_cast<const AppendText*>(other)->m_text; + return true; +} +//! [3] + + +//! [4] +stack.beginMacro("insert red text"); +stack.push(new InsertText(document, idx, text)); +stack.push(new SetColor(document, idx, text.length(), Qt::red)); +stack.endMacro(); // indexChanged() is emitted +//! [4] + + +//! [5] +QUndoCommand *insertRed = new QUndoCommand(); // an empty command +insertRed->setText("insert red text"); + +new InsertText(document, idx, text, insertRed); // becomes child of insertRed +new SetColor(document, idx, text.length(), Qt::red, insertRed); + +stack.push(insertRed); +//! [5] diff --git a/doc/src/snippets/code/src_gui_widgets_qabstractbutton.cpp b/doc/src/snippets/code/src_gui_widgets_qabstractbutton.cpp new file mode 100644 index 0000000000..3bfe1d2aaa --- /dev/null +++ b/doc/src/snippets/code/src_gui_widgets_qabstractbutton.cpp @@ -0,0 +1,60 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QPushButton *button = new QPushButton(tr("Ro&ck && Roll"), this); +//! [0] + + +//! [1] +button->setIcon(QIcon(":/images/print.png")); +button->setShortcut(tr("Alt+F7")); +//! [1] + + +//! [2] +void MyWidget::reactToToggle(bool checked) +{ + if (checked) { + // Examine the new button states. + ... + } +} +//! [2] diff --git a/doc/src/snippets/code/src_gui_widgets_qabstractspinbox.cpp b/doc/src/snippets/code/src_gui_widgets_qabstractspinbox.cpp new file mode 100644 index 0000000000..3a73308e63 --- /dev/null +++ b/doc/src/snippets/code/src_gui_widgets_qabstractspinbox.cpp @@ -0,0 +1,48 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QSpinBox *spinBox = new QSpinBox(this); +spinBox->setRange(0, 100); +spinBox->setWrapping(true); +spinBox->setValue(100); +spinBox->stepBy(1); +// value is 0 +//! [0] diff --git a/doc/src/snippets/code/src_gui_widgets_qcalendarwidget.cpp b/doc/src/snippets/code/src_gui_widgets_qcalendarwidget.cpp new file mode 100644 index 0000000000..336a4064b5 --- /dev/null +++ b/doc/src/snippets/code/src_gui_widgets_qcalendarwidget.cpp @@ -0,0 +1,79 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QCalendarWidget *calendar; +calendar->setGridVisible(true); +//! [0] + + +//! [1] +QCalendarWidget *calendar; +calendar->setGridVisible(true); +calendar->setMinimumDate(QDate(2006, 6, 19)); +//! [1] + + +//! [2] +QCalendarWidget *calendar; +calendar->setGridVisible(true); +calendar->setMaximumDate(QDate(2006, 7, 3)); +//! [2] + + +//! [3] +QCalendarWidget *calendar; + +calendar->setDateRange(min, max); +//! [3] + + +//! [4] +QCalendarWidget *calendar; + +calendar->setMinimumDate(min); +calendar->setMaximumDate(max); +//! [4] + + +//! [5] +QCalendarWidget *calendar; +calendar->setGridVisible(true); +//! [5] diff --git a/doc/src/snippets/code/src_gui_widgets_qcheckbox.cpp b/doc/src/snippets/code/src_gui_widgets_qcheckbox.cpp new file mode 100644 index 0000000000..785d0cfd93 --- /dev/null +++ b/doc/src/snippets/code/src_gui_widgets_qcheckbox.cpp @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QCheckBox *checkbox = new QCheckBox("C&ase sensitive", this); +//! [0] diff --git a/doc/src/snippets/code/src_gui_widgets_qdatetimeedit.cpp b/doc/src/snippets/code/src_gui_widgets_qdatetimeedit.cpp new file mode 100644 index 0000000000..73253f79f1 --- /dev/null +++ b/doc/src/snippets/code/src_gui_widgets_qdatetimeedit.cpp @@ -0,0 +1,79 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QDateTimeEdit *dateEdit = new QDateTimeEdit(QDate::currentDate()); +dateEdit->setMinimumDate(QDate::currentDate().addDays(-365)); +dateEdit->setMaximumDate(QDate::currentDate().addDays(365)); +dateEdit->setDisplayFormat("yyyy.MM.dd"); +//! [0] + + +//! [1] +setDateTimeRange(min, max); +//! [1] + + +//! [2] +setMinimumDateTime(min); +setMaximumDateTime(max); +//! [2] + + +//! [3] +setDateRange(min, max); +//! [3] + + +//! [4] +setMinimumDate(min); +setMaximumDate(max); +//! [4] + + +//! [5] +setTimeRange(min, max); +//! [5] + + +//! [6] +setMinimumTime(min); +setMaximumTime(max); +//! [6] diff --git a/doc/src/snippets/code/src_gui_widgets_qdockwidget.cpp b/doc/src/snippets/code/src_gui_widgets_qdockwidget.cpp new file mode 100644 index 0000000000..fd1d81769b --- /dev/null +++ b/doc/src/snippets/code/src_gui_widgets_qdockwidget.cpp @@ -0,0 +1,48 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QDockWidget *dockWidget = qobject_cast<QDockWidget*>(parentWidget()); +if (dockWidget->features() & QDockWidget::DockWidgetVerticalTitleBar) { + // I need to be vertical +} else { + // I need to be horizontal +} +//! [0] diff --git a/doc/src/snippets/code/src_gui_widgets_qframe.cpp b/doc/src/snippets/code/src_gui_widgets_qframe.cpp new file mode 100644 index 0000000000..5fb45c1f77 --- /dev/null +++ b/doc/src/snippets/code/src_gui_widgets_qframe.cpp @@ -0,0 +1,48 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QLabel label(...); +label.setFrameStyle(QFrame::Panel | QFrame::Raised); +label.setLineWidth(2); + +QProgressBar pbar(...); +label.setFrameStyle(QFrame::NoFrame); +//! [0] diff --git a/doc/src/snippets/code/src_gui_widgets_qgroupbox.cpp b/doc/src/snippets/code/src_gui_widgets_qgroupbox.cpp new file mode 100644 index 0000000000..0f4a5b8afa --- /dev/null +++ b/doc/src/snippets/code/src_gui_widgets_qgroupbox.cpp @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +g->setTitle("&User information"); +//! [0] diff --git a/doc/src/snippets/code/src_gui_widgets_qlabel.cpp b/doc/src/snippets/code/src_gui_widgets_qlabel.cpp new file mode 100644 index 0000000000..cda00fa349 --- /dev/null +++ b/doc/src/snippets/code/src_gui_widgets_qlabel.cpp @@ -0,0 +1,64 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QLabel *label = new QLabel(this); +label->setFrameStyle(QFrame::Panel | QFrame::Sunken); +label->setText("first line\nsecond line"); +label->setAlignment(Qt::AlignBottom | Qt::AlignRight); +//! [0] + + +//! [1] +QLineEdit* phoneEdit = new QLineEdit(this); +QLabel* phoneLabel = new QLabel("&Phone:", this); +phoneLabel->setBuddy(phoneEdit); +//! [1] + + +//! [2] +QLineEdit *nameEd = new QLineEdit(this); +QLabel *nameLb = new QLabel("&Name:", this); +nameLb->setBuddy(nameEd); +QLineEdit *phoneEd = new QLineEdit(this); +QLabel *phoneLb = new QLabel("&Phone:", this); +phoneLb->setBuddy(phoneEd); +// (layout setup not shown) +//! [2] diff --git a/doc/src/snippets/code/src_gui_widgets_qlineedit.cpp b/doc/src/snippets/code/src_gui_widgets_qlineedit.cpp new file mode 100644 index 0000000000..7b9e183703 --- /dev/null +++ b/doc/src/snippets/code/src_gui_widgets_qlineedit.cpp @@ -0,0 +1,50 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +void LineEdit::contextMenuEvent(QContextMenuEvent *event) +{ + QMenu *menu = createStandardContextMenu(); + menu->addAction(tr("My Menu Item")); + //... + menu->exec(event->globalPos()); + delete menu; +} +//! [0] diff --git a/doc/src/snippets/code/src_gui_widgets_qmainwindow.cpp b/doc/src/snippets/code/src_gui_widgets_qmainwindow.cpp new file mode 100644 index 0000000000..d465c7013d --- /dev/null +++ b/doc/src/snippets/code/src_gui_widgets_qmainwindow.cpp @@ -0,0 +1,59 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +void MyMainWindow::closeEvent(QCloseEvent *event) +{ + QSettings settings("MyCompany", "MyApp"); + settings.setValue("geometry", saveGeometry()); + settings.setValue("windowState", saveState()); + QMainWindow::closeEvent(event); +} +//! [0] + + +//! [1] +void MainWindow::readSettings() +{ + QSettings settings("MyCompany", "MyApp"); + restoreGeometry(settings.value("myWidget/geometry").toByteArray()); + restoreState(settings.value("myWidget/windowState").toByteArray()); +} +//! [1] diff --git a/doc/src/snippets/code/src_gui_widgets_qmenu.cpp b/doc/src/snippets/code/src_gui_widgets_qmenu.cpp new file mode 100644 index 0000000000..f2dd1ccf52 --- /dev/null +++ b/doc/src/snippets/code/src_gui_widgets_qmenu.cpp @@ -0,0 +1,77 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +exec(QCursor::pos()); +//! [0] + + +//! [1] +exec(somewidget.mapToGlobal(QPoint(0,0))); +//! [1] + + +//! [2] +exec(e->globalPos()); +//! [2] + + +//! [3] +exec(QCursor::pos()); +//! [3] + + +//! [4] +exec(somewidget.mapToGlobal(QPoint(0, 0))); +//! [4] + + +//! [5] +exec(e->globalPos()); +//! [5] + + +//! [6] +QMenu menu; +QAction *at = actions[0]; // Assumes actions is not empty +foreach (QAction *a, actions) + menu.addAction(a); +menu.exec(pos, at); +//! [6] diff --git a/doc/src/snippets/code/src_gui_widgets_qmenubar.cpp b/doc/src/snippets/code/src_gui_widgets_qmenubar.cpp new file mode 100644 index 0000000000..98eafb4239 --- /dev/null +++ b/doc/src/snippets/code/src_gui_widgets_qmenubar.cpp @@ -0,0 +1,48 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +menubar->addMenu(fileMenu); +//! [0] + + +//! [1] +QMenuBar *menuBar = new QMenuBar(0); +//! [1] diff --git a/doc/src/snippets/code/src_gui_widgets_qplaintextedit.cpp b/doc/src/snippets/code/src_gui_widgets_qplaintextedit.cpp new file mode 100644 index 0000000000..4b0219d68c --- /dev/null +++ b/doc/src/snippets/code/src_gui_widgets_qplaintextedit.cpp @@ -0,0 +1,55 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +void MyQPlainTextEdit::contextMenuEvent(QContextMenuEvent *event) +{ + QMenu *menu = createStandardContextMenu(); + menu->addAction(tr("My Menu Item")); + //... + menu->exec(event->globalPos()); + delete menu; +} +//! [0] + + +//! [1] +edit->textCursor().insertText(text); +//! [1] diff --git a/doc/src/snippets/code/src_gui_widgets_qpushbutton.cpp b/doc/src/snippets/code/src_gui_widgets_qpushbutton.cpp new file mode 100644 index 0000000000..099d087dcb --- /dev/null +++ b/doc/src/snippets/code/src_gui_widgets_qpushbutton.cpp @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QPushButton *button = new QPushButton("&Download", this); +//! [0] diff --git a/doc/src/snippets/code/src_gui_widgets_qradiobutton.cpp b/doc/src/snippets/code/src_gui_widgets_qradiobutton.cpp new file mode 100644 index 0000000000..3dc031c383 --- /dev/null +++ b/doc/src/snippets/code/src_gui_widgets_qradiobutton.cpp @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QRadioButton *button = new QRadioButton("Search from the &cursor", this); +//! [0] diff --git a/doc/src/snippets/code/src_gui_widgets_qrubberband.cpp b/doc/src/snippets/code/src_gui_widgets_qrubberband.cpp new file mode 100644 index 0000000000..3289344c43 --- /dev/null +++ b/doc/src/snippets/code/src_gui_widgets_qrubberband.cpp @@ -0,0 +1,62 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +void Widget::mousePressEvent(QMouseEvent *event) +{ + origin = event->pos(); + if (!rubberBand) + rubberBand = new QRubberBand(QRubberBand::Rectangle, this); + rubberBand->setGeometry(QRect(origin, QSize())); + rubberBand->show(); +} + +void Widget::mouseMoveEvent(QMouseEvent *event) +{ + rubberBand->setGeometry(QRect(origin, event->pos()).normalized()); +} + +void Widget::mouseReleaseEvent(QMouseEvent *event) +{ + rubberBand->hide(); + // determine selection, for example using QRect::intersects() + // and QRect::contains(). +} +//! [0] diff --git a/doc/src/snippets/code/src_gui_widgets_qscrollarea.cpp b/doc/src/snippets/code/src_gui_widgets_qscrollarea.cpp new file mode 100644 index 0000000000..64f8d293df --- /dev/null +++ b/doc/src/snippets/code/src_gui_widgets_qscrollarea.cpp @@ -0,0 +1,49 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QLabel *imageLabel = new QLabel; +QImage image("happyguy.png"); +imageLabel->setPixmap(QPixmap::fromImage(image)); + +scrollArea = new QScrollArea; +scrollArea->setBackgroundRole(QPalette::Dark); +scrollArea->setWidget(imageLabel); +//! [0] diff --git a/doc/src/snippets/code/src_gui_widgets_qspinbox.cpp b/doc/src/snippets/code/src_gui_widgets_qspinbox.cpp new file mode 100644 index 0000000000..d4022d790e --- /dev/null +++ b/doc/src/snippets/code/src_gui_widgets_qspinbox.cpp @@ -0,0 +1,80 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +sb->setPrefix("$"); +//! [0] + + +//! [1] +sb->setSuffix(" km"); +//! [1] + + +//! [2] +setRange(minimum, maximum); +//! [2] + + +//! [3] +setMinimum(minimum); +setMaximum(maximum); +//! [3] + + +//! [4] +spinbox->setPrefix("$"); +//! [4] + + +//! [5] +spinbox->setSuffix(" km"); +//! [5] + + +//! [6] +setRange(minimum, maximum); +//! [6] + + +//! [7] +setMinimum(minimum); +setMaximum(maximum); +//! [7] diff --git a/doc/src/snippets/code/src_gui_widgets_qsplashscreen.cpp b/doc/src/snippets/code/src_gui_widgets_qsplashscreen.cpp new file mode 100644 index 0000000000..c8ee298c78 --- /dev/null +++ b/doc/src/snippets/code/src_gui_widgets_qsplashscreen.cpp @@ -0,0 +1,55 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QPixmap pixmap(":/splash.png"); +QSplashScreen *splash = new QSplashScreen(pixmap); +splash->show(); + +... // Loading some items +splash->showMessage("Loaded modules"); + +qApp->processEvents(); + +... // Establishing connections +splash->showMessage("Established connections"); + +qApp->processEvents(); +//! [0] diff --git a/doc/src/snippets/code/src_gui_widgets_qsplitter.cpp b/doc/src/snippets/code/src_gui_widgets_qsplitter.cpp new file mode 100644 index 0000000000..05f907a7e6 --- /dev/null +++ b/doc/src/snippets/code/src_gui_widgets_qsplitter.cpp @@ -0,0 +1,47 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QWidget *widget = splitter->widget(index); +QSizePolicy policy = widget->sizePolicy(); +policy.setHorizontalStretch(stretch); +policy.setVerticalStretch(stretch); +widget->setSizePolicy(policy); +//! [0] diff --git a/doc/src/snippets/code/src_gui_widgets_qstatusbar.cpp b/doc/src/snippets/code/src_gui_widgets_qstatusbar.cpp new file mode 100644 index 0000000000..12e962c970 --- /dev/null +++ b/doc/src/snippets/code/src_gui_widgets_qstatusbar.cpp @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +statusBar()->addWidget(new MyReadWriteIndication); +//! [0] diff --git a/doc/src/snippets/code/src_gui_widgets_qtextbrowser.cpp b/doc/src/snippets/code/src_gui_widgets_qtextbrowser.cpp new file mode 100644 index 0000000000..8ad9deb4ea --- /dev/null +++ b/doc/src/snippets/code/src_gui_widgets_qtextbrowser.cpp @@ -0,0 +1,44 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +backaction.setToolTip(browser.historyTitle(-1)); +forwardaction.setToolTip(browser.historyTitle(+1)); +//! [0] diff --git a/doc/src/snippets/code/src_gui_widgets_qtextedit.cpp b/doc/src/snippets/code/src_gui_widgets_qtextedit.cpp new file mode 100644 index 0000000000..5ee24a04d3 --- /dev/null +++ b/doc/src/snippets/code/src_gui_widgets_qtextedit.cpp @@ -0,0 +1,60 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +void MyTextEdit::contextMenuEvent(QContextMenuEvent *event) +{ + QMenu *menu = createStandardContextMenu(); + menu->addAction(tr("My Menu Item")); + //... + menu->exec(event->globalPos()); + delete menu; +} +//! [0] + + +//! [1] +edit->textCursor().insertText(text); +//! [1] + + +//! [2] +edit->textCursor().insertHtml(fragment); +//! [2] diff --git a/doc/src/snippets/code/src_gui_widgets_qvalidator.cpp b/doc/src/snippets/code/src_gui_widgets_qvalidator.cpp new file mode 100644 index 0000000000..4a104ddc33 --- /dev/null +++ b/doc/src/snippets/code/src_gui_widgets_qvalidator.cpp @@ -0,0 +1,135 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QValidator *validator = new QIntValidator(100, 999, this); +QLineEdit *edit = new QLineEdit(this); + +// the edit lineedit will only accept integers between 100 and 999 +edit->setValidator(validator); +//! [0] + + +//! [1] +QString str; +int pos = 0; +QIntValidator v(100, 900, this); + +str = "1"; +v.validate(str, pos); // returns Intermediate +str = "012"; +v.validate(str, pos); // returns Intermediate + +str = "123"; +v.validate(str, pos); // returns Acceptable +str = "678"; +v.validate(str, pos); // returns Acceptable + +str = "999"; +v.validate(str, pos); // returns Intermediate + +str = "1234"; +v.validate(str, pos); // returns Invalid +str = "-123"; +v.validate(str, pos); // returns Invalid +str = "abc"; +v.validate(str, pos); // returns Invalid +str = "12cm"; +v.validate(str, pos); // returns Invalid +//! [1] + + +//! [2] +int pos = 0; + +s = "abc"; +v.validate(s, pos); // returns Invalid + +s = "5"; +v.validate(s, pos); // returns Intermediate + +s = "50"; +v.validate(s, pos); // returns Acceptable +//! [2] + + +//! [3] +// regexp: optional '-' followed by between 1 and 3 digits +QRegExp rx("-?\\d{1,3}"); +QValidator *validator = new QRegExpValidator(rx, this); + +QLineEdit *edit = new QLineEdit(this); +edit->setValidator(validator); +//! [3] + + +//! [4] +// integers 1 to 9999 +QRegExp rx("[1-9]\\d{0,3}"); +// the validator treats the regexp as "^[1-9]\\d{0,3}$" +QRegExpValidator v(rx, 0); +QString s; +int pos = 0; + +s = "0"; v.validate(s, pos); // returns Invalid +s = "12345"; v.validate(s, pos); // returns Invalid +s = "1"; v.validate(s, pos); // returns Acceptable + +rx.setPattern("\\S+"); // one or more non-whitespace characters +v.setRegExp(rx); +s = "myfile.txt"; v.validate(s, pos); // Returns Acceptable +s = "my file.txt"; v.validate(s, pos); // Returns Invalid + +// A, B or C followed by exactly five digits followed by W, X, Y or Z +rx.setPattern("[A-C]\\d{5}[W-Z]"); +v.setRegExp(rx); +s = "a12345Z"; v.validate(s, pos); // Returns Invalid +s = "A12345Z"; v.validate(s, pos); // Returns Acceptable +s = "B12"; v.validate(s, pos); // Returns Intermediate + +// match most 'readme' files +rx.setPattern("read\\S?me(\.(txt|asc|1st))?"); +rx.setCaseSensitive(false); +v.setRegExp(rx); +s = "readme"; v.validate(s, pos); // Returns Acceptable +s = "README.1ST"; v.validate(s, pos); // Returns Acceptable +s = "read me.txt"; v.validate(s, pos); // Returns Invalid +s = "readm"; v.validate(s, pos); // Returns Intermediate +//! [4] diff --git a/doc/src/snippets/code/src_gui_widgets_qworkspace.cpp b/doc/src/snippets/code/src_gui_widgets_qworkspace.cpp new file mode 100644 index 0000000000..fd1a43bf13 --- /dev/null +++ b/doc/src/snippets/code/src_gui_widgets_qworkspace.cpp @@ -0,0 +1,48 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +MainWindow::MainWindow() +{ + workspace = new QWorkspace; + setCentralWidget(workspace); + ... +} +//! [0] diff --git a/doc/src/snippets/code/src_network_access_qftp.cpp b/doc/src/snippets/code/src_network_access_qftp.cpp new file mode 100644 index 0000000000..621d10de0b --- /dev/null +++ b/doc/src/snippets/code/src_network_access_qftp.cpp @@ -0,0 +1,99 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QFtp *ftp = new QFtp(parent); +ftp->connectToHost("ftp.qt.nokia.com"); +ftp->login(); +//! [0] + + +//! [1] +ftp->connectToHost("ftp.qt.nokia.com"); // id == 1 +ftp->login(); // id == 2 +ftp->cd("qt"); // id == 3 +ftp->get("INSTALL"); // id == 4 +ftp->close(); // id == 5 +//! [1] + + +//! [2] +start(1) +stateChanged(HostLookup) +stateChanged(Connecting) +stateChanged(Connected) +finished(1, false) + +start(2) +stateChanged(LoggedIn) +finished(2, false) + +start(3) +finished(3, false) + +start(4) +dataTransferProgress(0, 3798) +dataTransferProgress(2896, 3798) +readyRead() +dataTransferProgress(3798, 3798) +readyRead() +finished(4, false) + +start(5) +stateChanged(Closing) +stateChanged(Unconnected) +finished(5, false) + +done(false) +//! [2] + + +//! [3] +start(1) +stateChanged(HostLookup) +stateChanged(Connecting) +stateChanged(Connected) +finished(1, false) + +start(2) +finished(2, true) + +done(true) +//! [3] diff --git a/doc/src/snippets/code/src_network_access_qhttp.cpp b/doc/src/snippets/code/src_network_access_qhttp.cpp new file mode 100644 index 0000000000..374f1f2121 --- /dev/null +++ b/doc/src/snippets/code/src_network_access_qhttp.cpp @@ -0,0 +1,125 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +content-type: text/html +//! [0] + + +//! [1] +header.setValue("content-type", "text/html"); +QString contentType = header.value("content-type"); +//! [1] + + +//! [2] +QHttpRequestHeader header("GET", QUrl::toPercentEncoding("/index.html")); +header.setValue("Host", "qt.nokia.com"); +http->setHost("qt.nokia.com"); +http->request(header); +//! [2] + + +//! [3] +http->setHost("qt.nokia.com"); // id == 1 +http->get(QUrl::toPercentEncoding("/index.html")); // id == 2 +//! [3] + + +//! [4] +requestStarted(1) +requestFinished(1, false) + +requestStarted(2) +stateChanged(Connecting) +stateChanged(Sending) +dataSendProgress(77, 77) +stateChanged(Reading) +responseHeaderReceived(responseheader) +dataReadProgress(5388, 0) +readyRead(responseheader) +dataReadProgress(18300, 0) +readyRead(responseheader) +stateChanged(Connected) +requestFinished(2, false) + +done(false) + +stateChanged(Closing) +stateChanged(Unconnected) +//! [4] + + +//! [5] +http->setHost("www.foo.bar"); // id == 1 +http->get("/index.html"); // id == 2 +http->post("register.html", data); // id == 3 +//! [5] + + +//! [6] +requestStarted(1) +requestFinished(1, false) + +requestStarted(2) +stateChanged(HostLookup) +requestFinished(2, true) + +done(true) + +stateChanged(Unconnected) +//! [6] + + +//! [7] +void Ticker::getTicks() +{ + http = new QHttp(this); + connect(http, SIGNAL(done(bool)), this, SLOT(showPage())); + http->setProxy("proxy.example.com", 3128); + http->setHost("ticker.example.com"); + http->get("/ticks.asp"); +} + +void Ticker::showPage() +{ + display(http->readAll()); +} +//! [7] diff --git a/doc/src/snippets/code/src_network_access_qhttpmultipart.cpp b/doc/src/snippets/code/src_network_access_qhttpmultipart.cpp new file mode 100644 index 0000000000..9ad2222434 --- /dev/null +++ b/doc/src/snippets/code/src_network_access_qhttpmultipart.cpp @@ -0,0 +1,67 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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$ +** +****************************************************************************/ + +//! [0] +QHttpMultiPart *multiPart = new QHttpMultiPart(QHttpMultiPart::FormDataType); + +QHttpPart textPart; +textPart.setHeader(QNetworkRequest::ContentDispositionHeader, QVariant("form-data; name=\"text\"")); +textPart.setBody("my text"); + +QHttpPart imagePart; +imagePart.setHeader(QNetworkRequest::ContentTypeHeader, QVariant("image/jpeg")); +imagePart.setHeader(QNetworkRequest::ContentDispositionHeader, QVariant("form-data; name=\"image\"")); +QFile *file = new QFile("image.jpg"); +file->open(QIODevice::ReadOnly); +imagePart.setBodyDevice(file); +file->setParent(multiPart); // we cannot delete the file now, so delete it with the multiPart + +multiPart->append(textPart); +multiPart->append(imagePart); + +QUrl url("http://my.server.tld"); +QNetworkRequest request(url); + +QNetworkAccessManager manager; +QNetworkReply *reply = manager.post(request, multiPart); +multiPart->setParent(reply); // delete the multiPart with the reply +// here connect signals etc. +//! [0] diff --git a/doc/src/snippets/code/src_network_access_qhttppart.cpp b/doc/src/snippets/code/src_network_access_qhttppart.cpp new file mode 100644 index 0000000000..0e2dbea43b --- /dev/null +++ b/doc/src/snippets/code/src_network_access_qhttppart.cpp @@ -0,0 +1,65 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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$ +** +****************************************************************************/ + +//! [0] +Content-Type: text/plain +Content-Disposition: form-data; name="text" + +here goes the body +//! [0] + +//! [1] +QHttpPart textPart; +textPart.setHeader(QNetworkRequest::ContentTypeHeader, QVariant("text/plain")); +textPart.setHeader(QNetworkRequest::ContentDispositionHeader, QVariant("form-data; name=\"text\"")); +textPart.setBody("here goes the body"); +//! [1] + +//! [2] +QHttpPart imagePart; +imagePart.setHeader(QNetworkRequest::ContentTypeHeader, QVariant("image/jpeg")); +imagePart.setHeader(QNetworkRequest::ContentDispositionHeader, QVariant("form-data; name=\"image\"")); +imagePart.setRawHeader("Content-ID", "my@content.id"); // add any headers you like via setRawHeader() +QFile *file = new QFile("image.jpg"); +file->open(QIODevice::ReadOnly); +imagePart.setBodyDevice(file); +//! [2] + diff --git a/doc/src/snippets/code/src_network_access_qnetworkaccessmanager.cpp b/doc/src/snippets/code/src_network_access_qnetworkaccessmanager.cpp new file mode 100644 index 0000000000..327d58f226 --- /dev/null +++ b/doc/src/snippets/code/src_network_access_qnetworkaccessmanager.cpp @@ -0,0 +1,79 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QNetworkAccessManager *manager = new QNetworkAccessManager(this); +connect(manager, SIGNAL(finished(QNetworkReply*)), + this, SLOT(replyFinished(QNetworkReply*))); + +manager->get(QNetworkRequest(QUrl("http://qt.nokia.com"))); +//! [0] + + +//! [1] +QNetworkRequest request; +request.setUrl(QUrl("http://qt.nokia.com")); +request.setRawHeader("User-Agent", "MyOwnBrowser 1.0"); + +QNetworkReply *reply = manager->get(request); +connect(reply, SIGNAL(readyRead()), this, SLOT(slotReadyRead())); +connect(reply, SIGNAL(error(QNetworkReply::NetworkError)), + this, SLOT(slotError(QNetworkReply::NetworkError))); +connect(reply, SIGNAL(sslErrors(QList<QSslError>)), + this, SLOT(slotSslErrors(QList<QSslError>))); +//! [1] + +//! [2] +QNetworkConfigurationManager manager; +networkAccessManager->setConfiguration(manager.defaultConfiguration()); +//! [2] + +//! [3] +networkAccessManager->setConfiguration(QNetworkConfiguration()); +//! [3] + +//! [4] +networkAccessManager->setNetworkAccessible(QNetworkAccessManager::NotAccessible); +//! [4] + +//! [5] +networkAccessManager->setNetworkAccessible(QNetworkAccessManager::Accessible); +//! [5] + diff --git a/doc/src/snippets/code/src_network_access_qnetworkdiskcache.cpp b/doc/src/snippets/code/src_network_access_qnetworkdiskcache.cpp new file mode 100644 index 0000000000..8d775bb20e --- /dev/null +++ b/doc/src/snippets/code/src_network_access_qnetworkdiskcache.cpp @@ -0,0 +1,64 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QNetworkAccessManager *manager = new QNetworkAccessManager(this); +QNetworkDiskCache *diskCache = new QNetworkDiskCache(this); +diskCache->setCacheDirectory("cacheDir"); +manager->setCache(diskCache); +//! [0] + +//! [1] +// do a normal request (preferred from network, as this is the default) +QNetworkRequest request(QUrl(QString("http://qt.nokia.com"))); +manager->get(request); + +// do a request preferred from cache +QNetworkRequest request2(QUrl(QString("http://qt.nokia.com"))); +request2.setAttribute(QNetworkRequest::CacheLoadControlAttribute, QNetworkRequest::PreferCache); +manager->get(request2); +//! [1] + +//! [2] +void replyFinished(QNetworkReply *reply) { + QVariant fromCache = reply->attribute(QNetworkRequest::SourceIsFromCacheAttribute); + qDebug() << "page from cache?" << fromCache.toBool(); +} +//! [2] diff --git a/doc/src/snippets/code/src_network_access_qnetworkreply.cpp b/doc/src/snippets/code/src_network_access_qnetworkreply.cpp new file mode 100644 index 0000000000..01f66bc63c --- /dev/null +++ b/doc/src/snippets/code/src_network_access_qnetworkreply.cpp @@ -0,0 +1,50 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QList<QSslCertificate> cert = QSslCertificate::fromPath(QLatin1String("server-certificate.pem")); +QSslError error(QSslError::SelfSignedCertificate, cert.at(0)); +QList<QSslError> expectedSslErrors; +expectedSslErrors.append(error); + +QNetworkReply *reply = manager.get(QNetworkRequest(QUrl("https://server.tld/index.html"))); +reply->ignoreSslErrors(expectedSslErrors); +// here connect signals etc. +//! [0] diff --git a/doc/src/snippets/code/src_network_access_qnetworkrequest.cpp b/doc/src/snippets/code/src_network_access_qnetworkrequest.cpp new file mode 100644 index 0000000000..685eb0c3bc --- /dev/null +++ b/doc/src/snippets/code/src_network_access_qnetworkrequest.cpp @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +request.setRawHeader("Last-Modified", "Sun, 06 Nov 1994 08:49:37 GMT"); +//! [0] diff --git a/doc/src/snippets/code/src_network_bearer_qnetworkconfigmanager.cpp b/doc/src/snippets/code/src_network_bearer_qnetworkconfigmanager.cpp new file mode 100644 index 0000000000..af1a3e84df --- /dev/null +++ b/doc/src/snippets/code/src_network_bearer_qnetworkconfigmanager.cpp @@ -0,0 +1,48 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QNetworkConfigurationManager mgr; +QList<QNetworkConfiguration> activeConfigs = mgr.allConfigurations(QNetworkConfiguration::Active) +if (activeConfigs.count() > 0) + Q_ASSERT(mgr.isOnline()) +else + Q_ASSERT(!mgr.isOnline()) +//! [0] diff --git a/doc/src/snippets/code/src_network_kernel_qhostaddress.cpp b/doc/src/snippets/code/src_network_kernel_qhostaddress.cpp new file mode 100644 index 0000000000..bd203862c9 --- /dev/null +++ b/doc/src/snippets/code/src_network_kernel_qhostaddress.cpp @@ -0,0 +1,48 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +Q_IPV6ADDR addr = hostAddr.toIPv6Address(); +// addr contains 16 unsigned characters + +for (int i = 0; i < 16; ++i) { + // process addr[i] +} +//! [0] diff --git a/doc/src/snippets/code/src_network_kernel_qhostinfo.cpp b/doc/src/snippets/code/src_network_kernel_qhostinfo.cpp new file mode 100644 index 0000000000..97d58ef32c --- /dev/null +++ b/doc/src/snippets/code/src_network_kernel_qhostinfo.cpp @@ -0,0 +1,90 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +// To find the IP address of qt.nokia.com +QHostInfo::lookupHost("qt.nokia.com", + this, SLOT(printResults(QHostInfo))); + +// To find the host name for 4.2.2.1 +QHostInfo::lookupHost("4.2.2.1", + this, SLOT(printResults(QHostInfo))); +//! [0] + + +//! [1] +QHostInfo info = QHostInfo::fromName("qt.nokia.com"); +//! [1] + + +//! [2] +QHostInfo::lookupHost("www.kde.org", + this, SLOT(lookedUp(QHostInfo))); +//! [2] + + +//! [3] +void MyWidget::lookedUp(const QHostInfo &host) +{ + if (host.error() != QHostInfo::NoError) { + qDebug() << "Lookup failed:" << host.errorString(); + return; + } + + foreach (const QHostAddress &address, host.addresses()) + qDebug() << "Found address:" << address.toString(); +} +//! [3] + + +//! [4] +QHostInfo::lookupHost("4.2.2.1", + this, SLOT(lookedUp(QHostInfo))); +//! [4] + + +//! [5] +QHostInfo info; +... +if (!info.addresses().isEmpty()) { + QHostAddress address = info.addresses().first(); + // use the first IP address +} +//! [5] diff --git a/doc/src/snippets/code/src_network_kernel_qnetworkproxy.cpp b/doc/src/snippets/code/src_network_kernel_qnetworkproxy.cpp new file mode 100644 index 0000000000..393674c6f1 --- /dev/null +++ b/doc/src/snippets/code/src_network_kernel_qnetworkproxy.cpp @@ -0,0 +1,54 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QNetworkProxy proxy; +proxy.setType(QNetworkProxy::Socks5Proxy); +proxy.setHostName("proxy.example.com"); +proxy.setPort(1080); +proxy.setUser("username"); +proxy.setPassword("password"); +QNetworkProxy::setApplicationProxy(proxy); +//! [0] + + +//! [1] +serverSocket->setProxy(QNetworkProxy::NoProxy); +//! [1] diff --git a/doc/src/snippets/code/src_network_socket_qabstractsocket.cpp b/doc/src/snippets/code/src_network_socket_qabstractsocket.cpp new file mode 100644 index 0000000000..8021b80733 --- /dev/null +++ b/doc/src/snippets/code/src_network_socket_qabstractsocket.cpp @@ -0,0 +1,70 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +socket->connectToHost("imap", 143); +if (socket->waitForConnected(1000)) + qDebug("Connected!"); +//! [0] + + +//! [1] +socket->disconnectFromHost(); + if (socket->state() == QAbstractSocket::UnconnectedState || + socket->waitForDisconnected(1000)) + qDebug("Disconnected!"); +//! [1] + + +//! [2] + // This slot is connected to QAbstractSocket::readyRead() + void SocketClass::readyReadSlot() + { + while (!socket.atEnd()) { + QByteArray data = socket.read(100); + .... + } + } +//! [2] + + +//! [3] +socket->setProxy(QNetworkProxy::NoProxy); +//! [3] diff --git a/doc/src/snippets/code/src_network_socket_qlocalsocket_unix.cpp b/doc/src/snippets/code/src_network_socket_qlocalsocket_unix.cpp new file mode 100644 index 0000000000..9a6e5c2830 --- /dev/null +++ b/doc/src/snippets/code/src_network_socket_qlocalsocket_unix.cpp @@ -0,0 +1,52 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +socket->connectToServer("market"); +if (socket->waitForConnected(1000)) + qDebug("Connected!"); +//! [0] + + +//! [1] +socket->disconnectFromServer(); +if (socket->waitForDisconnected(1000)) + qDebug("Disconnected!"); +//! [1] diff --git a/doc/src/snippets/code/src_network_socket_qnativesocketengine.cpp b/doc/src/snippets/code/src_network_socket_qnativesocketengine.cpp new file mode 100644 index 0000000000..85cf4d7a62 --- /dev/null +++ b/doc/src/snippets/code/src_network_socket_qnativesocketengine.cpp @@ -0,0 +1,61 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QNativeSocketEngine socketLayer; +socketLayer.initialize(QAbstractSocket::TcpSocket, QAbstractSocket::IPv4Protocol); +socketLayer.connectToHost(QHostAddress::LocalHost, 22); +// returns false + +socketLayer.waitForWrite(); +socketLayer.connectToHost(QHostAddress::LocalHost, 22); +// returns true +//! [0] + + +//! [1] +QNativeSocketEngine socketLayer; +socketLayer.bind(QHostAddress::Any, 4000); +socketLayer.listen(); +if (socketLayer.waitForRead()) { + int clientSocket = socketLayer.accept(); + // a client is connected +} +//! [1] diff --git a/doc/src/snippets/code/src_network_socket_qtcpserver.cpp b/doc/src/snippets/code/src_network_socket_qtcpserver.cpp new file mode 100644 index 0000000000..6dca8b6054 --- /dev/null +++ b/doc/src/snippets/code/src_network_socket_qtcpserver.cpp @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +server->setProxy(QNetworkProxy::NoProxy); +//! [0] diff --git a/doc/src/snippets/code/src_network_socket_qudpsocket.cpp b/doc/src/snippets/code/src_network_socket_qudpsocket.cpp new file mode 100644 index 0000000000..47f00b6b45 --- /dev/null +++ b/doc/src/snippets/code/src_network_socket_qudpsocket.cpp @@ -0,0 +1,65 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +void Server::initSocket() +{ + udpSocket = new QUdpSocket(this); + udpSocket->bind(QHostAddress::LocalHost, 7755); + + connect(udpSocket, SIGNAL(readyRead()), + this, SLOT(readPendingDatagrams())); +} + +void Server::readPendingDatagrams() +{ + while (udpSocket->hasPendingDatagrams()) { + QByteArray datagram; + datagram.resize(udpSocket->pendingDatagramSize()); + QHostAddress sender; + quint16 senderPort; + + udpSocket->readDatagram(datagram.data(), datagram.size(), + &sender, &senderPort); + + processTheDatagram(datagram); + } +} +//! [0] diff --git a/doc/src/snippets/code/src_network_ssl_qsslcertificate.cpp b/doc/src/snippets/code/src_network_ssl_qsslcertificate.cpp new file mode 100644 index 0000000000..679f41e1b4 --- /dev/null +++ b/doc/src/snippets/code/src_network_ssl_qsslcertificate.cpp @@ -0,0 +1,46 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +foreach (const QSslCertificate &cert, QSslCertificate::fromPath("C:/ssl/certificate.*.pem", QSsl::Pem, + QRegExp::Wildcard)) { + qDebug() << cert.issuerInfo(QSslCertificate::Organization); +} +//! [0] diff --git a/doc/src/snippets/code/src_network_ssl_qsslconfiguration.cpp b/doc/src/snippets/code/src_network_ssl_qsslconfiguration.cpp new file mode 100644 index 0000000000..7e078d3607 --- /dev/null +++ b/doc/src/snippets/code/src_network_ssl_qsslconfiguration.cpp @@ -0,0 +1,45 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QSslConfiguration config = sslSocket.sslConfiguration(); +config.setProtocol(QSsl::TlsV1); +sslSocket.setSslConfiguration(config); +//! [0] diff --git a/doc/src/snippets/code/src_network_ssl_qsslsocket.cpp b/doc/src/snippets/code/src_network_ssl_qsslsocket.cpp new file mode 100644 index 0000000000..d415bae034 --- /dev/null +++ b/doc/src/snippets/code/src_network_ssl_qsslsocket.cpp @@ -0,0 +1,107 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QSslSocket *socket = new QSslSocket(this); +connect(socket, SIGNAL(encrypted()), this, SLOT(ready())); + +socket->connectToHostEncrypted("imap.example.com", 993); +//! [0] + + +//! [1] +void SslServer::incomingConnection(int socketDescriptor) +{ + QSslSocket *serverSocket = new QSslSocket; + if (serverSocket->setSocketDescriptor(socketDescriptor)) { + connect(serverSocket, SIGNAL(encrypted()), this, SLOT(ready())); + serverSocket->startServerEncryption(); + } else { + delete serverSocket; + } +} +//! [1] + + +//! [2] +QSslSocket socket; +socket.connectToHostEncrypted("http.example.com", 443); +if (!socket.waitForEncrypted()) { + qDebug() << socket.errorString(); + return false; +} + +socket.write("GET / HTTP/1.0\r\n\r\n"); +while (socket.waitForReadyRead()) + qDebug() << socket.readAll().data(); +//! [2] + + +//! [3] +QSslSocket socket; +connect(&socket, SIGNAL(encrypted()), receiver, SLOT(socketEncrypted())); + +socket.connectToHostEncrypted("imap", 993); +socket->write("1 CAPABILITY\r\n"); +//! [3] + + +//! [4] +QSslSocket socket; +socket.setCiphers("DHE-RSA-AES256-SHA:DHE-DSS-AES256-SHA:AES256-SHA"); +//! [4] + + +//! [5] +socket->connectToHostEncrypted("imap", 993); +if (socket->waitForEncrypted(1000)) + qDebug("Encrypted!"); +//! [5] + +//! [6] +QList<QSslCertificate> cert = QSslCertificate::fromPath(QLatin1String("server-certificate.pem")); +QSslError error(QSslError::SelfSignedCertificate, cert.at(0)); +QList<QSslError> expectedSslErrors; +expectedSslErrors.append(error); + +QSslSocket socket; +socket.ignoreSslErrors(expectedSslErrors); +socket.connectToHostEncrypted("server.tld", 443); +//! [6] diff --git a/doc/src/snippets/code/src_opengl_qgl.cpp b/doc/src/snippets/code/src_opengl_qgl.cpp new file mode 100644 index 0000000000..6ef049ac90 --- /dev/null +++ b/doc/src/snippets/code/src_opengl_qgl.cpp @@ -0,0 +1,172 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QGLFormat fmt; +fmt.setAlpha(true); +fmt.setStereo(true); +QGLFormat::setDefaultFormat(fmt); +//! [0] + + +//! [1] +QGLFormat fmt; +fmt.setDoubleBuffer(false); // single buffer +fmt.setDirectRendering(false); // software rendering +MyGLWidget* myWidget = new MyGLWidget(fmt, ...); +//! [1] + + +//! [2] +QGLFormat fmt; +fmt.setOverlay(true); +fmt.setStereo(true); +MyGLWidget* myWidget = new MyGLWidget(fmt, ...); +if (!myWidget->format().stereo()) { + // ok, goggles off + if (!myWidget->format().hasOverlay()) { + qFatal("Cool hardware required"); + } +} +//! [2] + + +//! [3] +// The rendering in MyGLWidget depends on using +// stencil buffer and alpha channel +MyGLWidget::MyGLWidget(QWidget* parent) + : QGLWidget(QGLFormat(QGL::StencilBuffer | QGL::AlphaChannel), parent) +{ + if (!format().stencil()) + qWarning("Could not get stencil buffer; results will be suboptimal"); + if (!format().alpha()) + qWarning("Could not get alpha channel; results will be suboptimal"); + ... +} +//! [3] + + +//! [4] +QApplication a(argc, argv); +QGLFormat f; +f.setDoubleBuffer(false); +QGLFormat::setDefaultFormat(f); +//! [4] + + +//! [5] +QGLFormat f = QGLFormat::defaultOverlayFormat(); +f.setDoubleBuffer(true); +QGLFormat::setDefaultOverlayFormat(f); +//! [5] + + +//! [6] +// ...continued from above +MyGLWidget* myWidget = new MyGLWidget(QGLFormat(QGL::HasOverlay), ...); +if (myWidget->format().hasOverlay()) { + // Yes, we got an overlay, let's check _its_ format: + QGLContext* olContext = myWidget->overlayContext(); + if (olContext->format().doubleBuffer()) + ; // yes, we got a double buffered overlay + else + ; // no, only single buffered overlays are available +} +//! [6] + + +//! [7] +QGLContext *cx; +// ... +QGLFormat f; +f.setStereo(true); +cx->setFormat(f); +if (!cx->create()) + exit(); // no OpenGL support, or cannot render on the specified paintdevice +if (!cx->format().stereo()) + exit(); // could not create stereo context +//! [7] + + +//! [8] +class MyGLDrawer : public QGLWidget +{ + Q_OBJECT // must include this if you use Qt signals/slots + +public: + MyGLDrawer(QWidget *parent) + : QGLWidget(parent) {} + +protected: + + void initializeGL() + { + // Set up the rendering context, define display lists etc.: + ... + glClearColor(0.0, 0.0, 0.0, 0.0); + glEnable(GL_DEPTH_TEST); + ... + } + + void resizeGL(int w, int h) + { + // setup viewport, projection etc.: + glViewport(0, 0, (GLint)w, (GLint)h); + ... + glFrustum(...); + ... + } + + void paintGL() + { + // draw the scene: + ... + glRotatef(...); + glMaterialfv(...); + glBegin(GL_QUADS); + glVertex3f(...); + glVertex3f(...); + ... + glEnd(); + ... + } + +}; +//! [8] diff --git a/doc/src/snippets/code/src_opengl_qglcolormap.cpp b/doc/src/snippets/code/src_opengl_qglcolormap.cpp new file mode 100644 index 0000000000..3bd780ba45 --- /dev/null +++ b/doc/src/snippets/code/src_opengl_qglcolormap.cpp @@ -0,0 +1,61 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +#include <QApplication> +#include <QGLColormap> + +int main() +{ + QApplication app(argc, argv); + + MySuperGLWidget widget; // a QGLWidget in color-index mode + QGLColormap colormap; + + // This will fill the colormap with colors ranging from + // black to white. + for (int i = 0; i < colormap.size(); i++) + colormap.setEntry(i, qRgb(i, i, i)); + + widget.setColormap(colormap); + widget.show(); + return app.exec(); +} +//! [0] diff --git a/doc/src/snippets/code/src_opengl_qglpixelbuffer.cpp b/doc/src/snippets/code/src_opengl_qglpixelbuffer.cpp new file mode 100644 index 0000000000..6825ebfab8 --- /dev/null +++ b/doc/src/snippets/code/src_opengl_qglpixelbuffer.cpp @@ -0,0 +1,59 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QGLPixelBuffer pbuffer(...); +... +pbuffer.makeCurrent(); +GLuint dynamicTexture = pbuffer.generateDynamicTexture(); +pbuffer.bindToDynamicTexture(dynamicTexture); +... +pbuffer.releaseFromDynamicTexture(); +//! [0] + + +//! [1] +QGLPixelBuffer pbuffer(...); +... +pbuffer.makeCurrent(); +GLuint dynamicTexture = pbuffer.generateDynamicTexture(); +... +pbuffer.updateDynamicTexture(dynamicTexture); +//! [1] diff --git a/doc/src/snippets/code/src_opengl_qglshaderprogram.cpp b/doc/src/snippets/code/src_opengl_qglshaderprogram.cpp new file mode 100644 index 0000000000..aa5225a5e8 --- /dev/null +++ b/doc/src/snippets/code/src_opengl_qglshaderprogram.cpp @@ -0,0 +1,94 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QGLShader shader(QGLShader::Vertex); +shader.compileSourceCode(code); + +QGLShaderProgram program(context); +program.addShader(shader); +program.link(); + +program.bind(); +//! [0] + +//! [1] +program.addShaderFromSourceCode(QGLShader::Vertex, + "attribute highp vec4 vertex;\n" + "attribute mediump mat4 matrix;\n" + "void main(void)\n" + "{\n" + " gl_Position = matrix * vertex;\n" + "}"); +program.addShaderFromSourceCode(QGLShader::Fragment, + "uniform mediump vec4 color;\n" + "void main(void)\n" + "{\n" + " gl_FragColor = color;\n" + "}"); +program.link(); +program.bind(); + +int vertexLocation = program.attributeLocation("vertex"); +int matrixLocation = program.attributeLocation("matrix"); +int colorLocation = program.uniformLocation("color"); +//! [1] + +//! [2] +static GLfloat const triangleVertices[] = { + 60.0f, 10.0f, 0.0f, + 110.0f, 110.0f, 0.0f, + 10.0f, 110.0f, 0.0f +}; + +QColor color(0, 255, 0, 255); + +QMatrix4x4 pmvMatrix; +pmvMatrix.ortho(rect()); + +program.enableAttributeArray(vertexLocation); +program.setAttributeArray(vertexLocation, triangleVertices, 3); +program.setUniformValue(matrixLocation, pmvMatrix); +program.setUniformValue(colorLocation, color); + +glDrawArrays(GL_TRIANGLES, 0, 3); + +program.disableAttributeArray(vertexLocation); +//! [2] diff --git a/doc/src/snippets/code/src_qdbus_qdbusabstractinterface.cpp b/doc/src/snippets/code/src_qdbus_qdbusabstractinterface.cpp new file mode 100644 index 0000000000..ba1b902a7a --- /dev/null +++ b/doc/src/snippets/code/src_qdbus_qdbusabstractinterface.cpp @@ -0,0 +1,60 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QString value = retrieveValue(); +QDBusMessage reply; + +QDBusReply<int> api = interface->call(QLatin1String("GetAPIVersion")); +if (api >= 14) + reply = interface->call(QLatin1String("ProcessWorkUnicode"), value); +else + reply = interface->call(QLatin1String("ProcessWork"), QLatin1String("UTF-8"), value.toUtf8()); +//! [0] + +//! [1] +QString value = retrieveValue(); +QDBusPendingCall pcall = interface->asyncCall(QLatin1String("Process"), value); + +QDBusPendingCallWatcher *watcher = new QDBusPendingCallWatcher(pcall, this); + +QObject::connect(watcher, SIGNAL(finished(QDBusPendingCallWatcher*)), + this, SLOT(callFinishedSlot(QDBusPendingCallWatcher*))); +//! [1] diff --git a/doc/src/snippets/code/src_qdbus_qdbusargument.cpp b/doc/src/snippets/code/src_qdbus_qdbusargument.cpp new file mode 100644 index 0000000000..125dc332a9 --- /dev/null +++ b/doc/src/snippets/code/src_qdbus_qdbusargument.cpp @@ -0,0 +1,191 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +struct MyStructure +{ + int count; + QString name; +}; +Q_DECLARE_METATYPE(MyStructure) + +// Marshall the MyStructure data into a D-Bus argument +QDBusArgument &operator<<(QDBusArgument &argument, const MyStructure &mystruct) +{ + argument.beginStructure(); + argument << mystruct.count << mystruct.name; + argument.endStructure(); + return argument; +} + +// Retrieve the MyStructure data from the D-Bus argument +const QDBusArgument &operator>>(const QDBusArgument &argument, MyStructure &mystruct) +{ + argument.beginStructure(); + argument >> mystruct.count >> mystruct.name; + argument.endStructure(); + return argument; +} +//! [0] + + +//! [1] +qDBusRegisterMetaType<MyStructure>(); +//! [1] + + +//! [2] +MyType item = qdbus_cast<Type>(argument); +//! [2] + + +//! [3] +MyType item; +argument >> item; +//! [3] + + +//! [4] +QDBusArgument &operator<<(QDBusArgument &argument, const MyStructure &mystruct) +{ + argument.beginStructure(); + argument << mystruct.member1 << mystruct.member2 << ... ; + argument.endStructure(); + return argument; +} +//! [4] + + +//! [5] +QDBusArgument &operator<<(QDBusArgument &argument, const MyStructure &mystruct) +{ + argument.beginStructure(); + argument << mystruct.member1 << mystruct.member2; + + argument.beginStructure(); + argument << mystruct.member3.subMember1 << mystruct.member3.subMember2; + argument.endStructure(); + + argument << mystruct.member4; + argument.endStructure(); + return argument; +} +//! [5] + + +//! [6] +// append an array of MyElement types +QDBusArgument &operator<<(QDBusArgument &argument, const MyArray &myarray) +{ + argument.beginArray( qMetaTypeId<MyElement>() ); + for ( int i = 0; i < myarray.length; ++i ) + argument << myarray.elements[i]; + argument.endArray(); + return argument; +} +//! [6] + + +//! [7] +// append a dictionary that associates ints to MyValue types +QDBusArgument &operator<<(QDBusArgument &argument, const MyDictionary &mydict) +{ + argument.beginMap( QVariant::Int, qMetaTypeId<MyValue>() ); + for ( int i = 0; i < mydict.length; ++i ) { + argument.beginMapEntry(); + argument << mydict.data[i].key << mydict.data[i].value; + argument.endMapEntry(); + } + argument.endMap(); + return argument; +} +//! [7] + + +//! [8] +const QDBusArgument &operator>>(const QDBusArgument &argument, MyStructure &mystruct) +{ + argument.beginStructure() + argument >> mystruct.member1 >> mystruct.member2 >> mystruct.member3 >> ...; + argument.endStructure(); + return argument; +} +//! [8] + + +//! [9] +// extract a MyArray array of MyElement elements +const QDBusArgument &operator>>(const QDBusArgument &argument, MyArray &myarray) +{ + argument.beginArray(); + myarray.clear(); + + while ( !argument.atEnd() ) { + MyElement element; + argument >> element; + myarray.append( element ); + } + + argument.endArray(); + return argument; +} +//! [9] + + +//! [10] +// extract a MyDictionary map that associates ints to MyValue elements +const QDBusArgument &operator>>(const QDBusArgument &argument, MyDictionary &mydict) +{ + argument.beginMap(); + mydict.clear(); + + while ( !argMap.atEnd() ) { + int key; + MyValue value; + argument.beginMapEntry(); + argument >> key >> value; + argument.endMapEntry(); + mydict.append( key, value ); + } + + argument.endMap(); + return argument; +} +//! [10] diff --git a/doc/src/snippets/code/src_qdbus_qdbuscontext.cpp b/doc/src/snippets/code/src_qdbus_qdbuscontext.cpp new file mode 100644 index 0000000000..312b8bb545 --- /dev/null +++ b/doc/src/snippets/code/src_qdbus_qdbuscontext.cpp @@ -0,0 +1,72 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +class MyObject: public QObject, + protected QDBusContext +{ + Q_OBJECT + QDBusConnection conn; + QDBusMessage msg; + +... + +protected slots: + void process(); +public slots: + void methodWithError(); + QString methodWithDelayedReply(); +}; + +void MyObject::methodWithError() +{ + sendErrorReply(QDBusError::NotSupported, + "The method call 'methodWithError()' is not supported"); +} + +QString MyObject::methodWithDelayedReply() +{ + conn = connection(); + msg = message(); + setDelayedReply(true); + QMetaObject::invokeMethod(this, "process", Qt::QueuedConnection); + return QString(); +} +//! [0] diff --git a/doc/src/snippets/code/src_qdbus_qdbusinterface.cpp b/doc/src/snippets/code/src_qdbus_qdbusinterface.cpp new file mode 100644 index 0000000000..425a736d28 --- /dev/null +++ b/doc/src/snippets/code/src_qdbus_qdbusinterface.cpp @@ -0,0 +1,51 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QDBusInterface remoteApp( "com.example.Calculator", "/Calculator/Operations", + "org.mathematics.RPNCalculator" ); +remoteApp.call( "PushOperand", 2 ); +remoteApp.call( "PushOperand", 2 ); +remoteApp.call( "ExecuteOperation", "+" ); +QDBusReply<int> reply = remoteApp.call( "PopOperand" ); + +if ( reply.isValid() ) + printf( "%d", reply.value() ); // prints 4 +//! [0] diff --git a/doc/src/snippets/code/src_qdbus_qdbusmetatype.cpp b/doc/src/snippets/code/src_qdbus_qdbusmetatype.cpp new file mode 100644 index 0000000000..3774c10643 --- /dev/null +++ b/doc/src/snippets/code/src_qdbus_qdbusmetatype.cpp @@ -0,0 +1,44 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +#include <QDBusMetaType> +qDBusRegisterMetaType<MyClass>(); +//! [0] diff --git a/doc/src/snippets/code/src_qdbus_qdbusreply.cpp b/doc/src/snippets/code/src_qdbus_qdbusreply.cpp new file mode 100644 index 0000000000..2e6b33a6bd --- /dev/null +++ b/doc/src/snippets/code/src_qdbus_qdbusreply.cpp @@ -0,0 +1,54 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QDBusReply<QString> reply = interface->call("RemoteMethod"); +if (reply.isValid()) + // use the returned value + useValue(reply.value()); +else + // call failed. Show an error condition. + showError(reply.error()); +//! [0] + + +//! [1] +QString reply = interface->call("RemoteMethod"); +//! [1] diff --git a/doc/src/snippets/code/src_qtestlib_qtestcase.cpp b/doc/src/snippets/code/src_qtestlib_qtestcase.cpp new file mode 100644 index 0000000000..986026f089 --- /dev/null +++ b/doc/src/snippets/code/src_qtestlib_qtestcase.cpp @@ -0,0 +1,250 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + + +void wrapInFunction() +{ + +//! [0] +QVERIFY(1 + 1 == 2); +//! [0] + + +//! [1] +QVERIFY2(1 + 1 == 2, "A breach in basic arithmetic occurred."); +//! [1] + + +//! [2] +QCOMPARE(QString("hello").toUpper(), QString("HELLO")); +//! [2] + + +//! [3] +void TestQString::toInt_data() +{ + QTest::addColumn<QString>("aString"); + QTest::addColumn<int>("expected"); + + QTest::newRow("positive value") << "42" << 42; + QTest::newRow("negative value") << "-42" << -42; + QTest::newRow("zero") << "0" << 0; +} +//! [3] + + +//! [4] +void TestQString::toInt() +{ + QFETCH(QString, aString); + QFETCH(int, expected); + + QCOMPARE(aString.toInt(), expected); +} +//! [4] + + +//! [5] +if (sizeof(int) != 4) + QFAIL("This test has not been ported to this platform yet."); +//! [5] + + +//! [6] +QFETCH(QString, myString); +QCOMPARE(QString("hello").toUpper(), myString); +//! [6] + + +//! [7] +QTEST(QString("hello").toUpper(), "myString"); +//! [7] + + +//! [8] +if (!QSqlDatabase::drivers().contains("SQLITE")) + QSKIP("This test requires the SQLITE database driver", SkipAll); +//! [8] + + +//! [9] +QEXPECT_FAIL("", "Will fix in the next release", Continue); +QCOMPARE(i, 42); +QCOMPARE(j, 43); +//! [9] + + +//! [10] +QEXPECT_FAIL("data27", "Oh my, this is soooo broken", Abort); +QCOMPARE(i, 42); +//! [10] + + +//! [11] +class TestQString: public QObject { ... }; +QTEST_MAIN(TestQString) +//! [11] + + +//! [12] +#ifdef Q_WS_X11 + QTEST_MAIN(MyX11Test) +#else + // do nothing on non-X11 platforms + QTEST_NOOP_MAIN +#endif +//! [12] + + +//! [13] +QTest::keyClick(myWidget, 'a'); +//! [13] + + +//! [14] +QTest::keyClick(myWidget, Qt::Key_Escape); + +QTest::keyClick(myWidget, Qt::Key_Escape, Qt::ShiftModifier, 200); +//! [14] + + +//! [15] +QTest::keyClicks(myWidget, "hello world"); +//! [15] + + +//! [16] +namespace QTest { + template<> + char *toString(const MyPoint &point) + { + QByteArray ba = "MyPoint("; + ba += QByteArray::number(point.x()) + ", " + QByteArray::number(point.y()); + ba += ")"; + return qstrdup(ba.data()); + } +} +//! [16] + + +//! [17] +int i = 0; +while (myNetworkServerNotResponding() && i++ < 50) + QTest::qWait(250); +//! [17] + + +//! [18] +MyFirstTestObject test1; +QTest::qExec(&test1); + +MySecondTestObject test2; +QTest::qExec(&test2); +//! [18] + + +//! [19] +QDir dir; + +QTest::ignoreMessage(QtWarningMsg, "QDir::mkdir: Empty or null file name(s)"); +dir.mkdir(""); +//! [19] + + +//! [20] +void myTestFunction_data() +{ + QTest::addColumn<QString>("aString"); + QTest::newRow("just hello") << QString("hello"); + QTest::newRow("a null string") << QString(); +} +//! [20] + + +//! [21] +void myTestFunction_data() { + QTest::addColumn<int>("intval"); + QTest::addColumn<QString>("str"); + QTest::addColumn<double>("dbl"); + + QTest::newRow("row1") << 1 << "hello" << 1.5; +} +//! [21] + + +//! [22] +void MyTestClass::cleanup() +{ + if (qstrcmp(currentTestFunction(), "myDatabaseTest") == 0) { + // clean up all database connections + closeAllDatabases(); + } +} +//! [22] + + +//! [23] +QTest::qSleep(250); +//! [23] + +//! [24] +QWidget widget; +widget.show(); +QTest::qWaitForWindowShown(&widget); +//! [24] + +//! [25] +QWidget widget; + +QTest::touchEvent(&widget) + .press(0, QPoint(10, 10)); +QTest::touchEvent(&widget) + .stationary(0) + .press(1, QPoint(40, 10)); +QTest::touchEvent(&widget) + .move(0, QPoint(12, 12)) + .move(1, QPoint(45, 5)); +QTest::touchEvent(&widget) + .release(0) + .release(1); +//! [25] + +} + diff --git a/doc/src/snippets/code/src_sql_kernel_qsqldatabase.cpp b/doc/src/snippets/code/src_sql_kernel_qsqldatabase.cpp new file mode 100644 index 0000000000..50ea67c104 --- /dev/null +++ b/doc/src/snippets/code/src_sql_kernel_qsqldatabase.cpp @@ -0,0 +1,135 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +// WRONG +QSqlDatabase db = QSqlDatabase::database("sales"); +QSqlQuery query("SELECT NAME, DOB FROM EMPLOYEES", db); +QSqlDatabase::removeDatabase("sales"); // will output a warning + +// "db" is now a dangling invalid database connection, +// "query" contains an invalid result set +//! [0] + + +//! [1] +{ + QSqlDatabase db = QSqlDatabase::database("sales"); + QSqlQuery query("SELECT NAME, DOB FROM EMPLOYEES", db); +} +// Both "db" and "query" are destroyed because they are out of scope +QSqlDatabase::removeDatabase("sales"); // correct +//! [1] + + +//! [2] +QSqlDatabase::registerSqlDriver("MYDRIVER", + new QSqlDriverCreator<MyDatabaseDriver>); +QSqlDatabase db = QSqlDatabase::addDatabase("MYDRIVER"); +//! [2] + + +//! [3] +... +db = QSqlDatabase::addDatabase("QODBC"); +db.setDatabaseName("DRIVER={Microsoft Access Driver (*.mdb)};FIL={MS Access};DBQ=myaccessfile.mdb"); +if (db.open()) { + // success! +} +... +//! [3] + + +//! [4] +... +// MySQL connection +db.setConnectOptions("CLIENT_SSL=1;CLIENT_IGNORE_SPACE=1"); // use an SSL connection to the server +if (!db.open()) { + db.setConnectOptions(); // clears the connect option string + ... +} +... +// PostgreSQL connection +db.setConnectOptions("requiressl=1"); // enable PostgreSQL SSL connections +if (!db.open()) { + db.setConnectOptions(); // clear options + ... +} +... +// ODBC connection +db.setConnectOptions("SQL_ATTR_ACCESS_MODE=SQL_MODE_READ_ONLY;SQL_ATTR_TRACE=SQL_OPT_TRACE_ON"); // set ODBC options +if (!db.open()) { + db.setConnectOptions(); // don't try to set this option + ... +} +//! [4] + + +//! [5] +#include "qtdir/src/sql/drivers/psql/qsql_psql.cpp" +//! [5] + + +//! [6] +PGconn *con = PQconnectdb("host=server user=bart password=simpson dbname=springfield"); +QPSQLDriver *drv = new QPSQLDriver(con); +QSqlDatabase db = QSqlDatabase::addDatabase(drv); // becomes the new default connection +QSqlQuery query; +query.exec("SELECT NAME, ID FROM STAFF"); +... +//! [6] + + +//! [7] +unix:LIBS += -lpq +win32:LIBS += libpqdll.lib +//! [7] + + +//! [8] +QSqlDatabase db; +qDebug() << db.isValid(); // Returns false + +db = QSqlDatabase::database("sales"); +qDebug() << db.isValid(); // Returns true if "sales" connection exists + +QSqlDatabase::removeDatabase("sales"); +qDebug() << db.isValid(); // Returns false +//! [8] diff --git a/doc/src/snippets/code/src_sql_kernel_qsqldriver.cpp b/doc/src/snippets/code/src_sql_kernel_qsqldriver.cpp new file mode 100644 index 0000000000..d49b6e0e19 --- /dev/null +++ b/doc/src/snippets/code/src_sql_kernel_qsqldriver.cpp @@ -0,0 +1,64 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QSqlDatabase db = ...; +QVariant v = db.driver()->handle(); +if (v.isValid() && qstrcmp(v.typeName(), "sqlite3*")==0) { + // v.data() returns a pointer to the handle + sqlite3 *handle = *static_cast<sqlite3 **>(v.data()); + if (handle != 0) { // check that it is not NULL + ... + } +} +//! [0] + + +//! [1] +if (v.typeName() == "PGconn*") { + PGconn *handle = *static_cast<PGconn **>(v.data()); + if (handle != 0) ... +} + +if (v.typeName() == "MYSQL*") { + MYSQL *handle = *static_cast<MYSQL **>(v.data()); + if (handle != 0) ... +} +//! [1] diff --git a/doc/src/snippets/code/src_sql_kernel_qsqlerror.cpp b/doc/src/snippets/code/src_sql_kernel_qsqlerror.cpp new file mode 100644 index 0000000000..cb45abf336 --- /dev/null +++ b/doc/src/snippets/code/src_sql_kernel_qsqlerror.cpp @@ -0,0 +1,46 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QSqlQueryModel model; +model.setQuery("select * from myTable"); +if (model.lastError().isValid()) + qDebug() << model.lastError(); +//! [0] diff --git a/doc/src/snippets/code/src_sql_kernel_qsqlindex.cpp b/doc/src/snippets/code/src_sql_kernel_qsqlindex.cpp new file mode 100644 index 0000000000..bf04f2befb --- /dev/null +++ b/doc/src/snippets/code/src_sql_kernel_qsqlindex.cpp @@ -0,0 +1,48 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QStringList list = myIndex.toStringList(); +QStringList::Iterator it = list.begin(); +while(it != list.end()) { + myProcessing(*it); + ++it; +} +//! [0] diff --git a/doc/src/snippets/code/src_sql_kernel_qsqlquery.cpp b/doc/src/snippets/code/src_sql_kernel_qsqlquery.cpp new file mode 100644 index 0000000000..c739a9f499 --- /dev/null +++ b/doc/src/snippets/code/src_sql_kernel_qsqlquery.cpp @@ -0,0 +1,80 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +SELECT forename, surname FROM people; +//! [0] + + +//! [1] +QSqlQuery q("select * from employees"); +QSqlRecord rec = q.record(); + +qDebug() << "Number of columns: " << rec.count(); + +int nameCol = rec.indexOf("name"); // index of the field "name" +while (q.next()) + qDebug() << q.value(nameCol).toString(); // output all names +//! [1] + + +//! [2] +QSqlQuery q; +q.prepare("insert into myTable values (?, ?)"); + +QVariantList ints; +ints << 1 << 2 << 3 << 4; +q.addBindValue(ints); + +QVariantList names; +names << "Harald" << "Boris" << "Trond" << QVariant(QVariant::String); +q.addBindValue(names); + +if (!q.execBatch()) + qDebug() << q.lastError(); +//! [2] + + +//! [3] +1 Harald +2 Boris +3 Trond +4 NULL +//! [3] diff --git a/doc/src/snippets/code/src_sql_kernel_qsqlresult.cpp b/doc/src/snippets/code/src_sql_kernel_qsqlresult.cpp new file mode 100644 index 0000000000..96bb9fbbae --- /dev/null +++ b/doc/src/snippets/code/src_sql_kernel_qsqlresult.cpp @@ -0,0 +1,85 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QSqlQuery q; +q.prepare("insert into test (i1, i2, s) values (?, ?, ?)"); + +QVariantList col1; +QVariantList col2; +QVariantList col3; + +col1 << 1 << 3; +col2 << 2 << 4; +col3 << "hello" << "world"; + +q.bindValue(0, col1); +q.bindValue(1, col2); +q.bindValue(2, col3); + +if (!q.execBatch()) + qDebug() << q.lastError(); +//! [0] + + +//! [1] +QSqlQuery query = ... +QVariant v = query.result()->handle(); +if (v.isValid() && qstrcmp(v.typeName(), "sqlite3_stmt*")) { + // v.data() returns a pointer to the handle + sqlite3_stmt *handle = *static_cast<sqlite3_stmt **>(v.data()); + if (handle != 0) { // check that it is not NULL + ... + } +} +//! [1] + + +//! [2] +if (v.typeName() == "PGresult*") { + PGresult *handle = *static_cast<PGresult **>(v.data()); + if (handle != 0) ... +} + +if (v.typeName() == "MYSQL_STMT*") { + MYSQL_STMT *handle = *static_cast<MYSQL_STMT **>(v.data()); + if (handle != 0) ... +} +//! [2] diff --git a/doc/src/snippets/code/src_sql_models_qsqlquerymodel.cpp b/doc/src/snippets/code/src_sql_models_qsqlquerymodel.cpp new file mode 100644 index 0000000000..0d85803dc0 --- /dev/null +++ b/doc/src/snippets/code/src_sql_models_qsqlquerymodel.cpp @@ -0,0 +1,52 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +while (myModel->canFetchMore()) + myModel->fetchMore(); +//! [0] + + +//! [1] +QSqlQueryModel model; +model.setQuery("select * from MyTable"); +if (model.lastError().isValid()) + qDebug() << model.lastError(); +//! [1] diff --git a/doc/src/snippets/code/src_xml_dom_qdom.cpp b/doc/src/snippets/code/src_xml_dom_qdom.cpp new file mode 100644 index 0000000000..e49bcf40ee --- /dev/null +++ b/doc/src/snippets/code/src_xml_dom_qdom.cpp @@ -0,0 +1,218 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +QDomDocument doc; +QDomImplementation impl; + +// This will create the element, but the resulting XML document will +// be invalid, because '~' is not a valid character in a tag name. +impl.setInvalidDataPolicy(QDomImplementation::AcceptInvalidData); +QDomElement elt1 = doc.createElement("foo~bar"); + +// This will create an element with the tag name "foobar". +impl.setInvalidDataPolicy(QDomImplementation::DropInvalidData); +QDomElement elt2 = doc.createElement("foo~bar"); + +// This will create a null element. +impl.setInvalidDataPolicy(QDomImplementation::ReturnNullNode); +QDomElement elt3 = doc.createElement("foo~bar"); +//! [0] + + +//! [1] +QDomDocument d; +d.setContent(someXML); +QDomNode n = d.firstChild(); +while (!n.isNull()) { + if (n.isElement()) { + QDomElement e = n.toElement(); + cout << "Element name: " << e.tagName() << endl; + break; + } + n = n.nextSibling(); +} +//! [1] + + +//! [2] +QDomDocument document; +QDomElement element1 = document.documentElement(); +QDomElement element2 = element1; +//! [2] + + +//! [3] +QDomElement element3 = document.createElement("MyElement"); +QDomElement element4 = document.createElement("MyElement"); +//! [3] + + +//! [4] +<body> +<h1>Heading</h1> +<p>Hello <b>you</b></p> +</body> +//! [4] + + +//! [5] +<h1>Heading</h1> +<p>The text...</p> +<h2>Next heading</h2> +//! [5] + + +//! [6] +<h1>Heading</h1> +<p>The text...</p> +<h2>Next heading</h2> +//! [6] + + +//! [7] +<link href="http://qt.nokia.com" color="red" /> +//! [7] + + +//! [8] +QDomElement e = //... +//... +QDomAttr a = e.attributeNode("href"); +cout << a.value() << endl; // prints "http://qt.nokia.com" +a.setValue("http://qt.nokia.com/doc"); // change the node's attribute +QDomAttr a2 = e.attributeNode("href"); +cout << a2.value() << endl; // prints "http://qt.nokia.com/doc" +//! [8] + + +//! [9] +QDomElement e = //... +//... +QString s = e.text() +//! [9] + + +//! [10] +QString text; +QDomElement element = doc.documentElement(); +for(QDomNode n = element.firstChild(); !n.isNull(); n = n.nextSibling()) +{ + QDomText t = n.toText(); + if (!t.isNull()) + text += t.data(); +} +//! [10] + + +//! [11] +QDomDocument doc = // ... +QDomElement root = doc.firstChildElement("database"); +QDomElement elt = root.firstChildElement("entry"); +for (; !elt.isNull(); elt = elt.nextSiblingElement("entry")) { + // ... +} +//! [11] + + +//! [12] +<img src="myimg.png"> +//! [12] + + +//! [13] +<h1>Hello <b>Qt</b> <![CDATA[<xml is cool>]]></h1> +//! [13] + + +//! [14] +Hello Qt <xml is cool> +//! [14] + + +//! [15] +<!-- this is a comment --> +//! [15] + + +//! [16] +QDomDocument doc("mydocument"); +QFile file("mydocument.xml"); +if (!file.open(QIODevice::ReadOnly)) + return; +if (!doc.setContent(&file)) { + file.close(); + return; +} +file.close(); + +// print out the element names of all elements that are direct children +// of the outermost element. +QDomElement docElem = doc.documentElement(); + +QDomNode n = docElem.firstChild(); +while(!n.isNull()) { + QDomElement e = n.toElement(); // try to convert the node to an element. + if(!e.isNull()) { + cout << qPrintable(e.tagName()) << endl; // the node really is an element. + } + n = n.nextSibling(); +} + +// Here we append a new element to the end of the document +QDomElement elem = doc.createElement("img"); +elem.setAttribute("src", "myimage.png"); +docElem.appendChild(elem); +//! [16] + + +//! [17] +QDomDocument doc("MyML"); +QDomElement root = doc.createElement("MyML"); +doc.appendChild(root); + +QDomElement tag = doc.createElement("Greeting"); +root.appendChild(tag); + +QDomText t = doc.createTextNode("Hello World"); +tag.appendChild(t); + +QString xml = doc.toString(); +//! [17] diff --git a/doc/src/snippets/code/src_xml_sax_qxml.cpp b/doc/src/snippets/code/src_xml_sax_qxml.cpp new file mode 100644 index 0000000000..7cd7a33b76 --- /dev/null +++ b/doc/src/snippets/code/src_xml_sax_qxml.cpp @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +xmlReader.setFeature("http://xml.org/sax/features/namespace-prefixes", true); +//! [0] diff --git a/doc/src/snippets/complexpingpong-example.txt b/doc/src/snippets/complexpingpong-example.txt new file mode 100644 index 0000000000..257f7029e1 --- /dev/null +++ b/doc/src/snippets/complexpingpong-example.txt @@ -0,0 +1,4 @@ +Ask your question: When is the next Qt release? +Reply was: Sorry, I don't know the answer +Ask your question: What is the answer to life, the universe and everything? +Reply was: 42 diff --git a/doc/src/snippets/customstyle/customstyle.cpp b/doc/src/snippets/customstyle/customstyle.cpp new file mode 100644 index 0000000000..b2e90722f2 --- /dev/null +++ b/doc/src/snippets/customstyle/customstyle.cpp @@ -0,0 +1,92 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> + +#include "customstyle.h" + +CustomStyle::CustomStyle() +{ +//! [0] + QSpinBox *spinBox = qobject_cast<QSpinBox *>(widget); + if (spinBox) { +//! [0] //! [1] + } +//! [1] +} + +//! [2] +void CustomStyle::drawPrimitive(PrimitiveElement element, const QStyleOption *option, + QPainter *painter, const QWidget *widget) const +{ + if (element == PE_IndicatorSpinUp || element == PE_IndicatorSpinDown) { + QPolygon points(3); + int x = option->rect.x(); + int y = option->rect.y(); + int w = option->rect.width() / 2; + int h = option->rect.height() / 2; + x += (option->rect.width() - w) / 2; + y += (option->rect.height() - h) / 2; + + if (element == PE_IndicatorSpinUp) { + points[0] = QPoint(x, y + h); + points[1] = QPoint(x + w, y + h); + points[2] = QPoint(x + w / 2, y); + } else { // PE_SpinBoxDown + points[0] = QPoint(x, y); + points[1] = QPoint(x + w, y); + points[2] = QPoint(x + w / 2, y + h); + } + + if (option->state & State_Enabled) { + painter->setPen(option->palette.mid().color()); + painter->setBrush(option->palette.buttonText()); + } else { + painter->setPen(option->palette.buttonText().color()); + painter->setBrush(option->palette.mid()); + } + painter->drawPolygon(points); + } else { + QWindowsStyle::drawPrimitive(element, option, painter, widget); +//! [2] //! [3] + } +//! [3] //! [4] +} +//! [4] diff --git a/doc/src/snippets/customstyle/customstyle.h b/doc/src/snippets/customstyle/customstyle.h new file mode 100644 index 0000000000..6a87d75421 --- /dev/null +++ b/doc/src/snippets/customstyle/customstyle.h @@ -0,0 +1,60 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#ifndef CUSTOMSTYLE_H +#define CUSTOMSTYLE_H + +#include <QWindowsStyle> + +//! [0] +class CustomStyle : public QWindowsStyle +{ + Q_OBJECT + +public: + CustomStyle() + ~CustomStyle() {} + + void drawPrimitive(PrimitiveElement element, const QStyleOption *option, + QPainter *painter, const QWidget *widget) const; +}; +//! [0] + +#endif diff --git a/doc/src/snippets/customviewstyle.cpp b/doc/src/snippets/customviewstyle.cpp new file mode 100644 index 0000000000..b040f7563e --- /dev/null +++ b/doc/src/snippets/customviewstyle.cpp @@ -0,0 +1,69 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> + +#include "customviewstyle.h" + + + +void CustomViewStyle::drawPrimitive(PrimitiveElement element, const QStyleOption *option, QPainter *painter, const QWidget *widget) const +{ + +//![0] + switch (element) { + case (PE_PanelItemViewItem): { + painter->save(); + + QPoint topLeft = option->rect.topLeft(); + QPoint bottomRight = option->rect.topRight(); + QLinearGradient backgroundGradient(topLeft, bottomRight); + backgroundGradient.setColorAt(0.0, QColor(Qt::yellow).lighter(190)); + backgroundGradient.setColorAt(1.0, Qt::white); + painter->fillRect(option->rect, QBrush(backgroundGradient)); + + painter->restore(); + break; + } + default: + QWindowsStyle::drawPrimitive(element, option, painter, widget); + } +//![0] +} diff --git a/doc/src/snippets/dialogs/dialogs.cpp b/doc/src/snippets/dialogs/dialogs.cpp new file mode 100644 index 0000000000..de9a2d1e04 --- /dev/null +++ b/doc/src/snippets/dialogs/dialogs.cpp @@ -0,0 +1,268 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> + +typedef QDialog WordCountDialog; +typedef QDialog FindDialog; + +#define this 0 +#define setWordCount(x) isVisible() + +QString tr(const char *text) +{ + return QApplication::translate(text, text); +} + +class EditorWindow : public QMainWindow +{ +public: + void find(); + void countWords(); + +private: + FindDialog *findDialog; +}; + +//! [0] +void EditorWindow::find() +{ + if (!findDialog) { + findDialog = new FindDialog(this); + connect(findDialog, SIGNAL(findNext()), this, SLOT(findNext())); + } + + findDialog->show(); + findDialog->raise(); + findDialog->activateWindow(); +} +//! [0] + +//! [1] +void EditorWindow::countWords() +{ + WordCountDialog dialog(this); + dialog.setWordCount(document().wordCount()); + dialog.exec(); +} +//! [1] + +inline bool boo() +{ + QMessageBox::information(this, "Application name", + "Unable to find the user preferences file.\n" + "The factory default will be used instead."); + + QString filename; + if (QFile::exists(filename) && + QMessageBox::question( + this, + tr("Overwrite File? -- Application Name"), + tr("A file called %1 already exists." + "Do you want to overwrite it?") + .arg(filename), + tr("&Yes"), tr("&No"), + QString(), 0, 1)) + return false; + + switch(QMessageBox::warning(this, "Application name", + "Could not connect to the <mumble> server.\n" + "This program can't function correctly " + "without the server.\n\n", + "Retry", + "Quit", 0, 0, 1)) { + case 0: // The user clicked the Retry again button or pressed Enter + // try again + break; + case 1: // The user clicked the Quit or pressed Escape + // exit + break; + } + + switch(QMessageBox::information(this, "Application name here", + "The document contains unsaved changes\n" + "Do you want to save the changes before exiting?", + "&Save", "&Discard", "Cancel", + 0, // Enter == button 0 + 2)) { // Escape == button 2 + case 0: // Save clicked or Alt+S pressed or Enter pressed. + // save + break; + case 1: // Discard clicked or Alt+D pressed + // don't save but exit + break; + case 2: // Cancel clicked or Escape pressed + // don't exit + break; + } + + switch(QMessageBox::warning(this, "Application name here", + "Could not save the user preferences,\n" + "because the disk is full. You can delete\n" + "some files and press Retry, or you can\n" + "abort the Save Preferences operation.", + QMessageBox::Retry | QMessageBox::Default, + QMessageBox::Abort | QMessageBox::Escape)) { + case QMessageBox::Retry: // Retry clicked or Enter pressed + // try again + break; + case QMessageBox::Abort: // Abort clicked or Escape pressed + // abort + break; + } + + QString errorDetails; + QMessageBox::critical(0, "Application name here", + QString("An internal error occurred. Please ") + + "call technical support at 1234-56789 and report\n"+ + "these numbers:\n\n" + errorDetails + + "\n\nApplication will now exit."); + + QMessageBox::about(this, "About <Application>", + "<Application> is a <one-paragraph blurb>\n\n" + "Copyright 1991-2003 Such-and-such. " + "<License words here.>\n\n" + "For technical support, call 1234-56789 or see\n" + "http://www.such-and-such.com/Application/\n"); + + { + // saving the file + QMessageBox mb("Application name here", + "Saving the file will overwrite the original file on the disk.\n" + "Do you really want to save?", + QMessageBox::Information, + QMessageBox::Yes | QMessageBox::Default, + QMessageBox::No, + QMessageBox::Cancel | QMessageBox::Escape); + mb.setButtonText(QMessageBox::Yes, "Save"); + mb.setButtonText(QMessageBox::No, "Discard"); + switch(mb.exec()) { + case QMessageBox::Yes: + // save and exit + break; + case QMessageBox::No: + // exit without saving + break; + case QMessageBox::Cancel: + // don't save and don't exit + break; + } + } + + { + // hardware failure +//! [2] + QMessageBox mb("Application Name", + "Hardware failure.\n\nDisk error detected\nDo you want to stop?", + QMessageBox::Question, + QMessageBox::Yes | QMessageBox::Default, + QMessageBox::No | QMessageBox::Escape, + QMessageBox::NoButton); + if (mb.exec() == QMessageBox::No) { + // try again +//! [2] + } + } +} + +inline void moo() +{ + int numFiles; +//! [3] + QProgressDialog progress("Copying files...", "Abort Copy", 0, numFiles, this); + progress.setWindowModality(Qt::WindowModal); + + for (int i = 0; i < numFiles; i++) { + progress.setValue(i); + + if (progress.wasCanceled()) + break; + //... copy one file + } + progress.setValue(numFiles); +//! [3] +} + +class Operation : public QObject +{ +public: + Operation(QObject *parent); + void perform(); + void cancel(); + +private: + int steps; + QProgressDialog *pd; + QTimer *t; +}; + +//! [4] +// Operation constructor +Operation::Operation(QObject *parent) + : QObject(parent), steps(0) +{ + pd = new QProgressDialog("Operation in progress.", "Cancel", 0, 100); + connect(pd, SIGNAL(canceled()), this, SLOT(cancel())); + t = new QTimer(this); + connect(t, SIGNAL(timeout()), this, SLOT(perform())); + t->start(0); +} +//! [4] //! [5] + +void Operation::perform() +{ + pd->setValue(steps); + //... perform one percent of the operation + steps++; + if (steps > pd->maximum()) + t->stop(); +} +//! [5] //! [6] + +void Operation::cancel() +{ + t->stop(); + //... cleanup +} +//! [6] + +int main() +{ +} diff --git a/doc/src/snippets/dockwidgets/mainwindow.cpp b/doc/src/snippets/dockwidgets/mainwindow.cpp new file mode 100644 index 0000000000..10b7531ec4 --- /dev/null +++ b/doc/src/snippets/dockwidgets/mainwindow.cpp @@ -0,0 +1,122 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> + +#include "mainwindow.h" + +MainWindow::MainWindow(QWidget *parent) + : QMainWindow(parent) +{ + setWindowTitle("Dock Widgets"); + + setupDockWindow(); + setupContents(); + setupMenus(); + + textBrowser = new QTextBrowser(this); + + connect(headingList, SIGNAL(itemClicked(QListWidgetItem *)), + this, SLOT(updateText(QListWidgetItem *))); + + updateText(headingList->item(0)); + headingList->setCurrentRow(0); + setCentralWidget(textBrowser); +} + +void MainWindow::setupContents() +{ + QFile titlesFile(":/Resources/titles.txt"); + titlesFile.open(QFile::ReadOnly); + int chapter = 0; + + do { + QString line = titlesFile.readLine().trimmed(); + QStringList parts = line.split("\t", QString::SkipEmptyParts); + if (parts.size() != 2) + break; + + QString chapterTitle = parts[0]; + QString fileName = parts[1]; + + QFile chapterFile(fileName); + + chapterFile.open(QFile::ReadOnly); + QListWidgetItem *item = new QListWidgetItem(chapterTitle, headingList); + item->setData(Qt::DisplayRole, chapterTitle); + item->setData(Qt::UserRole, chapterFile.readAll()); + item->setFlags(Qt::ItemIsEnabled | Qt::ItemIsSelectable); + chapterFile.close(); + + chapter++; + } while (titlesFile.isOpen()); + + titlesFile.close(); +} + +void MainWindow::setupDockWindow() +{ +//! [0] + contentsWindow = new QDockWidget(tr("Table of Contents"), this); + contentsWindow->setAllowedAreas(Qt::LeftDockWidgetArea + | Qt::RightDockWidgetArea); + addDockWidget(Qt::LeftDockWidgetArea, contentsWindow); + + headingList = new QListWidget(contentsWindow); + contentsWindow->setWidget(headingList); +//! [0] +} + +void MainWindow::setupMenus() +{ + QAction *exitAct = new QAction(tr("E&xit"), this); + exitAct->setShortcut(tr("Ctrl+Q")); + exitAct->setStatusTip(tr("Exit the application")); + connect(exitAct, SIGNAL(triggered()), qApp, SLOT(closeAllWindows())); + + QMenu *fileMenu = menuBar()->addMenu(tr("&File")); + fileMenu->addAction(exitAct); +} + +void MainWindow::updateText(QListWidgetItem *item) +{ + QString text = item->data(Qt::UserRole).toString(); + textBrowser->setHtml(text); +} diff --git a/doc/src/snippets/dragging/mainwindow.cpp b/doc/src/snippets/dragging/mainwindow.cpp new file mode 100644 index 0000000000..0b3f64213a --- /dev/null +++ b/doc/src/snippets/dragging/mainwindow.cpp @@ -0,0 +1,110 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> + +#include "mainwindow.h" + +MainWindow::MainWindow(QWidget *parent) + : QMainWindow(parent) +{ + QFrame *centralFrame = new QFrame(this); + + QLabel *nameLabel = new QLabel(tr("Comment:"), centralFrame); + commentEdit = new QTextEdit(centralFrame); + QLabel *dragLabel = new QLabel(tr("<p>Drag the icon to a filer " + "window or the desktop background:</p>"), + centralFrame); + iconLabel = new QLabel(centralFrame); + iconPixmap.load(":/images/file.png"); + iconLabel->setPixmap(iconPixmap); + + QGridLayout *grid = new QGridLayout(centralFrame); + grid->addWidget(nameLabel, 0, 0); + grid->addWidget(commentEdit, 1, 0, 1, 2); + grid->addWidget(dragLabel, 2, 0); + grid->addWidget(iconLabel, 2, 1); + + statusBar(); + setCentralWidget(centralFrame); + setWindowTitle(tr("Dragging")); +} + +//! [0] +void MainWindow::mousePressEvent(QMouseEvent *event) +{ + if (event->button() == Qt::LeftButton + && iconLabel->geometry().contains(event->pos())) { + +//! [1] + QDrag *drag = new QDrag(this); + QMimeData *mimeData = new QMimeData; + + mimeData->setText(commentEdit->toPlainText()); + drag->setMimeData(mimeData); +//! [1] + drag->setPixmap(iconPixmap); + + Qt::DropAction dropAction = drag->exec(); +//! [0] + + QString actionText; + switch (dropAction) { + case Qt::CopyAction: + actionText = tr("The text was copied."); + break; + case Qt::MoveAction: + actionText = tr("The text was moved."); + break; + case Qt::LinkAction: + actionText = tr("The text was linked."); + break; + case Qt::IgnoreAction: + actionText = tr("The drag was ignored."); + break; + default: + actionText = tr("Unknown action."); + break; + } + statusBar()->showMessage(actionText); +//! [2] + } +} +//! [2] diff --git a/doc/src/snippets/droparea.cpp b/doc/src/snippets/droparea.cpp new file mode 100644 index 0000000000..6556f05bf0 --- /dev/null +++ b/doc/src/snippets/droparea.cpp @@ -0,0 +1,140 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> + +#include "droparea.h" + +DropArea::DropArea(QWidget *parent) + : QLabel(parent) +{ + setMinimumSize(200, 200); + setFrameStyle(QFrame::Sunken | QFrame::StyledPanel); + setAlignment(Qt::AlignCenter); + setAcceptDrops(true); + setAutoFillBackground(true); + clear(); +} + +void DropArea::dragEnterEvent(QDragEnterEvent *event) +{ + setText(tr("<drop content>")); + setBackgroundRole(QPalette::Highlight); + + event->acceptProposedAction(); + emit changed(event->mimeData()); +} + +void DropArea::dragMoveEvent(QDragMoveEvent *event) +{ + event->acceptProposedAction(); +} + +void DropArea::dropEvent(QDropEvent *event) +{ + const QMimeData *mimeData = event->mimeData(); + + if (mimeData->hasImage()) { + setPixmap(qvariant_cast<QPixmap>(mimeData->imageData())); + } else if (mimeData->hasHtml()) { + setText(mimeData->html()); + setTextFormat(Qt::RichText); + } else if (mimeData->hasText()) { + setText(mimeData->text()); + setTextFormat(Qt::PlainText); + } else { + setText(tr("Cannot display data")); + } + + setBackgroundRole(QPalette::Dark); + event->acceptProposedAction(); +} + +//![0] +void DropArea::paste() +{ + const QClipboard *clipboard = QApplication::clipboard(); + const QMimeData *mimeData = clipboard->mimeData(); + + if (mimeData->hasImage()) { + setPixmap(qvariant_cast<QPixmap>(mimeData->imageData())); + } else if (mimeData->hasHtml()) { + setText(mimeData->html()); + setTextFormat(Qt::RichText); + } else if (mimeData->hasText()) { + setText(mimeData->text()); + setTextFormat(Qt::PlainText); + } else { + setText(tr("Cannot display data")); + } +//![0] + + emit changed(mimeData); + setBackgroundRole(QPalette::Dark); + //event->acceptProposedAction(); +} + +void DropArea::dragLeaveEvent(QDragLeaveEvent *event) +{ + clear(); + event->accept(); +} + +void DropArea::clear() +{ + setText(tr("<drop content>")); + setBackgroundRole(QPalette::Dark); + + emit changed(); +} + +QPixmap DropArea::extractPixmap(const QByteArray &data, const QString &format) +{ + QList<QByteArray> imageFormats = QImageReader::supportedImageFormats(); + QPixmap pixmap; + + foreach (const QByteArray &imageFormat, imageFormats) { + if (format.mid(6) == QString(imageFormat)) { + pixmap.loadFromData(data, imageFormat); + break; + } + } + return pixmap; +} diff --git a/doc/src/snippets/file/file.cpp b/doc/src/snippets/file/file.cpp new file mode 100644 index 0000000000..ede4aa97d2 --- /dev/null +++ b/doc/src/snippets/file/file.cpp @@ -0,0 +1,123 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QFile> +#include <QTextStream> + +static void process_line(const QByteArray &) +{ +} + +static void process_line(const QString &) +{ +} + +static void noStream_snippet() +{ +//! [0] + QFile file("in.txt"); + if (!file.open(QIODevice::ReadOnly | QIODevice::Text)) + return; + + while (!file.atEnd()) { + QByteArray line = file.readLine(); + process_line(line); + } +//! [0] +} + +static void readTextStream_snippet() +{ +//! [1] + QFile file("in.txt"); + if (!file.open(QIODevice::ReadOnly | QIODevice::Text)) + return; + + QTextStream in(&file); + while (!in.atEnd()) { + QString line = in.readLine(); + process_line(line); + } +//! [1] +} + +static void writeTextStream_snippet() +{ +//! [2] + QFile file("out.txt"); + if (!file.open(QIODevice::WriteOnly | QIODevice::Text)) + return; + + QTextStream out(&file); + out << "The magic number is: " << 49 << "\n"; +//! [2] +} + +static void writeTextStream_snippet() +{ + QFile file("out.dat"); + if (!file.open(QIODevice::WriteOnly)) + return; + + QDataStream out(&file); + out << "The magic number is: " << 49 << "\n"; +} + +static void readRegularEmptyFile_snippet() +{ +//! [3] + QFile file("/proc/modules"); + if (!file.open(QIODevice::ReadOnly | QIODevice::Text)) + return; + + QTextStream in(&file); + QString line = in.readLine(); + while (!line.isNull()) { + process_line(line); + line = in.readLine(); + } +//! [3] +} + +int main() +{ + lineByLine_snippet(); + writeStream_snippet(); +} diff --git a/doc/src/snippets/filedialogurls.cpp b/doc/src/snippets/filedialogurls.cpp new file mode 100644 index 0000000000..2b6cdaaba8 --- /dev/null +++ b/doc/src/snippets/filedialogurls.cpp @@ -0,0 +1,61 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> + +int main(int argv, char **args) +{ + QApplication app(argv, args); + +//![0] + QList<QUrl> urls; + urls << QUrl::fromLocalFile("/home/gvatteka/dev/qt-45") + << QUrl::fromLocalFile(QDesktopServices::storageLocation(QDesktopServices::MusicLocation)); + + QFileDialog dialog; + dialog.setSidebarUrls(urls); + dialog.setFileMode(QFileDialog::AnyFile); + if(dialog.exec()) { + // ... + } +//![0] + + return app.exec(); +} diff --git a/doc/src/snippets/fileinfo/main.cpp b/doc/src/snippets/fileinfo/main.cpp new file mode 100644 index 0000000000..d0fc9f54dd --- /dev/null +++ b/doc/src/snippets/fileinfo/main.cpp @@ -0,0 +1,92 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QApplication> +#include <QPushButton> +#include <QFileInfo> +#include <QDir> +#include <QGroupBox> +#include <QVBoxLayout> +#include <QDebug> + +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + +//! [0] + QFileInfo fileInfo1("~/examples/191697/."); + QFileInfo fileInfo2("~/examples/191697/.."); + QFileInfo fileInfo3("~/examples/191697/main.cpp"); +//! [0] +//! [1] + QFileInfo fileInfo4("."); + QFileInfo fileInfo5(".."); + QFileInfo fileInfo6("main.cpp"); +//! [1] + + qDebug() << fileInfo1.fileName(); + qDebug() << fileInfo2.fileName(); + qDebug() << fileInfo3.fileName(); + qDebug() << fileInfo4.fileName(); + qDebug() << fileInfo5.fileName(); + qDebug() << fileInfo6.fileName(); + + QPushButton* button1 = new QPushButton(fileInfo1.dir().path()); + QPushButton* button2 = new QPushButton(fileInfo2.dir().path()); + QPushButton* button3 = new QPushButton(fileInfo3.dir().path()); + QPushButton* button4 = new QPushButton(fileInfo4.dir().path()); + QPushButton* button5 = new QPushButton(fileInfo5.dir().path()); + QPushButton* button6 = new QPushButton(fileInfo6.dir().path()); + + QVBoxLayout* vbox = new QVBoxLayout; + vbox->addWidget(button1); + vbox->addWidget(button2); + vbox->addWidget(button3); + vbox->addWidget(button4); + vbox->addWidget(button5); + vbox->addWidget(button6); + vbox->addStretch(1); + + QGroupBox *groupBox = new QGroupBox("QFileInfo::dir() test"); + groupBox->setLayout(vbox); + groupBox->show(); + + return app.exec(); +} diff --git a/doc/src/snippets/graphicssceneadditemsnippet.cpp b/doc/src/snippets/graphicssceneadditemsnippet.cpp new file mode 100644 index 0000000000..2c2c0d01a8 --- /dev/null +++ b/doc/src/snippets/graphicssceneadditemsnippet.cpp @@ -0,0 +1,80 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> + +class CustomScene : public QGraphicsScene +{ +public: + CustomScene() + { addItem(new QGraphicsEllipseItem(QRect(10, 10, 30, 30))); } + + void drawItems(QPainter *painter, int numItems, QGraphicsItem *items[], + const QStyleOptionGraphicsItem options[], + QWidget *widget = 0); +}; + +//! [0] +void CustomScene::drawItems(QPainter *painter, int numItems, + QGraphicsItem *items[], + const QStyleOptionGraphicsItem options[], + QWidget *widget) +{ + for (int i = 0; i < numItems; ++i) { + // Draw the item + painter->save(); + painter->setMatrix(items[i]->sceneMatrix(), true); + items[i]->paint(painter, &options[i], widget); + painter->restore(); + } +} +//! [0] + +int main(int argv, char **args) +{ + QApplication app(argv, args); + + CustomScene scene; + QGraphicsView view(&scene); + + view.show(); + + return app.exec(); +} diff --git a/doc/src/snippets/image/image.cpp b/doc/src/snippets/image/image.cpp new file mode 100644 index 0000000000..62d83089d3 --- /dev/null +++ b/doc/src/snippets/image/image.cpp @@ -0,0 +1,104 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> + +int main() +{ + int x, y; + { + // BIT ACCESS + QImage image; + // sets bit at (x, y) to 1 + if (image.format() == QImage::Format_MonoLSB) + image.scanLine(y)[x >> 3] |= 1 << (x & 7); + else + image.scanLine(y)[x >> 3] |= 1 << (7 - (x & 7)); + } + + { + // 8-BIT ACCESS + QImage image; + // set entry 19 in the color table to yellow + image.setColor(19, qRgb(255, 255, 0)); + + // set 8 bit pixel at (x,y) to value yellow (in color table) + image.scanLine(y)[x] = 19; + } + + { + // 32-BIT + QImage image; + // sets 32 bit pixel at (x,y) to yellow. + uint *ptr = reinterpret_cast<uint *>(image.scanLine(y)) + x; + *ptr = qRgb(255, 255, 0); + } + + { + // SAVE +//! [0] + QImage image; + QByteArray ba; + QBuffer buffer(&ba); + buffer.open(QIODevice::WriteOnly); + image.save(&buffer, "PNG"); // writes image into ba in PNG format +//! [0] + } + + { + // PIX SAVE +//! [1] + QPixmap pixmap; + QByteArray bytes; + QBuffer buffer(&bytes); + buffer.open(QIODevice::WriteOnly); + pixmap.save(&buffer, "PNG"); // writes pixmap into bytes in PNG format +//! [1] + } + + { + // MASK +//! [2] + QPixmap alpha("image-with-alpha.png"); + QPixmap alphacopy = alpha; + alphacopy.setMask(alphacopy.mask()); +//! [2] + } +} diff --git a/doc/src/snippets/image/supportedformat.cpp b/doc/src/snippets/image/supportedformat.cpp new file mode 100644 index 0000000000..55800d33f3 --- /dev/null +++ b/doc/src/snippets/image/supportedformat.cpp @@ -0,0 +1,52 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> + +int main(int argv, char **args) +{ +//! [0] + QImageWriter writer; + writer.setFormat("png"); + if (writer.supportsOption(QImageIOHandler::Description)) + qDebug() << "Png supports embedded text"; +//! [0] + return 0; +} diff --git a/doc/src/snippets/javastyle.cpp b/doc/src/snippets/javastyle.cpp new file mode 100644 index 0000000000..1cf7e5560d --- /dev/null +++ b/doc/src/snippets/javastyle.cpp @@ -0,0 +1,2745 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> + +#include "javastyle.h" +#include <math.h> + +static const int windowsItemFrame = 2; +static const int windowsSepHeight = 2; +static const int windowsItemHMargin = 3; +static const int windowsItemVMargin = 2; +static const int windowsArrowHMargin = 6; +static const int windowsTabSpacing = 12; +static const int windowsCheckMarkHMargin = 2; +static const int windowsRightBorder = 15; +static const int windowsCheckMarkWidth = 12; + +JavaStyle::JavaStyle() +{ + qApp->setPalette(standardPalette()); +} + + +inline QPoint JavaStyle::adjustScrollPoint(const QPoint &point, + Qt::Orientation orientation, + bool add) const +{ + int adder = add ? -1 : 1; + QPoint retPoint; + + if (orientation == Qt::Horizontal) { + retPoint = QPoint(point.y() * adder, point.x()); + } else { + retPoint = QPoint(point.x(), point.y() * adder); + } + + return retPoint; +} + +QPalette JavaStyle::standardPalette() const +{ + QPalette palette = QWindowsStyle::standardPalette(); + + palette.setBrush(QPalette::Active, QPalette::Button, + QColor(184, 207, 229)); + palette.setBrush(QPalette::Active, QPalette::WindowText, + Qt::black); + palette.setBrush(QPalette::Active, QPalette::Background, + QColor(238, 238, 238)); + palette.setBrush(QPalette::Active, QPalette::Window, + QColor(238 ,238, 238)); + palette.setBrush(QPalette::Active, QPalette::Base, Qt::white); + palette.setBrush(QPalette::Active, QPalette::AlternateBase, QColor(238, 238, 238)); + palette.setBrush(QPalette::Active, QPalette::Text, Qt::black); + palette.setBrush(QPalette::Active, QPalette::BrightText, Qt::white); + + palette.setBrush(QPalette::Active, QPalette::Light, QColor(163, 184, 204)); // focusFrameColor + palette.setBrush(QPalette::Active, QPalette::Midlight, QColor(99, 130, 191)); // tabBarBorderColor + palette.setBrush(QPalette::Active, QPalette::Dark, QColor(106, 104, 100)); + palette.setBrush(QPalette::Active, QPalette::Mid, QColor(122, 138, 153)); //defaultFrameColor + palette.setBrush(QPalette::Active, QPalette::Shadow, QColor(122, 138, 153)); // defaultFrame + + palette.setBrush(QPalette::Active, QPalette::Highlight, QColor(184, 207, 229)); + palette.setBrush(QPalette::Active, QPalette::HighlightedText, Qt::black); + + palette.setBrush(QPalette::Inactive, QPalette::Highlight, QColor(184, 207, 229)); + palette.setBrush(QPalette::Inactive, QPalette::HighlightedText, Qt::black); + + palette.setBrush(QPalette::Disabled, QPalette::Button, + QColor(238, 238, 238)); + palette.setBrush(QPalette::Disabled, QPalette::WindowText, + QColor(153, 153, 153)); + palette.setBrush(QPalette::Disabled, QPalette::Background, QColor(238, 238, 238)); + + palette.setBrush(QPalette::Inactive, QPalette::Button, + QColor(184, 207, 229)); + palette.setBrush(QPalette::Inactive, QPalette::Background, + QColor(238, 238, 238)); + palette.setBrush(QPalette::Inactive, QPalette::Window, + QColor(238 ,238, 238)); + palette.setBrush(QPalette::Inactive, QPalette::Light, QColor(163, 184, 204)); // focusFrameColor + palette.setBrush(QPalette::Inactive, QPalette::Midlight, QColor(99, 130, 191)); // tabBarBorderColor + palette.setBrush(QPalette::Inactive, QPalette::Dark,QColor(106, 104, 100)); + palette.setBrush(QPalette::Inactive, QPalette::Mid, QColor(122, 138, 153)); //defaultFrame + palette.setBrush(QPalette::Inactive, QPalette::Shadow, QColor(122, 138, 153)); // defaultFrame + + return palette; +} + +inline void JavaStyle::drawScrollBarArrow(const QRect &rect, QPainter *painter, + const QStyleOptionSlider *option, + bool add) const +{ + + painter->save(); + + Qt::Orientation orient = option->orientation; + QPoint offset; + + if (add) { + if (orient == Qt::Vertical) { + offset = rect.bottomLeft(); + } else { + offset = rect.topRight(); + } + } else { + offset = rect.topLeft(); + } + + QPainterPath arrow; + arrow.moveTo(offset + adjustScrollPoint(QPoint(4, 8), orient, add)); + arrow.lineTo(offset + adjustScrollPoint(QPoint(7, 5), orient, add)); + arrow.lineTo(offset + adjustScrollPoint(QPoint(8, 5), orient, add)); + arrow.lineTo(offset + adjustScrollPoint(QPoint(11, 8), orient, add)); + arrow.lineTo(offset + adjustScrollPoint(QPoint(4, 8), orient, add)); + + QColor fillColor; + if (option->state & State_Sunken) + fillColor = QColor(option->palette.color(QPalette::Button)); + else + fillColor = option->palette.color(QPalette::Background); + + painter->fillRect(rect, fillColor); + + painter->setPen(option->palette.color(QPalette::Base)); + int adjust = option->state & State_Sunken ? 0 : 1; + painter->drawRect(rect.adjusted(adjust, adjust, -1, -1)); + painter->setPen(option->palette.color(QPalette::Mid)); + painter->drawRect(rect.adjusted(0, 0, -1, -1)); + + painter->setPen(option->palette.color(QPalette::WindowText)); + painter->setBrush(option->palette.color(QPalette::WindowText)); + painter->drawPath(arrow); + + painter->restore(); +} + +inline QPoint JavaStyle::adjustScrollHandlePoint(Qt::Orientation orig, + const QPoint &point) const +{ + QPoint retPoint; + + if (orig == Qt::Vertical) + retPoint = point; + else + retPoint = QPoint(point.y(), point.x()); + + return retPoint; +} + +void JavaStyle::drawControl(ControlElement control, const QStyleOption *option, + QPainter *painter, const QWidget *widget) const +{ + + painter->save(); + + switch (control) { + case CE_ToolBoxTabShape: { + const QStyleOptionToolBox *box = + qstyleoption_cast<const QStyleOptionToolBox *>(option); + + painter->save(); + + if (box->direction == Qt::RightToLeft) { + painter->rotate(1); + painter->translate(box->rect.width(), -box->rect.height()); + } + + int textWidth = box->fontMetrics.width(box->text) + 20; + + QPolygon innerLine; + innerLine << (box->rect.topLeft() + QPoint(0, 1)) << + (box->rect.topLeft() + QPoint(textWidth, 1)) << + (box->rect.bottomLeft() + QPoint(textWidth + 15, -3)) << + (box->rect.bottomRight() + QPoint(0, -3)) << + box->rect.bottomRight() << + box->rect.bottomLeft() << + box->rect.topLeft(); + + painter->setPen(box->palette.color(QPalette::Base)); + painter->setBrush(QColor(200, 221, 242)); + painter->drawPolygon(innerLine); + + QPolygon outerLine; + outerLine << (box->rect.bottomRight() + QPoint(0, -3)) << + box->rect.bottomRight() << + box->rect.bottomLeft() << + box->rect.topLeft() << + (box->rect.topLeft() + QPoint(textWidth, 0)) << + (box->rect.bottomLeft() + QPoint(textWidth + 15, -4)) << + (box->rect.bottomRight() + QPoint(0, -4)); + + painter->setPen(box->palette.color(QPalette::Midlight)); + painter->setBrush(Qt::NoBrush); + painter->drawPolyline(outerLine); + + painter->restore(); + break; + } + case CE_DockWidgetTitle: { + const QStyleOptionDockWidgetV2 *docker = + new QStyleOptionDockWidgetV2( + *qstyleoption_cast<const QStyleOptionDockWidget *>(option)); + + QRect rect = docker->rect; + QRect titleRect = rect; + if (docker->verticalTitleBar) { + QRect r = rect; + QSize s = r.size(); + s.transpose(); + r.setSize(s); + + titleRect = QRect(r.left() + rect.bottom() + - titleRect.bottom(), + r.top() + titleRect.left() - rect.left(), + titleRect.height(), titleRect.width()); + + painter->translate(r.left(), r.top() + r.width()); + painter->rotate(-90); + painter->translate(-r.left(), -r.top()); + + rect = r; + } + + QLinearGradient gradient(rect.topLeft(), + rect.bottomLeft()); + gradient.setColorAt(1.0, QColor(191, 212, 231)); + gradient.setColorAt(0.3, Qt::white); + gradient.setColorAt(0.0, QColor(221, 232, 243)); + + painter->setPen(Qt::NoPen); + painter->setBrush(gradient); + painter->drawRect(rect.adjusted(0, 0, -1, -1)); + + if (!docker->title.isEmpty()) { + QRect textRect = docker->fontMetrics.boundingRect(docker->title); + textRect.moveCenter(rect.center()); + + QFont font = painter->font(); + font.setPointSize(font.pointSize() - 1); + painter->setFont(font); + painter->setPen(docker->palette.text().color()); + painter->drawText(textRect, docker->title, + QTextOption(Qt::AlignHCenter | + Qt::AlignVCenter)); + } + break; + } + case CE_RubberBand: { + painter->setPen(option->palette.color(QPalette::Active, + QPalette::WindowText)); + painter->drawRect(option->rect.adjusted(0, 0, -1, -1)); + break; + } + case CE_SizeGrip: { + break; + } + case CE_HeaderSection: { + const QStyleOptionHeader *header = + qstyleoption_cast<const QStyleOptionHeader *>(option); + + painter->setPen(Qt::NoPen); + painter->setBrush(option->palette.color(QPalette::Active, + QPalette::Background)); + painter->drawRect(option->rect); + + painter->setPen(header->palette.color(QPalette::Mid)); + if (header->orientation == Qt::Horizontal) { + if (header->position == QStyleOptionHeader::Beginning || + header->position == QStyleOptionHeader::OnlyOneSection) { + painter->drawRect(header->rect.adjusted(0, 0, -1, -1)); + painter->setPen(header->palette.color(QPalette::Base)); + painter->drawLine(header->rect.bottomLeft() + QPoint(1, -1), + header->rect.topLeft() + QPoint(1, 1)); + painter->drawLine(header->rect.topLeft() + QPoint(1, 1), + header->rect.topRight() + QPoint(-1, 1)); + } else { + painter->drawLine(header->rect.bottomRight(), + header->rect.topRight()); + painter->drawLine(header->rect.topLeft(), + header->rect.topRight()); + painter->drawLine(header->rect.bottomLeft(), + header->rect.bottomRight()); + painter->setPen(option->palette.color(QPalette::Base)); + painter->drawLine(header->rect.bottomLeft() + QPoint(0, -1), + header->rect.topLeft() + QPoint(0, 1)); + painter->drawLine(header->rect.topLeft() + QPoint(1, 1), + header->rect.topRight() + QPoint(-1, 1)); + } + } else { // Vertical + if (header->position == QStyleOptionHeader::Beginning || + header->position == QStyleOptionHeader::OnlyOneSection) { + painter->drawRect(header->rect.adjusted(0, 0, -1, -1)); + painter->setPen(header->palette.color(QPalette::Base)); + painter->drawLine(header->rect.bottomLeft() + QPoint(1, -1), + header->rect.topLeft() + QPoint(1, 1)); + painter->drawLine(header->rect.topLeft() + QPoint(1, 1), + header->rect.topRight() + QPoint(-1, 1)); + } else { + painter->drawLine(header->rect.bottomLeft(), + header->rect.bottomRight()); + painter->drawLine(header->rect.topLeft(), + header->rect.bottomLeft()); + painter->drawLine(header->rect.topRight(), + header->rect.bottomRight()); + painter->setPen(header->palette.color(QPalette::Base)); + painter->drawLine(header->rect.topLeft(), + header->rect.topRight() + QPoint(-1, 0)); + painter->drawLine(header->rect.bottomLeft() + QPoint(1, -1), + header->rect.topLeft() + QPoint(1, 0)); + } + } + break; + } + case CE_ToolBar: { + QRect rect = option->rect; + + QLinearGradient gradient(rect.topLeft(), rect.bottomLeft()); + gradient.setColorAt(1.0, QColor(221, 221, 221)); + gradient.setColorAt(0.0, QColor(241, 241, 241)); + + if (option->state & State_Horizontal) { + painter->setPen(QColor(204, 204, 204)); + painter->setBrush(gradient); + } else { + painter->setPen(Qt::NoPen); + painter->setBrush(option->palette.color(QPalette::Background)); + } + painter->drawRect(rect.adjusted(0, 0, -1, -1)); + break; + } + case CE_ProgressBar: { + const QStyleOptionProgressBar *bar1 = + qstyleoption_cast<const QStyleOptionProgressBar *>(option); + + QStyleOptionProgressBarV2 *bar = new QStyleOptionProgressBarV2(*bar1); + + QRect rect = bar->rect; + if (bar->orientation == Qt::Vertical) { + rect = QRect(rect.left(), rect.top(), rect.height(), rect.width()); + QMatrix m; + m.translate(rect.height()-1, 0); + m.rotate(90.0); + painter->setMatrix(m); + } + + painter->setPen(bar->palette.color(QPalette::Mid)); + painter->drawRect(rect.adjusted(0, 0, -1, -1)); + + QRect grooveRect = subElementRect(SE_ProgressBarGroove, bar, + widget); + if (bar->orientation == Qt::Vertical) { + grooveRect = QRect(grooveRect.left(), grooveRect.top(), + grooveRect.height(), grooveRect.width()); + } + + QStyleOptionProgressBar grooveBar = *bar; + grooveBar.rect = grooveRect; + + drawControl(CE_ProgressBarGroove, &grooveBar, painter, widget); + + QRect progressRect = subElementRect(SE_ProgressBarContents, bar, + widget); + if (bar->orientation == Qt::Vertical) { + progressRect = QRect(progressRect.left(), progressRect.top(), + progressRect.height(), progressRect.width()); + progressRect.adjust(0, 0, 0, -1); + } + QStyleOptionProgressBar progressOpt = *bar; + progressOpt.rect = progressRect; + drawControl(CE_ProgressBarContents, &progressOpt, painter, widget); + + QRect labelRect = subElementRect(SE_ProgressBarLabel, bar, widget); + if (bar->orientation == Qt::Vertical) { + labelRect = QRect(labelRect.left(), labelRect.top(), + labelRect.height(), labelRect.width()); + } + QStyleOptionProgressBar subBar = *bar; + subBar.rect = labelRect; + if (bar->textVisible) + drawControl(CE_ProgressBarLabel, &subBar, painter, widget); + + delete bar; + break; + } + case CE_ProgressBarGroove: { + painter->setBrush(option->palette.color(QPalette::Background)); + painter->setPen(Qt::NoPen); + painter->drawRect(option->rect.adjusted(0, 0, -1, -1)); + + painter->setPen(option->palette.color(QPalette::Button)); + painter->drawLine(option->rect.topLeft() + QPoint(0, 0), + option->rect.topRight() + QPoint(0, 0)); + break; + } + case CE_ProgressBarContents: { + const QStyleOptionProgressBar *bar = + qstyleoption_cast<const QStyleOptionProgressBar *>(option); + int progress = int((double(bar->progress) / + double(bar->maximum - bar->minimum)) * + bar->rect.width()); + + painter->setBrush(bar->palette.color(QPalette::Light)); + painter->setPen(Qt::NoPen); + QRect progressRect = QRect(bar->rect.topLeft(), QPoint(progress, + bar->rect.bottom())); + painter->drawRect(progressRect); + + painter->setPen(bar->palette.color(QPalette::Midlight)); + painter->setBrush(Qt::NoBrush); + + painter->drawLine(bar->rect.bottomLeft(), bar->rect.topLeft()); + painter->drawLine(bar->rect.topLeft(), QPoint(progress, + bar->rect.top())); + break; + } + case CE_ProgressBarLabel: { + painter->save(); + const QStyleOptionProgressBar *bar = + qstyleoption_cast<const QStyleOptionProgressBar *>(option); + + QRect rect = bar->rect; + QRect leftRect; + + int progressIndicatorPos = int((double(bar->progress) / + double(bar->maximum - bar->minimum)) * + bar->rect.width()); + + QFont font; + font.setBold(true); + painter->setFont(font); + painter->setPen(bar->palette.color(QPalette::Midlight)); + + if (progressIndicatorPos >= 0 && + progressIndicatorPos <= rect.width()) { + leftRect = QRect(bar->rect.topLeft(), + QPoint(progressIndicatorPos, + bar->rect.bottom())); + } else if (progressIndicatorPos > rect.width()) { + painter->setPen(bar->palette.color(QPalette::Base)); + } else { + painter->setPen(bar->palette.color(QPalette::Midlight)); + } + + QRect textRect = QFontMetrics(font).boundingRect(bar->text); + textRect.moveCenter(option->rect.center()); + painter->drawText(textRect, bar->text, + QTextOption(Qt::AlignCenter)); + if (!leftRect.isNull()) { + painter->setPen(bar->palette.color(QPalette::Base)); + painter->setClipRect(leftRect, Qt::IntersectClip); + painter->drawText(textRect, bar->text, + QTextOption(Qt::AlignCenter)); + } + + painter->restore(); + break; + } + case CE_MenuBarEmptyArea: { + QRect emptyArea = option->rect.adjusted(0, 0, -1, -1); + QLinearGradient gradient(emptyArea.topLeft(), emptyArea.bottomLeft() + - QPoint(0, 1)); + gradient.setColorAt(0.0, option->palette.color(QPalette::Base)); + gradient.setColorAt(1.0, QColor(223, 223, 223)); + + painter->setPen(QColor(238, 238, 238)); + painter->setBrush(gradient); + painter->drawRect(emptyArea.adjusted(0, 0, 0, -1)); + break; + } + case CE_MenuBarItem: { + if (!(option->state & State_Sunken)) { + QLinearGradient gradient(option->rect.topLeft(), + option->rect.bottomLeft()); + gradient.setColorAt(0.0, Qt::white); + gradient.setColorAt(1.0, QColor(223, 223, 223)); + + painter->setPen(Qt::NoPen); + painter->setBrush(gradient); + } else { + painter->setBrush(option->palette.color(QPalette::Light)); + } + + painter->drawRect(option->rect); + if (option->state & State_Sunken) { + painter->setPen(option->palette.color(QPalette::Mid)); + painter->drawRect(option->rect.adjusted(0, 0, -1, -1)); + painter->setPen(option->palette.color(QPalette::Base)); + painter->setBrush(Qt::NoBrush); + painter->drawLine(option->rect.bottomRight() + QPoint(0, -1), + option->rect.topRight() + QPoint(0, -1)); + } + QCommonStyle::drawControl(control, option, painter, widget); + break; + } + case CE_MenuItem: { + const QStyleOptionMenuItem *menuItem = + qstyleoption_cast<const QStyleOptionMenuItem *>(option); + + bool selected = menuItem->state & State_Selected; + bool checkable = menuItem->checkType != + QStyleOptionMenuItem::NotCheckable; + bool checked = menuItem->checked; + + if (menuItem->menuItemType == QStyleOptionMenuItem::Separator) { + QPoint center = menuItem->rect.center(); + + painter->setPen(menuItem->palette.color(QPalette::Midlight)); + painter->drawLine(QPoint(menuItem->rect.left() - 2, center.y()), + QPoint(menuItem->rect.right(), center.y())); + painter->setPen(menuItem->palette.color(QPalette::Base)); + painter->drawLine(QPoint(menuItem->rect.left() - 2, + center.y() + 1), + QPoint(menuItem->rect.right(), + center.y() + 1)); + + break; + } + + if (selected) { + painter->setBrush(menuItem->palette.color(QPalette::Light)); + painter->setPen(Qt::NoPen); + painter->drawRect(menuItem->rect); + painter->setPen(menuItem->palette.color(QPalette::Midlight)); + painter->drawLine(menuItem->rect.topLeft(), + menuItem->rect.topRight()); + painter->setPen(menuItem->palette.color(QPalette::Base)); + painter->drawLine(menuItem->rect.bottomLeft(), + menuItem->rect.bottomRight()); + } + + if (checkable) { + QRect checkRect(option->rect.left() + 5, + option->rect.center().y() - 5, 10, 10); + if (menuItem->checkType & QStyleOptionMenuItem::Exclusive) { + QStyleOptionButton button; + button.rect = checkRect; + button.state = menuItem->state; + if (button.state & State_Sunken) + button.state ^= State_Sunken; + if (checked) + button.state |= State_On; + button.palette = menuItem->palette; + drawPrimitive(PE_IndicatorRadioButton, &button, painter, + widget); + } else { + QBrush buttonBrush = gradientBrush(option->rect); + painter->setBrush(buttonBrush); + painter->setPen(option->palette.color(QPalette::Mid)); + + painter->drawRect(checkRect); + + if (checked) { + QImage image(":/images/checkboxchecked.png"); + painter->drawImage(QPoint(option->rect.left() + 5, + option->rect.center().y() - 8), image); + } + } + } + + bool dis = !(menuItem->state & State_Enabled); + bool act = menuItem->state & State_Selected; + const QStyleOption *opt = option; + const QStyleOptionMenuItem *menuitem = menuItem; + int checkcol = qMax(menuitem->maxIconWidth, 20); + if (menuItem->icon.isNull()) + checkcol = 0; + + QPainter *p = painter; + QRect vCheckRect = visualRect(opt->direction, menuitem->rect, + QRect(menuitem->rect.x(), + menuitem->rect.y(), + checkcol, menuitem->rect.height())); + if (!menuItem->icon.isNull()) { + QIcon::Mode mode = dis ? QIcon::Disabled : QIcon::Normal; + if (act && !dis) + mode = QIcon::Active; + QPixmap pixmap; + if (checked) + pixmap = menuItem->icon.pixmap( + pixelMetric(PM_SmallIconSize), mode, QIcon::On); + else + pixmap = menuItem->icon.pixmap( + pixelMetric(PM_SmallIconSize), mode); + int pixw = pixmap.width(); + int pixh = pixmap.height(); + + int adjustedIcon = checkable ? 15 : 0; + QRect pmr(0, 0, pixw, pixh); + pmr.moveCenter(vCheckRect.center()); + painter->setPen(menuItem->palette.text().color()); + if (checkable && checked) + painter->drawPixmap(QPoint(pmr.left() + + adjustedIcon, pmr.top() + 1), pixmap); + else + painter->drawPixmap(pmr.topLeft() + + QPoint(adjustedIcon, 0), pixmap); + } + + if (selected) { + painter->setPen(menuItem->palette.highlightedText().color()); + } else { + painter->setPen(menuItem->palette.text().color()); + } + int x, y, w, h; + menuitem->rect.getRect(&x, &y, &w, &h); + int tab = menuitem->tabWidth; + QColor discol; + if (dis) { + discol = menuitem->palette.text().color(); + p->setPen(discol); + } + int xm = windowsItemFrame + checkcol + windowsItemHMargin; + int xpos = menuitem->rect.x() + xm; + QRect textRect; + if (!menuItem->icon.isNull()) + textRect.setRect(xpos, y + windowsItemVMargin, w - xm - + windowsRightBorder - tab + 1, h - 2 * windowsItemVMargin); + else + textRect.setRect(menuItem->rect.left() + 9, + y + windowsItemVMargin, + w - xm - windowsRightBorder - tab, + h - 2 * windowsItemVMargin); + + if (checkable) + textRect.adjust(10, 0, 10, 0); + + QRect vTextRect = visualRect(opt->direction, menuitem->rect, + textRect); + QString s = menuitem->text; + if (!s.isEmpty()) { + int t = s.indexOf(QLatin1Char('\t')); + int text_flags = Qt::AlignVCenter | Qt::TextShowMnemonic | + Qt::TextDontClip | Qt::TextSingleLine; + if (!styleHint(SH_UnderlineShortcut, menuitem, widget)) + text_flags |= Qt::TextHideMnemonic; + text_flags |= Qt::AlignLeft; + if (t >= 0) { + QRect vShortcutRect = visualRect(opt->direction, + menuitem->rect, + QRect(textRect.topRight(), + QPoint(menuitem->rect.right(), textRect.bottom()))); + if (dis && !act) { + p->setPen(menuitem->palette.light().color()); + p->drawText(vShortcutRect.adjusted(1, 1, 1, 1), + text_flags, + s.mid(t + 1)); + p->setPen(discol); + } + p->drawText(vShortcutRect, text_flags, s.mid(t + 1)); + s = s.left(t); + } + QFont font = menuitem->font; + if (menuitem->menuItemType == QStyleOptionMenuItem::DefaultItem) + font.setBold(true); + p->setFont(font); + if (dis && !act) { + p->setPen(menuitem->palette.light().color()); + p->drawText(vTextRect.adjusted(1,1,1,1), text_flags, + s.left(t)); + p->setPen(discol); + } + p->drawText(vTextRect, text_flags, s.left(t)); + } + + if (menuItem->menuItemType & QStyleOptionMenuItem::SubMenu) { + QPoint center = menuItem->rect.center(); + QPoint drawStart(menuItem->rect.right() - 6, center.y() + 4); + + QPainterPath arrow; + arrow.moveTo(drawStart); + arrow.lineTo(drawStart + QPoint(0, -8)); + arrow.lineTo(drawStart + QPoint(4, -5)); + arrow.lineTo(drawStart + QPoint(4, -4)); + arrow.lineTo(drawStart + QPoint(0, 0)); + + painter->save(); + painter->setBrush(menuItem->palette.color(QPalette::Text)); + painter->setPen(Qt::NoPen); + painter->drawPath(arrow); + painter->restore(); + } + + break; + } + case CE_MenuVMargin: { + break; + } + case CE_MenuHMargin: { + break; + } + case CE_Splitter: { + drawSplitter(option, painter, option->state & State_Horizontal); + break; + } + case CE_ScrollBarAddPage: { + case CE_ScrollBarSubPage: + const QStyleOptionSlider *scrollBar = + qstyleoption_cast<const QStyleOptionSlider *>(option); + QRect myRect; + if (scrollBar->orientation == Qt::Horizontal) { + myRect = QRect(option->rect.topLeft(), + option->rect.bottomRight()).adjusted(0, 0, 1, -1); + } else { + myRect = option->rect; + } + + painter->setPen(Qt::NoPen); + painter->setBrush(option->palette.color(QPalette::Background)); + painter->drawRect(myRect); + + painter->setBrush(Qt::NoBrush); + painter->setPen(scrollBar->palette.color(QPalette::Mid)); + painter->drawRect(myRect.adjusted(0, 0, -1, 0)); + painter->setPen(scrollBar->palette.color(QPalette::Button)); + painter->drawLine(myRect.bottomLeft() + QPoint(1, 0), + myRect.topLeft() + QPoint(1, 1)); + painter->drawLine(myRect.topLeft() + QPoint(1, 1), + myRect.topRight() + QPoint(-1, 1)); + break; + } + case CE_ScrollBarSubLine: { + const QStyleOptionSlider *scrollBar = + qstyleoption_cast<const QStyleOptionSlider *>(option); + int scrollBarExtent = pixelMetric(PM_ScrollBarExtent); + QRect scrollBarSubLine = option->rect; + + QRect button1; + QRect button2; + + if (scrollBar->orientation == Qt::Horizontal) { + button1.setRect(scrollBarSubLine.left(), scrollBarSubLine.top(), + 16, scrollBarExtent); + button2.setRect(scrollBarSubLine.right() - 15, + scrollBarSubLine.top(), 16, scrollBarExtent); + } else { + button1.setRect(scrollBarSubLine.left(), scrollBarSubLine.top(), + scrollBarExtent, 16); + button2.setRect(scrollBarSubLine.left(), + scrollBarSubLine.bottom() - 15, scrollBarExtent, 16); + } + + painter->fillRect(button2, Qt::blue); + + drawScrollBarArrow(button1, painter, scrollBar); + drawScrollBarArrow(button2, painter, scrollBar); + break; + } + case CE_ScrollBarAddLine: { + const QStyleOptionSlider *scrollBar = + qstyleoption_cast<const QStyleOptionSlider *>(option); + QRect button(option->rect.left(), option->rect.top(), 16, 16); + drawScrollBarArrow(button, painter, scrollBar, true); + break; + } + case CE_ScrollBarSlider: { + const QStyleOptionSlider *scrollBar = + qstyleoption_cast<const QStyleOptionSlider *>(option); + + painter->setPen(scrollBar->palette.color(QPalette::Midlight)); + painter->drawRect(scrollBar->rect.adjusted(-1, 0, -3, -1)); + + QPoint g1, g2; + if (scrollBar->orientation == Qt::Horizontal) { + g1 = option->rect.topLeft(); + g2 = option->rect.bottomLeft(); + } else { + g1 = option->rect.topLeft(); + g2 = option->rect.topRight(); + } + + if (scrollBar->state & State_Enabled) { + QLinearGradient gradient(g1, g2); + gradient.setColorAt(1.0, QColor(188, 210, 230)); + gradient.setColorAt(0.3, Qt::white); + gradient.setColorAt(0.0, QColor(223, 233, 243)); + painter->setBrush(gradient); + } else { + painter->setPen(scrollBar->palette.buttonText().color()); + painter->setBrush(scrollBar->palette.button()); + } + painter->drawRect(scrollBar->rect.adjusted(0, 0, -1, -1)); + + int sliderLength = option->rect.height(); + int drawPos = scrollBar->orientation == Qt::Vertical ? + (sliderLength / 2) + 1 : 1 - ((option->rect.width() / 2)); + + QPoint origin; + if (scrollBar->orientation == Qt::Vertical) + origin = option->rect.bottomLeft(); + else + origin = option->rect.topLeft(); + + painter->setPen(scrollBar->palette.color(QPalette::Base)); + painter->drawLine(origin + adjustScrollHandlePoint( + scrollBar->orientation, + QPoint(4, -drawPos)), + origin + adjustScrollHandlePoint( + scrollBar->orientation, + QPoint(13, -drawPos))); + painter->drawLine(origin + adjustScrollHandlePoint( + scrollBar->orientation, + QPoint(4, 2 - drawPos)), + origin + adjustScrollHandlePoint( + scrollBar->orientation, + QPoint(13, 2 - drawPos))); + painter->drawLine(origin + adjustScrollHandlePoint( + scrollBar->orientation, + QPoint(4, 4 - drawPos)), + origin + adjustScrollHandlePoint( + scrollBar->orientation, + QPoint(13, 4 - drawPos))); + + painter->setPen(option->palette.color(QPalette::Midlight)); + painter->drawLine(origin + adjustScrollHandlePoint( + scrollBar->orientation, + QPoint(3, -(drawPos + 1))), + origin + adjustScrollHandlePoint( + scrollBar->orientation, + QPoint(12, -(drawPos + 1)))); + painter->drawLine(origin + adjustScrollHandlePoint( + scrollBar->orientation, + QPoint(3, 1 - drawPos)), + origin + adjustScrollHandlePoint( + scrollBar->orientation, + QPoint(12, 1 - drawPos))); + painter->drawLine(origin + adjustScrollHandlePoint( + scrollBar->orientation, + QPoint(3, 3 - drawPos)), + origin + adjustScrollHandlePoint( + scrollBar->orientation, + QPoint(12, 3 - drawPos))); + + break; + } + case CE_TabBarTabLabel: { + QStyleOptionTab copy = + *qstyleoption_cast<const QStyleOptionTab *>(option); + if (copy.state & State_HasFocus) + copy.state ^= State_HasFocus; + painter->setBrush(Qt::NoBrush); + QWindowsStyle::drawControl(CE_TabBarTabLabel, ©, painter, + widget); + break; + } + case CE_TabBarTabShape: { + const QStyleOptionTab *tab = + qstyleoption_cast<const QStyleOptionTab *>(option); + QRect myRect = option->rect; + QPoint bottomLeft, bottomRight, topLeft, topRight; + + if ((tab->position == QStyleOptionTab::Beginning) || + (tab->position == QStyleOptionTab::OnlyOneTab)) { + if (tab->shape == QTabBar::RoundedSouth || + tab->shape == QTabBar::RoundedNorth) { + myRect = myRect.adjusted(2, 0, 0, 0); + } else { + myRect = myRect.adjusted(0, 2, 0, 0); + } + } + + switch (tab->shape) { + case QTabBar::RoundedNorth: + topLeft = myRect.topLeft(); + topRight = myRect.topRight(); + bottomLeft = myRect.bottomLeft(); + bottomRight = myRect.bottomRight(); + break; + case QTabBar::RoundedSouth: + topLeft = myRect.bottomLeft(); + topRight = myRect.bottomRight(); + bottomLeft = myRect.topLeft(); + bottomRight = myRect.topRight(); + break; + case QTabBar::RoundedWest: + topLeft = myRect.topLeft(); + topRight = myRect.bottomLeft(); + bottomLeft = myRect.topRight(); + bottomRight = myRect.bottomRight(); + break; + case QTabBar::RoundedEast: + topLeft = myRect.topRight(); + topRight = myRect.bottomRight(); + bottomLeft = myRect.topLeft(); + bottomRight = myRect.bottomLeft(); + break; + default: + ; + } + + QPainterPath outerPath; + outerPath.moveTo(bottomLeft + adjustTabPoint(QPoint(0, -2), + tab->shape)); + outerPath.lineTo(bottomLeft + adjustTabPoint(QPoint(0, -14), + tab->shape)); + outerPath.lineTo(topLeft + adjustTabPoint(QPoint(6 , 0), + tab->shape)); + outerPath.lineTo(topRight + adjustTabPoint(QPoint(0, 0), + tab->shape)); + outerPath.lineTo(bottomRight + adjustTabPoint(QPoint(0, -2), + tab->shape)); + + if (tab->state & State_Selected || + tab->position == QStyleOptionTab::OnlyOneTab) { + QPainterPath innerPath; + innerPath.moveTo(topLeft + adjustTabPoint(QPoint(6, 2), + tab->shape)); + innerPath.lineTo(topRight + adjustTabPoint(QPoint(-1, 2), + tab->shape)); + innerPath.lineTo(bottomRight + adjustTabPoint(QPoint(-1 , -2), + tab->shape)); + innerPath.lineTo(bottomLeft + adjustTabPoint(QPoint(2 , -2), + tab->shape)); + innerPath.lineTo(bottomLeft + adjustTabPoint(QPoint(2 , -14), + tab->shape)); + innerPath.lineTo(topLeft + adjustTabPoint(QPoint(6, 2), + tab->shape)); + + QPainterPath whitePath; + whitePath.moveTo(bottomLeft + adjustTabPoint(QPoint(1, -2), + tab->shape)); + whitePath.lineTo(bottomLeft + adjustTabPoint(QPoint(1, -14), + tab->shape)); + whitePath.lineTo(topLeft + adjustTabPoint(QPoint(6, 1), + tab->shape)); + whitePath.lineTo(topRight + adjustTabPoint(QPoint(-1, 1), + tab->shape)); + + painter->setPen(tab->palette.color(QPalette::Midlight)); + painter->setBrush(QColor(200, 221, 242)); + painter->drawPath(outerPath); + painter->setPen(QColor(200, 221, 242)); + painter->drawRect(QRect(bottomLeft + adjustTabPoint( + QPoint(2, -3), tab->shape), + bottomRight + adjustTabPoint( + QPoint(-2, 0), tab->shape))); + painter->setPen(tab->palette.color(QPalette::Base)); + painter->setBrush(Qt::NoBrush); + painter->drawPath(whitePath); + + if (option->state & State_HasFocus) { + painter->setPen(option->palette.color(QPalette::Mid)); + painter->drawPath(innerPath); + } + } else { + painter->setPen(tab->palette.color(QPalette::Mid)); + painter->drawPath(outerPath); + } + break; + } + case CE_PushButtonLabel: + painter->save(); + + if (const QStyleOptionButton *button = + qstyleoption_cast<const QStyleOptionButton *>(option)) { + QRect ir = button->rect; + uint tf = Qt::AlignVCenter | Qt::TextShowMnemonic; + if (!styleHint(SH_UnderlineShortcut, button, widget)) + tf |= Qt::TextHideMnemonic; + + if (!button->icon.isNull()) { + QPoint point; + + QIcon::Mode mode = button->state & State_Enabled ? QIcon::Normal + : QIcon::Disabled; + if (mode == QIcon::Normal && button->state & State_HasFocus) + mode = QIcon::Active; + QIcon::State state = QIcon::Off; + if (button->state & State_On) + state = QIcon::On; + + QPixmap pixmap = button->icon.pixmap(button->iconSize, mode, + state); + int w = pixmap.width(); + int h = pixmap.height(); + + if (!button->text.isEmpty()) + w += button->fontMetrics.width(button->text) + 2; + + point = QPoint(ir.x() + ir.width() / 2 - w / 2, + ir.y() + ir.height() / 2 - h / 2); + + if (button->direction == Qt::RightToLeft) + point.rx() += pixmap.width(); + + painter->drawPixmap(visualPos(button->direction, button->rect, + point), pixmap); + + if (button->direction == Qt::RightToLeft) + ir.translate(-point.x() - 2, 0); + else + ir.translate(point.x() + pixmap.width(), 0); + + if (!button->text.isEmpty()) + tf |= Qt::AlignLeft; + + } else { + tf |= Qt::AlignHCenter; + } + + if (button->fontMetrics.height() > 14) + ir.translate(0, 1); + + drawItemText(painter, ir, tf, button->palette, (button->state & + State_Enabled), + button->text, QPalette::ButtonText); + } + + painter->restore(); + break; + + default: + QWindowsStyle::drawControl(control, option, painter, widget); + } + painter->restore(); +} + +inline QPoint JavaStyle::adjustTabPoint(const QPoint &point, + QTabBar::Shape shape) const +{ + QPoint rPoint; + + switch (shape) { + case QTabBar::RoundedWest: + rPoint = QPoint(point.y(), point.x()); + break; + case QTabBar::RoundedSouth: + rPoint = QPoint(point.x(), point.y() * -1); + break; + case QTabBar::RoundedEast: + rPoint = QPoint(point.y() * -1, point.x()); + break; + default: + rPoint = point; + } + return rPoint; +} + +QRect JavaStyle::subControlRect(ComplexControl control, + const QStyleOptionComplex *option, + SubControl subControl, + const QWidget *widget) const +{ + QRect rect = QWindowsStyle::subControlRect(control, option, subControl, + widget); + + switch (control) { + case CC_TitleBar: { + const QStyleOptionTitleBar *bar = + qstyleoption_cast<const QStyleOptionTitleBar *>(option); + + switch (subControl) { + case SC_TitleBarMinButton: { + rect = QRect(bar->rect.topRight() + QPoint(-68, 2), + QSize(15, 15)); + break; + } + case SC_TitleBarMaxButton: { + rect = QRect(bar->rect.topRight() + QPoint(-43, 3), + QSize(15, 15)); + break; + } + case SC_TitleBarCloseButton: { + rect = QRect(bar->rect.topRight() + QPoint(-18, 3), + QSize(15, 15)); + break; + } + case SC_TitleBarLabel: { + QRect labelRect = bar->fontMetrics.boundingRect(bar->text); + rect = labelRect; + rect.translate(bar->rect.left() + 30, 0); + rect.moveTop(bar->rect.top()); + rect.adjust(0, 2, 2, 2); + break; + } + case SC_TitleBarSysMenu: { + rect = QRect(bar->rect.topLeft() + QPoint(6, 3), + QSize(16, 16)); + break; + } + default: + ; + } + break; + } + case CC_GroupBox: { + const QStyleOptionGroupBox *box = + qstyleoption_cast<const QStyleOptionGroupBox *>(option); + bool hasCheckbox = box->subControls & SC_GroupBoxCheckBox; + int checkAdjust = 13; + + QRect textRect = box->fontMetrics.boundingRect(box->text); + + switch (subControl) { + case SC_GroupBoxFrame: { + rect = box->rect; + break; + } + case SC_GroupBoxCheckBox: { + if (hasCheckbox) { + rect = QRect(box->rect.topLeft() + QPoint(7, 4 + + (textRect.height() / 2 - checkAdjust / 2)), + QSize(checkAdjust, checkAdjust)); + } + else { + rect = QRect(); + } + break; + } + case SC_GroupBoxLabel: { + rect = QRect(box->rect.topLeft() + QPoint(7 + (hasCheckbox ? + checkAdjust + 2 : 0), 4), textRect.size()); + break; + } + case SC_GroupBoxContents: { + rect = box->rect.adjusted(10, 10 + textRect.height(), -10, + -10); + break; + } + default: + ; + } + break; + } + case CC_SpinBox: { + const QStyleOptionSpinBox *spinBox = + qstyleoption_cast<const QStyleOptionSpinBox *>(option); + int spinnerWidth = 16; + QRect myRect = spinBox->rect; + QPoint center = myRect.center(); + int frameWidth = pixelMetric(PM_SpinBoxFrameWidth, spinBox, widget); + + switch (subControl) { + case SC_SpinBoxUp: { + rect = QRect(myRect.topRight() + QPoint(-16, 0), + QSize(16, center.y() - myRect.topRight().y())); + break; + } + case SC_SpinBoxDown: { + rect = QRect(QPoint(myRect.bottomRight().x() - 16, + center.y() + 1), + QSize(16, myRect.bottomRight().y() - + center.y() - 1)); + break; + } + case SC_SpinBoxFrame: { + rect = QRect(myRect.topLeft(), myRect.bottomRight() + + QPoint(-16, 0)); + break; + } + case SC_SpinBoxEditField: { + rect = QRect(myRect.topLeft() + QPoint(2, 2), + myRect.bottomRight() + QPoint(-15 - frameWidth, -2)); + break; + } + default: + ; + } + break; + } + case CC_ToolButton: { + const QStyleOptionToolButton *button = + qstyleoption_cast<const QStyleOptionToolButton *>(option); + + switch (subControl) { + case SC_ToolButton: { + rect = option->rect.adjusted(1, 1, -1, -1); + break; + } + case SC_ToolButtonMenu: { + rect = QRect(option->rect.bottomRight() + + QPoint(-11, -11), QSize(10, 10)); + break; + } + } + break; + } + case CC_ComboBox: { + const QStyleOptionComboBox *combo = + qstyleoption_cast<const QStyleOptionComboBox *>(option); + + bool reverse = combo->direction == Qt::RightToLeft; + + switch (subControl) { + case SC_ComboBoxFrame: + rect = combo->rect; + break; + case SC_ComboBoxArrow: + if (reverse) { + rect = QRect(combo->rect.topLeft(), + combo->rect.bottomLeft() + QPoint(17, 0)); + } else { + rect = QRect(combo->rect.topRight() + QPoint(-17, 0), + combo->rect.bottomRight()); + } + break; + case SC_ComboBoxEditField: + if (reverse) { + rect = QRect(combo->rect.topLeft() + QPoint(19, 2), + combo->rect.bottomRight() + QPoint(-2, 2)); + } else { + rect = QRect(combo->rect.topLeft() + QPoint(2, 2), + combo->rect.bottomRight() + QPoint(-19, -2)); + } + break; + case SC_ComboBoxListBoxPopup: + rect = combo->rect; + break; + } + break; + } + case CC_ScrollBar: { + const QStyleOptionSlider *scrollBar = + qstyleoption_cast<const QStyleOptionSlider *>(option); + int scrollBarExtent = pixelMetric(PM_ScrollBarExtent, scrollBar, + widget); + int sliderMaxLength = ((scrollBar->orientation == Qt::Horizontal) ? + scrollBar->rect.width() : + scrollBar->rect.height()) - (16 * 3); + int sliderMinLength = pixelMetric(PM_ScrollBarSliderMin, scrollBar, + widget); + int sliderLength; + + if (scrollBar->maximum != scrollBar->minimum) { + uint valueRange = scrollBar->maximum - scrollBar->minimum; + sliderLength = (scrollBar->pageStep * sliderMaxLength) / + (valueRange + scrollBar->pageStep); + + if (sliderLength < sliderMinLength || valueRange > INT_MAX / 2) + sliderLength = sliderMinLength; + if (sliderLength > sliderMaxLength) + sliderLength = sliderMaxLength; + } else { + sliderLength = sliderMaxLength; + } + int sliderStart = 16 + sliderPositionFromValue(scrollBar->minimum, + scrollBar->maximum, + scrollBar->sliderPosition, + sliderMaxLength - sliderLength, + scrollBar->upsideDown); + QRect scrollBarRect = scrollBar->rect; + + switch (subControl) { + case SC_ScrollBarSubLine: + if (scrollBar->orientation == Qt::Horizontal) { + rect.setRect(scrollBarRect.left(), scrollBarRect.top(), + scrollBarRect.width() - 16, scrollBarExtent); + } else { + rect.setRect(scrollBarRect.left(), scrollBarRect.top(), + scrollBarExtent, scrollBarRect.height() - 16); + } + break; + case SC_ScrollBarAddLine: + if (scrollBar->orientation == Qt::Horizontal) { + rect.setRect(scrollBarRect.right() - 15, + scrollBarRect.top(), 16, scrollBarExtent); + } else { + rect.setRect(scrollBarRect.left(), scrollBarRect.bottom() + - 15, scrollBarExtent, 16); + } + break; + case SC_ScrollBarSubPage: + if (scrollBar->orientation == Qt::Horizontal) { + rect.setRect(scrollBarRect.left() + 16, scrollBarRect.top(), + sliderStart - (scrollBarRect.left() + 16), + scrollBarExtent); + } else { + rect.setRect(scrollBarRect.left(), scrollBarRect.top() + 16, + scrollBarExtent, + sliderStart - (scrollBarRect.left() + 16)); + } + break; + case SC_ScrollBarAddPage: + if (scrollBar->orientation == Qt::Horizontal) + rect.setRect(sliderStart + sliderLength, 0, + sliderMaxLength - sliderStart - + sliderLength + 16, scrollBarExtent); + else + rect.setRect(0, sliderStart + sliderLength, + scrollBarExtent, sliderMaxLength - + sliderStart - sliderLength + 16); + break; + case SC_ScrollBarGroove: + if (scrollBar->orientation == Qt::Horizontal) { + rect = scrollBarRect.adjusted(16, 0, -32, 0); + } else { + rect = scrollBarRect.adjusted(0, 16, 0, -32); + } + break; + case SC_ScrollBarSlider: + if (scrollBar->orientation == Qt::Horizontal) { + rect.setRect(sliderStart, 0, sliderLength, + scrollBarExtent); + } else { + rect.setRect(0, sliderStart, scrollBarExtent, + sliderLength); + } + break; + default: + return QWindowsStyle::subControlRect(control, option, + subControl, widget); + } + break; + } + case CC_Slider: { + const QStyleOptionSlider *slider = + qstyleoption_cast<const QStyleOptionSlider *>(option); + rect = slider->rect; + int tickSize = pixelMetric(PM_SliderTickmarkOffset, option, widget); + int handleSize = pixelMetric(PM_SliderControlThickness, option, + widget); + + int dist = slider->orientation == Qt::Vertical ? slider->rect.height() : + slider->rect.width(); + int pos = QStyle::sliderPositionFromValue(slider->minimum, + slider->maximum, slider->sliderValue, dist - handleSize); + + switch (subControl) { + case SC_SliderGroove: { + QPoint center = rect.center(); + + if (slider->orientation == Qt::Horizontal) { + rect.setHeight(handleSize); + if (slider->tickPosition == QSlider::TicksBelow) { + center.ry() -= tickSize; + } + } else { + rect.adjust(0, 0, 0, 0); + rect.setWidth(handleSize); + if (slider->tickPosition == QSlider::TicksBelow) { + center.rx() -= tickSize; + } + } + rect.moveCenter(center); + break; + } + case SC_SliderHandle: { + QPoint center = rect.center(); + + if (slider->orientation == Qt::Horizontal) { + rect.setHeight(handleSize); + if (slider->tickPosition == QSlider::TicksBelow) { + center.ry() -= tickSize; + } + + rect.moveCenter(center); + + if (slider->upsideDown) + rect.setLeft(slider->rect.right() - + pos - (handleSize - 1)); + else + rect.setLeft(pos); + + rect.setWidth(handleSize - 1); + } else { + rect.setWidth(handleSize); + if (slider->tickPosition == QSlider::TicksBelow) { + center.rx() -= tickSize; + } + + rect.moveCenter(center); + + if (slider->upsideDown) + rect.setTop(slider->rect.bottom() - + ((pos + handleSize) - 2)); + else + rect.setTop(slider->rect.top() + pos); + + rect.setHeight(handleSize); + } + break; + } + case SC_SliderTickmarks: { + QPoint center = slider->rect.center(); + + if (slider->tickPosition & QSlider::TicksBelow) { + if (slider->orientation == Qt::Horizontal) { + rect.setHeight(tickSize); + center.ry() += tickSize / 2; + rect.adjust(6, 0, -10, 0); + } else { + rect.setWidth(tickSize); + center.rx() += tickSize / 2; + rect.adjust(0, 6, 0, -10); + } + } else { + rect = QRect(); + } + rect.moveCenter(center); + break; + } + default: + ; + } + break; + } + default: + return QWindowsStyle::subControlRect(control, option, subControl, + widget); + } + return rect; +} + +static const char * const sliderHandleImage[] = { + "15 16 7 1", + " c None", + "+ c #FFFFFF", + "@ c #FFFFFF", + "$ c #FFFFFF", + "( c #E5EDF5", + ") c #F2F6FA", + "[ c #FFFFFF", + " +++++++++++++ ", + "+@@@@@@@@@@@@@+", + "+@(((((((((((@+", + "+@(((((((((((@+", + "+@)))))))))))@+", + "+@[[[[[[[[[[[@+", + "+@[[[[[[[[[[[@+", + "+@)))))))))))@+", + "+@)))))))))))@+", + " +@)))))))))@+ ", + " +@(((((((@+ ", + " +@(((((@+ ", + " +@(((@+ ", + " +@(@+ ", + " +@+ ", + " + "}; + + +void JavaStyle::drawComplexControl(ComplexControl control, + const QStyleOptionComplex *option, + QPainter *painter, + const QWidget *widget) const +{ + painter->save(); + + switch (control) { + case CC_TitleBar: { + const QStyleOptionTitleBar *bar = + qstyleoption_cast<const QStyleOptionTitleBar *>(option); + + bool sunken = bar->state & State_Sunken; + + QLinearGradient gradient(bar->rect.bottomLeft(), + bar->rect.topLeft()); + gradient.setColorAt(0.0, QColor(191, 212, 231)); + gradient.setColorAt(0.7, Qt::white); + gradient.setColorAt(1.0, QColor(221, 232, 243)); + + painter->setPen(Qt::NoPen); + if (bar->titleBarState & State_Active) { + painter->setBrush(gradient); + } + else + painter->setBrush(bar->palette.color(QPalette::Active, + QPalette::Background)); + + painter->drawRect(bar->rect.adjusted(0, 0, -1, -1)); + + painter->setBrush(QColor(233, 233, 233)); + painter->drawRect(QRect(bar->rect.bottomLeft() + QPoint(0, 1), + bar->rect.bottomRight() + QPoint(0, 2))); + + QRect minButtonRect = subControlRect(control, bar, + SC_TitleBarMinButton); + QRect maxButtonRect = subControlRect(control, bar, + SC_TitleBarMaxButton); + QRect closeButtonRect = subControlRect(control, bar, + SC_TitleBarCloseButton); + QRect systemButtonRect = subControlRect(control, bar, + SC_TitleBarSysMenu); + QRect labelRect = subControlRect(control, bar, SC_TitleBarLabel); + QRect gripRect = QRect(QPoint(labelRect.right() + 5, bar->rect.top() + 5), + QPoint(minButtonRect.left() - 5, + bar->rect.bottom() - 4)); + + QColor textColor = option->palette.color(QPalette::Text); + painter->setPen(textColor); + painter->setBrush(Qt::NoBrush); + + drawItemText(painter, labelRect, Qt::TextShowMnemonic | + Qt::AlignHCenter | Qt::AlignCenter, + bar->palette, bar->state & State_Enabled, bar->text, + textColor.isValid() ? QPalette::NoRole : + QPalette::WindowText); + + for (int i = 0; i < gripRect.width(); ++i) { + painter->setPen(i % 2 ? bar->palette.color(QPalette::Midlight) + : Qt::white); + + for (int j = 0; j < 4; ++j) { + painter->drawPoint(i + gripRect.left(), + gripRect.top() - 2 + i % 4 + 4 * j); + } + } + + QPixmap maximizePixmap(":/images/internalmaximize.png"); + QPixmap minimizePixmap(":/images/internalminimize.png"); + QPixmap closePixmap(":/images/internalclose.png"); + QPixmap internalPixmap(":/images/internalsystem.png"); + QPixmap internalCloseDownPixmap(":/images/internalclosedown.png"); + QPixmap minimizeDownPixmap(":/images/internalminimizedown.png"); + QPixmap maximizeDownPixmap(":/images/internalmaximizedown.png"); + + if (bar->activeSubControls & SC_TitleBarCloseButton && + bar->state & State_Sunken) + painter->drawPixmap(closeButtonRect.topLeft(), + internalCloseDownPixmap); + else + painter->drawPixmap(closeButtonRect.topLeft(), closePixmap); + + if (bar->activeSubControls & SC_TitleBarMinButton && + bar->state & State_Sunken) + painter->drawPixmap(minButtonRect.topLeft(), + minimizeDownPixmap); + else + painter->drawPixmap(minButtonRect.topLeft(), minimizePixmap); + + if (bar->activeSubControls & SC_TitleBarMaxButton && + bar->state & State_Sunken) + painter->drawPixmap(maxButtonRect.topLeft(), + maximizeDownPixmap); + else + painter->drawPixmap(maxButtonRect.topLeft(), maximizePixmap); + + painter->drawPixmap(systemButtonRect.topLeft(), internalPixmap); + + break; + } + case CC_GroupBox: { + const QStyleOptionGroupBox *box = + qstyleoption_cast<const QStyleOptionGroupBox *>(option); + + QRect frameRect = subControlRect(control, box, SC_GroupBoxFrame); + QRect labelRect = subControlRect(control, box, SC_GroupBoxLabel); + QRect contentsRect = subControlRect(control, box, + SC_GroupBoxContents); + QRect checkerRect = subControlRect(control, box, + SC_GroupBoxCheckBox); + + int y = labelRect.center().y(); + + painter->setPen(box->palette.color(QPalette::Button)); + painter->drawRect(frameRect.adjusted(2, y - frameRect.top(), -2, + -2)); + + painter->setPen(box->palette.color(QPalette::Background)); + + if (box->subControls & SC_GroupBoxCheckBox) { + painter->drawLine(checkerRect.left() - 1, y, + checkerRect.right() + 2, y); + QStyleOptionButton checker; + checker.QStyleOption::operator=(*box); + checker.rect = checkerRect; + drawPrimitive(PE_IndicatorCheckBox, &checker, painter, widget); + } + + if (box->subControls & SC_GroupBoxLabel && !box->text.isEmpty()) { + painter->drawLine(labelRect.left() - 1, y, + labelRect.right() +1, y); + + QColor textColor = box->textColor; + if (textColor.isValid()) + painter->setPen(textColor); + + drawItemText(painter, labelRect, Qt::TextShowMnemonic | + Qt::AlignHCenter | int(box->textAlignment), + box->palette, box->state & State_Enabled, + box->text, textColor.isValid() ? QPalette::NoRole : + QPalette::WindowText); + } + break; + } + case CC_SpinBox: { + const QStyleOptionSpinBox *spinner = + qstyleoption_cast<const QStyleOptionSpinBox *>(option); + + QRect frameRect = subControlRect(control, spinner, SC_SpinBoxFrame); + QRect upRect = subControlRect(control, spinner, SC_SpinBoxUp); + QRect downRect = subControlRect(control, spinner, SC_SpinBoxDown); + + painter->setPen(Qt::white); + painter->drawRect(frameRect.adjusted(1, 1, -1, -1)); + painter->drawPoint(frameRect.bottomLeft()); + + painter->setPen(spinner->palette.color(QPalette::Mid)); + painter->drawRect(frameRect.adjusted(0, 0, -1, -2)); + + bool isEnabled = (spinner->state & State_Enabled); + bool hover = isEnabled && (spinner->state & State_MouseOver); + bool sunken = (spinner->state & State_Sunken); + bool upIsActive = (spinner->activeSubControls == SC_SpinBoxUp); + bool downIsActive = (spinner->activeSubControls == SC_SpinBoxDown); + bool stepUpEnabled = spinner->stepEnabled & + QAbstractSpinBox::StepUpEnabled; + bool stepDownEnabled = spinner->stepEnabled & + QAbstractSpinBox::StepDownEnabled; + + painter->setBrush(spinner->palette.color(QPalette::Background)); + + painter->drawRect(upRect); + if (upIsActive && stepUpEnabled) { + if (sunken) { + drawSunkenButtonShadow(painter, upRect, + spinner->palette.color(QPalette::Mid)); + } else if (hover) { + drawButtonHoverFrame(painter, upRect, + spinner->palette.color(QPalette::Mid), + spinner->palette.color(QPalette::Button)); + } + } + + QStyleOptionSpinBox upSpin = *spinner; + upSpin.rect = upRect; + drawPrimitive(PE_IndicatorSpinUp, &upSpin, painter, widget); + + painter->drawRect(downRect); + if (downIsActive && stepDownEnabled) { + if (sunken) { + drawSunkenButtonShadow(painter, downRect, + spinner->palette.color(QPalette::Mid)); + } else if (hover) { + drawButtonHoverFrame(painter, downRect, + spinner->palette.color(QPalette::Mid), + spinner->palette.color(QPalette::Button)); + } + } + + QStyleOptionSpinBox downSpin = *spinner; + downSpin.rect = downRect; + drawPrimitive(PE_IndicatorSpinDown, &downSpin, painter, widget); + + break; + } + case CC_ToolButton: { + const QStyleOptionToolButton *button = + qstyleoption_cast<const QStyleOptionToolButton *>(option); + + painter->setPen(Qt::white); + painter->drawRect(button->rect.adjusted(1, 1, -1, -1)); + + QStyleOptionToolButton panelOption = *button; + QRect panelRect; + if (!(button->state & State_MouseOver) && + !(button->state & State_On)) { + painter->setPen(QColor(153, 153, 153)); + painter->drawRect(button->rect.adjusted(0, 0, -2, -2)); + + panelRect = subControlRect(control, option, SC_ToolButton); + panelOption.rect = panelRect; + } else { + panelOption.rect.adjust(0, 0, -1, -1); + } + + QRect menuRect = subControlRect(control, option, SC_ToolButtonMenu); + + drawPrimitive(PE_PanelButtonTool, &panelOption, painter, widget); + + QStyleOptionToolButton menuOption = *button; + menuOption.rect = menuRect; + + QStyleOptionToolButton label = *button; + int fw = 5; + + drawControl(CE_ToolButtonLabel, &label, painter, widget); + if (button->subControls & SC_ToolButtonMenu) { + painter->setPen(button->palette.color(QPalette::WindowText)); + drawPrimitive(PE_IndicatorArrowDown, &menuOption, painter, widget); + } + + if (button->state & State_HasFocus) { + QStyleOptionToolButton focusOption = *button; + focusOption.rect = label.rect.adjusted(-1, -1, 1, 1); + + drawPrimitive(PE_FrameFocusRect, &focusOption, painter, widget); + } + + break; + } + case CC_ComboBox: { + const QStyleOptionComboBox *combo = + qstyleoption_cast<const QStyleOptionComboBox *>(option); + + QRect frameRect = subControlRect(control, option, SC_ComboBoxFrame, + widget); + painter->setPen(combo->palette.color(QPalette::Mid)); + + if (option->state & State_HasFocus) + painter->setBrush(option->palette.color(QPalette::Light)); + else + painter->setBrush(combo->palette.color(QPalette::Background)); + + painter->drawRect(frameRect.adjusted(0, 0, -1, -1)); + + QRect arrowRect = subControlRect(control, option, SC_ComboBoxArrow, + widget); + painter->setPen(combo->palette.color(QPalette::Button)); + painter->setBrush(Qt::NoBrush); + + if (combo->direction == Qt::LeftToRight) { + painter->drawRect(QRect(frameRect.topLeft() + QPoint(1, 1), + arrowRect.bottomLeft() + QPoint(-2, -2))); + } else { + painter->drawRect(QRect(arrowRect.topLeft() + QPoint(1, 1), + frameRect.bottomRight() + QPoint(-2, -2))); + } + + QStyleOptionButton button; + button.rect = arrowRect; + button.state = combo->state; + button.palette = combo->palette; + + if (button.state & State_On) + button.state ^= State_On; + + painter->save(); + drawButtonBackground(&button, painter, false); + painter->restore(); + + QPoint center = arrowRect.center(); + QPoint offset = QPoint(arrowRect.bottomLeft().x() + 1, + center.y() + 7); + QPainterPath arrow; + arrow.moveTo(offset + QPoint(4, -8)); + arrow.lineTo(offset + QPoint(7, -5)); + arrow.lineTo(offset + QPoint(8, -5)); + arrow.lineTo(offset + QPoint(11, -8)); + arrow.lineTo(offset + QPoint(4, -8)); + + painter->setBrush(combo->palette.color(QPalette::WindowText)); + painter->setPen(combo->palette.color(QPalette::WindowText)); + + painter->drawPath(arrow); + + QRect fieldRect = subControlRect(control, option, + SC_ComboBoxEditField, widget); + + break; + } + case CC_Slider: { + const QStyleOptionSlider *slider = + qstyleoption_cast<const QStyleOptionSlider *>(option); + + bool horizontal = slider->orientation == Qt::Horizontal; + + QRect groove = subControlRect(control, option, SC_SliderGroove, + widget); + QRect ticks = subControlRect(control, option, SC_SliderTickmarks, + widget); + QRect handle = subControlRect(control, option, SC_SliderHandle, + widget); + + QRect afterHandle = QRect(handle.topLeft() + xySwitch(QPoint(4, 6), horizontal), + groove.bottomRight() + xySwitch(QPoint(-4, -6), horizontal)); + QRect beforeHandle = QRect(groove.topLeft() + xySwitch(QPoint(4, 6), horizontal), + handle.bottomRight() + xySwitch(QPoint(-4, -6), horizontal)); + + if (slider->upsideDown || !horizontal) { + QRect remember; + remember = afterHandle; + afterHandle = beforeHandle; + beforeHandle = remember; + } + + painter->setPen(slider->palette.color(QPalette::Mid)); + painter->setBrush(option->palette.color(QPalette::Background)); + painter->drawRect(afterHandle); + painter->setPen(slider->palette.color(QPalette::Light)); + painter->drawLine(afterHandle.topLeft() + xySwitch(QPoint(0, 1), horizontal), + afterHandle.topRight() + xySwitch(QPoint(0, 1), horizontal)); + painter->setPen(option->palette.color(QPalette::Midlight)); + + if (horizontal) { + painter->setBrush(gradientBrush(QRect(QPoint(groove.x(), + handle.y() + 1), + QSize(groove.width(), + handle.height() + 1)))); + } else { + QRect rect = QRect(QPoint(groove.x(), + handle.x() - 1), + QSize(groove.height(), + handle.width() + 1)); + QLinearGradient gradient(groove.bottomLeft(), + groove.bottomRight()); + gradient.setColorAt(1.0, QColor(188, 210, 230)); + gradient.setColorAt(0.3, Qt::white); + gradient.setColorAt(0.0, QColor(223, 233, 243)); + + painter->setBrush(gradient); + } + + painter->drawRect(beforeHandle); + + QPainterPath handlePath; + QPainterPath innerPath; + QPoint topLeft, topRight, bottomLeft; + if (horizontal) { + topLeft = handle.topLeft(); + topRight = handle.topRight(); + bottomLeft = handle.bottomLeft(); + } else { + topLeft = handle.bottomLeft(); + topRight = handle.topLeft(); + bottomLeft = handle.topRight(); + } + + if (horizontal) { + QImage image(sliderHandleImage); + + image.setColor(1, + option->palette.color(QPalette::Midlight).rgb()); + image.setColor(2, + option->palette.color(QPalette::Button).rgb()); + + if (!(slider->state & State_Enabled)) { + image.setColor(4, slider->palette.color(QPalette::Background).rgb()); + image.setColor(5, slider->palette.color(QPalette::Background).rgb()); + image.setColor(6, slider->palette.color(QPalette::Background).rgb()); + } + + painter->drawImage(handle.topLeft(), image); + } else { + QImage image(":/images/verticalsliderhandle.png"); + painter->drawImage(handle.topLeft(), image); + } + + if (slider->tickPosition & QSlider::TicksBelow) { + painter->setPen(slider->palette.color(QPalette::Light)); + int tickInterval = slider->tickInterval ? slider->tickInterval : + slider->pageStep; + + for (int i = 0; i <= slider->maximum; i += tickInterval) { + if (horizontal) { + int pos = int(((i / double(slider->maximum)) * + ticks.width()) - 1); + painter->drawLine(QPoint(ticks.left() + pos, + ticks.top() + 2), QPoint(ticks.left() + pos, ticks.top() + 8)); + } else { + int pos = int(((i / double(slider->maximum)) * + ticks.height()) - 1); + painter->drawLine(QPoint(ticks.left() + 2, ticks.bottom() - pos), + QPoint(ticks.right() - 2, ticks.bottom() - pos)); + } + } + if (horizontal) { + painter->drawLine(QPoint(ticks.right(), ticks.top() + 2), + QPoint(ticks.right(), ticks.top() + 8)); + } else { + painter->drawLine(QPoint(ticks.left() + 2, ticks.top()), + QPoint(ticks.right() - 2, ticks.top())); + } + } + break; + } + default: + QWindowsStyle::drawComplexControl(control, option, painter, widget); + } + painter->restore(); +} + +inline void JavaStyle::drawSunkenButtonShadow(QPainter *painter, + QRect rect, + const QColor &frameColor, + bool reverse) const +{ + painter->save(); + + painter->setPen(frameColor); + + if (!reverse) { + painter->drawLine(QLine(QPoint(rect.x() + 1, rect.y() + 1), + QPoint(rect.x() + rect.width() - 1, rect.y() + 1))); + painter->drawLine(QLine(QPoint(rect.x() + 1, rect.y()), + QPoint(rect.x() + 1, rect.y() + rect.height()))); + } else { + painter->drawLine(QLine(QPoint(rect.right(), rect.bottom()), + QPoint(rect.right(), rect.top()))); + painter->drawLine(QLine(QPoint(rect.left(), rect.top() + 1), + QPoint(rect.right(), rect.top() + 1))); + } + painter->restore(); +} + +inline void JavaStyle::drawButtonHoverFrame(QPainter *painter, QRect rect, + const QColor &frameColor, + const QColor &activeFrame) const +{ + painter->save(); + + painter->setPen(activeFrame); + painter->drawRect(rect); + rect.adjust(1, 1, -1, -1); + painter->setPen(frameColor); + painter->drawRect(rect); + rect.adjust(1, 1, -1, -1); + painter->setPen(activeFrame); + painter->drawRect(rect); + + painter->restore(); +} + +QStyle::SubControl JavaStyle::hitTestComplexControl(ComplexControl control, + const QStyleOptionComplex *option, + const QPoint &pos, + const QWidget *widget) const +{ + SubControl ret = SC_None; + + switch (control) { + case CC_TitleBar: { + const QStyleOptionTitleBar *bar = + qstyleoption_cast<const QStyleOptionTitleBar *>(option); + + QRect maximize = subControlRect(control, bar, SC_TitleBarMaxButton); + if (maximize.contains(pos)) { + ret = SC_TitleBarMaxButton; + break; + } + QRect minimize = subControlRect(control, bar, SC_TitleBarMinButton); + if (minimize.contains(pos)) { + ret = SC_TitleBarMinButton; + break; + } + QRect close = subControlRect(control, bar, SC_TitleBarCloseButton); + if (close.contains(pos)) { + ret = SC_TitleBarCloseButton; + break; + } + QRect system = subControlRect(control, bar, SC_TitleBarSysMenu); + if (system.contains(pos)) { + ret = SC_TitleBarSysMenu; + break; + } + ret = SC_TitleBarLabel; + break; + } + case CC_ScrollBar: + if (const QStyleOptionSlider *scrollBar = + qstyleoption_cast<const QStyleOptionSlider *>(option)) { + QRect slider = subControlRect(control, scrollBar, + SC_ScrollBarSlider, widget); + if (slider.contains(pos)) { + ret = SC_ScrollBarSlider; + break; + } + + QRect scrollBarAddLine = subControlRect(control, scrollBar, + SC_ScrollBarAddLine, widget); + if (scrollBarAddLine.contains(pos)) { + ret = SC_ScrollBarAddLine; + break; + } + + QRect scrollBarSubPage = subControlRect(control, scrollBar, + SC_ScrollBarSubPage, widget); + if (scrollBarSubPage.contains(pos)) { + ret = SC_ScrollBarSubPage; + break; + } + + QRect scrollBarAddPage = subControlRect(control, scrollBar, + SC_ScrollBarAddPage, widget); + if (scrollBarAddPage.contains(pos)) { + ret = SC_ScrollBarAddPage; + break; + } + + QRect scrollBarSubLine = subControlRect(control, scrollBar, + SC_ScrollBarSubLine, widget); + if (scrollBarSubLine.contains(pos)) { + ret = SC_ScrollBarSubLine; + break; + } + } + break; + + default: + ret = QWindowsStyle::hitTestComplexControl(control, option, pos, + widget); + } + return ret; +} + +void JavaStyle::polish(QWidget *widget) +{ + if (qobject_cast<QCheckBox *>(widget) || + qobject_cast<QRadioButton *>(widget) || + qobject_cast<QPushButton *>(widget) || + qobject_cast<QToolButton *>(widget) || + qobject_cast<QSpinBox *>(widget) || + qobject_cast<QGroupBox *>(widget)) + widget->setAttribute(Qt::WA_Hover, true); +} + +void JavaStyle::unpolish(QWidget *widget) +{ + if (qobject_cast<QPushButton *>(widget) || + qobject_cast<QCheckBox *>(widget) || + qobject_cast<QRadioButton *>(widget) || + qobject_cast<QToolButton *>(widget) || + qobject_cast<QSpinBox *>(widget) || + qobject_cast<QGroupBox *>(widget)) + widget->setAttribute(Qt::WA_Hover, false); +} + +void JavaStyle::drawSplitter(const QStyleOption *option, QPainter *painter, + bool horizontal) const +{ + QRect rect = option->rect; + + painter->setPen(Qt::NoPen); + painter->setBrush(option->palette.color(QPalette::Background)); + + painter->drawRect(rect); + + QColor colors[] = { Qt::white, option->palette.color(QPalette::Mid) }; + int iterations = horizontal ? rect.height() - 1 : rect.width() - 1; + for (int i = 0; i < iterations; ++i) { + painter->setPen(colors[i % 2]); + painter->drawPoint(xySwitch(QPoint(rect.x() + 0 + (i % 4), + rect.y() + i), horizontal)); + } +} + +inline QPoint JavaStyle::xySwitch(const QPoint &point, bool horizontal) const +{ + QPoint retPoint = point; + + if (!horizontal) { + retPoint = QPoint(point.y(), point.x()); + } + + return retPoint; +} + +void JavaStyle::drawPrimitive(PrimitiveElement element, + const QStyleOption *option, + QPainter *painter, + const QWidget *widget) const +{ + painter->save(); + + switch (element) { + case PE_PanelButtonBevel: + case PE_FrameButtonBevel: { + painter->save(); + painter->setBrush(option->palette.background()); + painter->setPen(Qt::NoPen); + painter->drawRect(option->rect); + painter->restore(); + break; + } + case PE_IndicatorBranch: { + painter->save(); + QColor lineColor(204, 204, 255); + QPixmap openPixmap(":/images/jtreeopen.png"); + QPixmap closedPixmap(":/images/jtreeclosed.png"); + QRect pixmapRect(QPoint(0, 0), QSize(12, 12)); + pixmapRect.moveCenter(option->rect.center()); + pixmapRect.translate(2, 0); + QPoint center = option->rect.center(); + + painter->setPen(lineColor); + painter->setBrush(Qt::NoBrush); + + if (option->state & State_Item) { + painter->drawLine(center, + QPoint(option->rect.right(), center.y())); + + painter->drawLine(center, QPoint(center.x(), + option->rect.top())); + + if (option->state & State_Sibling) { + painter->drawLine(center, QPoint(center.x(), + option->rect.bottom())); + } + + if (option->state & State_Children) + if (option->state & State_Open) + painter->drawPixmap(pixmapRect.topLeft(), closedPixmap); + else + painter->drawPixmap(pixmapRect.topLeft(), openPixmap); + } else if (option->state & State_Sibling) { + painter->drawLine(center.x(), option->rect.top(), center.x(), + option->rect.bottom()); + } + + painter->restore(); + break; + } + case PE_IndicatorViewItemCheck: { + break; + } + case PE_FrameWindow: { + painter->save(); + bool active = option->state & State_Active; + + painter->setPen(Qt::NoPen); + painter->setBrush(active ? option->palette.color(QPalette::Midlight) + : option->palette.color(QPalette::Mid)); + + painter->drawRect(QRect(option->rect.topLeft(), option->rect.bottomLeft() + QPoint(5, 0))); + painter->drawRect(QRect(option->rect.bottomLeft(), option->rect.bottomRight() + QPoint(0, -5))); + painter->drawRect(QRect(option->rect.bottomRight() + QPoint(-5, 0), option->rect.topRight())); + painter->drawRect(QRect(option->rect.topLeft(), option->rect.topRight() + QPoint(0, 4))); + + painter->setBrush(Qt::NoBrush); + painter->setPen(option->palette.color(QPalette::Active, QPalette::WindowText)); + painter->drawLine(option->rect.topLeft() + QPoint(2, 14), + option->rect.bottomLeft() + QPoint(2, -14)); + + painter->drawLine(option->rect.topRight() + QPoint(-2, 14), + option->rect.bottomRight() + QPoint(-2, -14)); + + painter->drawLine(option->rect.topLeft() + QPoint(14, 2), + option->rect.topRight() + QPoint(-14, 2)); + + painter->drawLine(option->rect.bottomLeft() + QPoint(14, -2), + option->rect.bottomRight() + QPoint(-14, -2)); + + painter->setPen(active ? option->palette.color(QPalette::Light) : + option->palette.color(QPalette::Button)); + painter->drawLine(option->rect.topLeft() + QPoint(3, 15), + option->rect.bottomLeft() + QPoint(3, -13)); + + painter->drawLine(option->rect.topRight() + QPoint(-1, 15), + option->rect.bottomRight() + QPoint(-1, -13)); + + painter->drawLine(option->rect.topLeft() + QPoint(15, 3), + option->rect.topRight() + QPoint(-13, 3)); + + painter->drawLine(option->rect.bottomLeft() + QPoint(15, -1), + option->rect.bottomRight() + QPoint(-13, -1)); + + painter->restore(); + break; + } + case PE_IndicatorSpinUp: { + const QStyleOptionSpinBox *spinner = + qstyleoption_cast<const QStyleOptionSpinBox *>(option); + int add = spinner->state & State_Sunken && + spinner->activeSubControls & SC_SpinBoxUp ? 1 : 0; + + QPoint center = option->rect.center(); + painter->drawLine(center.x() + add, center.y() + 1 + add, + center.x() + 2 + add, center.y() + 1 + add); + painter->drawPoint(center.x() + 1 + add, center.y() + add); + break; + } + case PE_IndicatorSpinDown: { + const QStyleOptionSpinBox *spinner = + qstyleoption_cast<const QStyleOptionSpinBox *>(option); + + int add = spinner->state & State_Sunken && + spinner->activeSubControls & SC_SpinBoxDown ? 1 : 0; + QPoint center = option->rect.center(); + painter->drawLine(center.x() + add, center.y() + add, + center.x() + 2 + add, center.y() + add); + painter->drawPoint(center.x() + 1 + add, center.y() + 1 + add); + break; + } + case PE_FrameDockWidget: { + drawPrimitive(PE_FrameWindow, option, painter, widget); + break; + } + case PE_IndicatorToolBarHandle: { + QPoint offset; + bool horizontal = option->state & State_Horizontal; + + if (horizontal) + offset = option->rect.topLeft(); + else + offset = option->rect.topLeft(); + + int iterations = horizontal ? option->rect.height() : + option->rect.width(); + + for (int i = 0; i < iterations; ++i) { + painter->setPen(i % 2 ? Qt::white : + option->palette.color(QPalette::Mid)); + int add = i % 4; + painter->drawPoint(offset + xySwitch(QPoint(add, i), + horizontal)); + painter->drawPoint(offset + xySwitch(QPoint(add + 4, i), + horizontal)); + if (add + 8 < 10) + painter->drawPoint(offset + xySwitch(QPoint(add + 8, i), + horizontal)); + } + + break; + } + case PE_IndicatorToolBarSeparator: { + break; + } + case PE_PanelButtonTool: { + const QStyleOptionToolButton *button = + qstyleoption_cast<const QStyleOptionToolButton *>(option); + + if (!button) { + painter->setPen(Qt::red); + if (!(option->state & State_Enabled)) + painter->drawRect(option->rect.adjusted(0, 0, -1, -1)); + drawButtonBackground(option, painter, false); + break; + } + + if (button->state & State_MouseOver || button->state & State_On) { + QStyleOptionButton bevel; + bevel.state = button->state; + bevel.rect = button->rect; + bevel.palette = button->palette; + + drawButtonBackground(&bevel, painter, false); + } else { + painter->setPen(Qt::NoPen); + painter->setBrush(button->palette.color(QPalette::Background)); + + painter->drawRect(button->rect.adjusted(0, 0, -1, -1)); + } + break; + } + case PE_FrameMenu: { + painter->setPen(option->palette.color(QPalette::Midlight)); + painter->drawRect(option->rect.adjusted(0, 0, -1, -1)); + break; + } + case PE_PanelButtonCommand: { + const QStyleOptionButton *btn = + qstyleoption_cast<const QStyleOptionButton *>(option); + bool hover = (btn->state & State_Enabled) && + (btn->state & State_MouseOver); + bool sunken = btn->state & State_Sunken; + bool isDefault = btn->features & QStyleOptionButton::DefaultButton; + bool on = option->state & State_On; + + drawButtonBackground(option, painter, false); + + QRect rect = option->rect.adjusted(0, 0, -1, -1); + if (hover && !sunken && !isDefault && !on) { + drawButtonHoverFrame(painter, rect, + btn->palette.color(QPalette::Mid), + btn->palette.color(QPalette::Button)); + } else if (isDefault) { + drawPrimitive(PE_FrameDefaultButton, option, painter, widget); + } + break; + } + case PE_FrameDefaultButton: { + painter->setPen(option->palette.color(QPalette::Mid)); + QRect rect = option->rect.adjusted(0, 0, -1, -1); + painter->drawRect(rect); + painter->drawRect(rect.adjusted(1, 1, -1, -1)); + break; + } +//! [0] + case PE_IndicatorCheckBox: { + painter->save(); + drawButtonBackground(option, painter, true); + + if (option->state & State_Enabled && + option->state & State_MouseOver && + !(option->state & State_Sunken)) { + painter->setPen(option->palette.color(QPalette::Button)); + QRect rect = option->rect.adjusted(1, 1, -2, -2); + painter->drawRect(rect); + rect = rect.adjusted(1, 1, -1, -1); + painter->drawRect(rect); + } + + if (option->state & State_On) { + QImage image(":/images/checkboxchecked.png"); + painter->drawImage(option->rect.topLeft(), image); + } + painter->restore(); + break; +//! [0] + } + case PE_IndicatorRadioButton: { + painter->save(); + QBrush radioBrush = option->palette.button(); + + if (!(option->state & State_Sunken) && + option->state & State_Enabled) + radioBrush = gradientBrush(option->rect); + + painter->setBrush(radioBrush); + if (option->state & State_Enabled) + painter->setPen(option->palette.color(QPalette::Mid)); + else + painter->setPen(option->palette.color(QPalette::Disabled, + QPalette::WindowText)); + painter->drawEllipse(option->rect.adjusted(0, 0, -1, -1)); + + if (option->state & State_MouseOver && + option->state & State_Enabled && + !(option->state & State_Sunken)) { + gradientBrush(option->rect); + painter->setPen(option->palette.color(QPalette::Button)); + painter->setBrush(Qt::NoBrush); + QRect rect = option->rect.adjusted(1, 1, -2, -2); + painter->drawEllipse(rect); + rect = rect.adjusted(1, 1, -1, -1); + painter->drawEllipse(rect); + } + + if (option->state & State_On) { + painter->setBrush(option->palette.color(QPalette::Text)); + painter->setPen(Qt::NoPen); + painter->drawEllipse(option->rect.adjusted(3, 3, -3, -3)); + } + if (option->state & State_Sunken && + option->state & State_Enabled) { + painter->setPen(option->palette.color(QPalette::Mid)); + painter->drawArc(option->rect.adjusted(1, 1, -2, -2), 80 * 16, + 100 * 16); + } + painter->restore(); + break; + } + case PE_FrameTabWidget: { + painter->setPen(option->palette.color(QPalette::Midlight)); + painter->drawRect(option->rect.adjusted(0, 0, -1, -1)); + painter->setPen(Qt::white); + painter->drawRect(option->rect.adjusted(1, 1, -2, -2)); + break; + } + case PE_Frame: + case PE_FrameLineEdit: { + const QStyleOptionFrame *frame = + qstyleoption_cast<const QStyleOptionFrame *>(option); + const QStyleOptionFrameV2 frameV2(*frame); + + painter->setPen(frame->palette.color(QPalette::Mid)); + painter->drawRect(frameV2.rect.adjusted(0, 0, -2, -2)); + painter->setPen(Qt::white); + painter->drawRect(frameV2.rect.adjusted(1, 1, -1, -1)); + painter->setPen(frameV2.palette.color(QPalette::Active, + QPalette::Background)); + painter->drawLine(frameV2.rect.bottomLeft(), + frameV2.rect.bottomLeft() + QPoint(1, -1)); + painter->drawLine(frameV2.rect.topRight(), + frameV2.rect.topRight() + QPoint(-1, 1)); + break; + } + case PE_FrameFocusRect: { + painter->setPen(option->palette.color(QPalette::Light)); + painter->setBrush(Qt::NoBrush); + QRect rect = option->rect; + rect = rect.adjusted(0,0, -1, -1); + painter->drawRect(rect); + break; + } + default: + QWindowsStyle::drawPrimitive(element, option, painter, widget); + } + painter->restore(); +} + +//! [1] +void JavaStyle::drawButtonBackground(const QStyleOption *option, + QPainter *painter, bool isCheckbox) const +{ + QBrush buttonBrush = option->palette.button(); + bool sunken = option->state & State_Sunken; + bool disabled = !(option->state & State_Enabled); + bool on = option->state & State_On; + + if (!sunken && !disabled && (!on || isCheckbox)) + buttonBrush = gradientBrush(option->rect); + + painter->fillRect(option->rect, buttonBrush); + + QRect rect = option->rect.adjusted(0, 0, -1, -1); + + if (disabled) + painter->setPen(option->palette.color(QPalette::Disabled, + QPalette::WindowText)); + else + painter->setPen(option->palette.color(QPalette::Mid)); + + painter->drawRect(rect); + + if (sunken && !disabled) { + drawSunkenButtonShadow(painter, rect, + option->palette.color(QPalette::Mid), + option->direction == Qt::RightToLeft); + } +} +//! [1] + +QBrush JavaStyle::gradientBrush(const QRect &rect) const +{ + QLinearGradient gradient(rect.topLeft(), rect.bottomLeft()); + gradient.setColorAt(1.0, QColor(188, 210, 230)); + gradient.setColorAt(0.3, Qt::white); + gradient.setColorAt(0.0, QColor(223, 233, 243)); + + return QBrush(gradient); +} + +QRect JavaStyle::subElementRect(SubElement element, + const QStyleOption *option, + const QWidget *widget) const +{ + QRect rect; + + switch (element) { + case SE_ToolBoxTabContents: { + const QStyleOptionToolBox *box = + qstyleoption_cast<const QStyleOptionToolBox *>(option); + + rect.moveTopLeft(box->rect.topLeft() + QPoint(0, 2)); + rect.setHeight(box->rect.height() - 4); + rect.setWidth(box->fontMetrics.width(box->text) + 15); + break; + } + case SE_ProgressBarLabel: + case SE_ProgressBarGroove: + case SE_ProgressBarContents: { + rect = option->rect.adjusted(1, 1, -1, -1); + break; + } + case SE_PushButtonFocusRect: { + const QStyleOptionButton *btn = + qstyleoption_cast<const QStyleOptionButton *>(option); + + rect = btn->fontMetrics.boundingRect(btn->text); + rect = QRect(0, 0, btn->fontMetrics.width(btn->text), + rect.height()); + + if (!btn->icon.isNull()) { + rect.adjust(0, 0, btn->iconSize.width(), btn->iconSize.height() + > rect.height() ? btn->iconSize.height() - rect.height() : 0); + rect.translate(-btn->iconSize.width(), 0); + rect.adjust(-1, -1, 1, 1); + } + rect = QRect(int(ceil((btn->rect.width() - rect.width()) / 2.0)), + int(ceil((btn->rect.height() - rect.height()) / 2.0)), + rect.width() - 1, rect.height()); + rect.adjust(-1, 0, 1, 0); + + break; + } + default: + rect = QWindowsStyle::subElementRect(element, option, widget); + } + return rect; +} + +int JavaStyle::pixelMetric(PixelMetric metric, + const QStyleOption* /* option */, + const QWidget* /*widget*/) const +{ + int value = 0; + + switch (metric) { + case PM_ButtonShiftHorizontal: + case PM_ButtonShiftVertical: + case PM_TabBarTabShiftHorizontal: + case PM_ButtonDefaultIndicator: + case PM_TabBarTabShiftVertical: + value = 0; + break; + case PM_TabBarBaseOverlap: + case PM_DefaultFrameWidth: + value = 2; + break; + case PM_TabBarTabVSpace: + value = 4; + break; + case PM_ScrollBarExtent: + value = 16; + break; + case PM_ScrollBarSliderMin: + value = 26; + break; + case PM_SplitterWidth: + value = 8; + break; + case PM_SliderThickness: + value = 16; + break; + case PM_SliderControlThickness: + value = 16; + break; + case PM_SliderTickmarkOffset: + value = 10; + break; + case PM_SliderSpaceAvailable: + break; + case PM_MenuPanelWidth: + value = 1; + break; + case PM_MenuVMargin: + value = 2; + break; + case PM_MenuBarPanelWidth: + value = 1; + break; + case PM_MenuBarItemSpacing: + value = 0; + break; + case PM_MenuBarHMargin: + value = 3; + break; + case PM_MenuBarVMargin: + value = 0; + break; + case PM_ComboBoxFrameWidth: + value = 1; + break; + case PM_MenuButtonIndicator: + value = 15; + break; + case PM_ToolBarItemMargin: + value = 3; + break; + case PM_ToolBarHandleExtent: + value = 13; + break; + case PM_SpinBoxFrameWidth: + value = 2; + break; + case PM_TitleBarHeight: { + value = 21; + break; + case PM_MDIFrameWidth: + value = 6; + break; + } + case PM_DockWidgetFrameWidth: { + value = 5; + break; + } + default: + value = QWindowsStyle::pixelMetric(metric); + } + return value; +} + + +int JavaStyle::styleHint(StyleHint hint, const QStyleOption *option, + const QWidget *widget, + QStyleHintReturn *returnData) const +{ + int ret; + + switch (hint) { + case SH_Table_GridLineColor: { + ret = static_cast<int>(option->palette.color(QPalette::Mid).rgb()); + break; + } + case QStyle::SH_Menu_Scrollable: + ret = 1; + break; + default: + ret = QWindowsStyle::styleHint(hint, option, widget, returnData); + } + return ret; +} + +QPixmap JavaStyle::standardPixmap(StandardPixmap standardPixmap, + const QStyleOption *option, + const QWidget *widget) const +{ + QPixmap pixmap = QWindowsStyle::standardPixmap(standardPixmap, option, + widget); + + QPixmap maximizePixmap(":/images/internalmaximize.png"); + QPixmap minimizePixmap(":/images/internalminimize.png"); + QPixmap closePixmap(":/images/internalclose.png"); + QPixmap internalPixmap(":/images/internalsystem.png"); + QPixmap internalCloseDownPixmap(":/images/internalclosedown.png"); + QPixmap minimizeDownPixmap(":/images/internalminimizedown.png"); + QPixmap maximizeDownPixmap(":/images/internalmaximizedown.png"); + QPixmap dirOpenPixmap(":/images/open24.png"); + QPixmap filePixmap(":/images/file.png"); + + switch (standardPixmap) { + case SP_DirLinkIcon: + case SP_DirClosedIcon: + case SP_DirIcon: + case SP_DirOpenIcon: { + pixmap = closePixmap; + break; + } + case SP_FileIcon: { + pixmap = filePixmap; + break; + } + case SP_FileDialogBack: { + pixmap = QPixmap(":/images/fileback.png"); + break; + } + case SP_FileDialogToParent: { + pixmap = QPixmap(":/images/fileparent.png"); + break; + } + case SP_FileDialogNewFolder: { + pixmap = QPixmap(":/images/open24.png"); + break; + } + case SP_FileDialogListView: { + pixmap = QPixmap(":/images/filelist.png"); + break; + } + case SP_FileDialogDetailedView: { + pixmap = QPixmap(":/images/filedetail.png"); + break; + } + case SP_MessageBoxInformation: { + pixmap = QPixmap(":/images/information.png"); + break; + } + case SP_MessageBoxWarning: { + pixmap = QPixmap(":/images/warning.png"); + } + case SP_MessageBoxCritical: { + pixmap = QPixmap(":/images/critical.png"); + break; + } + case SP_MessageBoxQuestion: { + pixmap = QPixmap(":/images/question.png"); + break; + } + case SP_TitleBarNormalButton: + pixmap = maximizePixmap; + break; + case SP_TitleBarCloseButton: + pixmap = closePixmap; + break; + default: + ; + } + + return pixmap; +} + +QSize JavaStyle::sizeFromContents(ContentsType type, + const QStyleOption *option, + const QSize &contentsSize, + const QWidget *widget) const +{ + switch (type) { + case CT_ComboBox: { + return QSize(contentsSize.width() + 27, contentsSize.height()); + } + case CT_Slider: { + const QStyleOptionSlider *slider = + qstyleoption_cast<const QStyleOptionSlider *>(option); + if (slider->tickPosition == QSlider::TicksBelow) { + return QSize(contentsSize.width(), contentsSize.height() + 15); + } else { + return contentsSize; + } + } + case CT_MenuBarItem: { + const QStyleOptionMenuItem *menuItem = + qstyleoption_cast<const QStyleOptionMenuItem *>(option); + QFontMetrics metrics(menuItem->font); + QRect boundingRect = metrics.boundingRect(menuItem->text); + int width = boundingRect.width() + 14; + int height = boundingRect.height() + 3; + if (height < 20) + height = 20; + + return QSize(width, height); + } + case CT_MenuItem: { + const QStyleOptionMenuItem *menuItem = + qstyleoption_cast<const QStyleOptionMenuItem *>(option); + QSize defaultSize = QWindowsStyle::sizeFromContents(type, option, + contentsSize, widget); + + if (menuItem->menuItemType == QStyleOptionMenuItem::Separator) + return defaultSize; + + int width = 30; + int height = 0; + + if (!menuItem->icon.isNull()) { + width += 20; + height += 20; + } + if (!menuItem->text.isEmpty()) { + QFontMetrics metrics(menuItem->font); + QString text = menuItem->text; + text.remove(QLatin1Char('\t')); + QRect textRect = metrics.boundingRect(text); + width += textRect.width(); + if (height < textRect.height()) + height += textRect.height(); + } + if (menuItem->checkType != QStyleOptionMenuItem::NotCheckable) { + width += 10; + if (height < 10) + height = 10; + } + return QSize(width, height); + } + default: + return QWindowsStyle::sizeFromContents(type, option, contentsSize, + widget); + } +} diff --git a/doc/src/snippets/layouts/layouts.cpp b/doc/src/snippets/layouts/layouts.cpp new file mode 100644 index 0000000000..2fdde84990 --- /dev/null +++ b/doc/src/snippets/layouts/layouts.cpp @@ -0,0 +1,165 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> + +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + + { +//! [0] + QWidget *window = new QWidget; +//! [0] //! [1] + QPushButton *button1 = new QPushButton("One"); +//! [1] //! [2] + QPushButton *button2 = new QPushButton("Two"); + QPushButton *button3 = new QPushButton("Three"); + QPushButton *button4 = new QPushButton("Four"); + QPushButton *button5 = new QPushButton("Five"); +//! [2] + +//! [3] + QHBoxLayout *layout = new QHBoxLayout; +//! [3] //! [4] + layout->addWidget(button1); + layout->addWidget(button2); + layout->addWidget(button3); + layout->addWidget(button4); + layout->addWidget(button5); + + window->setLayout(layout); +//! [4] + window->setWindowTitle("QHBoxLayout"); +//! [5] + window->show(); +//! [5] + } + + { +//! [6] + QWidget *window = new QWidget; +//! [6] //! [7] + QPushButton *button1 = new QPushButton("One"); +//! [7] //! [8] + QPushButton *button2 = new QPushButton("Two"); + QPushButton *button3 = new QPushButton("Three"); + QPushButton *button4 = new QPushButton("Four"); + QPushButton *button5 = new QPushButton("Five"); +//! [8] + +//! [9] + QVBoxLayout *layout = new QVBoxLayout; +//! [9] //! [10] + layout->addWidget(button1); + layout->addWidget(button2); + layout->addWidget(button3); + layout->addWidget(button4); + layout->addWidget(button5); + + window->setLayout(layout); +//! [10] + window->setWindowTitle("QVBoxLayout"); +//! [11] + window->show(); +//! [11] + } + + { +//! [12] + QWidget *window = new QWidget; +//! [12] //! [13] + QPushButton *button1 = new QPushButton("One"); +//! [13] //! [14] + QPushButton *button2 = new QPushButton("Two"); + QPushButton *button3 = new QPushButton("Three"); + QPushButton *button4 = new QPushButton("Four"); + QPushButton *button5 = new QPushButton("Five"); +//! [14] + +//! [15] + QGridLayout *layout = new QGridLayout; +//! [15] //! [16] + layout->addWidget(button1, 0, 0); + layout->addWidget(button2, 0, 1); + layout->addWidget(button3, 1, 0, 1, 2); + layout->addWidget(button4, 2, 0); + layout->addWidget(button5, 2, 1); + + window->setLayout(layout); +//! [16] + window->setWindowTitle("QGridLayout"); +//! [17] + window->show(); +//! [17] + } + + { +//! [18] + QWidget *window = new QWidget; +//! [18] +//! [19] + QPushButton *button1 = new QPushButton("One"); + QLineEdit *lineEdit1 = new QLineEdit(); +//! [19] +//! [20] + QPushButton *button2 = new QPushButton("Two"); + QLineEdit *lineEdit2 = new QLineEdit(); + QPushButton *button3 = new QPushButton("Three"); + QLineEdit *lineEdit3 = new QLineEdit(); +//! [20] +//! [21] + QFormLayout *layout = new QFormLayout; +//! [21] +//! [22] + layout->addRow(button1, lineEdit1); + layout->addRow(button2, lineEdit2); + layout->addRow(button3, lineEdit3); + + window->setLayout(layout); +//! [22] + window->setWindowTitle("QFormLayout"); +//! [23] + window->show(); +//! [23] + } + + return app.exec(); +} diff --git a/doc/src/snippets/mainwindowsnippet.cpp b/doc/src/snippets/mainwindowsnippet.cpp new file mode 100644 index 0000000000..70e638e7af --- /dev/null +++ b/doc/src/snippets/mainwindowsnippet.cpp @@ -0,0 +1,92 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> + +#include "mainwindow.h" + +MainWindow::MainWindow() +{ + createMenus(); + createToolBars(); + createDockWidgets(); + //setMenuWidget(new QPushButton("Hello")); +} + +void MainWindow::createMenus() +{ + //setMenuWidget(new QPushButton("Hello")); + QMenu *menu = new QMenu("File"); + menu->addAction("Save &As"); + + QMenuBar *bar = new QMenuBar; + bar->addMenu(menu); + + setMenuWidget(new QWidget()); +} + +void MainWindow::createToolBars() +{ + setToolButtonStyle(Qt::ToolButtonTextOnly); + QToolBar *t1 = new QToolBar; + t1->addAction(new QAction("t1", this)); + + QToolBar *t2 = new QToolBar; + t2->addAction(new QAction("t2", this)); + + addToolBar(Qt::LeftToolBarArea, t1); + addToolBar(Qt::LeftToolBarArea, t2); +} + +void MainWindow::createDockWidgets() +{ + QWidget *dockWidgetContents = new QWidget; + QVBoxLayout *layout = new QVBoxLayout; + layout->addWidget(new QPushButton("My Button.")); + dockWidgetContents->setLayout(layout); + +//! [0] + QDockWidget *dockWidget = new QDockWidget(tr("Dock Widget"), this); + dockWidget->setAllowedAreas(Qt::LeftDockWidgetArea | + Qt::RightDockWidgetArea); + dockWidget->setWidget(dockWidgetContents); + addDockWidget(Qt::LeftDockWidgetArea, dockWidget); +//! [0] +} diff --git a/doc/src/snippets/matrix/matrix.cpp b/doc/src/snippets/matrix/matrix.cpp new file mode 100644 index 0000000000..c7eb0b5943 --- /dev/null +++ b/doc/src/snippets/matrix/matrix.cpp @@ -0,0 +1,140 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> +#include <cmath> + +class SimpleTransformation : public QWidget +{ + void paintEvent(QPaintEvent *); +}; + +//! [0] +void SimpleTransformation::paintEvent(QPaintEvent *) +{ + QPainter painter(this); + painter.setPen(QPen(Qt::blue, 1, Qt::DashLine)); + painter.drawRect(0, 0, 100, 100); + + painter.rotate(45); + + painter.setFont(QFont("Helvetica", 24)); + painter.setPen(QPen(Qt::black, 1)); + painter.drawText(20, 10, "QMatrix"); +} +//! [0] + +class CombinedTransformation : public QWidget +{ + void paintEvent(QPaintEvent *); +}; + +//! [1] +void CombinedTransformation::paintEvent(QPaintEvent *) +{ + QPainter painter(this); + painter.setPen(QPen(Qt::blue, 1, Qt::DashLine)); + painter.drawRect(0, 0, 100, 100); + + QMatrix matrix; + matrix.translate(50, 50); + matrix.rotate(45); + matrix.scale(0.5, 1.0); + painter.setMatrix(matrix); + + painter.setFont(QFont("Helvetica", 24)); + painter.setPen(QPen(Qt::black, 1)); + painter.drawText(20, 10, "QMatrix"); +} +//! [1] + +class BasicOperations : public QWidget +{ + void paintEvent(QPaintEvent *); +}; + +//! [2] +void BasicOperations::paintEvent(QPaintEvent *) +{ + double pi = 3.14; + + double a = pi/180 * 45.0; + double sina = sin(a); + double cosa = cos(a); + + QMatrix translationMatrix(1, 0, 0, 1, 50.0, 50.0); + QMatrix rotationMatrix(cosa, sina, -sina, cosa, 0, 0); + QMatrix scalingMatrix(0.5, 0, 0, 1.0, 0, 0); + + QMatrix matrix; + matrix = scalingMatrix * rotationMatrix * translationMatrix; + + QPainter painter(this); + painter.setPen(QPen(Qt::blue, 1, Qt::DashLine)); + painter.drawRect(0, 0, 100, 100); + + painter.setMatrix(matrix); + + painter.setFont(QFont("Helvetica", 24)); + painter.setPen(QPen(Qt::black, 1)); + painter.drawText(20, 10, "QMatrix"); +} +//! [2] + +int main(int argc, char **argv) +{ + QApplication app(argc, argv); + + QWidget widget; + + SimpleTransformation *simpleWidget = new SimpleTransformation; + CombinedTransformation *combinedWidget = new CombinedTransformation; + BasicOperations *basicWidget = new BasicOperations; + + QVBoxLayout *layout = new QVBoxLayout; + layout->addWidget(simpleWidget); + layout->addWidget(combinedWidget); + layout->addWidget(basicWidget); + widget.setLayout(layout); + + widget.show(); + widget.resize(130, 350); + return app.exec(); +} diff --git a/doc/src/snippets/mdiareasnippets.cpp b/doc/src/snippets/mdiareasnippets.cpp new file mode 100644 index 0000000000..9d626a3f8d --- /dev/null +++ b/doc/src/snippets/mdiareasnippets.cpp @@ -0,0 +1,97 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> + +void mainWindowExample() +{ + QMdiArea *mdiArea = new QMdiArea; +//! [0] + QMainWindow *mainWindow = new QMainWindow; + mainWindow->setCentralWidget(mdiArea); +//! [0] + + mdiArea->addSubWindow(new QPushButton("Push Me Now!")); + + mainWindow->show(); +} + +void addingSubWindowsExample() +{ + QWidget *internalWidget1 = new QWidget; + QWidget *internalWidget2 = new QWidget; + +//! [1] + QMdiArea mdiArea; + QMdiSubWindow *subWindow1 = new QMdiSubWindow; + subWindow1->setWidget(internalWidget1); + subWindow1->setAttribute(Qt::WA_DeleteOnClose); + mdiArea.addSubWindow(subWindow1); + + QMdiSubWindow *subWindow2 = + mdiArea.addSubWindow(internalWidget2); + +//! [1] + subWindow1->show(); + subWindow2->show(); + + mdiArea.show(); +} + +int main(int argv, char **args) +{ + QApplication app(argv, args); + + mainWindowExample(); + //addingSubWindowsExample(); + + QAction *act = new QAction(qApp); + act->setShortcut(Qt::ALT + Qt::Key_S); + act->setShortcutContext( Qt::ApplicationShortcut ); + QObject::connect(act, SIGNAL(triggered()), qApp, SLOT(aboutQt())); + + QWidget widget5; + widget5.show(); + widget5.addAction(act); + + return app.exec(); +} + + diff --git a/doc/src/snippets/myscrollarea.cpp b/doc/src/snippets/myscrollarea.cpp new file mode 100644 index 0000000000..93b487d317 --- /dev/null +++ b/doc/src/snippets/myscrollarea.cpp @@ -0,0 +1,128 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> + +class MyScrollArea : public QAbstractScrollArea +{ +public: + MyScrollArea(QWidget *w); + void setWidget(QWidget *w); + +protected: + void scrollContentsBy(int dx, int dy); + void resizeEvent(QResizeEvent *event); + +private: + void updateWidgetPosition(); + void updateArea(); + + QWidget *widget; +}; + +MyScrollArea::MyScrollArea(QWidget *widget) + : QAbstractScrollArea() +{ + setWidget(widget); +} + +void MyScrollArea::setWidget(QWidget *w) +{ + widget = w; + widget->setParent(viewport()); + if (!widget->testAttribute(Qt::WA_Resized)) + widget->resize(widget->sizeHint()); + + verticalScrollBar()->setValue(0); + verticalScrollBar()->setValue(0); + + updateArea(); +} + +void MyScrollArea::updateWidgetPosition() +{ +//! [0] + int hvalue = horizontalScrollBar()->value(); + int vvalue = verticalScrollBar()->value(); + QPoint topLeft = viewport()->rect().topLeft(); + + widget->move(topLeft.x() - hvalue, topLeft.y() - vvalue); +//! [0] +} + +void MyScrollArea::scrollContentsBy(int /*dx*/, int /*dy*/) +{ + updateWidgetPosition(); +} + +void MyScrollArea::updateArea() +{ +//! [1] + QSize areaSize = viewport()->size(); + QSize widgetSize = widget->size(); + + verticalScrollBar()->setPageStep(widgetSize.height()); + horizontalScrollBar()->setPageStep(widgetSize.width()); + verticalScrollBar()->setRange(0, widgetSize.height() - areaSize.height()); + horizontalScrollBar()->setRange(0, widgetSize.width() - areaSize.width()); + updateWidgetPosition(); +//! [1] +} + +void MyScrollArea::resizeEvent(QResizeEvent *event) +{ + updateArea(); +} + +int main(int argv, char **args) +{ + QApplication app(argv, args); + + QPixmap pixmap("mypixmap.png"); + QLabel label; + label.setPixmap(pixmap); + MyScrollArea area(&label); + area.resize(300, 300); + area.show(); + + area.setWidget(&label); + + return app.exec(); +} diff --git a/doc/src/snippets/network/tcpwait.cpp b/doc/src/snippets/network/tcpwait.cpp new file mode 100644 index 0000000000..02cecb4f87 --- /dev/null +++ b/doc/src/snippets/network/tcpwait.cpp @@ -0,0 +1,69 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> +#include <QTcpSocket> + +#include "server.h" + +int main(int argv, char **args) +{ + QCoreApplication app(argv, args); + + QTcpSocket socket; + socket.connectToHost("localhost", 1025); + +//! [0] + int numRead = 0, numReadTotal = 0; + char buffer[50]; + + forever { + numRead = socket.read(buffer, 50); + + // do whatever with array + + numReadTotal += numRead; + if (numRead == 0 && !socket.waitForReadyRead()) + break; + } +//! [0] + + return app.exec(); +} diff --git a/doc/src/snippets/ntfsp.cpp b/doc/src/snippets/ntfsp.cpp new file mode 100644 index 0000000000..5d457124b2 --- /dev/null +++ b/doc/src/snippets/ntfsp.cpp @@ -0,0 +1,50 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + + +//! [0] +extern Q_CORE_EXPORT int qt_ntfs_permission_lookup; +//! [0] + +//! [1] +qt_ntfs_permission_lookup++; // turn checking on +qt_ntfs_permission_lookup--; // turn it off again +//! [1] + diff --git a/doc/src/snippets/picture/picture.cpp b/doc/src/snippets/picture/picture.cpp new file mode 100644 index 0000000000..3cead763e1 --- /dev/null +++ b/doc/src/snippets/picture/picture.cpp @@ -0,0 +1,151 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> + +void myProcessing(const QString &) +{ +} + +int main() +{ + QWidget myWidget; + { + // RECORD +//! [0] + QPicture picture; + QPainter painter; + painter.begin(&picture); // paint in picture + painter.drawEllipse(10,20, 80,70); // draw an ellipse + painter.end(); // painting done + picture.save("drawing.pic"); // save picture +//! [0] + } + + { + // REPLAY +//! [1] + QPicture picture; + picture.load("drawing.pic"); // load picture + QPainter painter; + painter.begin(&myImage); // paint in myImage + painter.drawPicture(0, 0, picture); // draw the picture at (0,0) + painter.end(); // painting done +//! [1] + } + + QPicture myPicture; + { + // FORMATS +//! [2] + QStringList list = QPicture::inputFormatList(); + foreach (const QString &string, list) + myProcessing(string); +//! [2] + } + + { + // OUTPUT +//! [3] + QStringList list = QPicture::outputFormatList(); + foreach (const QString &string, list) + myProcessing(string); +//! [3] + } + + { + // PIC READ +//! [4] + QPictureIO iio; + QPixmap pixmap; + iio.setFileName("vegeburger.pic"); + if (iio.read()) { // OK + QPicture picture = iio.picture(); + QPainter painter(&pixmap); + painter.drawPicture(0, 0, picture); + } +//! [4] + } + + { + QPixmap pixmap; + // PIC WRITE +//! [5] + QPictureIO iio; + QPicture picture; + QPainter painter(&picture); + painter.drawPixmap(0, 0, pixmap); + iio.setPicture(picture); + iio.setFileName("vegeburger.pic"); + iio.setFormat("PIC"); + if (iio.write()) + return true; // returned true if written successfully +//! [5] + } + +} + +// SVG READ +//! [6] +void readSVG(QPictureIO *picture) +{ + // read the picture using the picture->ioDevice() +} +//! [6] + +// SVG WRITE +//! [7] +void writeSVG(QPictureIO *picture) +{ + // write the picture using the picture->ioDevice() +} +//! [7] + +// USE SVG +void foo() { + +//! [8] + // add the SVG picture handler + // ... +//! [8] + QPictureIO::defineIOHandler("SVG", 0, 0, readSVG, writeSVG); + // ... + +} diff --git a/doc/src/snippets/pointer/pointer.cpp b/doc/src/snippets/pointer/pointer.cpp new file mode 100644 index 0000000000..b4ff3839cb --- /dev/null +++ b/doc/src/snippets/pointer/pointer.cpp @@ -0,0 +1,60 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QApplication> +#include <QLabel> +#include <QPointer> + +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + +//! [0] + QPointer<QLabel> label = new QLabel; + label->setText("&Status:"); +//! [0] + +//! [1] + if (label) +//! [1] //! [2] + label->show(); +//! [2] + return 0; +} diff --git a/doc/src/snippets/polygon/polygon.cpp b/doc/src/snippets/polygon/polygon.cpp new file mode 100644 index 0000000000..8b81db668d --- /dev/null +++ b/doc/src/snippets/polygon/polygon.cpp @@ -0,0 +1,112 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> + +int main() +{ + { + // STREAM +//! [0] + QPolygon polygon; + polygon << QPoint(10, 20) << QPoint(20, 30); +//! [0] + } + + { + // STREAMF +//! [1] + QPolygonF polygon; + polygon << QPointF(10.4, 20.5) << QPointF(20.2, 30.2); +//! [1] + } + + { + // SETPOINTS +//! [2] + static const int points[] = { 10, 20, 30, 40 }; + QPolygon polygon; + polygon.setPoints(2, points); +//! [2] + } + + { + // SETPOINTS2 +//! [3] + QPolygon polygon; + polygon.setPoints(2, 10, 20, 30, 40); +//! [3] + } + + { + // PUTPOINTS +//! [4] + QPolygon polygon(1); + polygon[0] = QPoint(4, 5); + polygon.putPoints(1, 2, 6,7, 8,9); +//! [4] + } + + { + // PUTPOINTS2 +//! [5] + QPolygon polygon(3); + polygon.putPoints(0, 3, 4,5, 0,0, 8,9); + polygon.putPoints(1, 1, 6,7); +//! [5] + } + + { + // PUTPOINTS3 +//! [6] + QPolygon polygon1; + polygon1.putPoints(0, 3, 1,2, 0,0, 5,6); + // polygon1 is now the three-point polygon(1,2, 0,0, 5,6); + + QPolygon polygon2; + polygon2.putPoints(0, 3, 4,4, 5,5, 6,6); + // polygon2 is now (4,4, 5,5, 6,6); + + polygon1.putPoints(2, 3, polygon2); + // polygon1 is now the five-point polygon(1,2, 0,0, 4,4, 5,5, 6,6); +//! [6] + } + return 0; +} diff --git a/doc/src/snippets/printing-qprinter/errors.cpp b/doc/src/snippets/printing-qprinter/errors.cpp new file mode 100644 index 0000000000..ff3ea9053e --- /dev/null +++ b/doc/src/snippets/printing-qprinter/errors.cpp @@ -0,0 +1,65 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> + +int main(int argc, char **argv) +{ + QApplication app(argc, argv); + +//! [0] + QPrinter printer; + printer.setOutputFormat(QPrinter::PdfFormat); + printer.setOutputFileName("/foobar/nonwritable.pdf"); + QPainter painter; + if (! painter.begin(&printer)) { // failed to open file + qWarning("failed to open file, is it writable?"); + return 1; + } + painter.drawText(10, 10, "Test"); + if (! printer.newPage()) { + qWarning("failed in flushing page to disk, disk full?"); + return 1; + } + painter.drawText(10, 10, "Test 2"); + painter.end(); +//! [0] + return 0; +} diff --git a/doc/src/snippets/printing-qprinter/object.cpp b/doc/src/snippets/printing-qprinter/object.cpp new file mode 100644 index 0000000000..0ee8dbdc56 --- /dev/null +++ b/doc/src/snippets/printing-qprinter/object.cpp @@ -0,0 +1,71 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> +#include "object.h" + +Object::Object(QObject *parent) + : QObject(parent) +{ +} + +void Object::print() +{ + int numberOfPages = 10; + int lastPage = numberOfPages - 1; + +//! [0] + QPrinter printer(QPrinter::HighResolution); + printer.setOutputFileName("print.ps"); + QPainter painter; + painter.begin(&printer); + + for (int page = 0; page < numberOfPages; ++page) { + + // Use the painter to draw on the page. + + if (page != lastPage) + printer.newPage(); + } + + painter.end(); +//! [0] + qApp->quit(); +} diff --git a/doc/src/snippets/process/process.cpp b/doc/src/snippets/process/process.cpp new file mode 100644 index 0000000000..a545b734bf --- /dev/null +++ b/doc/src/snippets/process/process.cpp @@ -0,0 +1,76 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QProcess> + +bool zip() +{ +//! [0] + QProcess gzip; + gzip.start("gzip", QStringList() << "-c"); + if (!gzip.waitForStarted()) + return false; + + gzip.write("Qt rocks!"); + gzip.closeWriteChannel(); + + if (!gzip.waitForFinished()) + return false; + + QByteArray result = gzip.readAll(); +//! [0] + + gzip.start("gzip", QStringList() << "-d" << "-c"); + gzip.write(result); + gzip.closeWriteChannel(); + + if (!gzip.waitForFinished()) + return false; + + qDebug("Result: %s", gzip.readAll().data()); + return true; +} + + +int main() +{ + zip(); + return 0; +} diff --git a/doc/src/snippets/qdbusextratypes/qdbusextratypes.cpp b/doc/src/snippets/qdbusextratypes/qdbusextratypes.cpp new file mode 100644 index 0000000000..1ab3488780 --- /dev/null +++ b/doc/src/snippets/qdbusextratypes/qdbusextratypes.cpp @@ -0,0 +1,66 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtCore> +#include <QtDBus> + +static QVariant callMyDBusFunction() { return QVariant(); } + +int main() +{ + QDBusMessage myDBusMessage; + +//! [0] + QList<QVariant> arguments; + arguments << QVariant(42) << QVariant::fromValue(QDBusVariant(43)) << QVariant("hello"); + myDBusMessage.setArguments(arguments); +//! [0] + +//! [1] + // call a D-Bus function that returns a D-Bus variant + QVariant v = callMyDBusFunction(); + // retrieve the D-Bus variant + QDBusVariant dbusVariant = qvariant_cast<QDBusVariant>(v); + // retrieve the actual value stored in the D-Bus variant + QVariant result = dbusVariant.variant(); +//! [1] + + return 0; +} diff --git a/doc/src/snippets/qdebug/qdebugsnippet.cpp b/doc/src/snippets/qdebug/qdebugsnippet.cpp new file mode 100644 index 0000000000..8e668d1736 --- /dev/null +++ b/doc/src/snippets/qdebug/qdebugsnippet.cpp @@ -0,0 +1,73 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> +#include <QtDebug> + +class Coordinate : public QObject +{ +public: + int myX, myY; + + int x() const { return myX; }; + int y() const { return myY; }; +}; + +//! [0] +QDebug operator<<(QDebug dbg, const Coordinate &c) +{ + dbg.nospace() << "(" << c.x() << ", " << c.y() << ")"; + + return dbg.space(); +} +//! [0] + +int main(int argv, char **args) +{ + Coordinate coordinate; + coordinate.myX = 10; + coordinate.myY = 44; + +//! [1] + qDebug() << "Date:" << QDate::currentDate(); + qDebug() << "Types:" << QString("String") << QChar('x') << QRect(0, 10, 50, 40); + qDebug() << "Custom coordinate type:" << coordinate; +//! [1] +} diff --git a/doc/src/snippets/qdir-listfiles/main.cpp b/doc/src/snippets/qdir-listfiles/main.cpp new file mode 100644 index 0000000000..cdce0d545a --- /dev/null +++ b/doc/src/snippets/qdir-listfiles/main.cpp @@ -0,0 +1,62 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +#include <QDir> +#include <iostream> + +int main(int argc, char *argv[]) +{ + QCoreApplication app(argc, argv); + QDir dir; + dir.setFilter(QDir::Files | QDir::Hidden | QDir::NoSymLinks); + dir.setSorting(QDir::Size | QDir::Reversed); + + QFileInfoList list = dir.entryInfoList(); + std::cout << " Bytes Filename" << std::endl; + for (int i = 0; i < list.size(); ++i) { + QFileInfo fileInfo = list.at(i); + std::cout << qPrintable(QString("%1 %2").arg(fileInfo.size(), 10) + .arg(fileInfo.fileName())); + std::cout << std::endl; + } + return 0; +} +//! [0] diff --git a/doc/src/snippets/qdir-namefilters/main.cpp b/doc/src/snippets/qdir-namefilters/main.cpp new file mode 100644 index 0000000000..a72bab1d0a --- /dev/null +++ b/doc/src/snippets/qdir-namefilters/main.cpp @@ -0,0 +1,65 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QDir> +#include <iostream> + +int main(int argc, char *argv[]) +{ + QDir dir; + dir.setFilter(QDir::Files | QDir::Hidden | QDir::NoSymLinks); + dir.setSorting(QDir::Size | QDir::Reversed); + +//! [0] + QStringList filters; + filters << "*.cpp" << "*.cxx" << "*.cc"; + dir.setNameFilters(filters); +//! [0] + + QFileInfoList list = dir.entryInfoList(); + std::cout << " Bytes Filename" << std::endl; + for (int i = 0; i < list.size(); ++i) { + QFileInfo fileInfo = list.at(i); + std::cout << qPrintable(QString("%1 %2").arg(fileInfo.size(), 10) + .arg(fileInfo.fileName())); + std::cout << std::endl; + } + return 0; +} diff --git a/doc/src/snippets/qelapsedtimer/main.cpp b/doc/src/snippets/qelapsedtimer/main.cpp new file mode 100644 index 0000000000..3e5b520f57 --- /dev/null +++ b/doc/src/snippets/qelapsedtimer/main.cpp @@ -0,0 +1,111 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the QtNetwork module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ +#include <QtCore> + +void slowOperation1() +{ + static char buf[256]; + for (int i = 0; i < (1<<20); ++i) + buf[i % sizeof buf] = i; +} + +void slowOperation2(int) { slowOperation1(); } + +void startExample() +{ +//![0] + QElapsedTimer timer; + timer.start(); + + slowOperation1(); + + qDebug() << "The slow operation took" << timer.elapsed() << "milliseconds"; +//![0] +} + +//![1] +void executeSlowOperations(int timeout) +{ + QElapsedTimer timer; + timer.start(); + slowOperation1(); + + int remainingTime = timeout - timer.elapsed(); + if (remainingTime > 0) + slowOperation2(remainingTime); +} +//![1] + +//![2] +void executeOperationsForTime(int ms) +{ + QElapsedTimer timer; + timer.start(); + + while (!timer.hasExpired(ms)) + slowOperation1(); +} +//![2] + +int restartExample() +{ +//![3] + QElapsedTimer timer; + + int count = 1; + timer.start(); + do { + count *= 2; + slowOperation2(count); + } while (timer.restart() < 250); + + return count; +//![3] +} + +int main(int argc, char **argv) +{ + QCoreApplication app(argc, argv); + + startExample(); + restartExample(); + executeSlowOperations(5); + executeOperationsForTime(5); +} diff --git a/doc/src/snippets/qfontdatabase/main.cpp b/doc/src/snippets/qfontdatabase/main.cpp new file mode 100644 index 0000000000..24ed688001 --- /dev/null +++ b/doc/src/snippets/qfontdatabase/main.cpp @@ -0,0 +1,74 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> + +int main(int argc, char **argv) +{ + QApplication app(argc, argv); + +//! [0] + QFontDatabase database; + QTreeWidget fontTree; + fontTree.setColumnCount(2); + fontTree.setHeaderLabels(QStringList() << "Font" << "Smooth Sizes"); + + foreach (const QString &family, database.families()) { + QTreeWidgetItem *familyItem = new QTreeWidgetItem(&fontTree); + familyItem->setText(0, family); + + foreach (const QString &style, database.styles(family)) { + QTreeWidgetItem *styleItem = new QTreeWidgetItem(familyItem); + styleItem->setText(0, style); + + QString sizes; + foreach (int points, database.smoothSizes(family, style)) + sizes += QString::number(points) + " "; + + styleItem->setText(1, sizes.trimmed()); + } +//! [0] //! [1] + } +//! [1] + + fontTree.resizeColumnToContents(0); + fontTree.show(); + return app.exec(); +} diff --git a/doc/src/snippets/qlistwidget-using/mainwindow.cpp b/doc/src/snippets/qlistwidget-using/mainwindow.cpp new file mode 100644 index 0000000000..0ec9c70ed3 --- /dev/null +++ b/doc/src/snippets/qlistwidget-using/mainwindow.cpp @@ -0,0 +1,158 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> + +#include "mainwindow.h" + +MainWindow::MainWindow() +{ + QMenu *fileMenu = new QMenu(tr("&File")); + + QAction *quitAction = fileMenu->addAction(tr("E&xit")); + quitAction->setShortcut(tr("Ctrl+Q")); + + QMenu *itemsMenu = new QMenu(tr("&Items")); + + insertAction = itemsMenu->addAction(tr("&Insert Item")); + removeAction = itemsMenu->addAction(tr("&Remove Item")); + QAction *ascendingAction = itemsMenu->addAction(tr("Sort in &Ascending Order")); + QAction *descendingAction = itemsMenu->addAction(tr("Sort in &Descending Order")); + + menuBar()->addMenu(fileMenu); + menuBar()->addMenu(itemsMenu); + +/* For convenient quoting: +//! [0] + QListWidget *listWidget = new QListWidget(this); +//! [0] +*/ + listWidget = new QListWidget(this); + listWidget->setSelectionMode(QAbstractItemView::SingleSelection); + + connect(quitAction, SIGNAL(triggered()), this, SLOT(close())); + connect(ascendingAction, SIGNAL(triggered()), this, SLOT(sortAscending())); + connect(descendingAction, SIGNAL(triggered()), this, SLOT(sortDescending())); + connect(insertAction, SIGNAL(triggered()), this, SLOT(insertItem())); + connect(removeAction, SIGNAL(triggered()), this, SLOT(removeItem())); + connect(listWidget, + SIGNAL(currentItemChanged(QListWidgetItem *, QListWidgetItem *)), + this, SLOT(updateMenus(QListWidgetItem *))); + + setupListItems(); + updateMenus(listWidget->currentItem()); + + setCentralWidget(listWidget); + setWindowTitle(tr("List Widget")); +} + +void MainWindow::setupListItems() +{ +//! [1] + new QListWidgetItem(tr("Oak"), listWidget); + new QListWidgetItem(tr("Fir"), listWidget); + new QListWidgetItem(tr("Pine"), listWidget); +//! [1] + new QListWidgetItem(tr("Birch"), listWidget); +//! [2] + new QListWidgetItem(tr("Hazel"), listWidget); +//! [2] + new QListWidgetItem(tr("Redwood"), listWidget); +//! [3] + new QListWidgetItem(tr("Sycamore"), listWidget); + new QListWidgetItem(tr("Chestnut"), listWidget); + new QListWidgetItem(tr("Mahogany"), listWidget); +//! [3] +} + +void MainWindow::sortAscending() +{ +//! [4] + listWidget->sortItems(Qt::AscendingOrder); +//! [4] +} + +void MainWindow::sortDescending() +{ +//! [5] + listWidget->sortItems(Qt::DescendingOrder); +//! [5] +} + +void MainWindow::insertItem() +{ + if (!listWidget->currentItem()) + return; + + QString itemText = QInputDialog::getText(this, tr("Insert Item"), + tr("Input text for the new item:")); + + if (itemText.isNull()) + return; + +//! [6] + QListWidgetItem *newItem = new QListWidgetItem; + newItem->setText(itemText); +//! [6] + int row = listWidget->row(listWidget->currentItem()); +//! [7] + listWidget->insertItem(row, newItem); +//! [7] + + QString toolTipText = tr("Tooltip:") + itemText; + QString statusTipText = tr("Status tip:") + itemText; + QString whatsThisText = tr("What's This?:") + itemText; +//! [8] + newItem->setToolTip(toolTipText); + newItem->setStatusTip(toolTipText); + newItem->setWhatsThis(whatsThisText); +//! [8] +} + +void MainWindow::removeItem() +{ + listWidget->takeItem(listWidget->row(listWidget->currentItem())); +} + +void MainWindow::updateMenus(QListWidgetItem *current) +{ + insertAction->setEnabled(current != 0); + removeAction->setEnabled(current != 0); +} diff --git a/doc/src/snippets/qmacnativewidget/main.mm b/doc/src/snippets/qmacnativewidget/main.mm new file mode 100644 index 0000000000..a57dc19a28 --- /dev/null +++ b/doc/src/snippets/qmacnativewidget/main.mm @@ -0,0 +1,134 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui/QtGui> +#include <QtGui/qmacnativewidget_mac.h> +#ifdef QT_MAC_USE_COCOA +#import <Cocoa/Cocoa.h> +#else +#include <Carbon/Carbon.h> +#endif + +int main(int argc, char **argv) +{ + QApplication app(argc, argv); +#ifdef QT_MAC_USE_COCOA +//![0] + NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init]; + NSWindow *window = [[NSWindow alloc] initWithContentRect:NSMakeRect(200, app.desktop()->height() - 200, 239, 200) + styleMask:NSTitledWindowMask | NSClosableWindowMask + | NSMiniaturizableWindowMask | NSResizableWindowMask + backing:NSBackingStoreBuffered defer:NO]; + + QMacNativeWidget *nativeWidget = new QMacNativeWidget(); + nativeWidget->move(0, 0); + nativeWidget->setPalette(QPalette(Qt::red)); + nativeWidget->setAutoFillBackground(true); + QVBoxLayout *layout = new QVBoxLayout(); + QPushButton *pushButton = new QPushButton("An Embedded Qt Button!", nativeWidget); + pushButton->setAttribute(Qt::WA_LayoutUsesWidgetRect); // Don't use the layout rect calculated from QMacStyle. + layout->addWidget(pushButton); + nativeWidget->setLayout(layout); + + // Adjust Cocoa layouts + NSView *nativeWidgetView = reinterpret_cast<NSView *>(nativeWidget->winId()); + NSView *contentView = [window contentView]; + [contentView setAutoresizesSubviews:YES]; + [nativeWidgetView setAutoresizingMask:NSViewWidthSizable | NSViewHeightSizable]; + [nativeWidgetView setAutoresizesSubviews:YES]; + NSView *pushButtonView = reinterpret_cast<NSView *>(pushButton->winId()); + [pushButtonView setAutoresizingMask:NSViewWidthSizable]; + + // Add the nativeWidget to the window. + [contentView addSubview:nativeWidgetView positioned:NSWindowAbove relativeTo:nil]; + nativeWidget->show(); + pushButton->show(); + + // Show the window. + [window makeKeyAndOrderFront:window]; + [pool release]; +//![0] +#else +//![1] + Rect contentRect; + SetRect(&contentRect, 200, 200, 400, 400); + HIWindowRef windowRef; + CreateNewWindow(kDocumentWindowClass, kWindowStandardDocumentAttributes | kWindowCompositingAttribute | kWindowStandardHandlerAttribute | kWindowLiveResizeAttribute, &contentRect, &windowRef); + HIViewRef contentView = 0; + GetRootControl(windowRef, &contentView); + + QMacNativeWidget *nativeWidget = new QMacNativeWidget(); + nativeWidget->move(0, 0); + nativeWidget->setPalette(QPalette(Qt::red)); + nativeWidget->setAutoFillBackground(true); + QVBoxLayout *layout = new QVBoxLayout(); + QPushButton *pushButton = new QPushButton("An Embedded Qt Button!", nativeWidget); + pushButton->setAttribute(Qt::WA_LayoutUsesWidgetRect); // Don't use the layout rect calculated from QMacStyle. + layout->addWidget(pushButton); + nativeWidget->setLayout(layout); + HIViewRef nativeWidgetView = reinterpret_cast<HIViewRef>(nativeWidget->winId()); + // Add the nativeWidget to the window. + HIViewAddSubview(contentView, nativeWidgetView); + + // Adjust Carbon layouts + HILayoutInfo layoutInfo; + layoutInfo.version = kHILayoutInfoVersionZero; + HIViewGetLayoutInfo(nativeWidgetView, &layoutInfo); + + layoutInfo.binding.top.toView = contentView; + layoutInfo.binding.top.kind = kHILayoutBindTop; + layoutInfo.binding.left.toView = contentView; + layoutInfo.binding.left.kind = kHILayoutBindLeft; + layoutInfo.binding.right.toView = contentView; + layoutInfo.binding.right.kind = kHILayoutBindRight; + layoutInfo.binding.bottom.toView = contentView; + layoutInfo.binding.bottom.kind = kHILayoutBindBottom; + + HIViewSetLayoutInfo(nativeWidgetView, &layoutInfo); + HIViewApplyLayout(nativeWidgetView); + + pushButton->show(); + nativeWidget->show(); + // Show the window. + ShowWindow(windowRef); +//![1] +#endif + return app.exec(); // gives us the same behavior in both +} diff --git a/doc/src/snippets/qprocess-environment/main.cpp b/doc/src/snippets/qprocess-environment/main.cpp new file mode 100644 index 0000000000..974095fe02 --- /dev/null +++ b/doc/src/snippets/qprocess-environment/main.cpp @@ -0,0 +1,73 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtCore> + +void startProcess() +{ + { +//! [0] +QProcess process; +QStringList env = QProcess::systemEnvironment(); +env << "TMPDIR=C:\\MyApp\\temp"; // Add an environment variable +env.replaceInStrings(QRegExp("^PATH=(.*)", Qt::CaseInsensitive), "PATH=\\1;C:\\Bin"); +process.setEnvironment(env); +process.start("myapp"); +//! [0] + } + + { +//! [1] +QProcess process; +QProcessEnvironment env = QProcessEnvironment::systemEnvironment(); +env.insert("TMPDIR", "C:\\MyApp\\temp"); // Add an environment variable +env.insert("PATH", env.value("Path") + ";C:\\Bin"); +process.setProcessEnvironment(env); +process.start("myapp"); +//! [1] + } +} + +int main(int argc, char *argv[]) +{ + QCoreApplication app(argc, argv); + startProcess(); + return app.exec(); +} diff --git a/doc/src/snippets/qprocess/qprocess-simpleexecution.cpp b/doc/src/snippets/qprocess/qprocess-simpleexecution.cpp new file mode 100644 index 0000000000..a5d097f3fe --- /dev/null +++ b/doc/src/snippets/qprocess/qprocess-simpleexecution.cpp @@ -0,0 +1,66 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QApplication> +#include <QtGui> + +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); +//! [0] + QObject *parent; +//! [0] + parent = &app; + +//! [1] + QString program = "./path/to/Qt/examples/widgets/analogclock"; +//! [1] + program = "./../../../../examples/widgets/analogclock/analogclock"; + +//! [2] + QStringList arguments; + arguments << "-style" << "motif"; + + QProcess *myProcess = new QProcess(parent); + myProcess->start(program, arguments); +//! [2] + + return app.exec(); +} diff --git a/doc/src/snippets/qsignalmapper/buttonwidget.cpp b/doc/src/snippets/qsignalmapper/buttonwidget.cpp new file mode 100644 index 0000000000..35f305570f --- /dev/null +++ b/doc/src/snippets/qsignalmapper/buttonwidget.cpp @@ -0,0 +1,66 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> + +#include "buttonwidget.h" + +//! [0] +ButtonWidget::ButtonWidget(QStringList texts, QWidget *parent) + : QWidget(parent) +{ + signalMapper = new QSignalMapper(this); + + QGridLayout *gridLayout = new QGridLayout; + for (int i = 0; i < texts.size(); ++i) { + QPushButton *button = new QPushButton(texts[i]); + connect(button, SIGNAL(clicked()), signalMapper, SLOT(map())); +//! [0] //! [1] + signalMapper->setMapping(button, texts[i]); + gridLayout->addWidget(button, i / 3, i % 3); + } + + connect(signalMapper, SIGNAL(mapped(const QString &)), +//! [1] //! [2] + this, SIGNAL(clicked(const QString &))); + + setLayout(gridLayout); +} +//! [2] diff --git a/doc/src/snippets/qsignalmapper/buttonwidget.h b/doc/src/snippets/qsignalmapper/buttonwidget.h new file mode 100644 index 0000000000..095fc2c70a --- /dev/null +++ b/doc/src/snippets/qsignalmapper/buttonwidget.h @@ -0,0 +1,67 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#ifndef BUTTONWIDGET_H +#define BUTTONWIDGET_H + +#include <qwidget.h> + +class QSignalMapper; +class QString; +class QStringList; + +//! [0] +class ButtonWidget : public QWidget +{ + Q_OBJECT + +public: + ButtonWidget(QStringList texts, QWidget *parent = 0); + +signals: + void clicked(const QString &text); + +private: + QSignalMapper *signalMapper; +//! [0] //! [1] +}; +//! [1] + +#endif diff --git a/doc/src/snippets/qsortfilterproxymodel-details/main.cpp b/doc/src/snippets/qsortfilterproxymodel-details/main.cpp new file mode 100644 index 0000000000..9de0cea1df --- /dev/null +++ b/doc/src/snippets/qsortfilterproxymodel-details/main.cpp @@ -0,0 +1,99 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> +#include <QApplication> +#include <QSortFilterProxyModel> + +class MyItemModel : public QStandardItemModel +{ +public: + MyItemModel(QWidget *parent = 0); +}; + +MyItemModel::MyItemModel(QWidget *parent) + : QStandardItemModel(parent) +{}; + +class Widget : public QWidget +{ +public: + Widget(QWidget *parent = 0); +}; + +Widget::Widget(QWidget *parent) + : QWidget(parent) +{ +//! [0] //! [1] + QTreeView *treeView = new QTreeView; +//! [0] + MyItemModel *model = new MyItemModel(this); + + treeView->setModel(model); +//! [1] + +//! [2] + MyItemModel *sourceModel = new MyItemModel(this); + QSortFilterProxyModel *proxyModel = new QSortFilterProxyModel(this); + + proxyModel->setSourceModel(sourceModel); + treeView->setModel(proxyModel); +//! [2] + +//! [3] + treeView->setSortingEnabled(true); +//! [3] + +//! [4] + proxyModel->sort(2, Qt::AscendingOrder); +//! [4] //! [5] + proxyModel->setFilterRegExp(QRegExp(".png", Qt::CaseInsensitive, + QRegExp::FixedString)); + proxyModel->setFilterKeyColumn(1); +//! [5] +} + +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + Widget widget; + widget.show(); + return app.exec(); +} diff --git a/doc/src/snippets/qsplashscreen/main.cpp b/doc/src/snippets/qsplashscreen/main.cpp new file mode 100644 index 0000000000..0a4ebb5f19 --- /dev/null +++ b/doc/src/snippets/qsplashscreen/main.cpp @@ -0,0 +1,63 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> +#include <stdlib.h> + +#include "mainwindow.h" + +//! [0] +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + QPixmap pixmap(":/splash.png"); + QSplashScreen splash(pixmap); + splash.show(); + app.processEvents(); +//! [0] + + sleep(5); +//! [1] + QMainWindow window; + window.show(); + splash.finish(&window); + return app.exec(); +} +//! [1] diff --git a/doc/src/snippets/qstack/main.cpp b/doc/src/snippets/qstack/main.cpp new file mode 100644 index 0000000000..8b6982e9e4 --- /dev/null +++ b/doc/src/snippets/qstack/main.cpp @@ -0,0 +1,55 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> +#include <iostream> +using namespace std; + +int main(int argc, char *argv[]) +{ +//! [0] + QStack<int> stack; + stack.push(1); + stack.push(2); + stack.push(3); + while (!stack.isEmpty()) + cout << stack.pop() << endl; +//! [0] +} diff --git a/doc/src/snippets/qstackedlayout/main.cpp b/doc/src/snippets/qstackedlayout/main.cpp new file mode 100644 index 0000000000..ca415e8be0 --- /dev/null +++ b/doc/src/snippets/qstackedlayout/main.cpp @@ -0,0 +1,89 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> +#include <QApplication> + +class Widget : public QWidget +{ +public: + Widget(QWidget *parent = 0); +}; + +Widget::Widget(QWidget *parent) + : QWidget(parent) +{ +//! [0] + QWidget *firstPageWidget = new QWidget; + QWidget *secondPageWidget = new QWidget; + QWidget *thirdPageWidget = new QWidget; + + QStackedLayout *stackedLayout = new QStackedLayout; + stackedLayout->addWidget(firstPageWidget); + stackedLayout->addWidget(secondPageWidget); + stackedLayout->addWidget(thirdPageWidget); + +//! [0] //! [1] + QComboBox *pageComboBox = new QComboBox; + pageComboBox->addItem(tr("Page 1")); + pageComboBox->addItem(tr("Page 2")); + pageComboBox->addItem(tr("Page 3")); + connect(pageComboBox, SIGNAL(activated(int)), + stackedLayout, SLOT(setCurrentIndex(int))); +//! [1] + +//! [2] + QVBoxLayout *mainLayout = new QVBoxLayout; +//! [2] + mainLayout->addWidget(pageComboBox); +//! [3] + mainLayout->addLayout(stackedLayout); + setLayout(mainLayout); +//! [3] +} + +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + Widget widget; + widget.show(); + return app.exec(); +} + diff --git a/doc/src/snippets/qstackedwidget/main.cpp b/doc/src/snippets/qstackedwidget/main.cpp new file mode 100644 index 0000000000..7e72bfacba --- /dev/null +++ b/doc/src/snippets/qstackedwidget/main.cpp @@ -0,0 +1,87 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> +#include <QApplication> + +class Widget : public QWidget +{ +public: + Widget(QWidget *parent = 0); +}; + +Widget::Widget(QWidget *parent) + : QWidget(parent) +{ +//! [0] + QWidget *firstPageWidget = new QWidget; + QWidget *secondPageWidget = new QWidget; + QWidget *thirdPageWidget = new QWidget; + + QStackedWidget *stackedWidget = new QStackedWidget; + stackedWidget->addWidget(firstPageWidget); + stackedWidget->addWidget(secondPageWidget); + stackedWidget->addWidget(thirdPageWidget); + +//! [0] //! [1] + QComboBox *pageComboBox = new QComboBox; + pageComboBox->addItem(tr("Page 1")); + pageComboBox->addItem(tr("Page 2")); + pageComboBox->addItem(tr("Page 3")); + connect(pageComboBox, SIGNAL(activated(int)), + stackedWidget, SLOT(setCurrentIndex(int))); + +//! [1] //! [2] + QVBoxLayout *layout = new QVBoxLayout; +//! [2] + layout->addWidget(pageComboBox); +//! [3] + layout->addWidget(stackedWidget); + setLayout(layout); +//! [3] +} + +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + Widget widget; + widget.show(); + return app.exec(); +} diff --git a/doc/src/snippets/qstatustipevent/main.cpp b/doc/src/snippets/qstatustipevent/main.cpp new file mode 100644 index 0000000000..b609db856c --- /dev/null +++ b/doc/src/snippets/qstatustipevent/main.cpp @@ -0,0 +1,82 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> +#include <QApplication> + +class MainWindow : public QMainWindow +{ +public: + MainWindow(QWidget *parent = 0); +}; + +//! [0] //! [1] +MainWindow::MainWindow(QWidget *parent) + : QMainWindow(parent) +{ +//! [0] + QWidget *myWidget = new QWidget; + myWidget->setStatusTip(tr("This is my widget.")); + + setCentralWidget(myWidget); +//! [1] + +//! [2] + QMenu *fileMenu = menuBar()->addMenu(tr("File")); + + QAction *newAct = new QAction(tr("&New"), this); + newAct->setStatusTip(tr("Create a new file.")); + fileMenu->addAction(newAct); +//! [2] + + statusBar()->showMessage(tr("Ready")); + setWindowTitle(tr("QStatusTipEvent")); +//! [3] +} +//! [3] + +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + MainWindow window; + window.show(); + return app.exec(); +} + diff --git a/doc/src/snippets/qstring/main.cpp b/doc/src/snippets/qstring/main.cpp new file mode 100644 index 0000000000..bbc9e98901 --- /dev/null +++ b/doc/src/snippets/qstring/main.cpp @@ -0,0 +1,941 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> +#include <QApplication> +#include <stdio.h> + +class Widget : public QWidget +{ +public: + Widget(QWidget *parent = 0); + + void constCharPointer(); + void constCharArray(); + void characterReference(); + void atFunction(); + void stringLiteral(); + void modify(); + void index(); + QString boolToString(bool b); + void nullVsEmpty(); + + void appendFunction(); + void argFunction(); + void chopFunction(); + void compareFunction(); + void compareSensitiveFunction(); + void containsFunction(); + void countFunction(); + void dataFunction(); + void endsWithFunction(); + void fillFunction(); + void fromRawDataFunction(); + + void indexOfFunction(); + void firstIndexOfFunction(); + void insertFunction(); + void isNullFunction(); + void isEmptyFunction(); + void lastIndexOfFunction(); + void leftFunction(); + void leftJustifiedFunction(); + void leftRefFunction(); + void midFunction(); + void midRefFunction(); + void numberFunction(); + + void prependFunction(); + void removeFunction(); + void replaceFunction(); + void reserveFunction(); + void resizeFunction(); + void rightFunction(); + void rightJustifiedFunction(); + void rightRefFunction(); + void sectionFunction(); + void setNumFunction(); + void simplifiedFunction(); + + void sizeFunction(); + void splitFunction(); + void splitCaseSensitiveFunction(); + void sprintfFunction(); + void startsWithFunction(); + void toDoubleFunction(); + void toFloatFunction(); + void toIntFunction(); + void toLongFunction(); + void toLongLongFunction(); + + void toLowerFunction(); + void toShortFunction(); + void toUIntFunction(); + void toULongFunction(); + void toULongLongFunction(); + void toUShortFunction(); + void toUpperFunction(); + void trimmedFunction(); + void truncateFunction(); + + void plusEqualOperator(); + void arrayOperator(); +}; + +Widget::Widget(QWidget *parent) + : QWidget(parent) +{ +} + +void Widget::constCharPointer() +{ + //! [0] + QString str = "Hello"; + //! [0] +} + +void Widget::constCharArray() +{ + //! [1] + static const QChar data[4] = { 0x0055, 0x006e, 0x10e3, 0x03a3 }; + QString str(data, 4); + //! [1] +} + +void Widget::characterReference() +{ + //! [2] + QString str; + str.resize(4); + + str[0] = QChar('U'); + str[1] = QChar('n'); + str[2] = QChar(0x10e3); + str[3] = QChar(0x03a3); + //! [2] +} + +void Widget::atFunction() +{ + //! [3] + QString str; + + for (int i = 0; i < str.size(); ++i) { + if (str.at(i) >= QChar('a') && str.at(i) <= QChar('f')) + qDebug() << "Found character in range [a-f]"; + } + //! [3] +} + +void Widget::stringLiteral() +{ + //! [4] + QString str; + + if (str == "auto" || str == "extern" + || str == "static" || str == "register") { + // ... + } + //! [4] +} + +void Widget::modify() +{ + //! [5] + QString str = "and"; + str.prepend("rock "); // str == "rock and" + str.append(" roll"); // str == "rock and roll" + str.replace(5, 3, "&"); // str == "rock & roll" + //! [5] +} + +void Widget::index() +{ + //! [6] + QString str = "We must be <b>bold</b>, very <b>bold</b>"; + int j = 0; + + while ((j = str.indexOf("<b>", j)) != -1) { + qDebug() << "Found <b> tag at index position" << j; + ++j; + } + //! [6] +} + +//! [7] +QString Widget::boolToString(bool b) +{ + QString result; + if (b) + result = "True"; + else + result = "False"; + return result; +} +//! [7] + + +void Widget::nullVsEmpty() +{ + //! [8] + QString().isNull(); // returns true + QString().isEmpty(); // returns true + + QString("").isNull(); // returns false + QString("").isEmpty(); // returns true + + QString("abc").isNull(); // returns false + QString("abc").isEmpty(); // returns false + //! [8] +} + +void Widget::appendFunction() +{ + //! [9] + QString x = "free"; + QString y = "dom"; + + x.append(y); + // x == "freedom" + //! [9] + + //! [10] + x.insert(x.size(), y); + //! [10] +} + +void Widget::argFunction() +{ + //! [11] + QString i; // current file's number + QString total; // number of files to process + QString fileName; // current file's name + + QString status = QString("Processing file %1 of %2: %3") + .arg(i).arg(total).arg(fileName); + //! [11] + + //! [12] //! [13] + QString str; + //! [12] + str = "%1 %2"; + + str.arg("%1f", "Hello"); // returns "%1f Hello" + str.arg("%1f").arg("Hello"); // returns "Hellof %2" + //! [13] + + //! [14] + str = QString("Decimal 63 is %1 in hexadecimal") + .arg(63, 0, 16); + // str == "Decimal 63 is 3f in hexadecimal" + + QLocale::setDefault(QLocale(QLocale::English, QLocale::UnitedStates)); + str = QString("%1 %L2 %L3") + .arg(12345) + .arg(12345) + .arg(12345, 0, 16); + // str == "12345 12,345 3039" + //! [14] +} + +void Widget::chopFunction() +{ + //! [15] + QString str("LOGOUT\r\n"); + str.chop(2); + // str == "LOGOUT" + //! [15] +} + +void Widget::compareFunction() +{ + int x = QString::compare("auto", "auto"); // x == 0 + int y = QString::compare("auto", "car"); // y < 0 + int z = QString::compare("car", "auto"); // z > 0 +} + +void Widget::compareSensitiveFunction() +{ + //! [16] + int x = QString::compare("aUtO", "AuTo", Qt::CaseInsensitive); // x == 0 + int y = QString::compare("auto", "Car", Qt::CaseSensitive); // y > 0 + int z = QString::compare("auto", "Car", Qt::CaseInsensitive); // z < 0 + //! [16] +} + +void Widget::containsFunction() +{ + //! [17] + QString str = "Peter Pan"; + str.contains("peter", Qt::CaseInsensitive); // returns true + //! [17] +} + +void Widget::countFunction() +{ + //! [18] + QString str = "banana and panama"; + str.count(QRegExp("a[nm]a")); // returns 4 + //! [18] +} + +void Widget::dataFunction() +{ + //! [19] + QString str = "Hello world"; + QChar *data = str.data(); + while (!data->isNull()) { + qDebug() << data->unicode(); + ++data; + } + //! [19] +} + +void Widget::endsWithFunction() +{ + //! [20] + QString str = "Bananas"; + str.endsWith("anas"); // returns true + str.endsWith("pple"); // returns false + //! [20] +} + +void Widget::fillFunction() +{ + //! [21] + QString str = "Berlin"; + str.fill('z'); + // str == "zzzzzz" + + str.fill('A', 2); + // str == "AA" + //! [21] +} + +void Widget::fromRawDataFunction() +{ + //! [22] + QRegExp pattern; + static const QChar unicode[] = { + 0x005A, 0x007F, 0x00A4, 0x0060, + 0x1009, 0x0020, 0x0020}; + int size = sizeof(unicode) / sizeof(QChar); + + QString str = QString::fromRawData(unicode, size); + if (str.contains(QRegExp(pattern))) { + // ... + //! [22] //! [23] + } + //! [23] +} + +void Widget::indexOfFunction() +{ + //! [24] + QString x = "sticky question"; + QString y = "sti"; + x.indexOf(y); // returns 0 + x.indexOf(y, 1); // returns 10 + x.indexOf(y, 10); // returns 10 + x.indexOf(y, 11); // returns -1 + //! [24] +} + +void Widget::firstIndexOfFunction() +{ + //! [25] + QString str = "the minimum"; + str.indexOf(QRegExp("m[aeiou]"), 0); // returns 4 + //! [25] +} + +void Widget::insertFunction() +{ + //! [26] + QString str = "Meal"; + str.insert(1, QString("ontr")); + // str == "Montreal" + //! [26] +} + +void Widget::isEmptyFunction() +{ + //! [27] + QString().isEmpty(); // returns true + QString("").isEmpty(); // returns true + QString("x").isEmpty(); // returns false + QString("abc").isEmpty(); // returns false + //! [27] +} + +void Widget::isNullFunction() +{ + //! [28] + QString().isNull(); // returns true + QString("").isNull(); // returns false + QString("abc").isNull(); // returns false + //! [28] +} + +void Widget::lastIndexOfFunction() +{ + //! [29] + QString x = "crazy azimuths"; + QString y = "az"; + x.lastIndexOf(y); // returns 6 + x.lastIndexOf(y, 6); // returns 6 + x.lastIndexOf(y, 5); // returns 2 + x.lastIndexOf(y, 1); // returns -1 + //! [29] + + //! [30] + QString str = "the minimum"; + str.lastIndexOf(QRegExp("m[aeiou]")); // returns 8 + //! [30] +} + +void Widget::leftFunction() +{ + //! [31] + QString x = "Pineapple"; + QString y = x.left(4); // y == "Pine" + //! [31] +} + +void Widget::leftJustifiedFunction() +{ + //! [32] + QString s = "apple"; + QString t = s.leftJustified(8, '.'); // t == "apple..." + //! [32] + + //! [33] + QString str = "Pineapple"; + str = str.leftJustified(5, '.', true); // str == "Pinea" + //! [33] +} + +void Widget::midFunction() +{ + //! [34] + QString x = "Nine pineapples"; + QString y = x.mid(5, 4); // y == "pine" + QString z = x.mid(5); // z == "pineapples" + //! [34] +} + +void Widget::numberFunction() +{ + //! [35] + long a = 63; + QString s = QString::number(a, 16); // s == "3f" + QString t = QString::number(a, 16).toUpper(); // t == "3F" + //! [35] +} + +void Widget::prependFunction() +{ + //! [36] + QString x = "ship"; + QString y = "air"; + x.prepend(y); + // x == "airship" + //! [36] +} + +void Widget::removeFunction() +{ + //! [37] + QString s = "Montreal"; + s.remove(1, 4); + // s == "Meal" + //! [37] + + //! [38] + QString t = "Ali Baba"; + t.remove(QChar('a'), Qt::CaseInsensitive); + // t == "li Bb" + //! [38] + + //! [39] + QString r = "Telephone"; + r.remove(QRegExp("[aeiou].")); + // r == "The" + //! [39] +} + +void Widget::replaceFunction() +{ + //! [40] + QString x = "Say yes!"; + QString y = "no"; + x.replace(4, 3, y); + // x == "Say no!" + //! [40] + + //! [41] + QString str = "colour behaviour flavour neighbour"; + str.replace(QString("ou"), QString("o")); + // str == "color behavior flavor neighbor" + //! [41] + + //! [42] + QString s = "Banana"; + s.replace(QRegExp("a[mn]"), "ox"); + // s == "Boxoxa" + //! [42] + + //! [43] + QString t = "A <i>bon mot</i>."; + t.replace(QRegExp("<i>([^<]*)</i>"), "\\emph{\\1}"); + // t == "A \\emph{bon mot}." + //! [43] + + //! [86] + QString equis = "xxxxxx"; + equis.replace("xx", "x"); + // equis == "xxx" + //! [86] +} + +void Widget::reserveFunction() +{ + //! [44] + QString result; + int maxSize; + bool condition; + QChar nextChar; + + result.reserve(maxSize); + + while (condition) + result.append(nextChar); + + result.squeeze(); + //! [44] +} + +void Widget::resizeFunction() +{ + //! [45] + QString s = "Hello world"; + s.resize(5); + // s == "Hello" + + s.resize(8); + // s == "Hello???" (where ? stands for any character) + //! [45] + + //! [46] + QString t = "Hello"; + t += QString(10, 'X'); + // t == "HelloXXXXXXXXXX" + //! [46] + + //! [47] + QString r = "Hello"; + r = r.leftJustified(10, ' '); + // r == "Hello " + //! [47] +} + +void Widget::rightFunction() +{ + //! [48] + QString x = "Pineapple"; + QString y = x.right(5); // y == "apple" + //! [48] +} + +void Widget::rightJustifiedFunction() +{ + //! [49] + QString s = "apple"; + QString t = s.rightJustified(8, '.'); // t == "...apple" + //! [49] + + //! [50] + QString str = "Pineapple"; + str = str.rightJustified(5, '.', true); // str == "Pinea" + //! [50] +} + +void Widget::sectionFunction() +{ + //! [51] //! [52] + QString str; + //! [51] + QString csv = "forename,middlename,surname,phone"; + QString path = "/usr/local/bin/myapp"; // First field is empty + QString::SectionFlag flag = QString::SectionSkipEmpty; + + + str = csv.section(',', 2, 2); // str == "surname" + str = path.section('/', 3, 4); // str == "bin/myapp" + str = path.section('/', 3, 3, flag); // str == "myapp" + //! [52] + + //! [53] + str = csv.section(',', -3, -2); // str == "middlename,surname" + str = path.section('/', -1); // str == "myapp" + //! [53] + + //! [54] + QString data = "forename**middlename**surname**phone"; + + str = data.section("**", 2, 2); // str == "surname" + str = data.section("**", -3, -2); // str == "middlename**surname" + //! [54] + + //! [55] + QString line = "forename\tmiddlename surname \t \t phone"; + QRegExp sep("\\s+"); + str = line.section(sep, 2, 2); // s == "surname" + str = line.section(sep, -3, -2); // s == "middlename surname" + //! [55] +} + +void Widget::setNumFunction() +{ + //! [56] + QString str; + str.setNum(1234); // str == "1234" + //! [56] +} + +void Widget::simplifiedFunction() +{ + //! [57] + QString str = " lots\t of\nwhitespace\r\n "; + str = str.simplified(); + // str == "lots of whitespace"; + //! [57] +} + +void Widget::sizeFunction() +{ + //! [58] + QString str = "World"; + int n = str.size(); // n == 5 + str.data()[0]; // returns 'W' + str.data()[4]; // returns 'd' + str.data()[5]; // returns '\0' + //! [58] +} + +void Widget::splitFunction() +{ + //! [59] + QString str; + QStringList list; + + str = "Some text\n\twith strange whitespace."; + list = str.split(QRegExp("\\s+")); + // list: [ "Some", "text", "with", "strange", "whitespace." ] + //! [59] + + //! [60] + str = "This time, a normal English sentence."; + list = str.split(QRegExp("\\W+"), QString::SkipEmptyParts); + // list: [ "This", "time", "a", "normal", "English", "sentence" ] + //! [60] + + //! [61] + str = "Now: this sentence fragment."; + list = str.split(QRegExp("\\b")); + // list: [ "", "Now", ": ", "this", " ", "sentence", " ", "fragment", "." ] + //! [61] +} + +void Widget::splitCaseSensitiveFunction() +{ + //! [62] + QString str = "a,,b,c"; + + QStringList list1 = str.split(","); + // list1: [ "a", "", "b", "c" ] + + QStringList list2 = str.split(",", QString::SkipEmptyParts); + // list2: [ "a", "b", "c" ] + //! [62] +} + +void Widget::sprintfFunction() +{ + //! [63] + size_t BufSize; + char buf[BufSize]; + + ::snprintf(buf, BufSize, "%lld", 123456789LL); + QString str = QString::fromAscii(buf); + //! [63] + + //! [64] + QString result; + QTextStream(&result) << "pi = " << 3.14; + // result == "pi = 3.14" + //! [64] +} + +void Widget::startsWithFunction() +{ + //! [65] + QString str = "Bananas"; + str.startsWith("Ban"); // returns true + str.startsWith("Car"); // returns false + //! [65] +} + +void Widget::toDoubleFunction() +{ + //! [66] + QString str = "1234.56"; + double val = str.toDouble(); // val == 1234.56 + //! [66] + + //! [67] + bool ok; + double d; + + d = QString( "1234.56e-02" ).toDouble(&ok); // ok == true, d == 12.3456 + //! [67] + + //! [68] //! [69] + QLocale::setDefault(QLocale::C); + d = QString( "1234,56" ).toDouble(&ok); // ok == false + //! [68] + d = QString( "1234.56" ).toDouble(&ok); // ok == true, d == 1234.56 + + //! [69] //! [70] + QLocale::setDefault(QLocale::German); + d = QString( "1234,56" ).toDouble(&ok); // ok == true, d == 1234.56 + d = QString( "1234.56" ).toDouble(&ok); // ok == true, d == 1234.56 + + //! [70] + QLocale::setDefault(QLocale::C); + d = QString( "1,234,567.89" ).toDouble(&ok); // ok == false +} + +void Widget::toFloatFunction() +{ + //! [71] + QString str1 = "1234.56"; + str1.toFloat(); // returns 1234.56 + + bool ok; + QString str2 = "R2D2"; + str2.toFloat(&ok); // returns 0.0, sets ok to false + //! [71] +} + +void Widget::toIntFunction() +{ + //! [72] + QString str = "FF"; + bool ok; + int hex = str.toInt(&ok, 16); // hex == 255, ok == true + int dec = str.toInt(&ok, 10); // dec == 0, ok == false + //! [72] +} + +void Widget::toLongFunction() +{ + //! [73] + QString str = "FF"; + bool ok; + + long hex = str.toLong(&ok, 16); // hex == 255, ok == true + long dec = str.toLong(&ok, 10); // dec == 0, ok == false + //! [73] +} + +void Widget::toLongLongFunction() +{ + //! [74] + QString str = "FF"; + bool ok; + + qint64 hex = str.toLongLong(&ok, 16); // hex == 255, ok == true + qint64 dec = str.toLongLong(&ok, 10); // dec == 0, ok == false + //! [74] +} + +void Widget::toLowerFunction() +{ + //! [75] + QString str = "Qt by NOKIA"; + str = str.toLower(); // str == "qt by nokia" + //! [75] +} + +void Widget::toShortFunction() +{ + //! [76] + QString str = "FF"; + bool ok; + + short hex = str.toShort(&ok, 16); // hex == 255, ok == true + short dec = str.toShort(&ok, 10); // dec == 0, ok == false + //! [76] +} + +void Widget::toUIntFunction() +{ + //! [77] + QString str = "FF"; + bool ok; + + uint hex = str.toUInt(&ok, 16); // hex == 255, ok == true + uint dec = str.toUInt(&ok, 10); // dec == 0, ok == false + //! [77] +} + +void Widget::toULongFunction() +{ + //! [78] + QString str = "FF"; + bool ok; + + ulong hex = str.toULong(&ok, 16); // hex == 255, ok == true + ulong dec = str.toULong(&ok, 10); // dec == 0, ok == false + //! [78] +} + +void Widget::toULongLongFunction() +{ + //! [79] + QString str = "FF"; + bool ok; + + quint64 hex = str.toULongLong(&ok, 16); // hex == 255, ok == true + quint64 dec = str.toULongLong(&ok, 10); // dec == 0, ok == false + //! [79] +} + +void Widget::toUShortFunction() +{ + //! [80] + QString str = "FF"; + bool ok; + + ushort hex = str.toUShort(&ok, 16); // hex == 255, ok == true + ushort dec = str.toUShort(&ok, 10); // dec == 0, ok == false + //! [80] +} + +void Widget::toUpperFunction() +{ + //! [81] + QString str = "TeXt"; + str = str.toUpper(); // str == "TEXT" + //! [81] +} + +void Widget::trimmedFunction() +{ + //! [82] + QString str = " lots\t of\nwhitespace\r\n "; + str = str.trimmed(); + // str == "lots\t of\nwhitespace" + //! [82] +} + +void Widget::truncateFunction() +{ + //! [83] + QString str = "Vladivostok"; + str.truncate(4); + // str == "Vlad" + //! [83] +} + +void Widget::plusEqualOperator() +{ + //! [84] + QString x = "free"; + QString y = "dom"; + x += y; + // x == "freedom" + //! [84] +} + +void Widget::arrayOperator() +{ + //! [85] + QString str; + + if (str[0] == QChar('?')) + str[0] = QChar('_'); + //! [85] +} + +void Widget::midRefFunction() +{ + //! [midRef] + QString x = "Nine pineapples"; + QStringRef y = x.midRef(5, 4); // y == "pine" + QStringRef z = x.midRef(5); // z == "pineapples" + //! [midRef] +} + +void Widget::leftRefFunction() +{ + //! [leftRef] + QString x = "Pineapple"; + QStringRef y = x.leftRef(4); // y == "Pine" + //! [leftRef] +} + +void Widget::rightRefFunction() +{ + //! [rightRef] + QString x = "Pineapple"; + QStringRef y = x.rightRef(5); // y == "apple" + //! [rightRef] +} + + +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + Widget widget; + widget.show(); + return app.exec(); +} diff --git a/doc/src/snippets/qstring/stringbuilder.cpp b/doc/src/snippets/qstring/stringbuilder.cpp new file mode 100644 index 0000000000..8ff1dd8206 --- /dev/null +++ b/doc/src/snippets/qstring/stringbuilder.cpp @@ -0,0 +1,67 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] + QString foo; + QString type = "long"; + + foo->setText(QLatin1String("vector<") + type + QLatin1String(">::iterator")); + + if (foo.startsWith("(" + type + ") 0x")) + ... +//! [0] + +//! [3] + #define QT_USE_FAST_CONCATENATION +//! [3] + +//! [4] + #define QT_USE_FAST_CONCATENATION + #define QT_USE_FAST_OPERATOR_PLUS +//! [4] + +//! [5] + #include <QStringBuilder> + + QString hello("hello"); + QStringRef el(&hello, 2, 3); + QLatin1String world("world"); + QString message = hello % el % world % QChar('!'); +//! [5] diff --git a/doc/src/snippets/qstringlist/main.cpp b/doc/src/snippets/qstringlist/main.cpp new file mode 100644 index 0000000000..3d56987b94 --- /dev/null +++ b/doc/src/snippets/qstringlist/main.cpp @@ -0,0 +1,155 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> +#include <iostream> +using namespace std; + +class Widget : public QWidget +{ +public: + Widget(QWidget *parent = 0); +}; + +Widget::Widget(QWidget *parent) + : QWidget(parent) +{ +//! [0] + QStringList fonts; + fonts << "Arial" << "Helvetica" << "Times" << "Courier"; +//! [0] + +//! [1] + for (int i = 0; i < fonts.size(); ++i) + cout << fonts.at(i).toLocal8Bit().constData() << endl; +//! [1] + +//! [2] + QStringListIterator javaStyleIterator(fonts); + while (javaStyleIterator.hasNext()) + cout << javaStyleIterator.next().toLocal8Bit().constData() << endl; +//! [2] + +//! [3] + QStringList::const_iterator constIterator; + for (constIterator = fonts.constBegin(); constIterator != fonts.constEnd(); + ++constIterator) + cout << (*constIterator).toLocal8Bit().constData() << endl; +//! [3] + +//! [4] + QString str = fonts.join(","); + // str == "Arial,Helvetica,Times,Courier" +//! [4] + +//! [5] //! [6] + QStringList list; +//! [5] + list = str.split(","); + // list: ["Arial", "Helvetica", "Times", "Courier"] +//! [6] + +//! [7] + QStringList monospacedFonts = fonts.filter(QRegExp("Courier|Fixed")); +//! [7] + +//! [8] + QStringList files; + files << "$QTDIR/src/moc/moc.y" + << "$QTDIR/src/moc/moc.l" + << "$QTDIR/include/qconfig.h"; + + files.replaceInStrings("$QTDIR", "/usr/lib/qt"); + // files: [ "/usr/lib/qt/src/moc/moc.y", ...] +//! [8] + + QString str1, str2, str3; +//! [9] + QStringList longerList = (QStringList() << str1 << str2 << str3); +//! [9] + + list.clear(); +//! [10] + list << "Bill Murray" << "John Doe" << "Bill Clinton"; + +//! [11] + QStringList result; +//! [11] + result = list.filter("Bill"); + // result: ["Bill Murray", "Bill Clinton"] +//! [10] + + result.clear(); +//! [12] + foreach (const QString &str, list) { + if (str.contains("Bill")) + result += str; + } +//! [12] + + list.clear(); +//! [13] + list << "alpha" << "beta" << "gamma" << "epsilon"; + list.replaceInStrings("a", "o"); + // list == ["olpho", "beto", "gommo", "epsilon"] +//! [13] + + list.clear(); +//! [14] + list << "alpha" << "beta" << "gamma" << "epsilon"; + list.replaceInStrings(QRegExp("^a"), "o"); + // list == ["olpha", "beta", "gamma", "epsilon"] +//! [14] + + list.clear(); +//! [15] + list << "Bill Clinton" << "Murray, Bill"; + list.replaceInStrings(QRegExp("^(.*), (.*)$"), "\\2 \\1"); + // list == ["Bill Clinton", "Bill Murray"] +//! [15] +} + +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + Widget widget; + widget.show(); + return app.exec(); +} diff --git a/doc/src/snippets/qstringlistmodel/main.cpp b/doc/src/snippets/qstringlistmodel/main.cpp new file mode 100644 index 0000000000..a64ba2b687 --- /dev/null +++ b/doc/src/snippets/qstringlistmodel/main.cpp @@ -0,0 +1,66 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> + +class Widget : public QWidget +{ +public: + Widget(QWidget *parent = 0); +}; + +Widget::Widget(QWidget *parent) + : QWidget(parent) +{ +//! [0] + QStringListModel *model = new QStringListModel(); + QStringList list; + list << "a" << "b" << "c"; + model->setStringList(list); +//! [0] +} + +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + Widget widget; + widget.show(); + return app.exec(); +} diff --git a/doc/src/snippets/qstyleoption/main.cpp b/doc/src/snippets/qstyleoption/main.cpp new file mode 100644 index 0000000000..c3ef7298dd --- /dev/null +++ b/doc/src/snippets/qstyleoption/main.cpp @@ -0,0 +1,139 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> +#include <QApplication> + +class MyPushButton : public QPushButton +{ +public: + MyPushButton(QWidget *parent = 0); + + void paintEvent(QPaintEvent *); +}; + +MyPushButton::MyPushButton(QWidget *parent) + : QPushButton(parent) +{ +} + +//! [0] +void MyPushButton::paintEvent(QPaintEvent *) +{ + QStyleOptionButton option; + option.initFrom(this); + option.state = isDown() ? QStyle::State_Sunken : QStyle::State_Raised; + if (isDefault()) + option.features |= QStyleOptionButton::DefaultButton; + option.text = text(); + option.icon = icon(); + + QPainter painter(this); + style()->drawControl(QStyle::CE_PushButton, &option, &painter, this); +} +//! [0] + + + +class MyStyle : public QStyle +{ +public: + MyStyle(); + + void drawPrimitive(PrimitiveElement element, const QStyleOption *option, + QPainter *painter, const QWidget *widget); +}; + +MyStyle::MyStyle() +{ +//! [1] + QStyleOptionFrame *option; + + if (const QStyleOptionFrame *frameOption = + qstyleoption_cast<const QStyleOptionFrame *>(option)) { + QStyleOptionFrameV2 frameOptionV2(*frameOption); + + // draw the frame using frameOptionV2 + } +//! [1] + +//! [2] + if (const QStyleOptionProgressBar *progressBarOption = + qstyleoption_cast<const QStyleOptionProgressBar *>(option)) { + QStyleOptionProgressBarV2 progressBarV2(*progressBarOption); + + // draw the progress bar using progressBarV2 + } +//! [2] + +//! [3] + if (const QStyleOptionTab *tabOption = + qstyleoption_cast<const QStyleOptionTab *>(option)) { + QStyleOptionTabV2 tabV2(*tabOption); + + // draw the tab using tabV2 + } +//! [3] +} + +//! [4] +void MyStyle::drawPrimitive(PrimitiveElement element, + const QStyleOption *option, + QPainter *painter, + const QWidget *widget) +{ + if (element == PE_FrameFocusRect) { + const QStyleOptionFocusRect *focusRectOption = + qstyleoption_cast<const QStyleOptionFocusRect *>(option); + if (focusRectOption) { + // ... + } + } + // ... +} +//! [4] + +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + MyPushButton button; + button.show(); + return app.exec(); +} diff --git a/doc/src/snippets/qstyleplugin/main.cpp b/doc/src/snippets/qstyleplugin/main.cpp new file mode 100644 index 0000000000..2c444d504b --- /dev/null +++ b/doc/src/snippets/qstyleplugin/main.cpp @@ -0,0 +1,97 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QApplication> +#include <QtGui> + +class MyStylePlugin : public QStylePlugin +{ +public: + MyStylePlugin(QObject *parent = 0); + + QStyle *create(const QString &key); + QStringList keys() const; +}; + +class RocketStyle : public QCommonStyle +{ +public: + RocketStyle() {}; + +}; + +class StarBusterStyle : public QCommonStyle +{ +public: + StarBusterStyle() {}; +}; + +MyStylePlugin::MyStylePlugin(QObject *parent) + : QStylePlugin(parent) +{ +} + +//! [0] +QStringList MyStylePlugin::keys() const +{ + return QStringList() << "Rocket" << "StarBuster"; +} +//! [0] + +//! [1] +QStyle *MyStylePlugin::create(const QString &key) +{ + QString lcKey = key; + if (lcKey == "rocket") { + return new RocketStyle; + } else if (lcKey == "starbuster") { + return new StarBusterStyle; + } + return 0; +//! [1] //! [2] +} +//! [2] + +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + MyStylePlugin plugin; + return app.exec(); +} diff --git a/doc/src/snippets/qtablewidget-resizing/mainwindow.cpp b/doc/src/snippets/qtablewidget-resizing/mainwindow.cpp new file mode 100644 index 0000000000..e26031f678 --- /dev/null +++ b/doc/src/snippets/qtablewidget-resizing/mainwindow.cpp @@ -0,0 +1,115 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> + +#include "mainwindow.h" + +MainWindow::MainWindow() +{ + QMenu *fileMenu = new QMenu(tr("&File")); + + QAction *quitAction = fileMenu->addAction(tr("E&xit")); + quitAction->setShortcut(tr("Ctrl+Q")); + + QMenu *tableMenu = new QMenu(tr("&Table")); + + QAction *tableWidthAction = tableMenu->addAction(tr("Change Table &Width")); + QAction *tableHeightAction = tableMenu->addAction(tr("Change Table &Height")); + + menuBar()->addMenu(fileMenu); + menuBar()->addMenu(tableMenu); + +//! [0] + tableWidget = new QTableWidget(this); +//! [0] + tableWidget->setSelectionMode(QAbstractItemView::ExtendedSelection); + + connect(quitAction, SIGNAL(triggered()), this, SLOT(close())); + connect(tableWidthAction, SIGNAL(triggered()), this, SLOT(changeWidth())); + connect(tableHeightAction, SIGNAL(triggered()), this, SLOT(changeHeight())); + + setupTableItems(); + + setCentralWidget(tableWidget); + setWindowTitle(tr("Table Widget Resizing")); +} + +void MainWindow::setupTableItems() +{ +//! [1] + tableWidget->setRowCount(10); + tableWidget->setColumnCount(5); +//! [1] + + for (int row = 0; row < tableWidget->rowCount(); ++row) { + for (int column = 0; column < tableWidget->columnCount(); ++column) { +//! [2] + QTableWidgetItem *newItem = new QTableWidgetItem(tr("%1").arg( + (row+1)*(column+1))); + tableWidget->setItem(row, column, newItem); +//! [2] + } + } +} + +void MainWindow::changeWidth() +{ + bool ok; + + int newWidth = QInputDialog::getInteger(this, tr("Change table width"), + tr("Input the number of columns required (1-20):"), + tableWidget->columnCount(), 1, 20, 1, &ok); + + if (ok) + tableWidget->setColumnCount(newWidth); +} + +void MainWindow::changeHeight() +{ + bool ok; + + int newHeight = QInputDialog::getInteger(this, tr("Change table height"), + tr("Input the number of rows required (1-20):"), + tableWidget->rowCount(), 1, 20, 1, &ok); + + if (ok) + tableWidget->setRowCount(newHeight); +} diff --git a/doc/src/snippets/qtablewidget-using/mainwindow.cpp b/doc/src/snippets/qtablewidget-using/mainwindow.cpp new file mode 100644 index 0000000000..79a01f56d6 --- /dev/null +++ b/doc/src/snippets/qtablewidget-using/mainwindow.cpp @@ -0,0 +1,150 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> +#include "math.h" + +#include "mainwindow.h" + +MainWindow::MainWindow() +{ + QMenu *fileMenu = new QMenu(tr("&File")); + + QAction *quitAction = fileMenu->addAction(tr("E&xit")); + quitAction->setShortcut(tr("Ctrl+Q")); + + QMenu *itemsMenu = new QMenu(tr("&Items")); + + QAction *sumItemsAction = itemsMenu->addAction(tr("&Sum Items")); + QAction *averageItemsAction = itemsMenu->addAction(tr("&Average Items")); + + menuBar()->addMenu(fileMenu); + menuBar()->addMenu(itemsMenu); + +//! [0] + tableWidget = new QTableWidget(12, 3, this); +//! [0] + tableWidget->setSelectionMode(QAbstractItemView::ExtendedSelection); + +//! [1] + QTableWidgetItem *valuesHeaderItem = new QTableWidgetItem(tr("Values")); + tableWidget->setHorizontalHeaderItem(0, valuesHeaderItem); +//! [1] + valuesHeaderItem->setTextAlignment(Qt::AlignVCenter); + QTableWidgetItem *squaresHeaderItem = new QTableWidgetItem(tr("Squares")); + squaresHeaderItem->setIcon(QIcon(QPixmap(":/Images/squared.png"))); + squaresHeaderItem->setTextAlignment(Qt::AlignVCenter); +//! [2] + QTableWidgetItem *cubesHeaderItem = new QTableWidgetItem(tr("Cubes")); + cubesHeaderItem->setIcon(QIcon(QPixmap(":/Images/cubed.png"))); + cubesHeaderItem->setTextAlignment(Qt::AlignVCenter); +//! [2] + tableWidget->setHorizontalHeaderItem(1, squaresHeaderItem); + tableWidget->setHorizontalHeaderItem(2, cubesHeaderItem); + + connect(quitAction, SIGNAL(triggered()), this, SLOT(close())); + connect(sumItemsAction, SIGNAL(triggered()), this, SLOT(sumItems())); + connect(averageItemsAction, SIGNAL(triggered()), this, SLOT(averageItems())); + + setupTableItems(); + + setCentralWidget(tableWidget); + setWindowTitle(tr("Table Widget")); +} + +void MainWindow::setupTableItems() +{ + for (int row = 0; row < tableWidget->rowCount()-1; ++row) { + for (int column = 0; column < tableWidget->columnCount(); ++column) { +//! [3] + QTableWidgetItem *newItem = new QTableWidgetItem(tr("%1").arg( + pow(row, column+1))); + tableWidget->setItem(row, column, newItem); +//! [3] + } + } + for (int column = 0; column < tableWidget->columnCount(); ++column) { + QTableWidgetItem *newItem = new QTableWidgetItem; + newItem->setFlags(Qt::ItemIsEnabled); + tableWidget->setItem(tableWidget->rowCount()-1, column, newItem); + } +} + +void MainWindow::averageItems() +{ + QList<QTableWidgetItem *> selected = tableWidget->selectedItems(); + QTableWidgetItem *item; + int number = 0; + double total = 0; + + foreach (item, selected) { + bool ok; + double value = item->text().toDouble(&ok); + + if (ok && !item->text().isEmpty()) { + total += value; + number++; + } + } + if (number > 0) + tableWidget->currentItem()->setText(QString::number(total/number)); +} + +void MainWindow::sumItems() +{ +//! [4] + QList<QTableWidgetItem *> selected = tableWidget->selectedItems(); + QTableWidgetItem *item; + int number = 0; + double total = 0; + + foreach (item, selected) { + bool ok; + double value = item->text().toDouble(&ok); + + if (ok && !item->text().isEmpty()) { + total += value; + number++; + } + } +//! [4] + if (number > 0) + tableWidget->currentItem()->setText(QString::number(total)); +} diff --git a/doc/src/snippets/qtcast/qtcast.cpp b/doc/src/snippets/qtcast/qtcast.cpp new file mode 100644 index 0000000000..68cff32ad5 --- /dev/null +++ b/doc/src/snippets/qtcast/qtcast.cpp @@ -0,0 +1,79 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QLabel> +#include <QPushButton> + +#include "qtcast.h" + +MyWidget::MyWidget() +{ +//! [0] + QObject *obj = new MyWidget; +//! [0] + +//! [1] + QWidget *widget = qobject_cast<QWidget *>(obj); +//! [1] + +//! [2] + MyWidget *myWidget = qobject_cast<MyWidget *>(obj); +//! [2] + +//! [3] + QLabel *label = qobject_cast<QLabel *>(obj); +//! [3] //! [4] + // label is 0 +//! [4] + +//! [5] + if (QLabel *label = qobject_cast<QLabel *>(obj)) { +//! [5] //! [6] + label->setText(tr("Ping")); + } else if (QPushButton *button = qobject_cast<QPushButton *>(obj)) { + button->setText(tr("Pong!")); + } +//! [6] +} + +int main() +{ + return 0; +} diff --git a/doc/src/snippets/qtreewidget-using/mainwindow.cpp b/doc/src/snippets/qtreewidget-using/mainwindow.cpp new file mode 100644 index 0000000000..a7e8277321 --- /dev/null +++ b/doc/src/snippets/qtreewidget-using/mainwindow.cpp @@ -0,0 +1,230 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> + +#include "mainwindow.h" + +MainWindow::MainWindow() +{ + QMenu *fileMenu = new QMenu(tr("&File")); + + QAction *quitAction = fileMenu->addAction(tr("E&xit")); + quitAction->setShortcut(tr("Ctrl+Q")); + + QMenu *itemsMenu = new QMenu(tr("&Items")); + + insertAction = itemsMenu->addAction(tr("&Insert Item")); + removeAction = itemsMenu->addAction(tr("&Remove Item")); + removeAction->setEnabled(false); + itemsMenu->addSeparator(); + ascendingAction = itemsMenu->addAction(tr("Sort in &Ascending Order")); + descendingAction = itemsMenu->addAction(tr("Sort in &Descending Order")); + autoSortAction = itemsMenu->addAction(tr("&Automatically Sort Items")); + autoSortAction->setCheckable(true); + itemsMenu->addSeparator(); + QAction *findItemsAction = itemsMenu->addAction(tr("&Find Items")); + findItemsAction->setShortcut(tr("Ctrl+F")); + + menuBar()->addMenu(fileMenu); + menuBar()->addMenu(itemsMenu); + +/* For convenient quoting: +//! [0] + QTreeWidget *treeWidget = new QTreeWidget(this); +//! [0] +*/ + treeWidget = new QTreeWidget(this); +//! [1] + treeWidget->setColumnCount(2); +//! [1] //! [2] + QStringList headers; + headers << tr("Subject") << tr("Default"); + treeWidget->setHeaderLabels(headers); +//! [2] + + connect(quitAction, SIGNAL(triggered()), this, SLOT(close())); + connect(ascendingAction, SIGNAL(triggered()), this, SLOT(sortAscending())); + connect(autoSortAction, SIGNAL(triggered()), this, SLOT(updateSortItems())); + connect(descendingAction, SIGNAL(triggered()), this, SLOT(sortDescending())); + connect(findItemsAction, SIGNAL(triggered()), this, SLOT(findItems())); + connect(insertAction, SIGNAL(triggered()), this, SLOT(insertItem())); + connect(removeAction, SIGNAL(triggered()), this, SLOT(removeItem())); + connect(treeWidget, + SIGNAL(currentItemChanged(QTreeWidgetItem *, QTreeWidgetItem *)), + this, SLOT(updateMenus(QTreeWidgetItem *))); + + setupTreeItems(); + updateMenus(treeWidget->currentItem()); + + setCentralWidget(treeWidget); + setWindowTitle(tr("Tree Widget")); +} + +void MainWindow::setupTreeItems() +{ +//! [3] + QTreeWidgetItem *cities = new QTreeWidgetItem(treeWidget); + cities->setText(0, tr("Cities")); + QTreeWidgetItem *osloItem = new QTreeWidgetItem(cities); + osloItem->setText(0, tr("Oslo")); + osloItem->setText(1, tr("Yes")); +//! [3] + + (new QTreeWidgetItem(cities))->setText(0, tr("Stockholm")); + (new QTreeWidgetItem(cities))->setText(0, tr("Helsinki")); + (new QTreeWidgetItem(cities))->setText(0, tr("Copenhagen")); + +//! [4] //! [5] + QTreeWidgetItem *planets = new QTreeWidgetItem(treeWidget, cities); +//! [4] + planets->setText(0, tr("Planets")); +//! [5] + (new QTreeWidgetItem(planets))->setText(0, tr("Mercury")); + (new QTreeWidgetItem(planets))->setText(0, tr("Venus")); + + QTreeWidgetItem *earthItem = new QTreeWidgetItem(planets); + earthItem->setText(0, tr("Earth")); + earthItem->setText(1, tr("Yes")); + + (new QTreeWidgetItem(planets))->setText(0, tr("Mars")); + (new QTreeWidgetItem(planets))->setText(0, tr("Jupiter")); + (new QTreeWidgetItem(planets))->setText(0, tr("Saturn")); + (new QTreeWidgetItem(planets))->setText(0, tr("Uranus")); + (new QTreeWidgetItem(planets))->setText(0, tr("Neptune")); + (new QTreeWidgetItem(planets))->setText(0, tr("Pluto")); +} + +void MainWindow::findItems() +{ + QString itemText = QInputDialog::getText(this, tr("Find Items"), + tr("Text to find (including wildcards):")); + + if (itemText.isEmpty()) + return; + +//! [6] + QTreeWidgetItem *item; +//! [6] + foreach (item, treeWidget->selectedItems()) + treeWidget->setItemSelected(item, false); + +//! [7] + QList<QTreeWidgetItem *> found = treeWidget->findItems( + itemText, Qt::MatchWildcard); + + foreach (item, found) { + treeWidget->setItemSelected(item, true); + // Show the item->text(0) for each item. + } +//! [7] +} + +void MainWindow::insertItem() +{ + QTreeWidgetItem *currentItem = treeWidget->currentItem(); + + if (!currentItem) + return; + + QString itemText = QInputDialog::getText(this, tr("Insert Item"), + tr("Input text for the new item:")); + + if (itemText.isEmpty()) + return; + +//! [8] + QTreeWidgetItem *parent = currentItem->parent(); + QTreeWidgetItem *newItem; + if (parent) + newItem = new QTreeWidgetItem(parent, treeWidget->currentItem()); + else +//! [8] //! [9] + newItem = new QTreeWidgetItem(treeWidget, treeWidget->currentItem()); +//! [9] + + newItem->setText(0, itemText); +} + +void MainWindow::removeItem() +{ + QTreeWidgetItem *currentItem = treeWidget->currentItem(); + + if (!currentItem) + return; + +//! [10] + QTreeWidgetItem *parent = currentItem->parent(); + int index; + + if (parent) { + index = parent->indexOfChild(treeWidget->currentItem()); + delete parent->takeChild(index); + } else { + index = treeWidget->indexOfTopLevelItem(treeWidget->currentItem()); + delete treeWidget->takeTopLevelItem(index); +//! [10] //! [11] + } +//! [11] +} + +void MainWindow::sortAscending() +{ + treeWidget->sortItems(0, Qt::AscendingOrder); +} + +void MainWindow::sortDescending() +{ + treeWidget->sortItems(0, Qt::DescendingOrder); +} + +void MainWindow::updateMenus(QTreeWidgetItem *current) +{ + insertAction->setEnabled(current != 0); + removeAction->setEnabled(current != 0); +} + +void MainWindow::updateSortItems() +{ + ascendingAction->setEnabled(!autoSortAction->isChecked()); + descendingAction->setEnabled(!autoSortAction->isChecked()); + + treeWidget->setSortingEnabled(autoSortAction->isChecked()); +} diff --git a/doc/src/snippets/qtreewidgetitemiterator-using/mainwindow.cpp b/doc/src/snippets/qtreewidgetitemiterator-using/mainwindow.cpp new file mode 100644 index 0000000000..497540e054 --- /dev/null +++ b/doc/src/snippets/qtreewidgetitemiterator-using/mainwindow.cpp @@ -0,0 +1,197 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> + +#include "mainwindow.h" + +MainWindow::MainWindow() +{ + QMenu *fileMenu = new QMenu(tr("&File")); + + QAction *quitAction = fileMenu->addAction(tr("E&xit")); + quitAction->setShortcut(tr("Ctrl+Q")); + + QMenu *itemsMenu = new QMenu(tr("&Items")); + + insertAction = itemsMenu->addAction(tr("&Insert Item")); + removeAction = itemsMenu->addAction(tr("&Remove Item")); + removeAction->setEnabled(false); + itemsMenu->addSeparator(); + ascendingAction = itemsMenu->addAction(tr("Sort in &Ascending Order")); + descendingAction = itemsMenu->addAction(tr("Sort in &Descending Order")); + autoSortAction = itemsMenu->addAction(tr("&Automatically Sort Items")); + autoSortAction->setCheckable(true); + itemsMenu->addSeparator(); + QAction *findItemsAction = itemsMenu->addAction(tr("&Find Items")); + findItemsAction->setShortcut(tr("Ctrl+F")); + + menuBar()->addMenu(fileMenu); + menuBar()->addMenu(itemsMenu); + +/* For convenient quoting: + QTreeWidget *treeWidget = new QTreeWidget(this); +*/ + treeWidget = new QTreeWidget(this); + treeWidget->setColumnCount(2); + QStringList headers; + headers << tr("Subject") << tr("Default"); + treeWidget->setHeaderLabels(headers); + + connect(quitAction, SIGNAL(triggered()), this, SLOT(close())); + connect(ascendingAction, SIGNAL(triggered()), this, SLOT(sortAscending())); + connect(autoSortAction, SIGNAL(triggered()), this, SLOT(updateSortItems())); + connect(descendingAction, SIGNAL(triggered()), this, SLOT(sortDescending())); + connect(findItemsAction, SIGNAL(triggered()), this, SLOT(findItems())); + connect(insertAction, SIGNAL(triggered()), this, SLOT(insertItem())); + connect(removeAction, SIGNAL(triggered()), this, SLOT(removeItem())); + connect(treeWidget, + SIGNAL(currentItemChanged(QTreeWidgetItem *, QTreeWidgetItem *)), + this, SLOT(updateMenus(QTreeWidgetItem *))); + + setupTreeItems(); + updateMenus(treeWidget->currentItem()); + + setCentralWidget(treeWidget); + setWindowTitle(tr("Tree Widget")); +} + +void MainWindow::setupTreeItems() +{ + QTreeWidgetItem *planets = new QTreeWidgetItem(treeWidget); + planets->setText(0, tr("Planets")); + (new QTreeWidgetItem(planets))->setText(0, tr("Mercury")); + (new QTreeWidgetItem(planets))->setText(0, tr("Venus")); + + QTreeWidgetItem *earthItem = new QTreeWidgetItem(planets); + earthItem->setText(0, tr("Earth")); + earthItem->setText(1, tr("Yes")); + + (new QTreeWidgetItem(planets))->setText(0, tr("Mars")); + (new QTreeWidgetItem(planets))->setText(0, tr("Jupiter")); + (new QTreeWidgetItem(planets))->setText(0, tr("Saturn")); + (new QTreeWidgetItem(planets))->setText(0, tr("Uranus")); + (new QTreeWidgetItem(planets))->setText(0, tr("Neptune")); + (new QTreeWidgetItem(planets))->setText(0, tr("Pluto")); +} + +void MainWindow::findItems() +{ + QString itemText = QInputDialog::getText(this, tr("Find Items"), + tr("Text to find:")); + + if (itemText.isEmpty()) + return; + +//! [0] + QTreeWidgetItemIterator it(treeWidget); + while (*it) { + if ((*it)->text(0) == itemText) + (*it)->setSelected(true); + ++it; + } +//! [0] +} + +void MainWindow::insertItem() +{ + QTreeWidgetItem *currentItem = treeWidget->currentItem(); + + if (!currentItem) + return; + + QString itemText = QInputDialog::getText(this, tr("Insert Item"), + tr("Input text for the new item:")); + + if (itemText.isEmpty()) + return; + + QTreeWidgetItem *parent = currentItem->parent(); + QTreeWidgetItem *newItem; + if (parent) + newItem = new QTreeWidgetItem(parent, treeWidget->currentItem()); + else + newItem = new QTreeWidgetItem(treeWidget, treeWidget->currentItem()); + + newItem->setText(0, itemText); +} + +void MainWindow::removeItem() +{ + QTreeWidgetItem *currentItem = treeWidget->currentItem(); + + if (!currentItem) + return; + + QTreeWidgetItem *parent = currentItem->parent(); + int index; + + if (parent) { + index = parent->indexOfChild(treeWidget->currentItem()); + delete parent->takeChild(index); + } else { + index = treeWidget->indexOfTopLevelItem(treeWidget->currentItem()); + delete treeWidget->takeTopLevelItem(index); + } +} + +void MainWindow::sortAscending() +{ + treeWidget->sortItems(0, Qt::AscendingOrder); +} + +void MainWindow::sortDescending() +{ + treeWidget->sortItems(0, Qt::DescendingOrder); +} + +void MainWindow::updateMenus(QTreeWidgetItem *current) +{ + insertAction->setEnabled(current != 0); + removeAction->setEnabled(current != 0); +} + +void MainWindow::updateSortItems() +{ + ascendingAction->setEnabled(!autoSortAction->isChecked()); + descendingAction->setEnabled(!autoSortAction->isChecked()); + + treeWidget->setSortingEnabled(autoSortAction->isChecked()); +} diff --git a/doc/src/snippets/quiloader/main.cpp b/doc/src/snippets/quiloader/main.cpp new file mode 100644 index 0000000000..2b9acd2d3f --- /dev/null +++ b/doc/src/snippets/quiloader/main.cpp @@ -0,0 +1,70 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> +#include <QtUiTools> + +#include "mywidget.h" + +//! [0] +QWidget *loadCustomWidget(QWidget *parent) +{ + QUiLoader loader; + QWidget *myWidget; + + QStringList availableWidgets = loader.availableWidgets(); + + if (availableWidgets.contains("AnalogClock")) + myWidget = loader.createWidget("AnalogClock", parent); + + return myWidget; +} +//! [0] + +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + MyWidget widget; + widget.show(); + + QWidget *customWidget = loadCustomWidget(0); + customWidget->show(); + return app.exec(); +} diff --git a/doc/src/snippets/quiloader/mywidget.cpp b/doc/src/snippets/quiloader/mywidget.cpp new file mode 100644 index 0000000000..989a5ef075 --- /dev/null +++ b/doc/src/snippets/quiloader/mywidget.cpp @@ -0,0 +1,60 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> +#include <QtUiTools> + +#include "mywidget.h" + +//! [0] +MyWidget::MyWidget(QWidget *parent) + : QWidget(parent) +{ + QUiLoader loader; + QFile file(":/forms/myform.ui"); + file.open(QFile::ReadOnly); + QWidget *myWidget = loader.load(&file, this); + file.close(); + + QVBoxLayout *layout = new QVBoxLayout; + layout->addWidget(myWidget); + setLayout(layout); +} +//! [0] diff --git a/doc/src/snippets/quiloader/mywidget.qrc b/doc/src/snippets/quiloader/mywidget.qrc new file mode 100644 index 0000000000..47684d68b8 --- /dev/null +++ b/doc/src/snippets/quiloader/mywidget.qrc @@ -0,0 +1,5 @@ +<!DOCTYPE RCC><RCC version="1.0"> +<qresource prefix="/forms"> +<file>myform.ui</file> +</qresource> +</RCC> diff --git a/doc/src/snippets/qx11embedcontainer/main.cpp b/doc/src/snippets/qx11embedcontainer/main.cpp new file mode 100644 index 0000000000..38d6d28292 --- /dev/null +++ b/doc/src/snippets/qx11embedcontainer/main.cpp @@ -0,0 +1,67 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> +#include <QX11EmbedContainer> + +//! [0] +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + + if (app.arguments().count() != 2) { + qFatal("Error - expected executable path as argument"); + return 1; + } + + QX11EmbedContainer container; + container.show(); + + QProcess process(&container); + QString executable(app.arguments()[1]); + QStringList arguments; + arguments << QString::number(container.winId()); + process.start(executable, arguments); + + int status = app.exec(); + process.close(); + return status; +} +//! [0] diff --git a/doc/src/snippets/qx11embedwidget/main.cpp b/doc/src/snippets/qx11embedwidget/main.cpp new file mode 100644 index 0000000000..4f82399699 --- /dev/null +++ b/doc/src/snippets/qx11embedwidget/main.cpp @@ -0,0 +1,61 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QApplication> +#include "embedwidget.h" + +//! [0] +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + + if (app.arguments().count() != 2) { + qFatal("Error - expected window id as argument"); + return 1; + } + + QString windowId(app.arguments()[1]); + EmbedWidget window; + window.embedInto(windowId.toULong()); + window.show(); + + return app.exec(); +} +//! [0] diff --git a/doc/src/snippets/qxmlstreamwriter/main.cpp b/doc/src/snippets/qxmlstreamwriter/main.cpp new file mode 100644 index 0000000000..2e7deff168 --- /dev/null +++ b/doc/src/snippets/qxmlstreamwriter/main.cpp @@ -0,0 +1,76 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QCoreApplication> +#include <QFile> +#include <QXmlStreamWriter> +#include <stdio.h> + +int main(int argc, char *argv[]) +{ + QCoreApplication app(argc, argv); + QFile output; + output.open(stdout, QIODevice::WriteOnly); +//! [write output] +//! [start stream] + QXmlStreamWriter stream(&output); + stream.setAutoFormatting(true); + stream.writeStartDocument(); +//! [start stream] + stream.writeDTD("<!DOCTYPE xbel>"); + stream.writeStartElement("xbel"); + stream.writeAttribute("version", "1.0"); + stream.writeStartElement("folder"); + stream.writeAttribute("folded", "no"); +//! [write element] + stream.writeStartElement("bookmark"); + stream.writeAttribute("href", "http://qt.nokia.com/"); + stream.writeTextElement("title", "Qt Home"); + stream.writeEndElement(); // bookmark +//! [write element] + stream.writeEndElement(); // folder + stream.writeEndElement(); // xbel +//! [finish stream] + stream.writeEndDocument(); +//! [finish stream] +//! [write output] + output.close(); + return 0; +} diff --git a/doc/src/snippets/separations/finalwidget.cpp b/doc/src/snippets/separations/finalwidget.cpp new file mode 100644 index 0000000000..8d2b7feacc --- /dev/null +++ b/doc/src/snippets/separations/finalwidget.cpp @@ -0,0 +1,126 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/* +finalwidget.cpp + +A widget to display an image and a label containing a description. +*/ + +#include <QtGui> +#include "finalwidget.h" + +FinalWidget::FinalWidget(QWidget *parent, const QString &name, + const QSize &labelSize) + : QFrame(parent) +{ + hasImage = false; + imageLabel = new QLabel; + imageLabel->setFrameShadow(QFrame::Sunken); + imageLabel->setFrameShape(QFrame::StyledPanel); + imageLabel->setMinimumSize(labelSize); + nameLabel = new QLabel(name); + + QVBoxLayout *layout = new QVBoxLayout; + layout->addWidget(imageLabel, 1); + layout->addWidget(nameLabel, 0); + setLayout(layout); +} + +/*! + If the mouse moves far enough when the left mouse button is held down, + start a drag and drop operation. +*/ + +void FinalWidget::mouseMoveEvent(QMouseEvent *event) +{ + if (!(event->buttons() & Qt::LeftButton)) + return; + if ((event->pos() - dragStartPosition).manhattanLength() + < QApplication::startDragDistance()) + return; + if (!hasImage) + return; + + QDrag *drag = new QDrag(this); + QMimeData *mimeData = new QMimeData; + +//! [0] + QByteArray output; + QBuffer outputBuffer(&output); + outputBuffer.open(QIODevice::WriteOnly); + imageLabel->pixmap()->toImage().save(&outputBuffer, "PNG"); + mimeData->setData("image/png", output); +//! [0] +/* +//! [1] + mimeData->setImageData(QVariant(*imageLabel->pixmap())); +//! [1] +*/ + drag->setMimeData(mimeData); + drag->setPixmap(imageLabel->pixmap()->scaled(64, 64, Qt::KeepAspectRatio)); +//! [2] + drag->setHotSpot(QPoint(drag->pixmap().width()/2, + drag->pixmap().height())); +//! [2] + + drag->start(); +} + +/*! + Check for left mouse button presses in order to enable drag and drop. +*/ + +void FinalWidget::mousePressEvent(QMouseEvent *event) +{ + if (event->button() == Qt::LeftButton) + dragStartPosition = event->pos(); +} + +const QPixmap* FinalWidget::pixmap() const +{ + return imageLabel->pixmap(); +} + +void FinalWidget::setPixmap(const QPixmap &pixmap) +{ + imageLabel->setPixmap(pixmap); + hasImage = true; +} diff --git a/doc/src/snippets/settings/settings.cpp b/doc/src/snippets/settings/settings.cpp new file mode 100644 index 0000000000..2cbe1804be --- /dev/null +++ b/doc/src/snippets/settings/settings.cpp @@ -0,0 +1,184 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> + +QWidget *win; +QWidget *panel; + +void snippet_ctor1() +{ +//! [0] + QSettings settings("MySoft", "Star Runner"); +//! [0] +} + +void snippet_ctor2() +{ +//! [1] + QCoreApplication::setOrganizationName("MySoft"); +//! [1] //! [2] + QCoreApplication::setOrganizationDomain("mysoft.com"); +//! [2] //! [3] + QCoreApplication::setApplicationName("Star Runner"); +//! [3] + +//! [4] + QSettings settings; +//! [4] + +//! [5] + settings.setValue("editor/wrapMargin", 68); +//! [5] //! [6] + int margin = settings.value("editor/wrapMargin").toInt(); +//! [6] + { +//! [7] + int margin = settings.value("editor/wrapMargin", 80).toInt(); +//! [7] + } + +//! [8] + settings.setValue("mainwindow/size", win->size()); +//! [8] //! [9] + settings.setValue("mainwindow/fullScreen", win->isFullScreen()); +//! [9] //! [10] + settings.setValue("outputpanel/visible", panel->isVisible()); +//! [10] + +//! [11] + settings.beginGroup("mainwindow"); + settings.setValue("size", win->size()); + settings.setValue("fullScreen", win->isFullScreen()); + settings.endGroup(); +//! [11] + +//! [12] + settings.beginGroup("outputpanel"); + settings.setValue("visible", panel->isVisible()); + settings.endGroup(); +//! [12] +} + +void snippet_locations() +{ +//! [13] + QSettings obj1("MySoft", "Star Runner"); +//! [13] //! [14] + QSettings obj2("MySoft"); + QSettings obj3(QSettings::SystemScope, "MySoft", "Star Runner"); + QSettings obj4(QSettings::SystemScope, "MySoft"); +//! [14] + + { +//! [15] + QSettings settings(QSettings::IniFormat, QSettings::UserScope, + "MySoft", "Star Runner"); +//! [15] + } + + { + QSettings settings("starrunner.ini", QSettings::IniFormat); + } + + { + QSettings settings("HKEY_CURRENT_USER\\Software\\Microsoft", + QSettings::NativeFormat); + } +} + +class MainWindow : public QMainWindow +{ +public: + MainWindow(); + + void writeSettings(); + void readSettings(); + +protected: + void closeEvent(QCloseEvent *event); +}; + +//! [16] +void MainWindow::writeSettings() +{ + QSettings settings("Moose Soft", "Clipper"); + + settings.beginGroup("MainWindow"); + settings.setValue("size", size()); + settings.setValue("pos", pos()); + settings.endGroup(); +} +//! [16] + +//! [17] +void MainWindow::readSettings() +{ + QSettings settings("Moose Soft", "Clipper"); + + settings.beginGroup("MainWindow"); + resize(settings.value("size", QSize(400, 400)).toSize()); + move(settings.value("pos", QPoint(200, 200)).toPoint()); + settings.endGroup(); +} +//! [17] + +//! [18] +MainWindow::MainWindow() +{ +//! [18] //! [19] + readSettings(); +//! [19] //! [20] +} +//! [20] + +bool userReallyWantsToQuit() { return true; } + +//! [21] +void MainWindow::closeEvent(QCloseEvent *event) +{ + if (userReallyWantsToQuit()) { + writeSettings(); + event->accept(); + } else { + event->ignore(); + } +} +//! [21] diff --git a/doc/src/snippets/shareddirmodel/main.cpp b/doc/src/snippets/shareddirmodel/main.cpp new file mode 100644 index 0000000000..1cd2bde1bd --- /dev/null +++ b/doc/src/snippets/shareddirmodel/main.cpp @@ -0,0 +1,81 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/* + main.cpp + + A simple example of how to view a model in several views, and share a + selection model. +*/ + +#include <QtGui> + +//! [0] //! [1] +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + QSplitter *splitter = new QSplitter; + +//! [2] //! [3] + QFileSystemModel *model = new QFileSystemModel; + model->setRootPath(QDir::currentPath()); +//! [0] //! [2] //! [4] //! [5] + QTreeView *tree = new QTreeView(splitter); +//! [3] //! [6] + tree->setModel(model); +//! [4] //! [6] //! [7] + tree->setRootIndex(model->index(QDir::currentPath())); +//! [7] + + QListView *list = new QListView(splitter); + list->setModel(model); + list->setRootIndex(model->index(QDir::currentPath())); + +//! [5] + QItemSelectionModel *selection = new QItemSelectionModel(model); + tree->setSelectionModel(selection); + list->setSelectionModel(selection); + +//! [8] + splitter->setWindowTitle("Two views onto the same file system model"); + splitter->show(); + return app.exec(); +} +//! [1] //! [8] diff --git a/doc/src/snippets/sharedemployee/employee.h b/doc/src/snippets/sharedemployee/employee.h new file mode 100644 index 0000000000..981e007b8d --- /dev/null +++ b/doc/src/snippets/sharedemployee/employee.h @@ -0,0 +1,94 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#ifndef EMPLOYEE_H +#define EMPLOYEE_H + +//! [0] +#include <QSharedData> +#include <QString> + +class EmployeeData : public QSharedData +{ + public: + EmployeeData() : id(-1) { } + EmployeeData(const EmployeeData &other) + : QSharedData(other), id(other.id), name(other.name) { } + ~EmployeeData() { } + + int id; + QString name; +}; + +class Employee +{ + public: +//! [1] + Employee() { d = new EmployeeData; } +//! [1] //! [2] + Employee(int id, QString name) { + d = new EmployeeData; + setId(id); + setName(name); + } +//! [2] //! [7] + Employee(const Employee &other) + : d (other.d) + { + } +//! [7] +//! [3] + void setId(int id) { d->id = id; } +//! [3] //! [4] + void setName(QString name) { d->name = name; } +//! [4] + +//! [5] + int id() const { return d->id; } +//! [5] //! [6] + QString name() const { return d->name; } +//! [6] + + private: + QSharedDataPointer<EmployeeData> d; +}; +//! [0] + +#endif diff --git a/doc/src/snippets/sharedemployee/main.cpp b/doc/src/snippets/sharedemployee/main.cpp new file mode 100644 index 0000000000..a8f53a738c --- /dev/null +++ b/doc/src/snippets/sharedemployee/main.cpp @@ -0,0 +1,50 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +#include "employee.h" + +int main() +{ + Employee e1(1001, "Albrecht Durer"); + Employee e2 = e1; + e1.setName("Hans Holbein"); +} +//! [0] diff --git a/doc/src/snippets/signalmapper/filereader.cpp b/doc/src/snippets/signalmapper/filereader.cpp new file mode 100644 index 0000000000..d7be2e854b --- /dev/null +++ b/doc/src/snippets/signalmapper/filereader.cpp @@ -0,0 +1,107 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the config.tests of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> +#include "filereader.h" + + +FileReader::FileReader(QWidget *parent) + : QWidget(parent) +{ + textEdit = new QTextEdit; + + taxFileButton = new QPushButton("Tax File"); + accountFileButton = new QPushButton("Accounts File"); + reportFileButton = new QPushButton("Report File"); + +//! [0] + signalMapper = new QSignalMapper(this); + signalMapper->setMapping(taxFileButton, QString("taxfile.txt")); + signalMapper->setMapping(accountFileButton, QString("accountsfile.txt")); + signalMapper->setMapping(reportFileButton, QString("reportfile.txt")); + + connect(taxFileButton, SIGNAL(clicked()), + signalMapper, SLOT (map())); + connect(accountFileButton, SIGNAL(clicked()), + signalMapper, SLOT (map())); + connect(reportFileButton, SIGNAL(clicked()), + signalMapper, SLOT (map())); +//! [0] + +//! [1] + connect(signalMapper, SIGNAL(mapped(QString)), + this, SLOT(readFile(QString))); +//! [1] + +/* +//! [2] + //slower due to signature normalization at runtime + + connect(signalMapper, SIGNAL(mapped(const QString &)), + this, SLOT(readFile(const QString &))); +//! [2] +*/ + QHBoxLayout *buttonLayout = new QHBoxLayout; + buttonLayout->addWidget(taxFileButton); + buttonLayout->addWidget(accountFileButton); + buttonLayout->addWidget(reportFileButton); + + QVBoxLayout *mainLayout = new QVBoxLayout; + mainLayout->addWidget(textEdit); + mainLayout->addLayout(buttonLayout); + + setLayout(mainLayout); +} + +void FileReader::readFile(const QString &filename) +{ + QFile file(filename); + + if (!file.open(QIODevice::ReadOnly)) { + QMessageBox::information(this, tr("Unable to open file"), + file.errorString()); + return; + } + + + QTextStream in(&file); + textEdit->setPlainText(in.readAll()); +} + diff --git a/doc/src/snippets/signalsandslots/lcdnumber.h b/doc/src/snippets/signalsandslots/lcdnumber.h new file mode 100644 index 0000000000..3706387d24 --- /dev/null +++ b/doc/src/snippets/signalsandslots/lcdnumber.h @@ -0,0 +1,88 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +#ifndef LCDNUMBER_H +//! [0] //! [1] +#define LCDNUMBER_H +//! [1] + +//! [2] +#include <QFrame> +//! [2] + +//! [3] +class LcdNumber : public QFrame +//! [3] //! [4] +{ +//! [4] //! [5] + Q_OBJECT +//! [5] + +//! [6] +public: +//! [6] //! [7] + LcdNumber(QWidget *parent = 0); +//! [7] + +//! [8] +signals: +//! [8] //! [9] + void overflow(); +//! [9] + +//! [10] +public slots: +//! [10] //! [11] + void display(int num); + void display(double num); + void display(const QString &str); + void setHexMode(); + void setDecMode(); + void setOctMode(); + void setBinMode(); + void setSmallDecimalPoint(bool point); +//! [11] //! [12] +}; +//! [12] + +//! [13] +#endif +//! [13] diff --git a/doc/src/snippets/signalsandslots/signalsandslots.cpp b/doc/src/snippets/signalsandslots/signalsandslots.cpp new file mode 100644 index 0000000000..42622322ed --- /dev/null +++ b/doc/src/snippets/signalsandslots/signalsandslots.cpp @@ -0,0 +1,84 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QAbstractButton> + +#include "signalsandslots.h" + +//! [0] +void Counter::setValue(int value) +{ + if (value != m_value) { + m_value = value; + emit valueChanged(value); + } +} +//! [0] + +int main() +{ +//! [1] + Counter a, b; +//! [1] //! [2] + QObject::connect(&a, SIGNAL(valueChanged(int)), + &b, SLOT(setValue(int))); +//! [2] + +//! [3] + a.setValue(12); // a.value() == 12, b.value() == 12 +//! [3] //! [4] + b.setValue(48); // a.value() == 12, b.value() == 48 +//! [4] + + + QWidget *widget = reinterpret_cast<QWidget *>(new QObject(0)); +//! [5] + if (widget->inherits("QAbstractButton")) { + QAbstractButton *button = static_cast<QAbstractButton *>(widget); + button->toggle(); +//! [5] //! [6] + } +//! [6] + +//! [7] + if (QAbstractButton *button = qobject_cast<QAbstractButton *>(widget)) + button->toggle(); +//! [7] +} diff --git a/doc/src/snippets/signalsandslots/signalsandslots.h b/doc/src/snippets/signalsandslots/signalsandslots.h new file mode 100644 index 0000000000..0671181f5f --- /dev/null +++ b/doc/src/snippets/signalsandslots/signalsandslots.h @@ -0,0 +1,89 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#ifndef SIGNALSANDSLOTS_H +#define SIGNALSANDSLOTS_H + +#define Counter PlainCounter + +//! [0] +class Counter +{ +public: + Counter() { m_value = 0; } + + int value() const { return m_value; } + void setValue(int value); + +private: + int m_value; +}; +//! [0] + +#undef Counter +#define Counter ObjectCounter + +//! [1] +#include <QObject> +//! [1] + +//! [2] +class Counter : public QObject +//! [2] //! [3] +{ + Q_OBJECT + +public: + Counter() { m_value = 0; } + + int value() const { return m_value; } + +public slots: + void setValue(int value); + +signals: + void valueChanged(int newValue); + +private: + int m_value; +}; +//! [3] + +#endif diff --git a/doc/src/snippets/splitter/splitter.cpp b/doc/src/snippets/splitter/splitter.cpp new file mode 100644 index 0000000000..b72eb02e4c --- /dev/null +++ b/doc/src/snippets/splitter/splitter.cpp @@ -0,0 +1,84 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> + +void processSize(int) +{ +} + +int main() +{ + QWidget *parent = 0; + +//! [0] + QSplitter *splitter = new QSplitter(parent); + QListView *listview = new QListView; + QTreeView *treeview = new QTreeView; + QTextEdit *textedit = new QTextEdit; + splitter->addWidget(listview); + splitter->addWidget(treeview); + splitter->addWidget(textedit); +//! [0] + + { + // SAVE STATE +//! [1] + QSettings settings; + settings.setValue("splitterSizes", splitter->saveState()); +//! [1] + } + + { + // RESTORE STATE +//! [2] + QSettings settings; + splitter->restoreState(settings.value("splitterSizes").toByteArray()); +//! [2] + } + +//! [3] + QListIterator<int> it(splitter->sizes()); + while (it.hasNext()) + processSize(it.next()); +//! [3] + + return 0; +} diff --git a/doc/src/snippets/splitterhandle/splitter.cpp b/doc/src/snippets/splitterhandle/splitter.cpp new file mode 100644 index 0000000000..6f76c57b41 --- /dev/null +++ b/doc/src/snippets/splitterhandle/splitter.cpp @@ -0,0 +1,78 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> + +#include "splitter.h" + +SplitterHandle::SplitterHandle(Qt::Orientation orientation, QSplitter *parent) + : QSplitterHandle(orientation, parent) +{ + gradient.setColorAt(0.0, Qt::darkGreen); + gradient.setColorAt(0.25, Qt::white); + gradient.setColorAt(1.0, Qt::darkGreen); +} + +//! [0] +void SplitterHandle::paintEvent(QPaintEvent *event) +{ + QPainter painter(this); + if (orientation() == Qt::Horizontal) { + gradient.setStart(rect().left(), rect().height()/2); + gradient.setFinalStop(rect().right(), rect().height()/2); + } else { + gradient.setStart(rect().width()/2, rect().top()); + gradient.setFinalStop(rect().width()/2, rect().bottom()); + } + painter.fillRect(event->rect(), QBrush(gradient)); +} +//! [0] + +Splitter::Splitter(Qt::Orientation orientation, QWidget *parent) + : QSplitter(orientation, parent) +{ +} + +//! [1] +QSplitterHandle *Splitter::createHandle() +{ + return new SplitterHandle(orientation(), this); +} +//! [1] diff --git a/doc/src/snippets/splitterhandle/splitter.h b/doc/src/snippets/splitterhandle/splitter.h new file mode 100644 index 0000000000..505c431f6d --- /dev/null +++ b/doc/src/snippets/splitterhandle/splitter.h @@ -0,0 +1,73 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#ifndef SPLITTER_H +#define SPLITTER_H + +#include <QLinearGradient> +#include <QSplitter> +#include <QSplitterHandle> + +class QPaintEvent; + +//! [0] +class Splitter : public QSplitter +{ +public: + Splitter(Qt::Orientation orientation, QWidget *parent = 0); + +protected: + QSplitterHandle *createHandle(); +}; +//! [0] + +class SplitterHandle : public QSplitterHandle +{ +public: + SplitterHandle(Qt::Orientation orientation, QSplitter *parent); + +protected: + void paintEvent(QPaintEvent *event); + +private: + QLinearGradient gradient; +}; + +#endif diff --git a/doc/src/snippets/sqldatabase/sqldatabase.cpp b/doc/src/snippets/sqldatabase/sqldatabase.cpp new file mode 100644 index 0000000000..4f428c7f5b --- /dev/null +++ b/doc/src/snippets/sqldatabase/sqldatabase.cpp @@ -0,0 +1,559 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> +#include <QtSql> + +#include <iostream> + +using namespace std; + +QString tr(const char *text) +{ + return QApplication::translate(text, text); +} + +void QSqlDatabase_snippets() +{ + { +//! [0] + QSqlDatabase db = QSqlDatabase::addDatabase("QPSQL"); + db.setHostName("acidalia"); + db.setDatabaseName("customdb"); + db.setUserName("mojito"); + db.setPassword("J0a1m8"); + bool ok = db.open(); +//! [0] + Q_UNUSED(ok); + } + + { +//! [1] + QSqlDatabase db = QSqlDatabase::database(); +//! [1] + } +} + +void QSqlField_snippets() +{ +#if 0 + { +//! [2] + QSqlField field("age", QVariant::Int); + field.setValue(QPixmap()); // WRONG +//! [2] + } +#endif + + { +//! [3] + QSqlField field("age", QVariant::Int); + field.setValue(QString("123")); // casts QString to int +//! [3] + } + + { +//! [4] + QSqlQuery query; +//! [4] //! [5] + QSqlRecord record = query.record(); +//! [5] //! [6] + QSqlField field = record.field("country"); +//! [6] + } +} + +void doSomething(const QString &) +{ +} + +void QSqlQuery_snippets() +{ + { + // typical loop +//! [7] + QSqlQuery query("SELECT country FROM artist"); + while (query.next()) { + QString country = query.value(0).toString(); + doSomething(country); + } +//! [7] + } + + { + // field index lookup +//! [8] + QSqlQuery query("SELECT * FROM artist"); + int fieldNo = query.record().indexOf("country"); + while (query.next()) { + QString country = query.value(fieldNo).toString(); + doSomething(country); + } +//! [8] + } + + { + // named with named +//! [9] + QSqlQuery query; + query.prepare("INSERT INTO person (id, forename, surname) " + "VALUES (:id, :forename, :surname)"); + query.bindValue(":id", 1001); + query.bindValue(":forename", "Bart"); + query.bindValue(":surname", "Simpson"); + query.exec(); +//! [9] + } + + { + // positional with named +//! [10] + QSqlQuery query; + query.prepare("INSERT INTO person (id, forename, surname) " + "VALUES (:id, :forename, :surname)"); + query.bindValue(0, 1001); + query.bindValue(1, "Bart"); + query.bindValue(2, "Simpson"); + query.exec(); +//! [10] + } + + { + // positional 1 +//! [11] + QSqlQuery query; + query.prepare("INSERT INTO person (id, forename, surname) " + "VALUES (?, ?, ?)"); + query.bindValue(0, 1001); + query.bindValue(1, "Bart"); + query.bindValue(2, "Simpson"); + query.exec(); +//! [11] + } + + { + // positional 2 +//! [12] + QSqlQuery query; + query.prepare("INSERT INTO person (id, forename, surname) " + "VALUES (?, ?, ?)"); + query.addBindValue(1001); + query.addBindValue("Bart"); + query.addBindValue("Simpson"); + query.exec(); +//! [12] + } + + { + // stored +//! [13] + QSqlQuery query; + query.prepare("CALL AsciiToInt(?, ?)"); + query.bindValue(0, "A"); + query.bindValue(1, 0, QSql::Out); + query.exec(); + int i = query.boundValue(1).toInt(); // i is 65 +//! [13] + Q_UNUSED(i); + } + + QSqlQuery query; + + { + // examine with named binding +//! [14] + QMapIterator<QString, QVariant> i(query.boundValues()); + while (i.hasNext()) { + i.next(); + cout << i.key().toAscii().data() << ": " + << i.value().toString().toAscii().data() << endl; + } +//! [14] + } + + { + // examine with positional binding +//! [15] + QList<QVariant> list = query.boundValues().values(); + for (int i = 0; i < list.size(); ++i) + cout << i << ": " << list.at(i).toString().toAscii().data() << endl; +//! [15] + } +} + +void QSqlQueryModel_snippets() +{ + { +//! [16] + QSqlQueryModel *model = new QSqlQueryModel; + model->setQuery("SELECT name, salary FROM employee"); + model->setHeaderData(0, Qt::Horizontal, tr("Name")); + model->setHeaderData(1, Qt::Horizontal, tr("Salary")); + +//! [17] + QTableView *view = new QTableView; +//! [17] //! [18] + view->setModel(model); +//! [18] //! [19] + view->show(); +//! [16] //! [19] //! [20] + view->setEditTriggers(QAbstractItemView::NoEditTriggers); +//! [20] + } + +//! [21] + QSqlQueryModel model; + model.setQuery("SELECT * FROM employee"); + int salary = model.record(4).value("salary").toInt(); +//! [21] + Q_UNUSED(salary); + + { +//! [22] + int salary = model.data(model.index(4, 2)).toInt(); +//! [22] + Q_UNUSED(salary); + } + + for (int row = 0; row < model.rowCount(); ++row) { + for (int col = 0; col < model.columnCount(); ++col) { + qDebug() << model.data(model.index(row, col)); + } + } +} + +class MyModel : public QSqlQueryModel +{ +public: + QVariant data(const QModelIndex &item, int role) const; + + int m_specialColumnNo; +}; + +//! [23] +QVariant MyModel::data(const QModelIndex &item, int role) const +{ + if (item.column() == m_specialColumnNo) { + // handle column separately + } + return QSqlQueryModel::data(item, role); +} +//! [23] + +void QSqlTableModel_snippets() +{ +//! [24] + QSqlTableModel *model = new QSqlTableModel(parentObject, database); + model->setTable("employee"); + model->setEditStrategy(QSqlTableModel::OnManualSubmit); + model->select(); + model->removeColumn(0); // don't show the ID + model->setHeaderData(0, Qt::Horizontal, tr("Name")); + model->setHeaderData(1, Qt::Horizontal, tr("Salary")); + + QTableView *view = new QTableView; + view->setModel(model); + view->show(); +//! [24] + + { +//! [25] + QSqlTableModel model; + model.setTable("employee"); + QString name = model.record(4).value("name").toString(); +//! [25] + } +} + +void sql_intro_snippets() +{ + { +//! [26] + QSqlDatabase db = QSqlDatabase::addDatabase("QMYSQL"); + db.setHostName("bigblue"); + db.setDatabaseName("flightdb"); + db.setUserName("acarlson"); + db.setPassword("1uTbSbAs"); + bool ok = db.open(); +//! [26] + Q_UNUSED(ok); + } + + { +//! [27] + QSqlDatabase firstDB = QSqlDatabase::addDatabase("QMYSQL", "first"); + QSqlDatabase secondDB = QSqlDatabase::addDatabase("QMYSQL", "second"); +//! [27] + } + + { +//! [28] + QSqlDatabase defaultDB = QSqlDatabase::database(); +//! [28] //! [29] + QSqlDatabase firstDB = QSqlDatabase::database("first"); +//! [29] //! [30] + QSqlDatabase secondDB = QSqlDatabase::database("second"); +//! [30] + } + + { + // SELECT1 +//! [31] + QSqlQuery query; + query.exec("SELECT name, salary FROM employee WHERE salary > 50000"); +//! [31] + +//! [32] + while (query.next()) { + QString name = query.value(0).toString(); + int salary = query.value(1).toInt(); + qDebug() << name << salary; + } +//! [32] + } + + { + // FEATURE +//! [33] + QSqlQuery query; + int numRows; + query.exec("SELECT name, salary FROM employee WHERE salary > 50000"); + + QSqlDatabase defaultDB = QSqlDatabase::database(); + if (defaultDB.driver()->hasFeature(QSqlDriver::QuerySize)) { + numRows = query.size(); + } else { + // this can be very slow + query.last(); + numRows = query.at() + 1; + } +//! [33] + } + + { + // INSERT1 +//! [34] + QSqlQuery query; + query.exec("INSERT INTO employee (id, name, salary) " + "VALUES (1001, 'Thad Beaumont', 65000)"); +//! [34] + } + + { + // NAMED BINDING +//! [35] + QSqlQuery query; + query.prepare("INSERT INTO employee (id, name, salary) " + "VALUES (:id, :name, :salary)"); + query.bindValue(":id", 1001); + query.bindValue(":name", "Thad Beaumont"); + query.bindValue(":salary", 65000); + query.exec(); +//! [35] + } + + { + // POSITIONAL BINDING +//! [36] + QSqlQuery query; + query.prepare("INSERT INTO employee (id, name, salary) " + "VALUES (?, ?, ?)"); + query.addBindValue(1001); + query.addBindValue("Thad Beaumont"); + query.addBindValue(65000); + query.exec(); +//! [36] + } + + { + // UPDATE1 +//! [37] + QSqlQuery query; + query.exec("UPDATE employee SET salary = 70000 WHERE id = 1003"); +//! [37] + } + + { + // DELETE1 +//! [38] + QSqlQuery query; + query.exec("DELETE FROM employee WHERE id = 1007"); +//! [38] + } + + { + // TRANSACTION +//! [39] + QSqlDatabase::database().transaction(); + QSqlQuery query; + query.exec("SELECT id FROM employee WHERE name = 'Torild Halvorsen'"); + if (query.next()) { + int employeeId = query.value(0).toInt(); + query.exec("INSERT INTO project (id, name, ownerid) " + "VALUES (201, 'Manhattan Project', " + + QString::number(employeeId) + ')'); + } + QSqlDatabase::database().commit(); +//! [39] + } + + { + // SQLQUERYMODEL1 +//! [40] + QSqlQueryModel model; + model.setQuery("SELECT * FROM employee"); + + for (int i = 0; i < model.rowCount(); ++i) { + int id = model.record(i).value("id").toInt(); + QString name = model.record(i).value("name").toString(); + qDebug() << id << name; + } +//! [40] + } + + { + // SQLTABLEMODEL1 +//! [41] + QSqlTableModel model; + model.setTable("employee"); + model.setFilter("salary > 50000"); + model.setSort(2, Qt::DescendingOrder); + model.select(); + + for (int i = 0; i < model.rowCount(); ++i) { + QString name = model.record(i).value("name").toString(); + int salary = model.record(i).value("salary").toInt(); + qDebug() << name << salary; + } +//! [41] + } + + { + // SQLTABLEMODEL2 + QSqlTableModel model; + model.setTable("employee"); + +//! [42] + for (int i = 0; i < model.rowCount(); ++i) { + QSqlRecord record = model.record(i); + double salary = record.value("salary").toInt(); + salary *= 1.1; + record.setValue("salary", salary); + model.setRecord(i, record); + } + model.submitAll(); +//! [42] + + // SQLTABLEMODEL3 + int row = 1; + int column = 2; +//! [43] + model.setData(model.index(row, column), 75000); + model.submitAll(); +//! [43] + + // SQLTABLEMODEL4 +//! [44] + model.insertRows(row, 1); + model.setData(model.index(row, 0), 1013); + model.setData(model.index(row, 1), "Peter Gordon"); + model.setData(model.index(row, 2), 68500); + model.submitAll(); +//! [44] + +//! [45] + model.removeRows(row, 5); +//! [45] //! [46] + model.submitAll(); +//! [46] + } +} + +//! [47] +class XyzResult : public QSqlResult +{ +public: + XyzResult(const QSqlDriver *driver) + : QSqlResult(driver) {} + ~XyzResult() {} + +protected: + QVariant data(int /* index */) { return QVariant(); } + bool isNull(int /* index */) { return false; } + bool reset(const QString & /* query */) { return false; } + bool fetch(int /* index */) { return false; } + bool fetchFirst() { return false; } + bool fetchLast() { return false; } + int size() { return 0; } + int numRowsAffected() { return 0; } + QSqlRecord record() const { return QSqlRecord(); } +}; +//! [47] + +//! [48] +class XyzDriver : public QSqlDriver +{ +public: + XyzDriver() {} + ~XyzDriver() {} + + bool hasFeature(DriverFeature /* feature */) const { return false; } + bool open(const QString & /* db */, const QString & /* user */, + const QString & /* password */, const QString & /* host */, + int /* port */, const QString & /* options */) + { return false; } + void close() {} + QSqlResult *createResult() const { return new XyzResult(this); } +}; +//! [48] + +int main(int argc, char **argv) +{ + QApplication app(argc, argv); + + QSqlDatabase_snippets(); + QSqlField_snippets(); + QSqlQuery_snippets(); + QSqlQueryModel_snippets(); + QSqlTableModel_snippets(); + + XyzDriver driver; + XyzResult result(&driver); +} diff --git a/doc/src/snippets/styles/styles.cpp b/doc/src/snippets/styles/styles.cpp new file mode 100644 index 0000000000..23ab71b485 --- /dev/null +++ b/doc/src/snippets/styles/styles.cpp @@ -0,0 +1,91 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QStyleOption> +#include <QStylePainter> +#include <QWidget> + +class MyWidget : public QWidget +{ +protected: + void paintEvent(QPaintEvent *event); + void paintEvent2(QPaintEvent *event); + +}; + +//! [0] //! [1] +void MyWidget::paintEvent(QPaintEvent * /* event */) +//! [0] +{ +//! [2] + QPainter painter(this); +//! [2] + + QStyleOptionFocusRect option; + option.initFrom(this); + option.backgroundColor = palette().color(QPalette::Background); + +//! [3] + style()->drawPrimitive(QStyle::PE_FrameFocusRect, &option, &painter, this); +//! [3] +} +//! [1] + +void MyWidget::paintEvent2(QPaintEvent * /* event */) +//! [4] +{ +//! [4] //! [5] //! [6] + QStylePainter painter(this); +//! [5] + + QStyleOptionFocusRect option; + option.initFrom(this); + option.backgroundColor = palette().color(QPalette::Background); + +//! [7] + painter.drawPrimitive(QStyle::PE_FrameFocusRect, option); +//! [7] +} +//! [6] + +int main() +{ + return 0; +} diff --git a/doc/src/snippets/stylesheet/common-mistakes.cpp b/doc/src/snippets/stylesheet/common-mistakes.cpp new file mode 100644 index 0000000000..8de7f7941f --- /dev/null +++ b/doc/src/snippets/stylesheet/common-mistakes.cpp @@ -0,0 +1,52 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [1] + QPushButton { + color: grey; + border-image: url(/home/kamlie/code/button.png) 3 10 3 10; + border-top: 3px transparent; + border-bottom: 3px transparent; + border-right: 10px transparent; + border-left: 10px transparent; + } +//! [1] + + diff --git a/doc/src/snippets/textblock-fragments/xmlwriter.cpp b/doc/src/snippets/textblock-fragments/xmlwriter.cpp new file mode 100644 index 0000000000..252720bc14 --- /dev/null +++ b/doc/src/snippets/textblock-fragments/xmlwriter.cpp @@ -0,0 +1,117 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> + +#include "xmlwriter.h" + +QDomDocument *XmlWriter::toXml() +{ + QDomImplementation implementation; + QDomDocumentType docType = implementation.createDocumentType( + "scribe-document", "scribe", "qt.nokia.com/scribe"); + + document = new QDomDocument(docType); + + // ### This processing instruction is required to ensure that any kind + // of encoding is given when the document is written. + QDomProcessingInstruction process = document->createProcessingInstruction( + "xml", "version=\"1.0\" encoding=\"utf-8\""); + document->appendChild(process); + + QDomElement documentElement = document->createElement("document"); + document->appendChild(documentElement); + +//! [0] + QTextBlock currentBlock = textDocument->begin(); + + while (currentBlock.isValid()) { +//! [0] + QDomElement blockElement = document->createElement("block"); + document->appendChild(blockElement); + + readFragment(currentBlock, blockElement, document); + +//! [1] + processBlock(currentBlock); +//! [1] + +//! [2] + currentBlock = currentBlock.next(); + } +//! [2] + + return document; +} + +void XmlWriter::readFragment(const QTextBlock ¤tBlock, + QDomElement blockElement, + QDomDocument *document) +{ +//! [3] //! [4] + QTextBlock::iterator it; + for (it = currentBlock.begin(); !(it.atEnd()); ++it) { + QTextFragment currentFragment = it.fragment(); + if (currentFragment.isValid()) +//! [3] //! [5] + processFragment(currentFragment); +//! [4] //! [5] + + if (currentFragment.isValid()) { + QDomElement fragmentElement = document->createElement("fragment"); + blockElement.appendChild(fragmentElement); + + fragmentElement.setAttribute("length", currentFragment.length()); + QDomText fragmentText = document->createTextNode(currentFragment.text()); + + fragmentElement.appendChild(fragmentText); + } +//! [6] //! [7] + } +//! [7] //! [6] +} + +void XmlWriter::processBlock(const QTextBlock ¤tBlock) +{ +} + +void XmlWriter::processFragment(const QTextFragment ¤tFragment) +{ +} diff --git a/doc/src/snippets/textdocument-css/main.cpp b/doc/src/snippets/textdocument-css/main.cpp new file mode 100644 index 0000000000..8c267455e5 --- /dev/null +++ b/doc/src/snippets/textdocument-css/main.cpp @@ -0,0 +1,59 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> + +int main(int argc, char **argv) +{ + QApplication app(argc, argv); + +//! [0] + QTextBrowser browser; + QColor linkColor(Qt::red); + QString sheet = QString::fromLatin1("a { text-decoration: underline; color: %1 }").arg(linkColor.name()); + browser.document()->setDefaultStyleSheet(sheet); +//! [0] + browser.setSource(QUrl("../../../html/index.html")); + browser.resize(800, 600); + browser.show(); + + return app.exec(); +} + diff --git a/doc/src/snippets/textdocument-imagedrop/textedit.cpp b/doc/src/snippets/textdocument-imagedrop/textedit.cpp new file mode 100644 index 0000000000..735dbe55ce --- /dev/null +++ b/doc/src/snippets/textdocument-imagedrop/textedit.cpp @@ -0,0 +1,71 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include "textedit.h" +#include <QtGui> + +TextEdit::TextEdit(QWidget *parent) + : QTextEdit(parent) +{ +} + +//! [0] +bool TextEdit::canInsertFromMimeData( const QMimeData *source ) const +{ + if (source->hasImage()) + return true; + else + return QTextEdit::canInsertFromMimeData(source); +} +//! [0] + +//! [1] +void TextEdit::insertFromMimeData( const QMimeData *source ) +{ + if (source->hasImage()) + { + QImage image = qvariant_cast<QImage>(source->imageData()); + QTextCursor cursor = this->textCursor(); + QTextDocument *document = this->document(); + document->addResource(QTextDocument::ImageResource, QUrl("image"), image); + cursor.insertImage("image"); + } +} +//! [1] diff --git a/doc/src/snippets/textdocument-lists/mainwindow.cpp b/doc/src/snippets/textdocument-lists/mainwindow.cpp new file mode 100644 index 0000000000..bcbfce72b8 --- /dev/null +++ b/doc/src/snippets/textdocument-lists/mainwindow.cpp @@ -0,0 +1,192 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> + +#include "mainwindow.h" + +MainWindow::MainWindow() +{ + QMenu *fileMenu = new QMenu(tr("&File")); + + fileMenu->addAction(tr("E&xit"), this, SLOT(close()), + QKeySequence(tr("Ctrl+Q", "File|Exit"))); + + QMenu *editMenu = new QMenu(tr("&Edit")); + + cutAction = editMenu->addAction(tr("Cu&t"), this, SLOT(cutSelection()), + QKeySequence(tr("Ctrl+X", "Edit|Cut"))); + copyAction = editMenu->addAction(tr("&Copy"), this, SLOT(copySelection()), + QKeySequence(tr("Ctrl+C", "Edit|Copy"))); + pasteAction = editMenu->addAction(tr("&Paste"), this, + SLOT(pasteSelection()), QKeySequence(tr("Ctrl+V", "Edit|Paste"))); + + QMenu *selectMenu = new QMenu(tr("&Select")); + selectMenu->addAction(tr("&Word"), this, SLOT(selectWord())); + selectMenu->addAction(tr("&Line"), this, SLOT(selectLine())); + selectMenu->addAction(tr("&Block"), this, SLOT(selectBlock())); + selectMenu->addAction(tr("&Frame"), this, SLOT(selectFrame())); + + QMenu *insertMenu = new QMenu(tr("&Insert")); + + insertMenu->addAction(tr("&List"), this, SLOT(insertList()), + QKeySequence(tr("Ctrl+L", "Insert|List"))); + + menuBar()->addMenu(fileMenu); + menuBar()->addMenu(editMenu); + menuBar()->addMenu(selectMenu); + menuBar()->addMenu(insertMenu); + + editor = new QTextEdit(this); + document = new QTextDocument(this); + editor->setDocument(document); + + connect(editor, SIGNAL(selectionChanged()), this, SLOT(updateMenus())); + + updateMenus(); + + setCentralWidget(editor); + setWindowTitle(tr("Text Document Writer")); +} + +void MainWindow::cutSelection() +{ + QTextCursor cursor = editor->textCursor(); + if (cursor.hasSelection()) { + selection = cursor.selection(); + cursor.removeSelectedText(); + } +} + +void MainWindow::copySelection() +{ + QTextCursor cursor = editor->textCursor(); + if (cursor.hasSelection()) { + selection = cursor.selection(); + cursor.clearSelection(); + } +} + +void MainWindow::pasteSelection() +{ + QTextCursor cursor = editor->textCursor(); + cursor.insertFragment(selection); +} + +void MainWindow::selectWord() +{ + QTextCursor cursor = editor->textCursor(); + QTextBlock block = cursor.block(); + + cursor.beginEditBlock(); + cursor.movePosition(QTextCursor::StartOfWord); + cursor.movePosition(QTextCursor::EndOfWord, QTextCursor::KeepAnchor); + cursor.endEditBlock(); + + editor->setTextCursor(cursor); +} + +void MainWindow::selectLine() +{ + QTextCursor cursor = editor->textCursor(); + QTextBlock block = cursor.block(); + + cursor.beginEditBlock(); + cursor.movePosition(QTextCursor::StartOfLine); + cursor.movePosition(QTextCursor::EndOfLine, QTextCursor::KeepAnchor); + cursor.endEditBlock(); + + editor->setTextCursor(cursor); +} + +void MainWindow::selectBlock() +{ + QTextCursor cursor = editor->textCursor(); + QTextBlock block = cursor.block(); + + cursor.beginEditBlock(); + cursor.movePosition(QTextCursor::StartOfBlock); + cursor.movePosition(QTextCursor::EndOfBlock, QTextCursor::KeepAnchor); + cursor.endEditBlock(); + + editor->setTextCursor(cursor); +} + +void MainWindow::selectFrame() +{ + QTextCursor cursor = editor->textCursor(); + QTextFrame *frame = cursor.currentFrame(); + + cursor.beginEditBlock(); + cursor.setPosition(frame->firstPosition()); + cursor.setPosition(frame->lastPosition(), QTextCursor::KeepAnchor); + cursor.endEditBlock(); + + editor->setTextCursor(cursor); +} + +void MainWindow::insertList() +{ + QTextCursor cursor = editor->textCursor(); + cursor.beginEditBlock(); + + QTextList *list = cursor.currentList(); +//! [0] + QTextListFormat listFormat; + if (list) { + listFormat = list->format(); + listFormat.setIndent(listFormat.indent() + 1); + } + + listFormat.setStyle(QTextListFormat::ListDisc); + cursor.insertList(listFormat); +//! [0] + + cursor.endEditBlock(); +} + +void MainWindow::updateMenus() +{ + QTextCursor cursor = editor->textCursor(); + cutAction->setEnabled(cursor.hasSelection()); + copyAction->setEnabled(cursor.hasSelection()); + + pasteAction->setEnabled(!selection.isEmpty()); +} diff --git a/doc/src/snippets/textdocument-tables/mainwindow.cpp b/doc/src/snippets/textdocument-tables/mainwindow.cpp new file mode 100644 index 0000000000..c432f4c8cd --- /dev/null +++ b/doc/src/snippets/textdocument-tables/mainwindow.cpp @@ -0,0 +1,204 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> + +#include "mainwindow.h" +#include "xmlwriter.h" + +MainWindow::MainWindow() +{ + QMenu *fileMenu = new QMenu(tr("&File")); + + QAction *saveAction = fileMenu->addAction(tr("&Save...")); + saveAction->setShortcut(tr("Ctrl+S")); + QAction *quitAction = fileMenu->addAction(tr("E&xit")); + quitAction->setShortcut(tr("Ctrl+Q")); + + QMenu *showMenu = new QMenu(tr("&Show")); + + QAction *showTableAction = showMenu->addAction(tr("&Table")); + + menuBar()->addMenu(fileMenu); + menuBar()->addMenu(showMenu); + + editor = new QTextEdit(); + +//! [0] //! [1] + QTextCursor cursor(editor->textCursor()); +//! [0] + cursor.movePosition(QTextCursor::Start); +//! [1] + + int rows = 11; + int columns = 4; + +//! [2] + QTextTableFormat tableFormat; + tableFormat.setBackground(QColor("#e0e0e0")); + QVector<QTextLength> constraints; + constraints << QTextLength(QTextLength::PercentageLength, 16); + constraints << QTextLength(QTextLength::PercentageLength, 28); + constraints << QTextLength(QTextLength::PercentageLength, 28); + constraints << QTextLength(QTextLength::PercentageLength, 28); + tableFormat.setColumnWidthConstraints(constraints); +//! [3] + QTextTable *table = cursor.insertTable(rows, columns, tableFormat); +//! [2] //! [3] + + int column; + int row; + QTextTableCell cell; + QTextCursor cellCursor; + + QTextCharFormat charFormat; + charFormat.setForeground(Qt::black); + +//! [4] + cell = table->cellAt(0, 0); + cellCursor = cell.firstCursorPosition(); + cellCursor.insertText(tr("Week"), charFormat); +//! [4] + +//! [5] + for (column = 1; column < columns; ++column) { + cell = table->cellAt(0, column); + cellCursor = cell.firstCursorPosition(); + cellCursor.insertText(tr("Team %1").arg(column), charFormat); + } + + for (row = 1; row < rows; ++row) { + cell = table->cellAt(row, 0); + cellCursor = cell.firstCursorPosition(); + cellCursor.insertText(tr("%1").arg(row), charFormat); + + for (column = 1; column < columns; ++column) { + if ((row-1) % 3 == column-1) { +//! [5] //! [6] + cell = table->cellAt(row, column); + QTextCursor cellCursor = cell.firstCursorPosition(); + cellCursor.insertText(tr("On duty"), charFormat); + } +//! [6] //! [7] + } +//! [7] //! [8] + } +//! [8] + + connect(saveAction, SIGNAL(triggered()), this, SLOT(saveFile())); + connect(quitAction, SIGNAL(triggered()), this, SLOT(close())); + connect(showTableAction, SIGNAL(triggered()), this, SLOT(showTable())); + + setCentralWidget(editor); + setWindowTitle(tr("Text Document Tables")); +} + +void MainWindow::saveFile() +{ + QString fileName = QFileDialog::getSaveFileName(this, + tr("Save document as:"), "", tr("XML (*.xml)")); + + if (!fileName.isEmpty()) { + if (writeXml(fileName)) + setWindowTitle(fileName); + else + QMessageBox::warning(this, tr("Warning"), + tr("Failed to save the document."), QMessageBox::Cancel, + QMessageBox::NoButton); + } +} + +void MainWindow::showTable() +{ + QTextCursor cursor = editor->textCursor(); + QTextTable *table = cursor.currentTable(); + + if (!table) + return; + + QTableWidget *tableWidget = new QTableWidget(table->rows(), table->columns()); + +//! [9] + for (int row = 0; row < table->rows(); ++row) { + for (int column = 0; column < table->columns(); ++column) { + QTextTableCell tableCell = table->cellAt(row, column); +//! [9] + QTextFrame::iterator it; + QString text; + for (it = tableCell.begin(); !(it.atEnd()); ++it) { + QTextBlock childBlock = it.currentBlock(); + if (childBlock.isValid()) + text += childBlock.text(); + } + QTableWidgetItem *newItem = new QTableWidgetItem(text); + tableWidget->setItem(row, column, newItem); + /* +//! [10] + processTableCell(tableCell); +//! [10] + */ +//! [11] + } +//! [11] //! [12] + } +//! [12] + + tableWidget->setWindowTitle(tr("Table Contents")); + tableWidget->show(); +} + +bool MainWindow::writeXml(const QString &fileName) +{ + XmlWriter documentWriter(editor->document()); + + QDomDocument *domDocument = documentWriter.toXml(); + QFile file(fileName); + + if (file.open(QFile::WriteOnly)) { + QTextStream textStream(&file); + textStream.setCodec(QTextCodec::codecForName("UTF-8")); + + textStream << domDocument->toString(1).toUtf8(); + file.close(); + return true; + } + else + return false; +} diff --git a/doc/src/snippets/textdocument-texttable/main.cpp b/doc/src/snippets/textdocument-texttable/main.cpp new file mode 100644 index 0000000000..1e3b7c2a89 --- /dev/null +++ b/doc/src/snippets/textdocument-texttable/main.cpp @@ -0,0 +1,84 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> + +int main(int argc, char * argv[]) +{ + int rows = 6; + int columns = 2; + + QApplication app(argc, argv); + QTextEdit *textEdit = new QTextEdit; + QTextCursor cursor(textEdit->textCursor()); + cursor.movePosition(QTextCursor::Start); + + QTextTableFormat tableFormat; + tableFormat.setAlignment(Qt::AlignHCenter); + tableFormat.setCellPadding(2); + tableFormat.setCellSpacing(2); + QTextTable *table = cursor.insertTable(rows, columns); + table->setFormat(tableFormat); + + QTextCharFormat boldFormat; + boldFormat.setFontWeight(QFont::Bold); + + QTextBlockFormat centerFormat; + centerFormat.setAlignment(Qt::AlignHCenter); + cursor.mergeBlockFormat(centerFormat); + + cursor = table->cellAt(0, 0).firstCursorPosition(); + cursor.insertText(("Details"), boldFormat); + + cursor = table->cellAt(1, 0).firstCursorPosition(); + cursor.insertText("Alan"); + + cursor = table->cellAt(1, 1).firstCursorPosition(); + cursor.insertText("5, Pickety Street"); + +//! [0] + table->mergeCells(0, 0, 1, 2); +//! [0] //! [1] + table->splitCell(0, 0, 1, 1); +//! [1] + + textEdit->show(); + return app.exec(); +} diff --git a/doc/src/snippets/textdocumentendsnippet.cpp b/doc/src/snippets/textdocumentendsnippet.cpp new file mode 100644 index 0000000000..3b28700ac3 --- /dev/null +++ b/doc/src/snippets/textdocumentendsnippet.cpp @@ -0,0 +1,56 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> +#include <iostream.h> + +int main(int argv, char **args) +{ + QString contentString("One\nTwp\nThree"); + + QTextDocument *doc = new QTextDocument(contentString); + +//! [0] + for (QTextBlock it = doc->begin(); it != doc->end(); it = it.next()) + cout << it.text().toStdString() << endl; +//! [0] + + return 0; +} diff --git a/doc/src/snippets/threads/threads.cpp b/doc/src/snippets/threads/threads.cpp new file mode 100644 index 0000000000..5661757c9c --- /dev/null +++ b/doc/src/snippets/threads/threads.cpp @@ -0,0 +1,117 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QCache> +#include <QMutex> +#include <QThreadStorage> + +#include "threads.h" + +//! [0] +void MyThread::run() +//! [0] //! [1] +{ +//! [1] //! [2] +} +//! [2] + +#define Counter ReentrantCounter + +//! [3] +class Counter +//! [3] //! [4] +{ +public: + Counter() { n = 0; } + + void increment() { ++n; } + void decrement() { --n; } + int value() const { return n; } + +private: + int n; +}; +//! [4] + +#undef Counter +#define Counter ThreadSafeCounter + +//! [5] +class Counter +//! [5] //! [6] +{ +public: + Counter() { n = 0; } + + void increment() { QMutexLocker locker(&mutex); ++n; } + void decrement() { QMutexLocker locker(&mutex); --n; } + int value() const { QMutexLocker locker(&mutex); return n; } + +private: + mutable QMutex mutex; + int n; +}; +//! [6] + +typedef int SomeClass; + +//! [7] +QThreadStorage<QCache<QString, SomeClass> > caches; + +void cacheObject(const QString &key, SomeClass *object) +//! [7] //! [8] +{ + caches.localData().insert(key, object); +} + +void removeFromCache(const QString &key) +//! [8] //! [9] +{ + if (!caches.hasLocalData()) + return; + + caches.localData().remove(key); +} +//! [9] + +int main() +{ + return 0; +} diff --git a/doc/src/snippets/timeline/main.cpp b/doc/src/snippets/timeline/main.cpp new file mode 100644 index 0000000000..b652069d68 --- /dev/null +++ b/doc/src/snippets/timeline/main.cpp @@ -0,0 +1,72 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> +#include <math.h> + +int main(int argv, char *args[]) +{ + QApplication app(argv, args); + +//! [0] + QGraphicsItem *ball = new QGraphicsEllipseItem(0, 0, 20, 20); + + QTimeLine *timer = new QTimeLine(5000); + timer->setFrameRange(0, 100); + + QGraphicsItemAnimation *animation = new QGraphicsItemAnimation; + animation->setItem(ball); + animation->setTimeLine(timer); + + for (int i = 0; i < 200; ++i) + animation->setPosAt(i / 200.0, QPointF(i, i)); + + QGraphicsScene *scene = new QGraphicsScene(); + scene->setSceneRect(0, 0, 250, 250); + scene->addItem(ball); + + QGraphicsView *view = new QGraphicsView(scene); + view->show(); + + timer->start(); +//! [0] + + return app.exec(); +} diff --git a/doc/src/snippets/timers/timers.cpp b/doc/src/snippets/timers/timers.cpp new file mode 100644 index 0000000000..015ab27387 --- /dev/null +++ b/doc/src/snippets/timers/timers.cpp @@ -0,0 +1,78 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QTimer> + +class Foo : public QObject +{ +public: + Foo(); +}; + +Foo::Foo() +{ +//! [0] + QTimer *timer = new QTimer(this); +//! [0] //! [1] + connect(timer, SIGNAL(timeout()), this, SLOT(updateCaption())); +//! [1] //! [2] + timer->start(1000); +//! [2] + +//! [3] + QTimer::singleShot(200, this, SLOT(updateCaption())); +//! [3] + + { + // ZERO-CASE +//! [4] + QTimer *timer = new QTimer(this); +//! [4] //! [5] + connect(timer, SIGNAL(timeout()), this, SLOT(processOneThing())); +//! [5] //! [6] + timer->start(); +//! [6] + } +} + +int main() +{ + +} diff --git a/doc/src/snippets/transform/main.cpp b/doc/src/snippets/transform/main.cpp new file mode 100644 index 0000000000..b1e3d74094 --- /dev/null +++ b/doc/src/snippets/transform/main.cpp @@ -0,0 +1,140 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> +#include <cmath> + +class SimpleTransformation : public QWidget +{ + void paintEvent(QPaintEvent *); +}; + +//! [0] +void SimpleTransformation::paintEvent(QPaintEvent *) +{ + QPainter painter(this); + painter.setPen(QPen(Qt::blue, 1, Qt::DashLine)); + painter.drawRect(0, 0, 100, 100); + + painter.rotate(45); + + painter.setFont(QFont("Helvetica", 24)); + painter.setPen(QPen(Qt::black, 1)); + painter.drawText(20, 10, "QTransform"); +} +//! [0] + +class CombinedTransformation : public QWidget +{ + void paintEvent(QPaintEvent *); +}; + +//! [1] +void CombinedTransformation::paintEvent(QPaintEvent *) +{ + QPainter painter(this); + painter.setPen(QPen(Qt::blue, 1, Qt::DashLine)); + painter.drawRect(0, 0, 100, 100); + + QTransform transform; + transform.translate(50, 50); + transform.rotate(45); + transform.scale(0.5, 1.0); + painter.setTransform(transform); + + painter.setFont(QFont("Helvetica", 24)); + painter.setPen(QPen(Qt::black, 1)); + painter.drawText(20, 10, "QTransform"); +} +//! [1] + +class BasicOperations : public QWidget +{ + void paintEvent(QPaintEvent *); +}; + +//! [2] +void BasicOperations::paintEvent(QPaintEvent *) +{ + double pi = 3.14; + + double a = pi/180 * 45.0; + double sina = sin(a); + double cosa = cos(a); + + QTransform translationTransform(1, 0, 0, 1, 50.0, 50.0); + QTransform rotationTransform(cosa, sina, -sina, cosa, 0, 0); + QTransform scalingTransform(0.5, 0, 0, 1.0, 0, 0); + + QTransform transform; + transform = scalingTransform * rotationTransform * translationTransform; + + QPainter painter(this); + painter.setPen(QPen(Qt::blue, 1, Qt::DashLine)); + painter.drawRect(0, 0, 100, 100); + + painter.setTransform(transform); + + painter.setFont(QFont("Helvetica", 24)); + painter.setPen(QPen(Qt::black, 1)); + painter.drawText(20, 10, "QTransform"); +} +//! [2] + +int main(int argc, char **argv) +{ + QApplication app(argc, argv); + + QWidget widget; + + SimpleTransformation *simpleWidget = new SimpleTransformation; + CombinedTransformation *combinedWidget = new CombinedTransformation; + BasicOperations *basicWidget = new BasicOperations; + + QVBoxLayout *layout = new QVBoxLayout; + layout->addWidget(simpleWidget); + layout->addWidget(combinedWidget); + layout->addWidget(basicWidget); + widget.setLayout(layout); + + widget.show(); + widget.resize(130, 350); + return app.exec(); +} diff --git a/doc/src/snippets/whatsthis/whatsthis.cpp b/doc/src/snippets/whatsthis/whatsthis.cpp new file mode 100644 index 0000000000..608fa3e62f --- /dev/null +++ b/doc/src/snippets/whatsthis/whatsthis.cpp @@ -0,0 +1,64 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> + +class MainWindow : public QMainWindow +{ +public: + MainWindow(); + + QAction *newAct; +}; + +MainWindow() +{ +//! [0] + newAct = new QAction(tr("&New"), this); + newAct->setShortcut(tr("Ctrl+N")); + newAct->setStatusTip(tr("Create a new file")); + newAct->setWhatsThis(tr("Click this option to create a new file.")); +//! [0] +} + +int main() +{ + return 0; +} diff --git a/doc/src/snippets/widget-mask/main.cpp b/doc/src/snippets/widget-mask/main.cpp new file mode 100644 index 0000000000..2d7defc02c --- /dev/null +++ b/doc/src/snippets/widget-mask/main.cpp @@ -0,0 +1,54 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> + +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); +//! [0] + QLabel topLevelLabel; + QPixmap pixmap(":/images/tux.png"); + topLevelLabel.setPixmap(pixmap); + topLevelLabel.setMask(pixmap.mask()); +//! [0] + topLevelLabel.show(); + return app.exec(); +} diff --git a/doc/src/snippets/widgetdelegate.cpp b/doc/src/snippets/widgetdelegate.cpp new file mode 100644 index 0000000000..c6d3963807 --- /dev/null +++ b/doc/src/snippets/widgetdelegate.cpp @@ -0,0 +1,66 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> + +#include "widgetdelegate.h" + +//![0] +void WidgetDelegate::paint(QPainter *painter, const QStyleOptionViewItem &option, + const QModelIndex &index) const +{ + if (index.column() == 1) { + int progress = index.data().toInt(); + + QStyleOptionProgressBar progressBarOption; + progressBarOption.rect = option.rect; + progressBarOption.minimum = 0; + progressBarOption.maximum = 100; + progressBarOption.progress = progress; + progressBarOption.text = QString::number(progress) + "%"; + progressBarOption.textVisible = true; + + QApplication::style()->drawControl(QStyle::CE_ProgressBar, + &progressBarOption, painter); + } else + QStyledItemDelegate::paint(painter, option, index); + +//![0] +} diff --git a/doc/src/snippets/widgetprinting.cpp b/doc/src/snippets/widgetprinting.cpp new file mode 100644 index 0000000000..a6ea3cb5d3 --- /dev/null +++ b/doc/src/snippets/widgetprinting.cpp @@ -0,0 +1,93 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <QtGui> + +class Window : public QWidget +{ + Q_OBJECT + +public: + Window() { + myWidget = new QPushButton("Print Me"); + connect(myWidget, SIGNAL(clicked()), this, SLOT(print())); + + QVBoxLayout *layout = new QVBoxLayout; + layout->addWidget(myWidget); + setLayout(layout); + } + +private slots: + void print() { + QPrinter printer(QPrinter::HighResolution); + + printer.setOutputFileName("test.pdf"); + +//! [0] + QPainter painter; + painter.begin(&printer); + double xscale = printer.pageRect().width()/double(myWidget->width()); + double yscale = printer.pageRect().height()/double(myWidget->height()); + double scale = qMin(xscale, yscale); + painter.translate(printer.paperRect().x() + printer.pageRect().width()/2, + printer.paperRect().y() + printer.pageRect().height()/2); + painter.scale(scale, scale); + painter.translate(-width()/2, -height()/2); + + myWidget->render(&painter); +//! [0] + } + +private: + QPushButton *myWidget; +}; + +int main(int argv, char **args) +{ + QApplication app(argv, args); + + Window window; + window.show(); + + return app.exec(); +} + +#include "main.moc" + diff --git a/doc/src/snippets/widgets-tutorial/template.cpp b/doc/src/snippets/widgets-tutorial/template.cpp new file mode 100644 index 0000000000..e2a2f61ab1 --- /dev/null +++ b/doc/src/snippets/widgets-tutorial/template.cpp @@ -0,0 +1,56 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [main.cpp body] +#include <QtGui> + +// Include header files for application components. +// ... + +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + + // Set up and show widgets. + // ... + + return app.exec(); +} +//! [main.cpp body] diff --git a/doc/src/snippets/xml/rsslisting/handler.cpp b/doc/src/snippets/xml/rsslisting/handler.cpp new file mode 100644 index 0000000000..fe9ef5cbe9 --- /dev/null +++ b/doc/src/snippets/xml/rsslisting/handler.cpp @@ -0,0 +1,182 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/* +handler.cpp + +Provides a handler for processing XML elements found by the reader. + +The handler looks for <title> and <link> elements within <item> elements, +and records the text found within them. Link information stored within +rdf:about attributes of <item> elements is also recorded when it is +available. + +For each item found, a signal is emitted which specifies its title and +link information. This may be used by user interfaces for the purpose of +displaying items as they are read. +*/ + +#include <QtGui> + +#include "handler.h" + +/* + Reset the state of the handler to ensure that new documents are + read correctly. + + We return true to indicate that parsing should continue. +*/ + +bool Handler::startDocument() +{ + inItem = false; + inTitle = false; + inLink = false; + + return true; +} + +/* + Process each starting element in the XML document. + + Nested item, title, or link elements are not allowed, so we return false + if we encounter any of these. We also prohibit multiple definitions of + title strings. + + Link destinations are read by this function if they are specified as + attributes in item elements. + + For all cases not explicitly checked for, we return true to indicate that + the element is acceptable, and that parsing should continue. By doing + this, we can ignore elements in which we are not interested. +*/ + +bool Handler::startElement(const QString &, const QString &, + const QString & qName, const QXmlAttributes &attr) +{ + if (qName == "item") { + + if (inItem) + return false; + else { + inItem = true; + linkString = attr.value("rdf:about"); + } + } + else if (qName == "title") { + + if (inTitle) + return false; + else if (!titleString.isEmpty()) + return false; + else if (inItem) + inTitle = true; + } + else if (qName == "link") { + + if (inLink) + return false; + else if (inItem) + inLink = true; + } + + return true; +} + +/* + Process each ending element in the XML document. + + For recognized elements, we reset flags to ensure that we can read new + instances of these elements. If we have read an item element, emit a + signal to indicate that a new item is available for display. + + We return true to indicate that parsing should continue. +*/ + +bool Handler::endElement(const QString &, const QString &, + const QString & qName) +{ + if (qName == "title" && inTitle) + inTitle = false; + else if (qName == "link" && inLink) + inLink = false; + else if (qName == "item") { + if (!titleString.isEmpty() && !linkString.isEmpty()) + emit newItem(titleString, linkString); + inItem = false; + titleString = ""; + linkString = ""; + } + + return true; +} + +/* + Collect characters when reading the contents of title or link elements + when they occur within an item element. + + We return true to indicate that parsing should continue. +*/ + +bool Handler::characters (const QString &chars) +{ + if (inTitle) + titleString += chars; + else if (inLink) + linkString += chars; + + return true; +} + +/* + Report a fatal parsing error, and return false to indicate to the reader + that parsing should stop. +*/ + +//! [0] +bool Handler::fatalError (const QXmlParseException & exception) +{ + qWarning() << "Fatal error on line" << exception.lineNumber() + << ", column" << exception.columnNumber() << ":" + << exception.message(); + + return false; +} +//! [0] diff --git a/doc/src/snippets/xml/rsslisting/rsslisting.cpp b/doc/src/snippets/xml/rsslisting/rsslisting.cpp new file mode 100644 index 0000000000..5047d0840d --- /dev/null +++ b/doc/src/snippets/xml/rsslisting/rsslisting.cpp @@ -0,0 +1,251 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/* +rsslisting.cpp + +Provides a widget for displaying news items from RDF news sources. +RDF is an XML-based format for storing items of information (see +http://www.w3.org/RDF/ for details). + +The widget itself provides a simple user interface for specifying +the URL of a news source, and controlling the downloading of news. + +The widget downloads and parses the XML asynchronously, feeding the +data to an XML reader in pieces. This allows the user to interrupt +its operation, and also allows very large data sources to be read. +*/ + + +#include <QtCore> +#include <QtGui> +#include <QtNetwork> +#include <QtXml> + +#include "rsslisting.h" + + +/* + Constructs an RSSListing widget with a simple user interface, and sets + up the XML reader to use a custom handler class. + + The user interface consists of a line edit, two push buttons, and a + list view widget. The line edit is used for entering the URLs of news + sources; the push buttons start and abort the process of reading the + news. +*/ + +RSSListing::RSSListing(QWidget *parent) + : QWidget(parent) +{ + lineEdit = new QLineEdit(this); + + fetchButton = new QPushButton(tr("Fetch"), this); + abortButton = new QPushButton(tr("Abort"), this); + abortButton->setEnabled(false); + + treeWidget = new QTreeWidget(this); + QStringList headerLabels; + headerLabels << tr("Title") << tr("Link"); + treeWidget->setHeaderLabels(headerLabels); + + handler = 0; + + connect(&http, SIGNAL(readyRead(const QHttpResponseHeader &)), + this, SLOT(readData(const QHttpResponseHeader &))); + + connect(&http, SIGNAL(requestFinished(int, bool)), + this, SLOT(finished(int, bool))); + + connect(lineEdit, SIGNAL(returnPressed()), this, SLOT(fetch())); + connect(fetchButton, SIGNAL(clicked()), this, SLOT(fetch())); + connect(abortButton, SIGNAL(clicked()), &http, SLOT(abort())); + + QVBoxLayout *layout = new QVBoxLayout(this); + + QHBoxLayout *hboxLayout = new QHBoxLayout; + + hboxLayout->addWidget(lineEdit); + hboxLayout->addWidget(fetchButton); + hboxLayout->addWidget(abortButton); + + layout->addLayout(hboxLayout); + layout->addWidget(treeWidget); + + setWindowTitle(tr("RSS listing example")); +} + +/* + Starts fetching data from a news source specified in the line + edit widget. + + The line edit is made read only to prevent the user from modifying its + contents during the fetch; this is only for cosmetic purposes. + The fetch button is disabled, and the abort button is enabled to allow + the user to interrupt processing. The list view is cleared, and we + define the last list view item to be 0, meaning that there are no + existing items in the list. + + We reset the flag used to determine whether parsing should begin again + or continue. A new handler is created, if required, and made available + to the reader. + + The HTTP handler is supplied with the raw contents of the line edit and + a fetch is initiated. We keep the ID value returned by the HTTP handler + for future reference. +*/ + +void RSSListing::fetch() +{ + lineEdit->setReadOnly(true); + fetchButton->setEnabled(false); + abortButton->setEnabled(true); + treeWidget->clear(); + + lastItemCreated = 0; + + newInformation = true; + + if (handler != 0) + delete handler; + handler = new Handler; + +//! [0] + xmlReader.setContentHandler(handler); + xmlReader.setErrorHandler(handler); +//! [0] + + connect(handler, SIGNAL(newItem(QString &, QString &)), + this, SLOT(addItem(QString &, QString &))); + + QUrl url(lineEdit->text()); + + http.setHost(url.host()); + connectionId = http.get(url.path()); +} + +/* + Reads data received from the RDF source. + + We read all the available data, and pass it to the XML + input source. The first time we receive new information, + the reader is set up for a new incremental parse; + we continue parsing using a different function on + subsequent calls involving the same data source. + + If parsing fails for any reason, we abort the fetch. +*/ + +//! [1] +void RSSListing::readData(const QHttpResponseHeader &resp) +{ + bool ok; + + if (resp.statusCode() != 200) + http.abort(); + else { + xmlInput.setData(http.readAll()); + + if (newInformation) { + ok = xmlReader.parse(&xmlInput, true); + newInformation = false; + } + else + ok = xmlReader.parseContinue(); + + if (!ok) + http.abort(); + } +} +//! [1] + +/* + Finishes processing an HTTP request. + + The default behavior is to keep the text edit read only. + + If an error has occurred, the user interface is made available + to the user for further input, allowing a new fetch to be + started. + + If the HTTP get request has finished, we perform a final + parsing operation on the data returned to ensure that it was + well-formed. Whether this is successful or not, we make the + user interface available to the user for further input. +*/ + +void RSSListing::finished(int id, bool error) +{ + if (error) { + qWarning("Received error during HTTP fetch."); + lineEdit->setReadOnly(false); + abortButton->setEnabled(false); + fetchButton->setEnabled(true); + } + else if (id == connectionId) { + + bool ok = xmlReader.parseContinue(); + if (!ok) + qWarning("Parse error at the end of input."); + + lineEdit->setReadOnly(false); + abortButton->setEnabled(false); + fetchButton->setEnabled(true); + } +} + +/* + Adds an item to the list view as it is reported by the handler. + + We keep a record of the last item created to ensure that the + items are created in sequence. +*/ + +void RSSListing::addItem(QString &title, QString &link) +{ + QTreeWidgetItem *item; + + item = new QTreeWidgetItem(treeWidget, lastItemCreated); + item->setText(0, title); + item->setText(1, link); + + lastItemCreated = item; +} + diff --git a/doc/src/snippets/xml/simpleparse/main.cpp b/doc/src/snippets/xml/simpleparse/main.cpp new file mode 100644 index 0000000000..5d9994d63e --- /dev/null +++ b/doc/src/snippets/xml/simpleparse/main.cpp @@ -0,0 +1,87 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#include <qfile.h> +#include <qxml.h> +#include "handler.h" + +#include <iostream> + +int main(int argc, char **argv) +{ + if (argc != 2) { + std::cout << "Usage: " << argv[0] << " <filename>" << std::endl; + return 1; + } + + QFile *file = new QFile(argv[1]); + +//! [0] + QXmlSimpleReader xmlReader; + QXmlInputSource *source = new QXmlInputSource(file); +//! [0] + +//! [1] + Handler *handler = new Handler; + xmlReader.setContentHandler(handler); + xmlReader.setErrorHandler(handler); +//! [1] + +//! [2] + bool ok = xmlReader.parse(source); + + if (!ok) + std::cout << "Parsing failed." << std::endl; +//! [2] + else { + QStringList names = handler->names(); + QList<int> indentations = handler->indentations(); + + int items = names.count(); + + for (int i = 0; i < items; ++i) { + for (int j = 0; j < indentations[i]; ++j) + std::cout << " "; + std::cout << names[i].toLocal8Bit().constData() << std::endl; + } + } + + return 0; +} diff --git a/doc/src/sql-programming/qsqldatatype-table.qdoc b/doc/src/sql-programming/qsqldatatype-table.qdoc new file mode 100644 index 0000000000..e0cb991e9c --- /dev/null +++ b/doc/src/sql-programming/qsqldatatype-table.qdoc @@ -0,0 +1,570 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page sql-types.html + \title Data Types for Qt-supported Database Systems + \brief Recommended data types for database systems + + \ingroup qt-sql + + \section1 Recommended Data Types for Qt-Supported Database Systems + + This table shows the recommended data types for extracting data from + the databases supported in Qt. Note that types used in Qt are not + necessarily valid as input types to a specific database + system. e.g., A double might work perfectly as input for floating + point records in a particular database, but not necessarily as a + storage format for output from that database, because it would be + stored with 64-bit precision in C++. + + \tableofcontents + + \section2 IBM DB2 Data Types + + \table 90% + \header + \o IBM DB2 data type + \o SQL type description + \o Recommended input (C++ or Qt data type) + \row + \o SMALLINT + \o 16-bit signed integer + \o typedef qint16 + \row + \o INTEGER + \o 32-bit signed integer + \o typedef qint32 + \row + \o BIGINT + \o 64-bit signed integer + \o typedef qint64 + \row + \o REAL + \o 32-bit Single-precision floating point + \o By default mapping to QString + \row + \o DOUBLE PRECISION + \o 64-bit Double-precision floating point + \o By default mapping to QString + \row + \o FLOAT + \o 64-bit Double-precision floating point + \o By default mapping to QString + \row + \o CHAR + \o Fixed-length, null-terminated character string + \o Mapped to QString + \row + \o VARCHAR + \o Null-terminated varying length string + \o Mapped to QString + \row + \o LONG VARCHAR + \o Not null-terminated varying length character string + \o Mapped to QString + \row + \o BLOB + \o Not null-terminated varying binary string with 4-byte string + length indicator + \o Mapped to QByteArray + \row + \o CLOB + \o Character large string object + \o Mapped to QString + \row + \o DATE + \o Null-terminated character string of the following format: + yyyy-mm-dd + \o Mapped to QDate + \row + \o TIME + \o Null-terminated character string of the following format: hh.mm.ss + \o Mapped to QTime + \row + \o TIMESTAMP + \o Null-terminated character string of the following format: yyyy-mm-dd-hh.mm.ss.nnnnnn + \o Mapped to QDateTime + \endtable + + \section2 Borland InterBase Data Types + + \table 90% + \header + \o Borland InterBase data type + \o SQL type description + \o Recommended input (C++ or Qt data type) + \row + \o BOOLEAN + \o Boolean + \o bool + \row + \o TINYINT + \o 8 bit signed integer + \o typedef qint8 + \row + \o SMALLINT + \o 16-bit signed integer + \o typedef qint16 + \row + \o INTEGER + \o 32-bit signed integer + \o typedef qint32 + \row + \o BIGINT LONG + \o 64-bit signed integer + \o typedef qint64 + \row + \o REAL FLOAT + \o 32-bit floating point + \o By default mapping to QString + \row + \o FLOAT + \o 64-bit floating point + \o By default mapping to QString + \row + \o DOUBLE + \o 64-bit floating point + \o By default mapping to QString + \row + \o DOUBLE PRECISION + \o 64-bit Double-precision floating point + \o By default mapping to QString + \row + \o VARCHAR STRING + \o Character string, Unicode + \o Mapped to QString + \row + \o CLOB + \o Character large string object + \o Mapped to QString + \row + \o DATE + \o Displays date. Format: 'yyyy-mm-dd' + \o Mapped to QDate + \row + \o TIME + \o Displays time. Format is 'hh:mm:ss' in 24-hour format + \o Mapped to QTime + \row + \o TIMESTAMP + \o Displays a timestamp. Format is 'yyyy-mm-dd hh:mm:ss' + \o Mapped to QDateTime + \endtable + + \section2 MySQL Data Types + + \table 90% + \header + \o MySQL data type + \o SQL type description + \o Recommended input (C++ or Qt data type) + \row + \o TINYINT + \o 8 bit signed integer + \o typedef qint8 + \row + \o TINYINT UNSIGNED + \o 8 bit unsigned integer + \o typedef quint8 + \row + \o SMALLINT + \o 16-bit signed integer + \o typedef qint16 + \row + \o SMALLINT UNSIGNED + \o 16-bit unsigned integer + \o typedef quint16 + \row + \o INT + \o 32-bit signed integer + \o typedef qint32 + \row + \o INT UNSIGNED + \o 32-bit unsigned integer + \o typedef quint32 + \row + \o BIGINT + \o 64-bit signed integer + \o typedef qint64 + \row + \o FLOAT + \o 32-bit Floating Point + \o By default mapping to QString + \row + \o DOUBLE + \o 64-bit Floating Point + \o By default mapping to QString + \row + \o CHAR + \o Character string + \o Mapped to QString + \row + \o VARCHAR + \o Character string + \o Mapped to QString + \row + \o TINYTEXT + \o Character string + \o Mapped to QString + \row + \o TEXT + \o Character string + \o Mapped to QString + \row + \o MEDIUMTEXT + \o Character string + \o Mapped to QString + \row + \o LONGTEXT + \o Character string + \o Mapped to QString + \row + \o CLOB + \o Character large string object + \o Mapped to QString + \row + \o all BLOB types + \o BLOB + \o Mapped to QByteArray + \row + \o DATE + \o Date without Time + \o Mapped to QDate + \row + \o DATETIME + \o Date and Time + \o Mapped to QDateTime + \row + \o TIMESTAMP + \o Date and Time + \o Mapped to QDateTime + \row + \o TIME + \o Time + \o Mapped to QTime + \row + \o YEAR + \o Year (int) + \o Mapped to QDateTime + \row + \o ENUM + \o Enumeration of Value Set + \o Mapped to QString + \endtable + + \section2 Oracle Call Interface Data Types + + \table 90% + \header + \o Oracle Call Interface data type + \o SQL type description + \o Recommended input (C++ or Qt data type) + \row + \o NUMBER + \o FLOAT, DOUBLE, PRECISIONc REAL + \o By default mapping to QString + \row + \o NUMBER(38) + \o INTEGER INT SMALLINT + \o typedef qint8/16/32/64 + \row + \o NUMBER(p,s) + \o NUMERIC(p,s) DECIMAL(p,s)a + \o By default mapping to QString + \row + \o NVARCHAR2(n) + \o Character string (NATIONAL CHARACTER VARYING(n) NATIONAL + CHAR VARYING(n) NCHAR VARYING(n)) + \o Mapped to QString + \row + \o NCHAR(n) + \o Character string (NATIONAL CHARACTER(n) NATIONAL CHAR(n) + NCHAR(n)) + \o Mapped to QString + \row + \o CHAR(n) + \o Character string (CHARACTER(n) CHAR(n)) + \o Mapped to QString + \row + \o CLOB + \o Character large string object + \o Mapped to QString + \row + \o BLOB + \o A binary large object + \o Mapped to QByteArray + \row + \o TIMESTAMP + \o Year, month, and day values of date, as well as hour, minute, + and second values of time + \o Mapped to QDateTime + \endtable + + \section2 ODBC Data Types + + \table 90% + \header + \o ODBC data type + \o SQL type description + \o Recommended input (C++ or Qt data type) + \row + \o BIT + \o Boolean + \o BOOL + \row + \o TINYINT + \o 8 bit integer + \o typedef qint8 + \row + \o SMALLINT + \o 16-bit signed integer + \o typedef qint16 + \row + \o INTEGER + \o 32-bit signed integer + \o typedef qint32 + \row + \o BIGINT + \o 64-bit signed integer + \o typedef qint64 + \row + \o REAL + \o 32-bit Single-precision floating point + \o By default mapping to QString + \row + \o FLOAT + \o 64-bit Double floating point + \o By default mapping to QString + \row + \o DOUBLE + \o 64-bit Double floating point + \o By default mapping to QString + \row + \o CHAR + \o Character string + \o Mapped to QString + \row + \o VARCHAR + \o Character string + \o Mapped to QString + \row + \o LONGVARCHAR + \o Character string + \o Mapped to QString + \row + \o CLOB + \o Character large string object + \o Mapped to QString + \row + \o DATE + \o Character string + \o Mapped to QDate + \row + \o TIME + \o Character Time, Character string + \o Mapped to QTime + \row + \o TIMESTAMP + \o Character Time, Character string + \o Mapped to QDateTime + \endtable + + \section2 PostgreSQL Data Types + + \table 90% + \header + \o PostgreSQL data type + \o SQL type description + \o Recommended input (C++ or Qt data type) + \row + \o BOOLEAN + \o Boolean + \o bool + \row + \o SMALLINT + \o 16-bit signed integer + \o typedef qint16 + \row + \o INTEGER + \o 32-bit signed integer + \o typedef qint32 + \row + \o BIGINT + \o 64-bit signed integer + \o typedef qint64 + \row + \o REAL + \o 32-bit variable-precision floating point + \o By default mapping to QString + \row + \o DOUBLE PRECISION + \o 64-bit variable-precision floating point + \o By default mapping to QString + \row + \o DECIMAL VARIABLE + \o user-specified precision, exact + \o Mapped to QString + \row + \o NUMERIC VARIABLE + \o user-specified precision, exact + \o Mapped to QString + \row + \o VARCHAR + \o variable-length character string + \o Mapped to QString + \row + \o CHARACTER + \o Character string of fixed-length + \o Mapped to QString + \row + \o TEXT + \o Character string of variable-length + \o Mapped to QString + \row + \o CLOB + \o Character large string object + \o Mapped to QString + \row + \o TIMESTAMP + \o 8 bytes, both date and time + \o Mapped to QDateTime + \row + \o TIMESTAMP + \o 8 bytes, both date and time, with time zone + \o Mapped to QDateTime + \row + \o DATE + \o 4 bytes, dates only + \o Mapped to QDate + \row + \o TIME + \o 8 bytes, times of day only 00:00:00.00 - 23:59:59.99 + \o Mapped to QTime + \row + \o TIME + \o 12 bytes times of day only, with time zone 00:00:00.00+12 + \o Mapped to QDateTime + \endtable + + \section2 QSQLITE SQLite version 3 Data Types + + \table 90% + \header + \o QSQLITE SQLite version 3 data type + \o SQL type description + \o Recommended input (C++ or Qt data type) + \row + \o NULL + \o NULL value. + \o NULL + \row + \o INTEGER + \o Signed integer, stored in 8, 16, 24, 32, 48, or 64-bits + depending on the magnitude of the value. + \o typedef qint8/16/32/64 + \row + \o REAL + \o 64-bit floating point value. + \o By default mapping to QString + \row + \o TEXT + \o Character string (UTF-8, UTF-16BE or UTF-16-LE). + \o Mapped to QString + \row + \o CLOB + \o Character large string object + \o Mapped to QString + \row + \o BLOB + \o The value is a BLOB of data, stored exactly as it was input. + \o Mapped to QByteArray + \endtable + + \section2 Sybase Adaptive Server Data Types + + \table 90% + \header + \o Sybase Adaptive Server data type + \o SQL type description + \o Recommended input (C++ or Qt data type) + \row + \o BINARY + \o Describes a fixed-length binary value up to 255 bytes in size. + \o Mapped to QByteArray + \row + \o CHAR + \o Character String + \o Mapped to QString + \row + \o DATETIME + \o Date and time. Range: 1753-01-01 00:00:00 through 9999-12-31 23:59:59. + \o Mapped to QDateTime + \row + \o NCHAR + \o Character String of fixed length + \o Mapped to QString + \row + \o NVARACHAR + \o Character String of variable length + \o Mapped to QString + \row + \o VARCHAR + \o Character String of fixed length + \o Mapped to QString + \row + \o CLOB + \o Character large string object + \o Mapped to QString + \row + \o TIMESTAMP + \o A unique number within a database + \o Mapped to QString + \row + \o SMALLDATETIME + \o Date and time. Range: 1900-01-01 00:00 through 2079-12-31 23:59 + \o Mapped to QDateTime + \row + \o UNICHAR + \o Character String of fixed length.(Unicode) + \o Mapped to QString + \row + \o UNIVARCHAR + \o Character String of variable length.(Unicode) + \o Mapped to QString + \row + \o VARBINARY + \o Describes a variable-length binary value up to 255 bytes in size + \o Mapped to QByteArray + \endtable + + \section2 SQLite Version 2 + + SQLite version 2 is "typeless". This means that you can store any kind of + data you want in any column of any table, regardless of the declared + data type of that column. We recommend that you map the data to QString. +*/ diff --git a/doc/src/sql-programming/sql-driver.qdoc b/doc/src/sql-programming/sql-driver.qdoc new file mode 100644 index 0000000000..2cb7aaba18 --- /dev/null +++ b/doc/src/sql-programming/sql-driver.qdoc @@ -0,0 +1,828 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page sql-driver.html + \title SQL Database Drivers + \brief How to configure and install QtSql drivers for supported databases. + + \ingroup qt-sql + + The QtSql module uses driver \l{How to Create Qt + Plugins}{plugins} to communicate with the different database + APIs. Since Qt's SQL Module API is database-independent, all + database-specific code is contained within these drivers. Several + drivers are supplied with Qt and other drivers can be added. The + driver source code is supplied and can be used as a model for + \l{#development}{writing your own drivers}. + + \tableofcontents + + \section1 Supported Databases + + The table below lists the drivers included with Qt. Due to + license incompatibilities with the GPL, not all of the plugins + are provided with Open Source Versions of Qt. + + \table + \header \o Driver name \o DBMS + \row \o \link #QDB2 QDB2\endlink \o IBM DB2 (version 7.1 and above) + \row \o \link #QIBASE QIBASE\endlink \o Borland InterBase + \row \o \link #QMYSQL QMYSQL\endlink \o MySQL + \row \o \link #QOCI QOCI\endlink \o Oracle Call Interface Driver + \row \o \link #QODBC QODBC\endlink + \o Open Database Connectivity (ODBC) - Microsoft SQL Server and other + ODBC-compliant databases + \row \o \link #QPSQL QPSQL\endlink \o PostgreSQL (versions 7.3 and above) + \row \o \link #QSQLITE2 QSQLITE2\endlink \o SQLite version 2 + \row \o \link #QSQLITE QSQLITE\endlink \o SQLite version 3 + \row \o \link #QTDS QTDS\endlink \o Sybase Adaptive Server \note obsolete from Qt 4.7 + \endtable + + SQLite is the in-process database system with the best test coverage + and support on all platforms. Oracle via OCI, and PostreSQL and MySQL + through either ODBC or a native driver are well-tested on Windows and + Linux. The completeness of the support for other systems depends on the + availability and quality of client libraries. + + \bold{Note:} To build a driver plugin you need to have the appropriate + client library for your Database Management System (DBMS). This provides + access to the API exposed by the DBMS, and is typically shipped with it. + Most installation programs also allow you to install "development + libraries", and these are what you need. These libraries are responsible + for the low-level communication with the DBMS. + + \target building + \section1 Building the Drivers Using Configure + + On Unix and Mac OS X, the Qt \c configure script tries to + automatically detect the available client libraries on your + machine. Run \c{configure -help} to see what drivers can be + built. You should get an output similar to this: + + \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 0 + + The \c configure script cannot detect the neccessary libraries + and include files if they are not in the standard paths, so it + may be necessary to specify these paths using the \c -I and \c -L + command-line options. For example, if your MySQL include files + are installed in \c /usr/local/mysql (or in \c{C:\mysql\include} + on Windows), then pass the following parameter to configure: \c + -I/usr/local/mysql (or \c{-I C:\mysql\include} for Windows). + + On Windows the \c -I parameter doesn't accept spaces in + filenames, so use the 8.3 name instead; for example, use + \c{C:\progra~1\mysql} instead of \c{C:\Program Files\mysql}. + + Use the \c{-qt-sql-<driver>} parameter to build the database driver + statically into your Qt library or \c{-plugin-sql-<driver>} to build + the driver as a plugin. Look at the sections that follow for + additional information about required libraries. + + \target buildingmanually + \section1 Building the Plugins Manually + + \target QMYSQL + \section2 QMYSQL for MySQL 4 and higher + + \section3 QMYSQL Stored Procedure Support + + MySQL 5 introduces stored procedure support at the SQL level, but no + API to control IN, OUT and INOUT parameters. Therefore, parameters + have to be set and read using SQL commands instead of QSqlQuery::bindValue(). + + Example stored procedure: + + \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 1 + + Source code to access the OUT values: + + \snippet doc/src/snippets/code/doc_src_sql-driver.cpp 2 + + \bold{Note:} \c{@outval1} and \c{@outval2} are variables local to the current + connection and will not be affected by queries sent from another host + or connection. + + \section3 Embedded MySQL Server + + The MySQL embedded server is a drop-in replacement for the normal + client library. With the embedded MySQL server, a MySQL server is + not required to use MySQL functionality. + + To use the embedded MySQL server, simply link the Qt plugin to \c + libmysqld instead of libmysqlclient. This can be done by replacing + \c -lmysqlclient_r by \c -lmysqld in the \c qmake command in the + section below. + + Please refer to the MySQL documentation, chapter "libmysqld, the Embedded + MySQL Server Library" for more information about the MySQL embedded server. + + \section3 How to Build the QMYSQL Plugin on Unix and Mac OS X + + You need the MySQL header files and as well as the shared library + \c{libmysqlclient.so}. Depending on your Linux distribution you may + need to install a package which is usually called "mysql-devel". + + Tell \l qmake where to find the MySQL header files and shared + libraries (here it is assumed that MySQL is installed in + \c{/usr/local}) and run \c{make}: + + \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 3 + + After installing Qt, as described in the \l{Installing Qt for X11 + Platforms} document, you also need to install the plugin in the + standard location: + + \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 4 + + \section3 How to Build the QMYSQL Plugin on Windows + + You need to get the MySQL installation files. Run \c SETUP.EXE and + choose "Custom Install". Install the "Libs & Include Files" Module. + Build the plugin as follows (here it is assumed that MySQL is + installed in \c{C:\MySQL}): + + \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 5 + + If you are not using a Microsoft compiler, replace \c nmake with \c + make in the line above. + + \note This database plugin is not supported for Windows CE. + + \note Including \c{"-o Makefile"} as an argument to \l qmake to + tell it where to build the makefile can cause the plugin to be + built in release mode only. If you are expecting a debug version + to be built as well, don't use the \c{"-o Makefile"} option. + + \section3 How to build the MySQL driver for MinGW users + + The following steps have been used successfully for WinXP SP3. In + this example, Qt 4.6.2 is shown. + + \list + + \o Download the following components: + \list + \o \c{MinGW-5.1.6.exe} + \o \c{mingw-utils-0.3.tar.gz} + \o Qt sources, e.g. \c{qt-everywhere-opensource-src-4.6.2.zip} + \o \c{mysql-5.1.35-win32.msi} + \endlist + + \o Install \c{MinGW-5.1.6.exe} in, e.g. \c{C:\MinGW}. + + \o Extract \c{mingw-utils-0.3.tar.gz} into, e.g. \c{C:\MinGW}. + + \o Add the path for \c{MinGW-5.1.6.exe} to your \c{PATH} variable, + e.g. \c{C:\MinGW\bin;} + + \o Extract the Qt sources, (\c{qt-everywhere-opensource-src-4.6.2.zip}), + into, e.g. \c{C:\Qt}. + + \o Add the path for the eventual Qt binary to your \c{PATH} variable, + e.g. \c{C:\Qt\4.6.2\bin;}. + + \o Install MySQL (\c{mysql-5.1.35-win32.msi}), customizing the + components. Select only the headers and libraries. Install in, + e.g. \c{C:\MySQL\MySQL51}. + + \o Open the DOS prompt, go to \c{C:\MySQL\MySQL51\lib\opt}, and run + the following commands: + \list + \o \c{reimp -d libmysql.lib} + \o \c{dlltool -k -d libmysql.def -l libmysql.a} + \endlist + + \o Open the DOS prompt, go to \c{C:\Qt\4.6.2} and run the following commands: + \list + \o \c{configure.exe -debug-and-release -platform win32-g++ -qt-sql-mysql + -l mysql -I C:\MySQL\MySQL51\include -L C:\MySQL\MySQL51\lib\opt} + \o \c{mingw32-make sub-src} + \endlist + This step takes a long time. + + \o Open the DOS prompt, go to + \c{C:\Qt\4.6.2\src\plugins\sqldrivers\mysql} and run the + following command: + \list + \o \c{qmake "INCLUDEPATH+=C:\MySQL\MySQL51\include" "LIBS+=-L. mysql" mysql.pro} + \endlist + + \o Now the following libraries are ready in \c{C:\Qt\4.6.2\plugins\sqldrivers}. + \list + \o \c{libqsqlmysql4.a} + \o \c{libqsqlmysqld4.a} + \o \c{qsqlmysql4.dll} + \o \c{qsqlmysqld4.dll} + \endlist + To use the SDK and QtCreator directly, copy these libraries to + your \c{C:\Qt\...\qt\plugins\sqldrivers\}, and copy + \c{C:\MySQL\MySQL51\lib\opt\libmysql.dll} to your \c{C:\Qt\...\qt\bin\}. + + \endlist + + \target QOCI + \section2 QOCI for the Oracle Call Interface (OCI) + + \section3 General Information about the OCI plugin + + The Qt OCI plugin supports Oracle 9i, 10g and higher. After + connecting to the Oracle server, the plugin will auto-detect the + database version and enable features accordingly. + + It's possible to connect to a Oracle database without a tnsnames.ora file. + This requires that the database SID is passed to the driver as the database + name and that a hostname is given. + + \section3 OCI User Authentication + + The Qt OCI plugin supports authentication using + external credentials (OCI_CRED_EXT). Usually, this means that the database + server will use the user authentication provided by the operating system + instead of its own authentication mechanism. + + Leave the username and password empty when opening a connection with + QSqlDatabase to use the external credentials authentication. + + \section3 OCI BLOB/LOB Support + + Binary Large Objects (BLOBs) can be read and written, but be aware + that this process may require a lot of memory. You should use a forward + only query to select LOB fields (see QSqlQuery::setForwardOnly()). + + Inserting BLOBs should be done using either a prepared query where the + BLOBs are bound to placeholders or QSqlTableModel, which uses a prepared + query to do this internally. + + \section3 How to Build the OCI Plugin on Unix and Mac OS X + + For Oracle 10g, all you need is the "Instant Client Package - Basic" and + "Instant Client Package - SDK". For Oracle prior to 10g, you require + the standard Oracle client and the SDK packages. + + Oracle library files required to build the driver: + + \list + \i \c libclntsh.so (all versions) + \i \c libwtc9.so (only Oracle 9) + \endlist + + Tell \c qmake where to find the Oracle header files and shared + libraries and run make: + + For Oracle version 9: + \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 6 + + For Oracle version 10, we assume that you installed the RPM packages of the + Instant Client Package SDK (you need to adjust the version number accordingly): + \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 7 + + \bold{Note:} If you are using the Oracle Instant Client package, + you will need to set LD_LIBRARY_PATH when building the OCI SQL plugin + and when running an applicaiton that uses the OCI SQL plugin. You can + avoid this requirement by setting and RPATH and listing all of the + libraries to link to. Here is an example: + \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 32 + + If you wish to build the OCI plugin manually with this method the procedure looks like this: + \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 33 + + \section3 How to Build the OCI Plugin on Windows + + Choosing the option "Programmer" in the Oracle Client Installer from + the Oracle Client Installation CD is generally sufficient to build the + plugin. For some versions of Oracle Client, you may also need to select + the "Call Interface (OCI)" option if it is available. + + Build the plugin as follows (here it is assumed that Oracle Client is + installed in \c{C:\oracle}): + + \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 8 + + If you are not using a Microsoft compiler, replace \c nmake with \c + make in the line above. + + When you run your application you will also need to add the \c oci.dll + path to your \c PATH environment variable: + + \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 9 + + \bold{Note:} This database plugin is not supported for Windows CE. + + \target QODBC + \section2 QODBC for Open Database Connectivity (ODBC) + + \section3 General Information about the ODBC plugin + + ODBC is a general interface that allows you to connect to multiple + DBMSs using a common interface. The QODBC driver allows you to connect + to an ODBC driver manager and access the available data sources. Note + that you also need to install and configure ODBC drivers for the ODBC + driver manager that is installed on your system. The QODBC plugin + then allows you to use these data sources in your Qt applications. + + \bold{Note:} You should use native drivers in preference to the ODBC + driver where they are available. ODBC support can be used as a fallback + for compliant databases if no native drivers are available. + + On Windows an ODBC driver manager should be installed by default. + For Unix systems there are some implementations which must be + installed first. Note that every client that uses your application is + required to have an ODBC driver manager installed, otherwise the + QODBC plugin will not work. + + Be aware that when connecting to an ODBC datasource you must pass in + the name of the ODBC datasource to the QSqlDatabase::setDatabaseName() + function rather than the actual database name. + + The QODBC Plugin needs an ODBC compliant driver manager version 2.0 or + later to work. Some ODBC drivers claim to be version 2.0 compliant, + but do not offer all the necessary functionality. The QODBC plugin + therefore checks whether the data source can be used after a + connection has been established and refuses to work if the check + fails. If you don't like this behavior, you can remove the \c{#define + ODBC_CHECK_DRIVER} line from the file \c{qsql_odbc.cpp}. Do this at + your own risk! + + By default, Qt instructs the ODBC driver to behave as an ODBC 2.x + driver. However, for some \e{driver-manager/ODBC 3.x-driver} + combinations (e.g., \e{unixODBC/MaxDB ODBC}), telling the ODBC + driver to behave as a 2.x driver can cause the driver plugin to + have unexpected behavior. To avoid this problem, instruct the ODBC + driver to behave as a 3.x driver by + \l{QSqlDatabase::setConnectOptions()} {setting the connect option} + \c{"SQL_ATTR_ODBC_VERSION=SQL_OV_ODBC3"} before you + \l{QSqlDatabase::open()} {open your database connection}. Note + that this will affect multiple aspects of ODBC driver behavior, + e.g., the SQLSTATEs. Before setting this connect option, consult + your ODBC documentation about behavior differences you can expect. + + If you experience very slow access of the ODBC datasource, make sure + that ODBC call tracing is turned off in the ODBC datasource manager. + + Some drivers don't support scrollable cursors. In that case case only + queries in forwardOnly mode can be used successfully. + + \section3 ODBC Stored Procedure Support + + With Microsoft SQL Server the result set returned by a stored + procedure that uses the return statement, or returns multiple result + sets, will be accessible only if you set the query's forward only + mode to \e forward using \l QSqlQuery::setForwardOnly(). + + \snippet doc/src/snippets/code/doc_src_sql-driver.cpp 10 + + \bold{Note:} The value returned by the stored procedure's return statement + is discarded. + + \section3 ODBC Unicode Support + + The QODBC Plugin will use the Unicode API if UNICODE is defined. On + Windows NT based systems, this is the default. Note that the ODBC + driver and the DBMS must also support Unicode. + + Some driver managers and drivers don't support UNICODE. To use the + QODBC plugin with such drivers it has to be compiled with the + Q_ODBC_VERSION_2 defined. + + For the Oracle 9 ODBC driver (Windows), it is neccessary to check + "SQL_WCHAR support" in the ODBC driver manager otherwise Oracle + will convert all Unicode strings to local 8-bit. + + \section3 How to Build the ODBC Plugin on Unix and Mac OS X + + It is recommended that you use unixODBC. You can find the latest + version and ODBC drivers at \l http://www.unixodbc.org. + You need the unixODBC header files and shared libraries. + + Tell \c qmake where to find the unixODBC header files and shared + libraries (here it is assumed that unixODBC is installed in + \c{/usr/local/unixODBC}) and run \c{make}: + + \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 11 + + \section3 How to Build the ODBC Plugin on Windows + + The ODBC header and include files should already be installed in the + right directories. You just have to build the plugin as follows: + + \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 12 + + If you are not using a Microsoft compiler, replace \c nmake with \c + make in the line above. + + \bold{Note:} This database plugin is not officially supported for Windows CE. + + \target QPSQL + \section2 QPSQL for PostgreSQL (Version 7.3 and Above) + + \section3 General Information about the QPSQL driver + + The QPSQL driver supports version 7.3 and higher of the PostgreSQL server. + We recommend that you use a client library from version 7.3.15, 7.4.13, + 8.0.8, 8.1.4 or more recent as these versions contain security fixes, and + as the QPSQL driver might not build with older versions of the client + library depending on your platform. + + For more information about PostgreSQL visit \l http://www.postgresql.org. + + \section3 QPSQL Unicode Support + + The QPSQL driver automatically detects whether the PostgreSQL + database you are connecting to supports Unicode or not. Unicode is + automatically used if the server supports it. Note that the driver + only supports the UTF-8 encoding. If your database uses any other + encoding, the server must be compiled with Unicode conversion + support. + + Unicode support was introduced in PostgreSQL version 7.1 and it will + only work if both the server and the client library have been compiled + with multibyte support. More information about how to set up a + multibyte enabled PostgreSQL server can be found in the PostgreSQL + Administrator Guide, Chapter 5. + + \section3 QPSQL BLOB Support + + Binary Large Objects are supported through the \c BYTEA field type in + PostgreSQL server versions >= 7.1. + + \section3 How to Build the QPSQL Plugin on Unix and Mac OS X + + You need the PostgreSQL client library and headers installed. + + To make \c qmake find the PostgreSQL header files and shared + libraries, run \c qmake the following way (assuming that the + PostgreSQL client is installed in \c{/usr}): + + \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 13 + + After installing Qt, as described in the \l{Installing Qt for X11 Platforms} document, + you also need to install the plugin in the standard location: + + \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 14 + + \section3 How to Build the QPSQL Plugin on Windows + + Install the appropriate PostgreSQL developer libraries for your + compiler. Assuming that PostgreSQL was installed in \c{C:\psql}, + build the plugin as follows: + + \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 15 + + Users of MinGW may wish to consult the following online document: + \l{Compiling PostgreSQL On Native Win32 FAQ}. + + \bold{Note:} This database plugin is not supported for Windows CE. + + \target QTDS + \section2 QTDS for Sybase Adaptive Server + + \note TDS is no longer used by MS Sql Server, and is superceded by + \l{QODBC}{ODBC}. QTDS is obsolete from Qt 4.7. + + \section3 General Information about QTDS + + It is not possible to set the port with QSqlDatabase::setPort() due to limitations in the + Sybase client library. Refer to the Sybase documentation for information on how to set up + a Sybase client configuration file to enable connections to databases on non-default ports. + + \section3 How to Build the QTDS Plugin on Unix and Mac OS X + + Under Unix, two libraries are available which support the TDS protocol: + + \list + \i FreeTDS, a free implementation of the TDS protocol + (\l{http://www.freetds.org}). Note that FreeTDS is not yet stable, + so some functionality may not work as expected. + + \i Sybase Open Client, available from \l{http://www.sybase.com}. + Note for Linux users: Get the Open Client RPM from + \l{http://linux.sybase.com}. + \endlist + + Regardless of which library you use, the shared object file + \c{libsybdb.so} is needed. Set the \c SYBASE environment variable to + point to the directory where you installed the client library and + execute \c{qmake}: + + \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 16 + + \section3 How to Build the QDTS Plugin on Windows + + You can either use the DB-Library supplied by Microsoft or the Sybase + Open Client (\l{http://www.sybase.com}). You must include \c + NTWDBLIB.LIB to build the plugin: + + \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 17 + + By default the Microsoft library is used on Windows, if you want to + force the use of the Sybase Open Client, you must define \c + Q_USE_SYBASE in \c{%QTDIR%\src\sql\drivers\tds\qsql_tds.cpp}. If you + are not using a Microsoft compiler, replace \c nmake with \c make in + the line above. + + \bold{Note:} This database plugin is not supported for Windows CE. + + \target QDB2 + \section2 QDB2 for IBM DB2 (Version 7.1 and Above) + + \section3 General Information about QDB2 + + The Qt DB2 plugin makes it possible to access IBM DB2 databases. It + has been tested with IBM DB2 v7.1 and 7.2. You must install the IBM + DB2 development client library, which contains the header and library + files necessary for compiling the QDB2 plugin. + + The QDB2 driver supports prepared queries, reading/writing of Unicode + strings and reading/writing of BLOBs. + + We suggest using a forward-only query when calling stored procedures + in DB2 (see QSqlQuery::setForwardOnly()). + + \section3 How to Build the QDB2 Plugin on Unix and Mac OS X + + \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 18 + + After installing Qt, as described in the \l{Installing Qt for X11 Platforms} document, + you also need to install the plugin in the standard location: + + \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 19 + + \section3 How to Build the QDB2 Plugin on Windows + + The DB2 header and include files should already be installed in the + right directories. You just have to build the plugin as follows: + + \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 20 + + If you are not using a Microsoft compiler, replace \c nmake + with \c make in the line above. + + \bold{Note:} This database plugin is not supported for Windows CE. + + \target QSQLITE2 + \section2 QSQLITE2 for SQLite Version 2 + + The Qt SQLite 2 plugin is offered for compatibility. Whenever + possible, use the \l{#QSQLITE}{version 3 plugin} instead. The + build instructions for version 3 apply to version 2 as well. + + \target QSQLITE + \section2 QSQLITE for SQLite (Version 3 and Above) + + \section3 General Information about QSQLITE + + The Qt SQLite plugin makes it possible to access SQLite + databases. SQLite is an in-process database, which means that it + is not necessary to have a database server. SQLite operates on a + single file, which must be set as the database name when opening + a connection. If the file does not exist, SQLite will try to + create it. SQLite also supports in-memory databases, simply pass + ":memory:" as the database name. + + SQLite has some restrictions regarding multiple users and + multiple transactions. If you try to read/write on a resource from different + transactions, your application might freeze until one transaction commits + or rolls back. The Qt SQLite driver will retry to write to a locked resource + until it runs into a timeout (see \c{QSQLITE_BUSY_TIMEOUT} + at QSqlDatabase::setConnectOptions()). + + In SQLite any column, with the exception of an INTEGER PRIMARY KEY column, + may be used to store any type of value. For instance, a column declared as + INTEGER may contain an integer value in one row and a text value in the + next. This is due to SQLite associating the type of a value with the value + itself rather than with the column it is stored in. A consequence of this + is that the type returned by QSqlField::type() only indicates the field's + recommended type. No assumption of the actual type should be made from + this and the type of the individual values should be checked. + + The driver is locked for updates while a select is executed. This + may cause problems when using QSqlTableModel because Qt's item views + fetch data as needed (with QSqlQuery::fetchMore() in the case of + QSqlTableModel). + + You can find information about SQLite on \l{http://www.sqlite.org}. + + \section3 How to Build the QSQLITE Plugin + + SQLite version 3 is included as a third-party library within Qt. + It can be built by passing the following parameters to the + configure script: \c{-plugin-sql-sqlite} (build as a plugin) or + \c{-qt-sql-sqlite} (linked directly into the Qt library). + + If you don't want to use the SQLite library included with Qt, you + can build it manually (replace \c $SQLITE by the directory where + SQLite resides): + + \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 21 + + After installing Qt, as described in the \l{Installing Qt for X11 Platforms} document, + you also need to install the plugin in the standard location: + + \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 22 + + On Windows: + + \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 23 + + \section3 QSQLITE File Format Compatibility + + SQLite minor releases sometimes break file format forward compatibility. + For example, SQLite 3.3 can read database files created with SQLite 3.2, + but databases created with SQLite 3.3 cannot be read by SQLite 3.2. + Please refer to the SQLite documentation and change logs for information about + file format compatibility between versions. + + Qt minor releases usually follow the SQLite minor releases, while Qt patch releases + follow SQLite patch releases. Patch releases are therefore both backward and forward + compatible. + + To force SQLite to use a specific file format, it is neccessary to build and + ship your own database plugin with your own SQLite library as illustrated above. + Some versions of SQLite can be forced to write a specific file format by setting + the \c{SQLITE_DEFAULT_FILE_FORMAT} define when building SQLite. + + \target QIBASE + \section2 QIBASE for Borland InterBase + + \section3 General Information about QIBASE + + The Qt InterBase plugin makes it possible to access the InterBase and + Firebird databases. InterBase can either be used as a client/server or + without a server in which case it operates on local files. The + database file must exist before a connection can be established. Firebird + must be used with a server configuration. + + Note that InterBase requires you to specify the full path to the + database file, no matter whether it is stored locally or on another + server. + + \snippet doc/src/snippets/code/doc_src_sql-driver.cpp 24 + + You need the InterBase/Firebird development headers and libraries + to build this plugin. + + Due to license incompatibilities with the GPL, users of the Qt Open Source + Edition are not allowed to link this plugin to the commercial editions of + InterBase. Please use Firebird or the free edition of InterBase. + + \section3 QIBASE Unicode Support and Text Encoding + + By default the driver connects to the database using UNICODE_FSS. This can + be overridden by setting the ISC_DPB_LC_CTYPE parameter with + QSqlDatabase::setConnectOptions() before opening the connection. + + \snippet doc/src/snippets/code/doc_src_sql-driver.cpp 25 + + If Qt doesn't support the given text encoding the driver will issue a + warning message and connect to the database using UNICODE_FSS. + + Note that if the text encoding set when connecting to the database is + not the same as in the database, problems with transliteration might arise. + + \section3 QIBASE Stored procedures + + InterBase/Firebird return OUT values as result set, so when calling stored + procedure, only IN values need to be bound via QSqlQuery::bindValue(). The + RETURN/OUT values can be retrieved via QSqlQuery::value(). Example: + + \snippet doc/src/snippets/code/doc_src_sql-driver.cpp 26 + + \section3 How to Build the QIBASE Plugin on Unix and Mac OS X + + The following assumes InterBase or Firebird is installed in + \c{/opt/interbase}: + + If you are using InterBase: + + \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 27 + + If you are using Firebird, the Firebird library has to be set explicitly: + + \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 28 + + \section3 How to Build the QIBASE Plugin on Windows + + The following assumes InterBase or Firebird is installed in + \c{C:\interbase}: + + If you are using InterBase: + + \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 29 + + If you are using Firebird, the Firebird library has to be set explicitely: + + \snippet doc/src/snippets/code/doc_src_sql-driver.qdoc 30 + + If you are not using a Microsoft compiler, replace \c nmake + with \c make in the line above. + + Note that \c{C:\interbase\bin} must be in the \c PATH. + + \bold{Note:} This database plugin is not supported for Windows CE. + + \target troubleshooting + \section1 Troubleshooting + + You should always use client libraries that have been compiled with + the same compiler as you are using for your project. If you cannot get + a source distibution to compile the client libraries yourself, you + must make sure that the pre-compiled library is compatible with + your compiler, otherwise you will get a lot of "undefined symbols" + errors. Some compilers have tools to convert libraries, e.g. Borland + ships the tool \c{COFF2OMF.EXE} to convert libraries that have been + generated with Microsoft Visual C++. + + If the compilation of a plugin succeeds but it cannot be loaded, + make sure that the following requirements are met: + + \list + \i Ensure that you are using a shared Qt library; you cannot use the + plugins with a static build. + \i Ensure that the plugin is in the correct directory. You can use + QApplication::libraryPaths() to determine where Qt looks for plugins. + \i Ensure that the client libraries of the DBMS are available on the + system. On Unix, run the command \c{ldd} and pass the name of the + plugin as parameter, for example \c{ldd libqsqlmysql.so}. You will + get a warning if any of the client libraries couldn't be found. + On Windows, you can use Visual Studio's dependency walker. + \i Compile Qt with \c{QT_DEBUG_COMPONENT} defined to get very verbose + debug output when loading plugins. + \endlist + + Make sure you have followed the guide to \l{Deploying Plugins}. + If you experience plugin load problems and see output like this: + + \snippet doc/src/snippets/code/doc_src_sql-driver.cpp 31 + + the problem is usually that the plugin had the wrong \l{Deploying + Plugins#The Build Key}{build key}. This might require removing an + entry from the \l{Deploying Plugins#The Plugin Cache} {plugin cache}. + + \target development + \section1 How to Write Your Own Database Driver + + QSqlDatabase is responsible for loading and managing database driver + plugins. When a database is added (see QSqlDatabase::addDatabase()), + the appropriate driver plugin is loaded (using QSqlDriverPlugin). + QSqlDatabase relies on the driver plugin to provide interfaces for + QSqlDriver and QSqlResult. + + QSqlDriver is an abstract base class which defines the functionality + of a SQL database driver. This includes functions such as + QSqlDriver::open() and QSqlDriver::close(). QSqlDriver is responsible + for connecting to a database, establish the proper environment, etc. + In addition, QSqlDriver can create QSqlQuery objects appropriate for + the particular database API. QSqlDatabase forwards many of its + function calls directly to QSqlDriver which provides the concrete + implementation. + + QSqlResult is an abstract base class which defines the functionality + of a SQL database query. This includes statements such as \c{SELECT}, + \c{UPDATE}, and \c{ALTER} \c{TABLE}. QSqlResult contains functions + such as QSqlResult::next() and QSqlResult::value(). QSqlResult is + responsible for sending queries to the database, returning result + data, etc. QSqlQuery forwards many of its function calls directly to + QSqlResult which provides the concrete implementation. + + QSqlDriver and QSqlResult are closely connected. When implementing a + Qt SQL driver, both of these classes must to be subclassed and the + abstract virtual methods in each class must be implemented. + + To implement a Qt SQL driver as a plugin (so that it is + recognized and loaded by the Qt library at runtime), the driver + must use the Q_EXPORT_PLUGIN2() macro. Read \l{How to Create Qt + Plugins} for more information on this. You can also check out how + this is done in the SQL plugins that are provided with Qt in + \c{QTDIR/src/plugins/sqldrivers} and \c{QTDIR/src/sql/drivers}. + + The following code can be used as a skeleton for a SQL driver: + + \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 47 + \codeline + \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 48 +*/ diff --git a/doc/src/sql-programming/sql-programming.qdoc b/doc/src/sql-programming/sql-programming.qdoc new file mode 100644 index 0000000000..184dafabf1 --- /dev/null +++ b/doc/src/sql-programming/sql-programming.qdoc @@ -0,0 +1,609 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \group database + \title Database Classes + + \brief Database related classes, e.g. for SQL databases. +*/ + +/*! + \page sql-programming.html + \title SQL Programming + \ingroup qt-sql + \nextpage Connecting to Databases + + \brief Database integration for Qt applications. + + This overview assumes that you have at least a basic knowledge of + SQL. You should be able to understand simple \c SELECT, \c + INSERT, \c UPDATE, and \c DELETE statements. Although the \l + QSqlTableModel class provides an interface to database browsing + and editing that does not require a knowledge of SQL, a basic + understanding of SQL is highly recommended. A standard text + covering SQL databases is \e {An Introduction to Database Systems} + (7th Ed.) by C. J. Date, ISBN 0201385902. + + \section1 Topics: + + \list + \o \l{Database Classes} + \o \l{Connecting to Databases} + \list + \o \l{SQL Database Drivers} + \endlist + \o \l{Executing SQL Statements} + \list + \o \l{Data Types for Qt-supported Database Systems} + \endlist + \o \l{Using the SQL Model Classes} + \o \l{Presenting Data in a Table View} + \o \l{Creating Data-Aware Forms} + \endlist + + \section1 Database Classes + + These classes provide access to SQL databases. + + \annotatedlist database + + The SQL classes are divided into three layers: + + \section2 Driver Layer + + This comprises the classes QSqlDriver, QSqlDriverCreator<T>, + QSqlDriverCreatorBase, QSqlDriverPlugin, and QSqlResult. + + This layer provides the low-level bridge between the specific databases + and the SQL API layer. See \l{SQL Database Drivers} for more information. + + \section2 SQL API Layer + + These classes provide access to databases. Connections + are made using the QSqlDatabase class. Database + interaction is achieved by using the QSqlQuery class. + In addition to QSqlDatabase and QSqlQuery, the SQL API + layer is supported by QSqlError, QSqlField, QSqlIndex, + and QSqlRecord. + + \section2 User Interface Layer + + These classes link the data from a database to data-aware widgets. + They include QSqlQueryModel, QSqlTableModel, and QSqlRelationalTableModel. + These classes are designed to work with Qt's + \l{Model/View Programming}{model/view framework}. + + Note that to use any of these classes, a QCoreApplication object + must have been instantiated first. +*/ + +/*! + \page sql-connecting.html + \title Connecting to Databases + \ingroup qt-sql + + \contentspage SQL Programming + \previouspage SQL Programming + \nextpage Executing SQL Statements + + To access a database with QSqlQuery or QSqlQueryModel, create and + open one or more database connections. Database connections are + normally identified by connection name, \e{not} by database name. + You can have multiple connections to the same database. + QSqlDatabase also supports the concept of a \e{default} + connection, which is an unnamed connection. When calling QSqlQuery + or QSqlQueryModel member functions that take a connection name + argument, if you don't pass a connection name, the default + connection will be used. Creating a default connection is + convenient when your application only requires one database + connection. + + Note the difference between creating a connection and opening it. + Creating a connection involves creating an instance of class + QSqlDatabase. The connection is not usable until it is opened. The + following snippet shows how to create a \e{default} connection + and then open it: + + \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 26 + + The first line creates the connection object, and the last line + opens it for use. In between, we initialize some connection + information, including the \l{QSqlDatabase::setDatabaseName()} + {database name}, the \l{QSqlDatabase::setHostName()} {host name}, + the \l{QSqlDatabase::setUserName()} {user name}, and the + \l{QSqlDatabase::setPassword()} {password}. In this case, we are + connecting to the MySQL database \c{flightdb} on the host + \c{bigblue}. The \c{"QMYSQL"} argument to + \l{QSqlDatabase::addDatabase()} {addDatabase()} specifies the type + of database driver to use for the connection. The set of database + drivers included with Qt are shown in the table of \l{SQL Database + Drivers#Supported Databases} {supported database drivers}. + + The connection in the snippet will be the \e{default} connection, + because we don't pass the second argument to + \l{QSqlDatabase::addDatabase()} {addDatabase()}, which is the + connection name. For example, here we establish two MySQL database + connections named \c{"first"} and \c{"second"}: + + \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 27 + + After these connections have been initialized, \l{QSqlDatabase::} + {open()} for each one to establish the live connections. If the + \l{QSqlDatabase::} {open()} fails, it returns false. In that case, + call QSqlDatabase::lastError() to get error information. + + Once a connection is established, we can call the static function + QSqlDatabase::database() from anywhere with a connection name to + get a pointer to that database connection. If we don't pass a + connection name, it will return the default connection. For + example: + + \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 28 + \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 29 + \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 30 + + To remove a database connection, first close the database using + QSqlDatabase::close(), then remove it using the static method + QSqlDatabase::removeDatabase(). +*/ + +/*! + \page sql-sqlstatements.html + \title Executing SQL Statements + \ingroup qt-sql + + \previouspage Connecting to Databases + \contentspage SQL Programming + \nextpage Using the SQL Model Classes + + + The QSqlQuery class provides an interface for executing SQL + statements and navigating through the result set of a query. + + The QSqlQueryModel and QSqlTableModel classes described in the + next section provide a higher-level interface for accessing + databases. If you are unfamiliar with SQL, you might want to skip + directly to the next section (\l{Using the SQL Model Classes}). + + \section2 Executing a Query + + To execute an SQL statement, simply create a QSqlQuery object and + call QSqlQuery::exec() like this: + + \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 31 + + The QSqlQuery constructor accepts an optional QSqlDatabase object + that specifies which database connection to use. In the example + above, we don't specify any connection, so the default connection + is used. + + If an error occurs, \l{QSqlQuery::exec()}{exec()} returns false. + The error is then available as QSqlQuery::lastError(). + + \section2 Navigating the Result Set + + QSqlQuery provides access to the result set one record at a time. + After the call to \l{QSqlQuery::exec()}{exec()}, QSqlQuery's + internal pointer is located one position \e{before} the first + record. We must call QSqlQuery::next() once to advance to the + first record, then \l{QSqlQuery::next()}{next()} again repeatedly + to access the other records, until it returns false. Here's a + typical loop that iterates over all the records in order: + + \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 32 + + The QSqlQuery::value() function returns the value of a field in + the current record. Fields are specified as zero-based indexes. + QSqlQuery::value() returns a QVariant, a type that can hold + various C++ and core Qt data types such as \c int, QString, and + QByteArray. The different database types are automatically mapped + into the closest Qt equivalent. In the code snippet, we call + QVariant::toString() and QVariant::toInt() to convert + variants to QString and \c int. + + For an overview of the recommended types for use with Qt-supported + Databases, please refer to \l{Data Types for Qt-supported Database + Systems} {this table}. + + You can iterate back and forth using QSqlQuery::next(), + QSqlQuery::previous(), QSqlQuery::first(), QSqlQuery::last(), and + QSqlQuery::seek(). The current row index is returned by + QSqlQuery::at(), and the total number of rows in the result set + is avaliable as QSqlQuery::size() for databases that support it. + + To determine whether a database driver supports a given feature, + use QSqlDriver::hasFeature(). In the following example, we call + QSqlQuery::size() to determine the size of a result set of + the underlying database supports that feature; otherwise, we + navigate to the last record and use the query's position to tell + us how many records there are. + + \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 33 + + If you iterate through a result set only using next() and seek() + with positive values, you can call + QSqlQuery::setForwardOnly(true) before calling exec(). This is an + easy optimization that will speed up the query significantly when + operating on large result sets. + + \section2 Inserting, Updating, and Deleting Records + + QSqlQuery can execute arbitrary SQL statements, not just + \c{SELECT}s. The following example inserts a record into a table + using \c{INSERT}: + + \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 34 + + If you want to insert many records at the same time, it is often + more efficient to separate the query from the actual values being + inserted. This can be done using placeholders. Qt supports two + placeholder syntaxes: named binding and positional binding. + Here's an example of named binding: + + \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 35 + + Here's an example of positional binding: + + \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 36 + + Both syntaxes work with all database drivers provided by Qt. If + the database supports the syntax natively, Qt simply forwards the + query to the DBMS; otherwise, Qt simulates the placeholder syntax + by preprocessing the query. The actual query that ends up being + executed by the DBMS is available as QSqlQuery::executedQuery(). + + When inserting multiple records, you only need to call + QSqlQuery::prepare() once. Then you call + \l{QSqlQuery::bindValue()}{bindValue()} or + \l{QSqlQuery::addBindValue()}{addBindValue()} followed by + \l{QSqlQuery::exec()}{exec()} as many times as necessary. + + Besides performance, one advantage of placeholders is that you + can easily specify arbitrary values without having to worry about + escaping special characters. + + Updating a record is similar to inserting it into a table: + + \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 37 + + You can also use named or positional binding to associate + parameters to actual values. + + Finally, here's an example of a \c DELETE statement: + + \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 38 + + \section2 Transactions + + If the underlying database engine supports transactions, + QSqlDriver::hasFeature(QSqlDriver::Transactions) will return + true. You can use QSqlDatabase::transaction() to initiate a + transaction, followed by the SQL commands you want to execute + within the context of the transaction, and then either + QSqlDatabase::commit() or QSqlDatabase::rollback(). When + using transactions you must start the transaction before you + create your query. + + Example: + + \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 39 + + Transactions can be used to ensure that a complex operation is + atomic (for example, looking up a foreign key and creating a + record), or to provide a means of canceling a complex change in + the middle. + + \omit + It would be useful to mention transactions, and the fact that + some databases don't support them. + \endomit +*/ + +/*! + \page sql-model.html + \title Using the SQL Model Classes + \ingroup qt-sql + + \previouspage Executing SQL Statements + \contentspage SQL Programming + \nextpage Presenting Data in a Table View + + In addition to QSqlQuery, Qt offers three higher-level classes + for accessing databases. These classes are QSqlQueryModel, + QSqlTableModel, and QSqlRelationalTableModel. + + \table + \row \o QSqlQueryModel + \o A read-only model based on an arbitrary SQL query. + \row \o QSqlTableModel + \o A read-write model that works on a single table. + \row \o QSqlRelationalTableModel + \o A QSqlTableModel subclass with foreign key support. + \endtable + + These classes derive from QAbstractTableModel (which in turn + inherits from QAbstractItemModel) and make it easy to present + data from a database in an item view class such as QListView and + QTableView. This is explained in detail in the \l{Presenting Data + in a Table View} section. + + Another advantage of using these classes is that it can make your + code easier to adapt to other data sources. For example, if you + use QSqlTableModel and later decide to use XML files to store + data instead of a database, it is essentially just a matter of + replacing one data model with another. + + \section2 The SQL Query Model + + QSqlQueryModel offers a read-only model based on an SQL query. + + Example: + + \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 40 + + After setting the query using QSqlQueryModel::setQuery(), you can + use QSqlQueryModel::record(int) to access the individual records. + You can also use QSqlQueryModel::data() and any of the other + functions inherited from QAbstractItemModel. + + There's also a \l{QSqlQueryModel::setQuery()}{setQuery()} + overload that takes a QSqlQuery object and operates on its result + set. This enables you to use any features of QSqlQuery to set up + the query (e.g., prepared queries). + + \section2 The SQL Table Model + + QSqlTableModel offers a read-write model that works on a single + SQL table at a time. + + Example: + + \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 41 + + QSqlTableModel is a high-level alternative to QSqlQuery for + navigating and modifying individual SQL tables. It typically + results in less code and requires no knowledge of SQL syntax. + + Use QSqlTableModel::record() to retrieve a row in the table, and + QSqlTableModel::setRecord() to modify the row. For example, the + following code will increase every employee's salary by 10 per + cent: + + \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 42 + + You can also use QSqlTableModel::data() and + QSqlTableModel::setData(), which are inherited from + QAbstractItemModel, to access the data. For example, here's how + to update a record using + \l{QSqlTableModel::setData()}{setData()}: + + \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 43 + + Here's how to insert a row and populate it: + + \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 44 + + Here's how to delete five consecutive rows: + + \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 45 + \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 46 + + The first argument to QSqlTableModel::removeRows() is the index + of the first row to delete. + + When you're finished changing a record, you should always call + QSqlTableModel::submitAll() to ensure that the changes are + written to the database. + + When and whether you actually \e need to call submitAll() depends + on the table's \l{QSqlTableModel::editStrategy()}{edit strategy}. + The default strategy is QSqlTableModel::OnRowChange, which + specifies that pending changes are applied to the database when + the user selects a different row. Other strategies are + QSqlTableModel::OnManualSubmit (where all changes are cached in + the model until you call submitAll()) and + QSqlTableModel::OnFieldChange (where no changes are cached). + These are mostly useful when QSqlTableModel is used with a view. + + QSqlTableModel::OnFieldChange seems to deliver the promise that + you never need to call submitAll() explicitly. There are two + pitfalls, though: + + \list + \o Without any caching, performance may drop significantly. + \o If you modify a primary key, the record might slip through + your fingers while you are trying to populate it. + \endlist + + \section2 The SQL Relational Table Model + + QSqlRelationalTableModel extends QSqlTableModel to provide + support for foreign keys. A foreign key is a 1-to-1 mapping + between a field in one table and the primary key field of another + table. For example, if a \c book table has a field called \c + authorid that refers to the author table's \c id field, we say + that \c authorid is a foreign key. + + \table + \row \o \inlineimage noforeignkeys.png + \o \inlineimage foreignkeys.png + \endtable + + The screenshot on the left shows a plain QSqlTableModel in a + QTableView. Foreign keys (\c city and \c country) aren't resolved + to human-readable values. The screenshot on the right shows a + QSqlRelationalTableModel, with foreign keys resolved into + human-readable text strings. + + The following code snippet shows how the QSqlRelationalTableModel + was set up: + + \snippet examples/sql/relationaltablemodel/relationaltablemodel.cpp 0 + \codeline + \snippet examples/sql/relationaltablemodel/relationaltablemodel.cpp 1 + \snippet examples/sql/relationaltablemodel/relationaltablemodel.cpp 2 + + See the QSqlRelationalTableModel documentation for details. +*/ + +/*! + \page sql-presenting.html + \title Presenting Data in a Table View + \ingroup qt-sql + + \previouspage Using the SQL Model Classes + \contentspage SQL Programming + \nextpage Creating Data-Aware Forms + + The QSqlQueryModel, QSqlTableModel, and QSqlRelationalTableModel + classes can be used as a data source for Qt's view classes such + as QListView, QTableView, and QTreeView. In practice, QTableView + is by far the most common choice, because an SQL result set is + essentially a two-dimensional data structure. + + \image relationaltable.png A table view displaying a QSqlTableModel + + The following example creates a view based on an SQL data model: + + \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 17 + \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 18 + \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 19 + + If the model is a read-write model (e.g., QSqlTableModel), the + view lets the user edit the fields. You can disable this by + calling + + \snippet doc/src/snippets/sqldatabase/sqldatabase.cpp 20 + + You can use the same model as a data source for multiple views. + If the user edits the model through one of the views, the other + views will reflect the changes immediately. The + \l{sql/tablemodel}{Table Model} example shows how it works. + + View classes display a header at the top to label the columns. To + change the header texts, call + \l{QAbstractItemModel::setHeaderData()}{setHeaderData()} on the + model. The header's labels default to the table's field names. + For example: + + \snippet examples/sql/relationaltablemodel/relationaltablemodel.cpp 3 + + QTableView also has a vertical header on the left with numbers + identifying the rows. If you insert rows programmatically using + QSqlTableModel::insertRows(), the new rows will be marked with an + asterisk (*) until they are submitted using + \l{QSqlTableModel::submitAll()}{submitAll()} or automatically + when the user moves to another record (assuming the + \l{QSqlTableModel::EditStrategy}{edit strategy} is + QSqlTableModel::OnRowChange). + + \image insertrowinmodelview.png Inserting a row in a model + + Likewise, if you remove rows using + \l{QSqlTableModel::removeRows()}{removeRows()}, the rows will be + marked with an exclamation mark (!) until the change is + submitted. + + The items in the view are rendered using a delegate. The default + delegate, QItemDelegate, handles the most common data types (\c + int, QString, QImage, etc.). The delegate is also responsible for + providing editor widgets (e.g., a combobox) when the user starts + editing an item in the view. You can create your own delegates by + subclassing QAbstractItemDelegate or QItemDelegate. See + \l{Model/View Programming} for more information. + + QSqlTableModel is optimized to operate on a single table at a + time. If you need a read-write model that operates on an + arbitrary result set, you can subclass QSqlQueryModel and + reimplement \l{QAbstractItemModel::flags()}{flags()} and + \l{QAbstractItemModel::setData()}{setData()} to make it + read-write. The following two functions make fields 1 and 2 of a + query model editable: + + \snippet examples/sql/querymodel/editablesqlmodel.cpp 0 + \codeline + \snippet examples/sql/querymodel/editablesqlmodel.cpp 1 + + The setFirstName() helper function is defined as follows: + + \snippet examples/sql/querymodel/editablesqlmodel.cpp 2 + + The setLastName() function is similar. See the + \l{sql/querymodel}{Query Model} example for the complete source code. + + Subclassing a model makes it possible to customize it in many + ways: You can provide tooltips for the items, change the + background color, provide calculated values, provide different + values for viewing and editing, handle null values specially, and + more. See \l{Model/View Programming} as well as the \l + QAbstractItemView reference documentation for details. + + If all you need is to resolve a foreign key to a more + human-friendly string, you can use QSqlRelationalTableModel. For + best results, you should also use QSqlRelationalDelegate, a + delegate that provides combobox editors for editing foreign keys. + + \image relationaltable.png Editing a foreign key in a relational table + + The \l{sql/relationaltablemodel}{Relational Table Model} example + illustrates how to use QSqlRelationalTableModel in conjunction with + QSqlRelationalDelegate to provide tables with foreign key + support. +*/ + +/*! + \page sql-forms.html + \title Creating Data-Aware Forms + \ingroup qt-sql + + \previouspage Presenting Data in a Table View + \contentspage SQL Programming + + Using the SQL models described above, the contents of a database can + be presented to other model/view components. For some applications, + it is sufficient to present this data using a standard item view, + such as QTableView. However, users of record-based applications often + require a form-based user interface in which data from a specific + row or column in a database table is used to populate editor widgets + on a form. + + Such data-aware forms can be created with the QDataWidgetMapper class, + a generic model/view component that is used to map data from a model + to specific widgets in a user interface. + + QDataWidgetMapper operates on a specific database table, mapping items + in the table on a row-by-row or column-by-column basis. As a result, + using QDataWidgetMapper with a SQL model is as simple as using it with + any other table model. + + \image qdatawidgetmapper-simple.png + + The \l{demos/books}{Books} demonstration shows how information can + be presented for easy access by using QDataWidgetMapper and a set of + simple input widgets. +*/ diff --git a/doc/src/tutorials/addressbook-fr.qdoc b/doc/src/tutorials/addressbook-fr.qdoc new file mode 100644 index 0000000000..7badaeffde --- /dev/null +++ b/doc/src/tutorials/addressbook-fr.qdoc @@ -0,0 +1,1036 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page tutorials-addressbook-fr.html + + \title Tutoriel "Carnet d'adresses" + \brief Une introduction à la programation d'interface graphique montrant comment construire une application simple avec Qt. + + Ce tutoriel est une introduction à la programmation de GUI (interface utilisateur) + à l'aide des outils fournis par la plateforme multiplate-forme Qt. + + \image addressbook-tutorial-screenshot.png + + Ce tutoriel va nous amener à découvrir quelques technologies fondamentales fournies + par Qt, tel que: + + \list + \o Les Widgets et leur mise en page à l'aide des layouts + \o Les signaux et slots + \o Les structures de données de collections + \o Les entrées/sorties + \endlist + + Si c'est votre premier contact avec Qt, lisez \l{How to Learn Qt}{Comment apprendre Qt} + si ce n'est déjà fait. + + Le code source du tutoriel est distribué avec Qt dans le dossier \c examples/tutorials/addressbook + + Les chapitres du tutoriel: + + \list 1 + \o \l{tutorials/addressbook-fr/part1}{Conception de l'interface utilisateur} + \o \l{tutorials/addressbook-fr/part2}{Ajouter des adresses} + \o \l{tutorials/addressbook-fr/part3}{Navigation entre les éléments} + \o \l{tutorials/addressbook-fr/part4}{éditer et supprimer des adresses} + \o \l{tutorials/addressbook-fr/part5}{Ajout d'une fonction de recherche} + \o \l{tutorials/addressbook-fr/part6}{Sauvegarde et chargement} + \o \l{tutorials/addressbook-fr/part7}{Fonctionnalités avancées} + \endlist + + La petite application que nous développerons ici ne possède pas tous les éléments + des interfaces dernier cri, elle va nous permettre d'utiliser les techniques de base + utilisées dans les applications plus complexes. + + Lorsque vous aurez terminé ce tutoriel, nous vous recommandons de poursuivre avec l'exemple + "\l{mainwindows/application}{Application}", qui présente une interface simple utilisant + les menus et barres d'outils, la barre d'état, etc. + +*/ + +/*! + \page tutorials-addressbook-fr-part1.html + + \example tutorials/addressbook-fr/part1 + \title Carnet d'adresses 1 - Conception de l'interface utilisateur + + La première partie de ce tutoriel traite de la conception d'une interface graphique + (GUI) basique, que l'on utilisera pour l'application Carnet d'adresses. + + La première étape dans la création d'applications graphiques est la conception de + l'interface utilisateur. Dans ce chapitre, nous verrons comment créer les labels + et champs de saisie nécessaires à l'implementation d'un carnet d'adresses de base. + Le résultat attendu est illustré par la capture d'écran ci-dessous. + + \image addressbook-tutorial-part1-screenshot.png + + Nous allons avoir besoin de deux objets QLabel, \c nameLabel et \c addressLabel, + ainsi que deux champs de saisie: un objet QLineEdit, \c nameLine, et un objet + QTextEdit, \c addressText, afin de permettre à l'utilisateur d'entrer le nom d'un + contact et son adresse. Les widgets utilisés ainsi que leur placement sont visibles ci-dessous. + + \image addressbook-tutorial-part1-labeled-screenshot.png + + Trois fichiers sont nécessaires à l'implémentation de ce carnet d'adresses: + + \list + \o \c{addressbook.h} - le fichier de définition (header) pour la classe \c AddressBook, + \o \c{addressbook.cpp} - le fichier source, qui comprend l'implémentation de la classe + \c AddressBook + \o \c{main.cpp} - le fichier qui contient la méthode \c main() , et + une instance de la classe \c AddressBook. + \endlist + + \section1 Programmation en Qt - héritage + + + Lorsque l'on écrit des programmes avec Qt, on a généralement recours à + l'héritage depuis des objets Qt, afin d'y ajouter des fonctionnalités. + C'est l'un des concepts fondamentaux de la création de widgets personnalisés + ou de collections de widgets. Utiliser l'héritage afin de compléter + ou modifier le comportement d'un widget présente les avantages suivants: + + \list + \o La possibilité d'implémenter des méthodes virtuelles et des méthodes + virtuelles pures pour obtenir exactement ce que l'on souhaite, avec la possibilité + d'utiliser l'implémentation de la classe mère si besoin est. + \o Cela permet l'encapsulation partielle de l'interface utilisateur dans une classe, + afin que les autres parties de l'application n'aient pas à se soucier de chacun des + widgets qui forment l'interface utilisateur. + \o La classe fille peut être utilisée pour créer de nombreux widgets personnalisés + dans une même application ou bibliothèque, et le code de la classe fille peut être + réutilisé dans d'autres projets + \endlist + + Comme Qt ne fournit pas de widget standard pour un carnet d'adresses, nous + partirons d'une classe de widget Qt standard et y ajouterons des fonctionnalités. + La classe \c AddressBook crée dans ce tutoriel peut être réutilisée si on a besoin d'un + widget carnet d'adresses basique. + + + \section1 La classe AddressBook + + Le fichier \l{tutorials/addressbook-fr/part1/addressbook.h}{\c addressbook.h} permet de + définir la classe \c AddressBook. + + On commence par définir \c AddressBook comme une classe fille de QWidget et déclarer + un constructeur. On utilise également la macro Q_OBJECT pour indiquer que la classe + exploite les fonctionnalités de signaux et slots offertes par Qt ainsi que + l'internationalisation, bien que nous ne les utilisions pas à ce stade. + + \snippet tutorials/addressbook-fr/part1/addressbook.h class definition + + La classe contient les déclarations de \c nameLine et \c addressText, + les instances privées de QLineEdit et QTextEdit mentionnées précédemment. + Vous verrez, dans les chapitres à venir que les informations contenues + dans \c nameLine et \c addressText sont nécessaires à de nombreuses méthodes + du carnet d'adresses. + + Il n'est pas nécessaire de déclarer les objets QLabel que nous allons utiliser + puisque nous n'aurons pas besoin d'y faire référence après leur création. + La façon dont Qt gère la parenté des objets est traitée dans la section suivante. + + La macro Q_OBJECT implémente des fonctionnalités parmi les plus avancées de Qt. + Pour le moment, il est bon de voir la macro Q_OBJECT comme un raccourci nous + permettant d'utiliser les méthodes \l{QObject::}{tr()} et \l{QObject::}{connect()}. + + Nous en avons maintenant terminé avec le fichier \c addressbook.h et allons + passer à l'implémentation du fichier \c addressbook.cpp. + + \section1 Implémentation de la classe AddressBook + + Le constructeur de la classe \c{AddressBook} prend en paramètre un QWidget, \e parent. + Par convention, on passe ce paramètre au constructeur de la classe mère. + Ce concept de parenté, où un parent peut avoir un ou plusieurs enfants, est utile + pour regrouper les Widgets avec Qt. Par exemple, si vous détruisez le parent, + tous ses enfants seront détruits égalament. + + + \snippet tutorials/addressbook/part1/addressbook.cpp constructor and input fields + + à l'intérieur de ce constructeur, on déclare et instancie deux objets locaux + QLabel, \c nameLabel et \c addressLabel, de même on instancie \c nameLine et + \c addressText. La méthode \l{QObject::tr()}{tr()} renvoie une version traduite + de la chaîne de caractères, si elle existe; dans le cas contraire, elle renvoie + la chaîne elle même. On peut voir cette méthode comme un marqueur \tt{<insérer + la traduction ici>}, permettant de repérer les objets QString à considérer + pour traduire une application. Vous remarquerez, dans les chapitres à venir + comme dans les \l{Qt Examples}{exemples Qt}, qu'elle est utilisée chaque fois + que l'on utilise une chaîne susceptible d'être traduite. + + Lorsque l'on programme avec Qt, il est utile de savoir comment fonctionnent les + agencements ou layouts. Qt fournit trois classes principales de layouts pour + contrôler le placement des widgets: QHBoxLayout, QVBoxLayout et QGridLayout. + + \image addressbook-tutorial-part1-labeled-layout.png + + On utilise un QGridLayout pour positionner nos labels et champs de saisie de manière + structurée. QGridLayout divise l'espace disponible en une grille, et place les + widgets dans les cellules que l'on spécifie par les numéros de ligne et de colonne. + Le diagramme ci-dessus présente les cellules et la position des widgets, et cette + organisation est obtenue à l'aide du code suivant: + + \snippet tutorials/addressbook/part1/addressbook.cpp layout + + On remarque que le label \c AddressLabel est positionné en utilisant Qt::AlignTop + comme argument optionnel. Ceci est destiné à assurer qu'il ne sera pas centré + verticalement dans la cellule (1,0). Pour un aperçu rapide des layouts de Qt, + consultez la section \l{Layout Management}. + + Afin d'installer l'objet layout dans un widget, il faut appeler la méthode + \l{QWidget::setLayout()}{setLayout()} du widget en question: + + \snippet tutorials/addressbook/part1/addressbook.cpp setting the layout + + Enfin, on initialise le titre du widget à "Simple Address Book" + + \section1 Exécution de l'application + + Un fichier séparé, \c main.cpp, est utilisé pour la méthode \c main(). Dans cette + fonction, on crée une instance de QApplication, \c app. QApplication se charge de + des ressources communes à l'ensemble de l'application, tel que les polices de + caractères et le curseur par défaut, ainsi que de l'exécution de la boucle d'évènements. + De ce fait, il y a toujours un objet QApplication dans toute application graphique en Qt. + + \snippet tutorials/addressbook/part1/main.cpp main function + + On construit un nouveau widget \c AddressBook sur la pile et on invoque + sa méthode \l{QWidget::show()}{show()} pour l'afficher. + Cependant, le widget ne sera pas visible tant que la boucle d'évènements + n'aura pas été lancée. On démarre la boucle d'évènements en appelant la + méthode \l{QApplication::}{exec()} de l'application; le résultat renvoyé + par cette méthode est lui même utilisé comme valeur de retour pour la méthode + \c main(). + On comprend maintenant pourquoi \c AddressBook a été créé sur la pile: à la fin + du programme, l'objet sort du scope de la fonction \c main() et tous ses widgets enfants + sont supprimés, assurant ainsi qu'il n'y aura pas de fuites de mémoire. +*/ + +/*! + \page tutorials-addressbook-fr-part2.html + + \example tutorials/addressbook-fr/part2 + \title Carnet d'adresses 2 - Ajouter des adresses + + La prochaine étape pour créer notre carnet d'adresses est d'ajouter un soupçon + d'interactivité. + + \image addressbook-tutorial-part2-add-contact.png + + Nous allons fournir un bouton que l'utilisateur peut + cliquer pour ajouter un nouveau contact. Une structure de données est aussi + nécessaire afin de pouvoir stocker les contacts en mémoire. + + \section1 Définition de la classe AddressBook + + Maintenant que nous avons mis en place les labels et les champs de saisie, + nous ajoutons les boutons pour compléter le processus d'ajout d'un contact. + Cela veut dire que notre fichier \c addressbook.h a maintenant trois + objets QPushButton et trois slots publics correspondant. + + \snippet tutorials/addressbook/part2/addressbook.h slots + + Un slot est une méthode qui répond à un signal. Nous allons + voir ce concept en détail lorsque nous implémenterons la classe \c{AddressBook}. + Pour une explication détaillée du concept de signal et slot, vous pouvez + vous référer au document \l{Signals and Slots}. + + Les trois objets QPushButton \c addButton, \c submitButton et \c cancelButton + sont maintenant inclus dans la déclaration des variables privées, avec + \c nameLine et \c addressText du chapitre précédent. + + \snippet tutorials/addressbook/part2/addressbook.h pushbutton declaration + + Nous avons besoin d'un conteneur pour stocker les contacts du carnet + d'adresses, de façon à pouvoir les énumérer et les afficher. + Un objet QMap, \c contacts, est utilisé pour ça, car il permet de stocker + des paires clé-valeur: le nom du contact est la \e{clé} et l'adresse du contact + est la \e{valeur}. + + \snippet tutorials/addressbook/part2/addressbook.h remaining private variables + + Nous déclarons aussi deux objects QString privés: \c oldName et \c oldAddress. + Ces objets sont nécessaires pour conserver le nom et l'adresse du dernier contact + affiché avant que l'utilisateur ne clique sur le bouton "Add". Grâce à ces variables + si l'utilisateur clique sur "Cancel", il est possible de revenir + à l'affichage du dernier contact. + + \section1 Implémentation de la classe AddressBook + + Dans le constructeur de \c AddressBook, \c nameLine et + \c addressText sont mis en mode lecture seule, de façon à autoriser l'affichage + mais pas la modification du contact courant. + + \dots + \snippet tutorials/addressbook/part2/addressbook.cpp setting readonly 1 + \dots + \snippet tutorials/addressbook/part2/addressbook.cpp setting readonly 2 + + Ensuite, nous instancions les boutons \c addButton, \c submitButton, et + \c cancelButton. + + \snippet tutorials/addressbook/part2/addressbook.cpp pushbutton declaration + + Le bouton \c addButton est affiché en invoquant la méthode \l{QPushButton::show()} + {show()}, tandis que \c submitButton et \c cancelButton sont cachés en invoquant + \l{QPushButton::hide()}{hide()}. Ces deux boutons ne seront affichés que lorsque + l'utilisateur cliquera sur "Add", et ceci est géré par la méthode \c addContact() + décrite plus loin. + + \snippet tutorials/addressbook/part2/addressbook.cpp connecting signals and slots + + Nous connectons le signal \l{QPushButton::clicked()}{clicked()} de chaque bouton + au slot qui gèrera l'action. + L'image ci-dessous illustre ceci: + + \image addressbook-tutorial-part2-signals-and-slots.png + + Ensuite, nous arrangeons proprement les boutons sur la droite du widget + AddressBook, et nous utilisons un QVBoxLayout pour les aligner verticalement. + + \snippet tutorials/addressbook/part2/addressbook.cpp vertical layout + + La methode \l{QBoxLayout::addStretch()}{addStretch()} est utilisée pour + assurer que les boutons ne sont pas répartis uniformément, mais regroupés + dans la partie supperieure du widget. La figure ci-dessous montre la différence + si \l{QBoxLayout::addStretch()}{addStretch()} est utilisé ou pas. + + \image addressbook-tutorial-part2-stretch-effects.png + + Ensuite nous ajoutons \c buttonLayout1 à \c mainLayout, en utilisant + \l{QGridLayout::addLayout()}{addLayout()}. Ceci nous permet d'imbriquer les + mises en page puisque \c buttonLayout1 est maintenant un enfant de \c mainLayout. + + \snippet tutorials/addressbook/part2/addressbook.cpp grid layout + + Les coordonnées du layout global ressemblent maintenant à ça: + + \image addressbook-tutorial-part2-labeled-layout.png + + Dans la méthode \c addContact(), nous stockons les détails du dernier + contact affiché dans \c oldName et \c oldAddress. Ensuite, nous + vidons ces champs de saisie et nous désactivons le mode + lecture seule. Le focus est placé sur \c nameLine et on affiche + \c submitButton et \c cancelButton. + + \snippet tutorials/addressbook/part2/addressbook.cpp addContact + + La méthode \c submitContact() peut être divisée en trois parties: + + \list 1 + \o Nous extrayons les détails du contact depuis \c nameLine et \c addressText + et les stockons dans des objets QString. Nous les validons pour s'assurer + que l'utilisateur n'a pas cliqué sur "Add" avec des champs de saisie + vides; sinon un message est affiché avec QMessageBox pour rappeller à + l'utilisateur que les deux champs doivent être complétés. + + \snippet tutorials/addressbook/part2/addressbook.cpp submitContact part1 + + \o Ensuite, nous vérifions si le contact existe déjà . Si aucun contacts + existant n'entre en conflit avec le nouveau, nous l'ajoutons à + \c contacts et nous affichons un QMessageBox pour informer l'utilisateur + que le contact a été ajouté. + + \snippet tutorials/addressbook/part2/addressbook.cpp submitContact part2 + + Si le contact existe déjà , nous affichons un QMessageBox pour informer + l'utilisateur du problème. + Notre objet \c contacts est basé sur des paires clé-valeur formés par + le nom et l'adresse, nous voulons nous assurer que la \e clé est unique. + + \o Une fois que les deux vérifications précédentes ont été traitées, + nous restaurons les boutons à leur état normal à l'aide du code + suivant: + + \snippet tutorials/addressbook/part2/addressbook.cpp submitContact part3 + + \endlist + + La capture d'écran ci-dessous montre l'affichage fournit par un objet + QMessageBox, utilisé ici pour afficher un message d'information + à l'utilisateur: + + \image addressbook-tutorial-part2-add-successful.png + + La méthode \c cancel() restaure les détails du dernier contact, active + \c addButton, et cache \c submitButton et \c cancelButton. + + \snippet tutorials/addressbook/part2/addressbook.cpp cancel + + L'idée générale pour augmenter la flexibilité lors de l'ajout d'un + contact est de donner la possiblité de cliquer sur "Add" + ou "Cancel" à n'importe quel moment. + L'organigramme ci-dessous reprend l'ensemble des interactions dévelopées + jusqu'ici: + + \image addressbook-tutorial-part2-add-flowchart.png +*/ + +/*! + \page tutorials-addressbook-fr-part3.html + + \example tutorials/addressbook-fr/part3 + \title Carnet d'adresses 3 - Navigation entre les éléments + + L'application "Carnet d'adresses" est maintenant à moitié terminée. Il + nous faut maintenant ajouter quelques fonctions pour naviguer entre + les contacts. Avant de commencer, il faut se décider sur le type de structure de + données le plus approprié pour stocker les contacts. + + Dans le chapitre 2, nous avons utilisé un QMap utilisant des paires clé-valeur, + avec le nom du contact comme \e clé, et l'adresse du contact comme \e valeur. + Cela fonctionnait bien jusqu'ici, mais pour ajouter la navigation entre les + entrées, quelques améliorations sont nécessaires. + + Nous améliorerons le QMap en le faisant ressembler à une structure de données + similaire à une liste liée, où tous les éléments sont connectés, y compris + le premier et le dernier élément. La figure ci-dessous illustre cette structure + de donnée. + + \image addressbook-tutorial-part3-linkedlist.png + + \section1 Définition de la classe AddressBook + + Pour ajouter les fonctions de navigation au carnet d'adresses, nous avons + besoin de deux slots supplémentaires dans notre classe \c AddressBook: + \c next() et \c previous(). Ceux-ci sont ajoutés au fichier addressbook.h: + + \snippet tutorials/addressbook/part3/addressbook.h navigation functions + + Nous avons aussi besoin de deux nouveaux objets QPushButton, nous ajoutons + donc les variables privées \c nextButton et \c previousButton. + + \snippet tutorials/addressbook/part3/addressbook.h navigation pushbuttons + + \section1 Implémentation de la classe AddressBook + + A l'intérieur du constructeur de \c AddressBook, dans \c addressbook.cpp, nous + instancions \c nextButton et \c previousButton et nous les désactivons + par défaut. Nous faisons ceci car la navigation ne doit être activée + que lorsqu'il y a plus d'un contact dans le carnet d'adresses. + + \snippet tutorials/addressbook/part3/addressbook.cpp navigation pushbuttons + + Nous connectons alors ces boutons à leur slots respectifs: + + \snippet tutorials/addressbook/part3/addressbook.cpp connecting navigation signals + + L'image ci-dessous montre l'interface utilisateur que nous allons créer. + Remarquez que cela ressemble de plus en plus à l'interface du programme + complet. + + \image addressbook-tutorial-part3-screenshot.png + + Nous suivons les conventions pour les fonctions \c next() et \c previous() + en plaçant \c nextButton à droite et \c previousButton à gauche. Pour + faire cette mise en page intuitive, nous utilisons un QHBoxLayout pour + placer les widgets côte à côte: + + \snippet tutorials/addressbook/part3/addressbook.cpp navigation layout + + L'objet QHBoxLayout, \c buttonLayout2, est ensuite ajouté à \c mainLayout. + + \snippet tutorials/addressbook/part3/addressbook.cpp adding navigation layout + + La figure ci-dessous montre les systèmes de coordonnées pour les widgets du + \c mainLayout. + \image addressbook-tutorial-part3-labeled-layout.png + + Dans notre méthode \c addContact(), nous avons desactivé ces boutons + pour être sûr que l'utilisateur n'utilise pas la navigation lors de + l'ajout d'un contact. + + \snippet tutorials/addressbook/part3/addressbook.cpp disabling navigation + + Dans notre méthode \c submitContact(), nous activons les boutons de + navigation, \c nextButton et \c previousButton, en fonction de la + taille de \c contacts. Commen mentionné plus tôt, la navigation n'est + activée que si il y a plus d'un contact dans le carnet d'adresses. + Les lignes suivantes montrent comment faire cela: + + \snippet tutorials/addressbook/part3/addressbook.cpp enabling navigation + + Nous incluons aussi ces lignes de code dans le bouton \c cancel(). + + Souvenez vous que nous voulons émuler une liste-liée ciruculaire à + l'aide de l'objet QMap, \c contacts. Pour faire cela, nous obtenons un itérateur + sur \c contact dans la méthode \c next(), et ensuite: + + \list + \o Si l'itérateur n'est pas à la fin de \c contacts, nous l'incrémentons + \o Si l'itérateur est à la fin de \c contacts, nous changeons sa position + jusqu'au début de \c contacts. Cela donne l'illusion que notre QMap + fonctionne comme une liste circulaire. + \endlist + + \snippet tutorials/addressbook/part3/addressbook.cpp next() function + + Une fois que nous avons itéré jusqu'à l'objet recherché dans \c contacts, + nous affichons son contenu sur \c nameLine et \c addressText. + + De la même façon, pour la méthode \c previous(), nous obtenons un + itérateur sur \c contacts et ensuite: + + \list + \o Si l'itérateur est à la fin de \c contacts, on réinitialise + l'affichage et on retourne. + \o Si l'itérateur est au début de \c contacts, on change sa + position jusqu'à la fin + \o Ensuite, on décrémente l'itérateur + \endlist + + \snippet tutorials/addressbook/part3/addressbook.cpp previous() function + + à nouveau, nous affichons le contenu de l'objet courant dans \c contacts. + +*/ + +/*! + + \page tutorials-addressbook-fr-part4.html + + \example tutorials/addressbook-fr/part4 + \title Carnet d'Adresses 4 - éditer et supprimer des adresses + + + Dans ce chapitre, nous verrons comment modifier les données des contacts + contenus dans l'application carnet d'adresses. + + + \image addressbook-tutorial-screenshot.png + + Nous avons maintenant un carnet d'adresses qui ne se contente pas de + lister des contacts de façon ordonnée, mais permet également la + navigation. Il serait pratique d'inclure des fonctions telles qu'éditer et + supprimer, afin que les détails associés à un contact puissent être + modifiés lorsque c'est nécessaire. Cependant, cela requiert une légère + modification, sous la forme d'énumérations. Au chapitre précédent, nous avions deux + modes: \c {AddingMode} et \c {NavigationMode}, mais ils n'étaient pas + définis en tant qu'énumérations. Au lieu de ça, on activait et désactivait les + boutons correspondants manuellement, au prix de multiples redondances dans + le code. + + Dans ce chapitre, on définit l'énumération \c Mode avec trois valeurs possibles. + + \list + \o \c{NavigationMode}, + \o \c{AddingMode}, et + \o \c{EditingMode}. + \endlist + + \section1 Définition de la classe AddressBook + + Le fichier \c addressbook.h est mis a jour pour contenir l'énumération \c Mode : + + \snippet tutorials/addressbook/part4/addressbook.h Mode enum + + On ajoute également deux nouveaux slots, \c editContact() et + \c removeContact(), à notre liste de slots publics. + + \snippet tutorials/addressbook/part4/addressbook.h edit and remove slots + + Afin de basculer d'un mode à l'autre, on introduit la méthode + \c updateInterface() pour contrôller l'activation et la désactivation de + tous les objets QPushButton. On ajoute également deux nouveaux boutons, + \c editButton et \c removeButton, pour les fonctions d'édition + et de suppression mentionnées plus haut. + + \snippet tutorials/addressbook/part4/addressbook.h updateInterface() declaration + \dots + \snippet tutorials/addressbook/part4/addressbook.h buttons declaration + \dots + \snippet tutorials/addressbook/part4/addressbook.h mode declaration + + Enfin, on déclare \c currentMode pour garder une trace du mode + actuellement utilisé. + + \section1 Implémentation de la classe AddressBook + + Il nous faut maintenant implémenter les fonctionnalités de changement de + mode de l'application carnet d'adresses. Les boutons \c editButton et + \c removeButton sont instanciés et désactivés par défaut, puisque le + carnet d'adresses démarre sans aucun contact en mémoire. + + \snippet tutorials/addressbook/part4/addressbook.cpp edit and remove buttons + + Ces boutons sont ensuite connectés à leurs slots respectifs, + \c editContact() et \c removeContact(), avant d'être ajoutés à + \c buttonLayout1. + + \snippet tutorials/addressbook/part4/addressbook.cpp connecting edit and remove + \dots + \snippet tutorials/addressbook/part4/addressbook.cpp adding edit and remove to the layout + + La methode \c editContact() place les anciens détails du contact dans + \c oldName et \c oldAddress, avant de basculer vers le mode + \c EditingMode. Dans ce mode, les boutons \c submitButton et + \c cancelButton sont tous deux activés, l'utilisateur peut par conséquent + modifier les détails du contact et cliquer sur l'un de ces deux boutons + par la suite. + + \snippet tutorials/addressbook/part4/addressbook.cpp editContact() function + + La méthode \c submitContact() a été divisée en deux avec un bloc + \c{if-else}. On teste \c currentMode pour voir si le mode courant est + \c AddingMode. Si c'est le cas, on procède à l'ajout. + + \snippet tutorials/addressbook/part4/addressbook.cpp submitContact() function beginning + \dots + \snippet tutorials/addressbook/part4/addressbook.cpp submitContact() function part1 + + Sinon, on s'assure que \c currentMode est en \c EditingMode. Si c'est le + cas, on compare \c oldName et \c name. Si le nom a changé, on supprime + l'ancien contact de \c contacts et on insère le contact mis a jour. + + \snippet tutorials/addressbook/part4/addressbook.cpp submitContact() function part2 + + Si seule l'adresse a changé (i.e. \c oldAddress n'est pas identique à + \c address), on met à jour l'adresse du contact. Enfin on règle + \c currentMode à \c NavigationMode. C'est une étape importante puisque + c'est cela qui réactive tous les boutons désactivés. + + Afin de retirer un contact du carnet d'adresses, on implémente la méthode + \c removeContact(). Cette méthode vérifie que le contact est présent dans + \c contacts. + + \snippet tutorials/addressbook/part4/addressbook.cpp removeContact() function + + Si c'est le cas, on affiche une boîte de dialogue QMessageBox, demandant + confirmation de la suppression à l'utilisateur. Une fois la confirmation + effectuée, on appelle \c previous(), afin de s'assurer que l'interface + utilisateur affiche une autre entrée, et on supprime le contact en + utilisant le méthode \l{QMap::remove()}{remove()} de \l{QMap}. Dans un + souci pratique, on informe l'utilisateur de la suppression par le biais + d'une autre QMessageBox. Les deux boîtes de dialogue utilisées dans cette + méthode sont représentées ci-dessous. + + \image addressbook-tutorial-part4-remove.png + + \section2 Mise à jour de l'Interface utilisateur + + On a évoqué plus haut la méthode \c updateInterface() comme moyen + d'activer et de désactiver les différents boutons de l'interface en + fonction du mode. Cette méthode met à jour le mode courant selon + l'argument \c mode qui lui est passé, en l'assignant à \c currentMode, + avant de tester sa valeur. + + Chacun des boutons est ensuite activé ou désactivé, en fonction du mode. + Le code source pour les cas \c AddingMode et \c EditingMode est visible + ci-dessous: + + \snippet tutorials/addressbook/part4/addressbook.cpp update interface() part 1 + + Dans le cas de \c NavigationMode, en revanche, des tests conditionnels + sont passés en paramètre de QPushButton::setEnabled(). Ceci permet de + s'assurer que les boutons \c editButton et \c removeButton ne sont activés + que s'il existe au moins un contact dans le carnet d'adresses; + \c nextButton et \c previousButton ne sont activés que lorsqu'il existe + plus d'un contact dans le carnet d'adresses. + + \snippet tutorials/addressbook/part4/addressbook.cpp update interface() part 2 + + En effectuant les opérations de réglage du mode et de mise à jour de + l'interface utilisateur au sein de la même méthode, on est à l'abri de + l'éventualité où l'interface utilisateur se "désynchronise" de l'état + interne de l'application. + +*/ + +/*! + \page tutorials-addressbook-fr-part5.html + + \example tutorials/addressbook-fr/part5 + \title Carnet d'adresse 5 - Ajout d'une fonction de recherche + + Dans ce chapitre, nous allons voir les possibilités pour rechercher + des contacts dans le carnet d'adresse. + + \image addressbook-tutorial-part5-screenshot.png + + Plus nous ajoutons des contacts dans l'application, plus + il devient difficile de naviguer avec les boutons \e Next et \e Previous. + Dans ce cas, une fonction de recherche serait plus efficace pour rechercher + les contacts. + La capture d'écran ci-dessus montre le bouton de recherche \e Find et sa position + dans le paneau de bouton. + + Lorsque l'utilisateur clique sur le bouton \e Find, il est courant d'afficher + une boîte de dialogue qui demande à l'utilisateur d'entrer un nom de contact. + Qt fournit la classe QDialog, que nous sous-classons dans ce chapitre pour + implémenter la class \c FindDialog. + + \section1 Définition de la classe FindDialog + + \image addressbook-tutorial-part5-finddialog.png + + Pour sous-classer QDialog, nous commençons par inclure le header de + QDialog dans le fichier \c finddialog.h. De plus, nous déclarons les + classes QLineEdit et QPushButton car nous utilisons ces widgets dans + notre classe dialogue. + + Tout comme dans la classe \c AddressBook, la classe \c FindDialog utilise + la macro Q_OBJECT et son constructeur est défini de façon à accepter + un QWidget parent, même si cette boîte de dialogue sera affichée dans une + fenêtre séparée. + + \snippet tutorials/addressbook/part5/finddialog.h FindDialog header + + Nous définissons la méthode publique \c getFindText() pour être utilisée + par les classes qui instancient \c FindDialog, ce qui leur permet d'obtenir + le texte entré par l'utilisateur. Un slot public, \c findClicked(), est + défini pour prendre en charge le texte lorsque l'utilisateur clique sur + le bouton \gui Find. + + Finalement, nous définissons les variables privées \c findButton, + \c lineEdit et \c findText, qui correspondent respectivement au bouton + \gui Find, au champ de texte dans lequel l'utilisateur tape le texte + à rechercher, et à une variable interne stockant le texte pour une + utilisation ultérieure. + + \section1 Implémentation de la classe FindDialog + + Dans le constructeur de \c FindDialog, nous instancions les objets des + variables privées \c lineEdit, \c findButton et \c findText. Nous utilisons ensuite + un QHBoxLayout pour positionner les widgets. + + \snippet tutorials/addressbook/part5/finddialog.cpp constructor + + Nous mettons en place la mise en page et le titre de la fenêtre, et + nous connectons les signaux aux slots. Remarquez que le signal + \l{QPushButton::clicked()}{clicked()} de \c{findButton} est connecté + à \c findClicked() et \l{QDialog::accept()}{accept()}. Le slot + \l{QDialog::accept()}{accept()} fourni par le QDialog ferme + la boîte de dialogue et lui donne le code de retour \l{QDialog::}{Accepted}. + Nous utilisons cette fonction pour aider la méthode \c findContact() de la classe + \c{AddressBook} à savoir si l'objet \c FindDialog a été fermé. Ceci sera + expliqué plus loin lorsque nous verrons la méthode \c findContact(). + + \image addressbook-tutorial-part5-signals-and-slots.png + + Dans \c findClicked(), nous validons le champ de texte pour nous + assurer que l'utilisateur n'a pas cliqué sur le bouton \gui Find sans + avoir entré un nom de contact. Ensuite, nous stockons le texte du champ + d'entrée \c lineEdit dans \c findText. Et finalement nous vidons le + contenu de \c lineEdit et cachons la boîte de dialogue. + + \snippet tutorials/addressbook/part5/finddialog.cpp findClicked() function + + La variable \c findText a un accesseur publique associé: \c getFindText(). + Étant donné que nous ne modifions \c findText directement que dans le + constructeur et la méthode \c findClicked(), nous ne créons pas + de manipulateurs associé à \c getFindText(). + Puisque \c getFindText() est publique, les classes instanciant et + utilisant \c FindDialog peuvent toujours accéder à la chaîne de + caractères que l'utilisateur a entré et accepté. + + \snippet tutorials/addressbook/part5/finddialog.cpp getFindText() function + + \section1 Définition de la classe AddressBook + + Pour utiliser \c FindDialog depuis la classe \c AddressBook, nous + incluons \c finddialog.h dans le fichier \c addressbook.h. + + \snippet tutorials/addressbook/part5/addressbook.h include finddialog's header + + Jusqu'ici, toutes les fonctionnalités du carnet d'adresses ont un + QPushButton et un slot correspondant. De la même façon, pour la + fonctionnalité \gui Find, nous avons \c findButton et \c findContact(). + + Le \c findButton est déclaré comme une variable privée et la + méthode \c findContact() est déclarée comme un slot public. + + \snippet tutorials/addressbook/part5/addressbook.h findContact() declaration + \dots + \snippet tutorials/addressbook/part5/addressbook.h findButton declaration + + Finalement, nous déclarons la variable privée \c dialog que nous allons + utiliser pour accéder à une instance de \c FindDialog. + + \snippet tutorials/addressbook/part5/addressbook.h FindDialog declaration + + Une fois que nous avons instancié la boîte de dialogue, nous voulons l'utiliser + plus qu'une fois. Utiliser une variable privée nous permet d'y référer + à plus d'un endroit dans la classe. + + \section1 Implémentation de la classe AddressBook + + Dans le constructeur de \c AddressBook, nous instancions nos objets privés, + \c findbutton et \c findDialog: + + \snippet tutorials/addressbook/part5/addressbook.cpp instantiating findButton + \dots + \snippet tutorials/addressbook/part5/addressbook.cpp instantiating FindDialog + + Ensuite, nous connectons le signal \l{QPushButton::clicked()}{clicked()} de + \c{findButton} à \c findContact(). + + \snippet tutorials/addressbook/part5/addressbook.cpp signals and slots for find + + Maintenant, tout ce qui manque est le code de notre méthode \c findContact(): + + \snippet tutorials/addressbook/part5/addressbook.cpp findContact() function + + Nous commençons par afficher l'instance de \c FindDialog, \c dialog. + L'utilisateur peut alors entrer le nom du contact à rechercher. Lorsque + l'utilisateur clique sur le bouton \c findButton, la boîte de dialogue est + masquée et le code de retour devient QDialog::Accepted. Ce code de retour + vient remplir la condition du premier if. + + Ensuite, nous extrayons le texte que nous utiliserons pour la recherche, + il s'agit ici de \c contactName obtenu à l'aide de la méthode \c getFindText() + de \c FindDialog. Si le contact existe dans le carnet d'adresse, nous + l'affichons directement. Sinon, nous affichons le QMessageBox suivant pour + indiquer que la recherche à échouée. + + \image addressbook-tutorial-part5-notfound.png +*/ + +/*! + \page tutorials-addressbook-part6.html + + \example tutorials/addressbook-fr/part6 + \title Carnet d'Adresses 6 - Sauvegarde et chargement + + Ce chapitre couvre les fonctionnalités de gestion des fichiers de Qt que + l'on utilise pour écrire les procédures de sauvegarde et chargement pour + l'application carnet d'adresses. + + \image addressbook-tutorial-part6-screenshot.png + + Bien que la navigation et la recherche de contacts soient des + fonctionnalités importantes, notre carnet d'adresses ne sera pleinement + utilisable qu'une fois que l'on pourra sauvegarder les contacts existants + et les charger à nouveau par la suite. + Qt fournit de nombreuses classes pour gérer les \l{Input/Output and + Networking}{entrées et sorties}, mais nous avons choisi de nous contenter d'une + combinaison de deux classes simples à utiliser ensemble: QFile et QDataStream. + + Un objet QFile représente un fichier sur le disque qui peut être lu, et + dans lequel on peut écrire. QFile est une classe fille de la classe plus + générique QIODevice, qui peut représenter différents types de + périphériques. + + Un objet QDataStream est utilisé pour sérialiser des données binaires + dans le but de les passer à un QIODevice pour les récupérer dans le + futur. Pour lire ou écrire dans un QIODevice, il suffit d'ouvrir le + flux, avec le périphérique approprié en paramètre, et d'y lire ou + écrire. + + \section1 Définition de la classe AddressBook + + On déclare deux slots publics, \c saveToFile() et \c loadFromFile(), + ainsi que deux objets QPushButton, \c loadButton et \c saveButton. + + \snippet tutorials/addressbook/part6/addressbook.h save and load functions declaration + \dots + \snippet tutorials/addressbook/part6/addressbook.h save and load buttons declaration + + \section1 Implémentation de la classe AddressBook + + Dans notre constructeur, on instancie \c loadButton et \c saveButton. + Idéalement, l'interface serait plus conviviale avec des boutons + affichant "Load contacts from a file" et "Save contacts to a file". Mais + compte tenu de la dimension des autres boutons, on initialise les labels + des boutons à \gui{Load...} et \gui{Save...}. Heureusement, Qt offre une + façon simple d'ajouter des info-bulles avec + \l{QWidget::setToolTip()}{setToolTip()}, et nous l'exploitons de la façon + suivante pour nos boutons: + + \snippet tutorials/addressbook/part6/addressbook.cpp tooltip 1 + \dots + \snippet tutorials/addressbook/part6/addressbook.cpp tooltip 2 + + Bien qu'on ne cite pas le code correspondant ici, nous ajoutons ces deux boutons au + layout de droite, \c button1Layout, comme pour les fonctionnalités précédentes, et + nous connectons leurs signaux + \l{QPushButton::clicked()}{clicked()} à leurs slots respectifs. + + Pour la sauvegarde, on commence par récupérer le nom de fichier + \c fileName, en utilisant QFileDialog::getSaveFileName(). C'est une + méthode pratique fournie par QFileDialog, qui ouvre une boîte de + dialogue modale et permet à l'utilisateur d'entrer un nom de fichier ou + de choisir un fichier \c{.abk} existant. Les fichiers \c{.abk} + correspondent à l'extension choisie pour la sauvegarde des contacts de + notre carnet d'adresses. + + \snippet tutorials/addressbook/part6/addressbook.cpp saveToFile() function part1 + + La boîte de dialogue affichée est visible sur la capture d'écran ci- + dessous. + + \image addressbook-tutorial-part6-save.png + + Si \c fileName n'est pas vide, on crée un objet QFile, \c file, à partir + de \c fileName. QFile fonctionne avec QDataStream puisqu'il dérive de + QIODevice. + + Ensuite, on essaie d'ouvrir le fichier en écriture, ce qui correspond au + mode \l{QIODevice::}{WriteOnly}. Si cela échoue, on en informe + l'utilisateur avec une QMessageBox. + + \snippet tutorials/addressbook/part6/addressbook.cpp saveToFile() function part2 + + Dans le cas contraire, on instancie un objet QDataStream, \c out, afin + d'écrire dans le fichier ouvert. QDataStream nécessite que la même + version de flux soit utilisée pour la lecture et l'écriture. On s'assure + que c'est le cas en spécifiant explicitement d'utiliser la + \l{QDataStream::Qt_4_5}{version introduite avec Qt 4.5} avant de + sérialiser les données vers le fichier \c file. + + \snippet tutorials/addressbook/part6/addressbook.cpp saveToFile() function part3 + + Pour le chargement, on récupère également \c fileName en utilisant + QFileDialog::getOpenFileName(). Cette méthode est l'homologue de + QFileDialog::getSaveFileName() et affiche également une boîte de + dialogue modale permettant à l'utilisateur d'entrer un nom de fichier ou + de selectionner un fichier \c{.abk} existant, afin de le charger dans le + carnet d'adresses. + + \snippet tutorials/addressbook/part6/addressbook.cpp loadFromFile() function part1 + + Sous Windows, par exemple, cette méthode affiche une boîte de dialogue + native pour la sélection de fichier, comme illustré sur la capture + d'écran suivante: + + \image addressbook-tutorial-part6-load.png + + Si \c fileName n'est pas vide, on utilise une fois de plus un objet + QFile, \c file, et on tente de l'ouvrir en lecture, avec le mode + \l{QIODevice::}{ReadOnly}. De même que précédemment dans notre + implémentation de \c saveToFile(), si cette tentative s'avère + infructueuse, on en informe l'utilisateur par le biais d'une + QMessageBox. + + \snippet tutorials/addressbook/part6/addressbook.cpp loadFromFile() function part2 + + Dans le cas contraire, on instancie un objet QDataStream, \c in, en + spécifiant la version à utiliser comme précédemment, et on lit les + informations sérialisées vers la structure de données \c contacts. Notez + qu'on purge \c contacts avant d'y mettre les informations lues afin de + simplifier le processus de lecture de fichier. Une façon plus avancée de + procéder serait de lire les contacts dans un objet QMap temporaire, et + de copier uniquement les contacts n'existant pas encore dans + \c contacts. + + \snippet tutorials/addressbook/part6/addressbook.cpp loadFromFile() function part3 + + Pour afficher les contacts lus depuis le fichier, on doit d'abord + valider les données obtenues afin de s'assurer que le fichier lu + contient effectivement des entrées de carnet d'adresses. Si c'est le + cas, on affiche le premier contact; sinon on informe l'utilisateur du + problème par une QMessageBox. Enfin, on met à jour l'interface afin + d'activer et de désactiver les boutons de façon appropriée. +*/ + +/*! + \page tutorials-addressbook-fr-part7.html + + \example tutorials/addressbook-fr/part7 + \title Carnet d'adresse 7 - Fonctionnalités avancées + + Ce chapitre couvre quelques fonctionnalités additionnelles qui + feront de notre carnet d'adresses une application plus pratique + pour une utilisation quotidienne. + + \image addressbook-tutorial-part7-screenshot.png + + Bien que notre application carnet d'adresses soit utile en tant que telle, + il serait pratique de pouvoir échanger les contacts avec d'autres applications. + Le format vCard est un un format de fichier populaire pour échanger + ce type de données. + Dans ce chapitre, nous étendrons notre carnet d'adresses pour permettre + d'exporter des contacts dans des fichiers vCard \c{.vcf}. + + \section1 Définition de la classe AddressBook + + Nous ajoutons un objet QPushButton, \c exportButton, et un slot + public correspondant, \c exportAsVCard(), à notre classe \c AddressBook + dans le fichier \c addressbook.h. + + \snippet tutorials/addressbook/part7/addressbook.h exportAsVCard() declaration + \dots + \snippet tutorials/addressbook/part7/addressbook.h exportButton declaration + + \section1 Implémentation de la classe AddressBook + + Dans le constructeur de \c AddressBook, nous connectons le signal + \l{QPushButton::clicked()}{clicked()} de \c{exportButton} au slot + \c exportAsVCard(). + Nous ajoutons aussi ce bouton à \c buttonLayout1, le layout responsable + du groupe de boutons sur la droite. + + Dans la méthode \c exportAsVCard(), nous commençons par extraire le + nom du contact dans \n name. Nous déclarons \c firstname, \c lastName et + \c nameList. + Ensuite, nous cherchons la position du premier espace blanc de \c name. + Si il y a un espace, nous séparons le nom du contact en \c firstName et + \c lastName. Finalement, nous remplaçons l'espace par un underscore ("_"). + Si il n'y a pas d'espace, nous supposons que le contact ne comprend que + le prénom. + + \snippet tutorials/addressbook/part7/addressbook.cpp export function part1 + + Comme pour la méthode \c saveToFile(), nous ouvrons une boîte de dialogue + pour donner la possibilité à l'utilisateur de choisir un emplacement pour + le fichier. Avec le nom de fichier choisi, nous créons une instance de QFile + pour y écrire. + + Nous essayons d'ouvrir le fichier en mode \l{QIODevice::}{WriteOnly}. Si + cela échoue, nous affichons un QMessageBox pour informer l'utilisateur + à propos de l'origine du problème et nous quittons la méthode. Sinon, nous passons le + fichier comme paramètre pour créer un objet QTextStream, \c out. De la même façon que + QDataStream, la classe QTextStream fournit les fonctionnalités pour + lire et écrire des fichiers de texte. Grâce à celà , le fichier \c{.vcf} + généré pourra être ouvert et édité à l'aide d'un simple éditeur de texte. + + \snippet tutorials/addressbook/part7/addressbook.cpp export function part2 + + Nous écrivons ensuite un fichier vCard avec la balise \c{BEGIN:VCARD}, + suivit par \c{VERSION:2.1}. + Le nom d'un contact est écrit à l'aide de la balise \c{N:}. Pour la balise + \c{FN:}, qui remplit le titre du contact, nous devons vérifier si le contact + à un nom de famille défini ou non. Si oui, nous utilions les détails de + \c nameList pour remplir le champ, dans le cas contraire on écrit uniquement le contenu + de \c firstName. + + \snippet tutorials/addressbook/part7/addressbook.cpp export function part3 + + Nous continuons en écrivant l'adresse du contact. Les points-virgules + dans l'adresse sont échappés à l'aide de "\\", les retours de ligne sont + remplacés par des points-virgules, et les vigules sont remplacées par des espaces. + Finalement nous écrivons les balises \c{ADR;HOME:;} suivies par l'adresse + et la balise \c{END:VCARD}. + + \snippet tutorials/addressbook/part7/addressbook.cpp export function part4 + + À la fin de la méthode, un QMessageBox est affiché pour informer l'utilisateur + que la vCard a été exportée avec succès. + + \e{vCard est une marque déposée de \l{http://www.imc.org} + {Internet Mail Consortium}}. +*/ diff --git a/doc/src/tutorials/addressbook.qdoc b/doc/src/tutorials/addressbook.qdoc new file mode 100644 index 0000000000..ec4a4f312c --- /dev/null +++ b/doc/src/tutorials/addressbook.qdoc @@ -0,0 +1,981 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page tutorials-addressbook.html + + \title Address Book Tutorial + \brief An introduction to GUI programming, showing how to put together a + simple yet fully-functioning application. + + This tutorial is an introduction to GUI programming with the Qt + cross-platform framework. + + \image addressbook-tutorial-screenshot.png + + \omit + It doesn't cover everything; the emphasis is on teaching the programming + philosophy of GUI programming, and Qt's features are introduced as needed. + Some commonly used features are never used in this tutorial. + \endomit + + In this tutorial, you will learn about some of the basic + components of Qt, including: + + \list + \o Widgets and layout managers + \o Container classes + \o Signals and slots + \o Input and output devices + \endlist + + If you are new to Qt, we recommend reading \l{How to Learn Qt} first. + + Tutorial contents: + + \list 1 + \o \l{tutorials/addressbook/part1}{Designing the User Interface} + \o \l{tutorials/addressbook/part2}{Adding Addresses} + \o \l{tutorials/addressbook/part3}{Navigating between Entries} + \o \l{tutorials/addressbook/part4}{Editing and Removing Addresses} + \o \l{tutorials/addressbook/part5}{Adding a Find Function} + \o \l{tutorials/addressbook/part6}{Loading and Saving} + \o \l{tutorials/addressbook/part7}{Additional Features} + \endlist + + The tutorial source code is located in \c{examples/tutorials/addressbook}. + + Although this little application does not look much like a + fully-fledged modern GUI application, it uses many of the basic + elements that are used in more complex applications. After you + have worked through this tutorial, we recommend reading the + \l{mainwindows/application}{Application} example, which presents a + small GUI application, with menus, toolbars, a status bar, and so + on. +*/ + +/*! + \page tutorials-addressbook-part1.html + + \example tutorials/addressbook/part1 + \title Part 1 - Designing the User Interface + + This first part covers the design of the basic graphical user + interface (GUI) for our address book application. + + The first step in creating a GUI program is to design the user + interface. Here the our goal is to set up the labels and input + fields to implement a basic address book. The figure below is a + screenshot of the expected output. + + \image addressbook-tutorial-part1-screenshot.png + + We require two QLabel objects, \c nameLabel and \c addressLabel, as well + as two input fields, a QLineEdit object, \c nameLine, and a QTextEdit + object, \c addressText, to enable the user to enter a contact's name and + address. The widgets used and their positions are shown in the figure + below. + + \image addressbook-tutorial-part1-labeled-screenshot.png + + There are three files used to implement this address book: + + \list + \o \c{addressbook.h} - the definition file for the \c AddressBook + class, + \o \c{addressbook.cpp} - the implementation file for the + \c AddressBook class, and + \o \c{main.cpp} - the file containing a \c main() function, with + an instance of \c AddressBook. + \endlist + + \section1 Qt Programming - Subclassing + + When writing Qt programs, we usually subclass Qt objects to add + functionality. This is one of the essential concepts behind creating + custom widgets or collections of standard widgets. Subclassing to + extend or change the behavior of a widget has the following advantages: + + \list + \o We can write implementations of virtual or pure virtual functions to + obtain exactly what we need, falling back on the base class's implementation + when necessary. + \o It allows us to encapsulate parts of the user interface within a class, + so that the other parts of the application don't need to know about the + individual widgets in the user interface. + \o The subclass can be used to create multiple custom widgets in the same + application or library, and the code for the subclass can be reused in other + projects. + \endlist + + Since Qt does not provide a specific address book widget, we subclass a + standard Qt widget class and add features to it. The \c AddressBook class + we create in this tutorial can be reused in situations where a basic address + book widget is needed. + + \section1 Defining the AddressBook Class + + The \l{tutorials/addressbook/part1/addressbook.h}{\c addressbook.h} file is + used to define the \c AddressBook class. + + We start by defining \c AddressBook as a QWidget subclass and declaring + a constructor. We also use the Q_OBJECT macro to indicate that the class + uses internationalization and Qt's signals and slots features, even + if we do not use all of these features at this stage. + + \snippet tutorials/addressbook/part1/addressbook.h class definition + + The class holds declarations of \c nameLine and \c addressText, + the private instances of QLineEdit and QTextEdit mentioned + earlier. The data stored in \c nameLine and \c addressText will + be needed for many of the address book functions. + + We don't include declarations of the QLabel objects we will use + because we will not need to reference them once they have been + created. The way Qt tracks the ownership of objects is explained + in the next section. + + The Q_OBJECT macro itself implements some of the more advanced features of Qt. + For now, it is useful to think of the Q_OBJECT macro as a shortcut which allows + us to use the \l{QObject::}{tr()} and \l{QObject::}{connect()} functions. + + We have now completed the \c addressbook.h file and we move on to + implement the corresponding \c addressbook.cpp file. + + \section1 Implementing the AddressBook Class + + The constructor of \c AddressBook accepts a QWidget parameter, \a parent. + By convention, we pass this parameter to the base class's constructor. + This concept of ownership, where a parent can have one or more children, + is useful for grouping widgets in Qt. For example, if you delete a parent, + all of its children will be deleted as well. + + \snippet tutorials/addressbook/part1/addressbook.cpp constructor and input fields + + In this constructor, the QLabel objects \c nameLabel and \c + addressLabel are instantiated, as well as \c nameLine and \c + addressText. The \l{QObject::tr()}{tr()} function returns a + translated version of the string, if there is one + available. Otherwise it returns the string itself. This function + marks its QString parameter as one that should be translated into + other languages. It should be used wherever a translatable string + appears. + + When programming with Qt, it is useful to know how layouts work. + Qt provides three main layout classes: QHBoxLayout, QVBoxLayout + and QGridLayout to handle the positioning of widgets. + + \image addressbook-tutorial-part1-labeled-layout.png + + We use a QGridLayout to position our labels and input fields in a + structured manner. QGridLayout divides the available space into a grid and + places widgets in the cells we specify with row and column numbers. The + diagram above shows the layout cells and the position of our widgets, and + we specify this arrangement using the following code: + + \snippet tutorials/addressbook/part1/addressbook.cpp layout + + Notice that \c addressLabel is positioned using Qt::AlignTop as an + additional argument. This is to make sure it is not vertically centered in + cell (1,0). For a basic overview on Qt Layouts, refer to the + \l{Layout Management} documentation. + + In order to install the layout object onto the widget, we have to invoke + the widget's \l{QWidget::setLayout()}{setLayout()} function: + + \snippet tutorials/addressbook/part1/addressbook.cpp setting the layout + + Lastly, we set the widget's title to "Simple Address Book". + + \section1 Running the Application + + A separate file, \c main.cpp, is used for the \c main() function. Within + this function, we instantiate a QApplication object, \c app. QApplication + is responsible for various application-wide resources, such as the default + font and cursor, and for running an event loop. Hence, there is always one + QApplication object in every GUI application using Qt. + + \snippet tutorials/addressbook/part1/main.cpp main function + + We construct a new \c AddressBook widget on the stack and invoke + its \l{QWidget::show()}{show()} function to display it. + However, the widget will not be shown until the application's event loop + is started. We start the event loop by calling the application's + \l{QApplication::}{exec()} function; the result returned by this function + is used as the return value from the \c main() function. At this point, + it becomes apparent why we instanciated \c AddressBook on the stack: It + will now go out of scope. Therefore, \c AddressBook and all its child widgets + will be deleted, thus preventing memory leaks. +*/ + +/*! + \page tutorials-addressbook-part2.html + + \example tutorials/addressbook/part2 + \title Part 2 - Adding Addresses + + The next step in creating the address book is to implement some + user interactions. + + \image addressbook-tutorial-part2-add-contact.png + + We will provide a push button that the user can click to add a new contact. + Also, some form of data structure is needed to store these contacts in an + organized way. + + \section1 Defining the AddressBook Class + + Now that we have the labels and input fields set up, we add push buttons to + complete the process of adding a contact. This means that our + \c addressbook.h file now has three QPushButton objects declared and three + corresponding public slots. + + \snippet tutorials/addressbook/part2/addressbook.h slots + + A slot is a function that responds to a particular signal. We will discuss + this concept in further detail when implementing the \c AddressBook class. + However, for an overview of Qt's signals and slots concept, you can refer + to the \l{Signals and Slots} document. + + Three QPushButton objects (\c addButton, \c submitButton, and + \c cancelButton) are now included in our private variable declarations, + along with \c nameLine and \c addressText. + + \snippet tutorials/addressbook/part2/addressbook.h pushbutton declaration + + We need a container to store our address book contacts, so that we can + traverse and display them. A QMap object, \c contacts, is used for this + purpose as it holds a key-value pair: the contact's name as the \e key, + and the contact's address as the \e{value}. + + \snippet tutorials/addressbook/part2/addressbook.h remaining private variables + + We also declare two private QString objects, \c oldName and \c oldAddress. + These objects are needed to hold the name and address of the contact that + was last displayed, before the user clicked \gui Add. So, when the user clicks + \gui Cancel, we can revert to displaying the details of the last contact. + + \section1 Implementing the AddressBook Class + + Within the constructor of \c AddressBook, we set the \c nameLine and + \c addressText to read-only, so that we can only display but not edit + existing contact details. + + \dots + \snippet tutorials/addressbook/part2/addressbook.cpp setting readonly 1 + \dots + \snippet tutorials/addressbook/part2/addressbook.cpp setting readonly 2 + + Then, we instantiate our push buttons: \c addButton, \c submitButton, and + \c cancelButton. + + \snippet tutorials/addressbook/part2/addressbook.cpp pushbutton declaration + + The \c addButton is displayed by invoking the \l{QPushButton::show()} + {show()} function, while the \c submitButton and \c cancelButton are + hidden by invoking \l{QPushButton::hide()}{hide()}. These two push + buttons will only be displayed when the user clicks \gui Add and this is + handled by the \c addContact() function discussed below. + + \snippet tutorials/addressbook/part2/addressbook.cpp connecting signals and slots + + We connect the push buttons' \l{QPushButton::clicked()}{clicked()} signal + to their respective slots. The figure below illustrates this. + + \image addressbook-tutorial-part2-signals-and-slots.png + + Next, we arrange our push buttons neatly to the right of our address book + widget, using a QVBoxLayout to line them up vertically. + + \snippet tutorials/addressbook/part2/addressbook.cpp vertical layout + + The \l{QBoxLayout::addStretch()}{addStretch()} function is used to ensure + the push buttons are not evenly spaced, but arranged closer to the top of + the widget. The figure below shows the difference between using + \l{QBoxLayout::addStretch()}{addStretch()} and not using it. + + \image addressbook-tutorial-part2-stretch-effects.png + + We then add \c buttonLayout1 to \c mainLayout, using + \l{QGridLayout::addLayout()}{addLayout()}. This gives us nested layouts + as \c buttonLayout1 is now a child of \c mainLayout. + + \snippet tutorials/addressbook/part2/addressbook.cpp grid layout + + Our layout coordinates now look like this: + + \image addressbook-tutorial-part2-labeled-layout.png + + In the \c addContact() function, we store the last displayed contact + details in \c oldName and \c oldAddress. Then we clear these input + fields and turn off the read-only mode. The focus is set on \c nameLine + and we display \c submitButton and \c cancelButton. + + \snippet tutorials/addressbook/part2/addressbook.cpp addContact + + The \c submitContact() function can be divided into three parts: + + \list 1 + \o We extract the contact's details from \c nameLine and \c addressText + and store them in QString objects. We also validate to make sure that the + user did not click \gui Submit with empty input fields; otherwise, a + QMessageBox is displayed to remind the user for a name and address. + + \snippet tutorials/addressbook/part2/addressbook.cpp submitContact part1 + + \o We then proceed to check if the contact already exists. If it does not + exist, we add the contact to \c contacts and we display a QMessageBox to + inform the user that the contact has been added. + + \snippet tutorials/addressbook/part2/addressbook.cpp submitContact part2 + + If the contact already exists, again, we display a QMessageBox to inform + the user about this, preventing the user from adding duplicate contacts. + Our \c contacts object is based on key-value pairs of name and address, + hence, we want to ensure that \e key is unique. + + \o Once we have handled both cases mentioned above, we restore the push + buttons to their normal state with the following code: + + \snippet tutorials/addressbook/part2/addressbook.cpp submitContact part3 + + \endlist + + The screenshot below shows the QMessageBox object we use to display + information messages to the user. + + \image addressbook-tutorial-part2-add-successful.png + + The \c cancel() function restores the last displayed contact details and + enables \c addButton, as well as hides \c submitButton and + \c cancelButton. + + \snippet tutorials/addressbook/part2/addressbook.cpp cancel + + The general idea behind adding a contact is to give the user the + flexibility to click \gui Submit or \gui Cancel at any time. The flowchart below + further explains this concept: + + \image addressbook-tutorial-part2-add-flowchart.png +*/ + +/*! + \page tutorials-addressbook-part3.html + + \example tutorials/addressbook/part3 + \title Part 3 - Navigating between Entries + + The address book is now about half complete. We should add the + capability to navigate among the contacts, but first we must + decide what sort of a data structure we need for containing these + contacts. + + In the previous section, we used a QMap of key-value pairs with + the contact's name as the \e key, and the contact's address as the + \e value. This works well for our case. However, in order to + navigate and display each entry, a little bit of enhancement is + needed. + + We enhance the QMap by making it replicate a data structure similar to a + circularly-linked list, where all elements are connected, including the + first element and the last element. The figure below illustrates this data + structure. + + \image addressbook-tutorial-part3-linkedlist.png + + \section1 Defining the AddressBook Class + + To add navigation functions to the address book, we must add two + more slots to the \c AddressBook class: \c next() and \c + previous() to the \c addressbook.h file: + + \snippet tutorials/addressbook/part3/addressbook.h navigation functions + + We also require another two QPushButton objects, so we declare \c nextButton + and \c previousButton as private variables: + + \snippet tutorials/addressbook/part3/addressbook.h navigation pushbuttons + + \section1 Implementing the AddressBook Class + + In the \c AddressBook constructor in \c addressbook.cpp, we instantiate + \c nextButton and \c previousButton and disable them by default. This is + because navigation is only enabled when there is more than one contact + in the address book. + + \snippet tutorials/addressbook/part3/addressbook.cpp navigation pushbuttons + + We then connect these push buttons to their respective slots: + + \snippet tutorials/addressbook/part3/addressbook.cpp connecting navigation signals + + The image below is the expected graphical user interface. + + \image addressbook-tutorial-part3-screenshot.png + + We follow basic conventions for \c next() and \c previous() functions by + placing the \c nextButton on the right and the \c previousButton on the + left. In order to achieve this intuitive layout, we use QHBoxLayout to + place the widgets side-by-side: + + \snippet tutorials/addressbook/part3/addressbook.cpp navigation layout + + The QHBoxLayout object, \c buttonLayout2, is then added to \c mainLayout. + + \snippet tutorials/addressbook/part3/addressbook.cpp adding navigation layout + + The figure below shows the coordinates of the widgets in \c mainLayout. + \image addressbook-tutorial-part3-labeled-layout.png + + Within our \c addContact() function, we have to disable these buttons so + that the user does not attempt to navigate while adding a contact. + + \snippet tutorials/addressbook/part3/addressbook.cpp disabling navigation + + Also, in our \c submitContact() function, we enable the navigation + buttons, \c nextButton and \c previousButton, depending on the size + of \c contacts. As mentioned earlier, navigation is only enabled when + there is more than one contact in the address book. The following lines + of code demonstrates how to do this: + + \snippet tutorials/addressbook/part3/addressbook.cpp enabling navigation + + We also include these lines of code in the \c cancel() function. + + Recall that we intend to emulate a circularly-linked list with our QMap + object, \c contacts. So, in the \c next() function, we obtain an iterator + for \c contacts and then: + + \list + \o If the iterator is not at the end of \c contacts, we increment it + by one. + \o If the iterator is at the end of \c contacts, we move it to the + beginning of \c contacts. This gives us the illusion that our QMap is + working like a circularly-linked list. + \endlist + + \snippet tutorials/addressbook/part3/addressbook.cpp next() function + + Once we have iterated to the correct object in \c contacts, we display + its contents on \c nameLine and \c addressText. + + Similarly, for the \c previous() function, we obtain an iterator for + \c contacts and then: + + \list + \o If the iterator is at the end of \c contacts, we clear the + display and return. + \o If the iterator is at the beginning of \c contacts, we move it to + the end. + \o We then decrement the iterator by one. + \endlist + + \snippet tutorials/addressbook/part3/addressbook.cpp previous() function + + Again, we display the contents of the current object in \c contacts. + +*/ + +/*! + \page tutorials-addressbook-part4.html + + \example tutorials/addressbook/part4 + \title Part 4 - Editing and Removing Addresses + + Now we look at ways to modify the contents of contacts stored in + the address book. + + \image addressbook-tutorial-screenshot.png + + We now have an address book that not only holds contacts in an + organized manner, but also allows navigation. It would be + convenient to include edit and remove functions so that a + contact's details can be changed when needed. However, this + requires a little improvement, in the form of enums. We defined + two modes: \c{AddingMode} and \c{NavigationMode}, but they were + not defined as enum values. Instead, we enabled and disabled the + corresponding buttons manually, resulting in multiple lines of + repeated code. + + Here we define the \c Mode enum with three different values: + + \list + \o \c{NavigationMode}, + \o \c{AddingMode}, and + \o \c{EditingMode}. + \endlist + + \section1 Defining the AddressBook Class + + The \c addressbook.h file is updated to contain the \c Mode enum: + + \snippet tutorials/addressbook/part4/addressbook.h Mode enum + + We also add two new slots, \c editContact() and \c removeContact(), to + our current list of public slots. + + \snippet tutorials/addressbook/part4/addressbook.h edit and remove slots + + In order to switch between modes, we introduce the \c updateInterface() function + to control the enabling and disabling of all QPushButton objects. We also + add two new push buttons, \c editButton and \c removeButton, for the edit + and remove functions mentioned earlier. + + \snippet tutorials/addressbook/part4/addressbook.h updateInterface() declaration + \dots + \snippet tutorials/addressbook/part4/addressbook.h buttons declaration + \dots + \snippet tutorials/addressbook/part4/addressbook.h mode declaration + + Lastly, we declare \c currentMode to keep track of the enum's current mode. + + \section1 Implementing the AddressBook Class + + We now implement the mode-changing features of the address + book. The \c editButton and \c removeButton are instantiated and + disabled by default. The address book starts with zero contacts + in memory. + + \snippet tutorials/addressbook/part4/addressbook.cpp edit and remove buttons + + These buttons are then connected to their respective slots, \c editContact() + and \c removeContact(), and we add them to \c buttonLayout1. + + \snippet tutorials/addressbook/part4/addressbook.cpp connecting edit and remove + \dots + \snippet tutorials/addressbook/part4/addressbook.cpp adding edit and remove to the layout + + The \c editContact() function stores the contact's old details in + \c oldName and \c oldAddress, before switching the mode to \c EditingMode. + In this mode, the \c submitButton and \c cancelButton are both enabled, + hence, the user can change the contact's details and click either button. + + \snippet tutorials/addressbook/part4/addressbook.cpp editContact() function + + The \c submitContact() function has been divided in two with an \c{if-else} + statement. We check \c currentMode to see if it's in \c AddingMode. If it is, + we proceed with our adding process. + + \snippet tutorials/addressbook/part4/addressbook.cpp submitContact() function beginning + \dots + \snippet tutorials/addressbook/part4/addressbook.cpp submitContact() function part1 + + Otherwise, we check to see if \c currentMode is in \c EditingMode. If it + is, we compare \c oldName with \c name. If the name has changed, we remove + the old contact from \c contacts and insert the newly updated contact. + + \snippet tutorials/addressbook/part4/addressbook.cpp submitContact() function part2 + + If only the address has changed (i.e., \c oldAddress is not the same as \c address), + we update the contact's address. Lastly, we set \c currentMode to + \c NavigationMode. This is an important step as it re-enables all the + disabled push buttons. + + To remove a contact from the address book, we implement the + \c removeContact() function. This function checks to see if the contact + exists in \c contacts. + + \snippet tutorials/addressbook/part4/addressbook.cpp removeContact() function + + If it does, we display a QMessageBox, to confirm the removal with the + user. Once the user has confirmed, we call \c previous() to ensure that the + user interface shows another contact, and we remove the contact using \l{QMap}'s + \l{QMap::remove()}{remove()} function. As a courtesy, we display a QMessageBox + to inform the user. Both the message boxes used in this function are shown below: + + \image addressbook-tutorial-part4-remove.png + + \section2 Updating the User Interface + + We mentioned the \c updateInterface() function earlier as a means to + enable and disable the push buttons depending on the current mode. + The function updates the current mode according to the \c mode argument + passed to it, assigning it to \c currentMode before checking its value. + + Each of the push buttons is then enabled or disabled, depending on the + current mode. The code for \c AddingMode and \c EditingMode is shown below: + + \snippet tutorials/addressbook/part4/addressbook.cpp update interface() part 1 + + For \c NavigationMode, however, we include conditions within the parameters + of the QPushButton::setEnabled() function. This is to ensure that + \c editButton and \c removeButton are enabled when there is at least one + contact in the address book; \c nextButton and \c previousButton are only + enabled when there is more than one contact in the address book. + + \snippet tutorials/addressbook/part4/addressbook.cpp update interface() part 2 + + By setting the mode and updating the user interface in the same + function, we avoid the possibility of the user interface getting + out of sync with the internal state of the application. + */ + +/*! + \page tutorials-addressbook-part5.html + + \example tutorials/addressbook/part5 + \title Part 5 - Adding a Find Function + + Here we look at ways to locate contacts and addresses in the + address book. + + \image addressbook-tutorial-part5-screenshot.png + + As we add contacts to our address book, it becomes tedious to + navigate the list with the \e Next and \e Previous buttons. A \e + Find function would be more efficient. The screenshot above shows + the \e Find button and its position on the panel of buttons. + + When the user clicks on the \e Find button, it is useful to + display a dialog that prompts for a contact's name. Qt provides + QDialog, which we subclass here to implement a \c FindDialog + class. + + \section1 Defining the FindDialog Class + + \image addressbook-tutorial-part5-finddialog.png + + In order to subclass QDialog, we first include the header for QDialog in + the \c finddialog.h file. Also, we use forward declaration to declare + QLineEdit and QPushButton since we will be using those widgets in our + dialog class. + + As in our \c AddressBook class, the \c FindDialog class includes + the Q_OBJECT macro and its constructor is defined to accept a parent + QWidget, even though the dialog will be opened as a separate window. + + \snippet tutorials/addressbook/part5/finddialog.h FindDialog header + + We define a public function, \c getFindText(), to be used by classes that + instantiate \c FindDialog. This function allows these classes to obtain the + search string entered by the user. A public slot, \c findClicked(), is also + defined to handle the search string when the user clicks the \gui Find + button. + + Lastly, we define the private variables, \c findButton, \c lineEdit + and \c findText, corresponding to the \gui Find button, the line edit + into which the user types the search string, and an internal string + used to store the search string for later use. + + \section1 Implementing the FindDialog Class + + Within the constructor of \c FindDialog, we set up the private variables, + \c lineEdit, \c findButton and \c findText. We use a QHBoxLayout to + position the widgets. + + \snippet tutorials/addressbook/part5/finddialog.cpp constructor + + We set the layout and window title, as well as connect the signals to their + respective slots. Notice that \c{findButton}'s \l{QPushButton::clicked()} + {clicked()} signal is connected to to \c findClicked() and + \l{QDialog::accept()}{accept()}. The \l{QDialog::accept()}{accept()} slot + provided by QDialog hides the dialog and sets the result code to + \l{QDialog::}{Accepted}. We use this function to help \c{AddressBook}'s + \c findContact() function know when the \c FindDialog object has been + closed. We will explain this logic in further detail when discussing the + \c findContact() function. + + \image addressbook-tutorial-part5-signals-and-slots.png + + In \c findClicked(), we validate \c lineEdit to ensure that the user + did not click the \gui Find button without entering a contact's name. Then, we set + \c findText to the search string, extracted from \c lineEdit. After that, + we clear the contents of \c lineEdit and hide the dialog. + + \snippet tutorials/addressbook/part5/finddialog.cpp findClicked() function + + The \c findText variable has a public getter function, \c getFindText(), + associated with it. Since we only ever set \c findText directly in both the + constructor and in the \c findClicked() function, we do not create a + setter function to accompany \c getFindText(). + Because \c getFindText() is public, classes instantiating and using + \c FindDialog can always access the search string that the user has + entered and accepted. + + \snippet tutorials/addressbook/part5/finddialog.cpp getFindText() function + + \section1 Defining the AddressBook Class + + To ensure we can use \c FindDialog from within our \c AddressBook class, we + include \c finddialog.h in the \c addressbook.h file. + + \snippet tutorials/addressbook/part5/addressbook.h include finddialog's header + + So far, all our address book features have a QPushButton and a + corresponding slot. Similarly, for the \gui Find feature we have + \c findButton and \c findContact(). + + The \c findButton is declared as a private variable and the + \c findContact() function is declared as a public slot. + + \snippet tutorials/addressbook/part5/addressbook.h findContact() declaration + \dots + \snippet tutorials/addressbook/part5/addressbook.h findButton declaration + + Lastly, we declare the private variable, \c dialog, which we will use to + refer to an instance of \c FindDialog. + + \snippet tutorials/addressbook/part5/addressbook.h FindDialog declaration + + Once we have instantiated a dialog, we will want to use it more than once; + using a private variable allows us to refer to it from more than one place + in the class. + + \section1 Implementing the AddressBook Class + + Within the \c AddressBook class's constructor, we instantiate our private + objects, \c findButton and \c findDialog: + + \snippet tutorials/addressbook/part5/addressbook.cpp instantiating findButton + \dots + \snippet tutorials/addressbook/part5/addressbook.cpp instantiating FindDialog + + Next, we connect the \c{findButton}'s + \l{QPushButton::clicked()}{clicked()} signal to \c findContact(). + + \snippet tutorials/addressbook/part5/addressbook.cpp signals and slots for find + + Now all that is left is the code for our \c findContact() function: + + \snippet tutorials/addressbook/part5/addressbook.cpp findContact() function + + We start out by displaying the \c FindDialog instance, \c dialog. This is + when the user enters a contact name to look up. Once the user clicks + the dialog's \c findButton, the dialog is hidden and the result code is + set to QDialog::Accepted. This ensures that + our \c if statement is always true. + + We then proceed to extract the search string, which in this case is + \c contactName, using \c{FindDialog}'s \c getFindText() function. If the + contact exists in our address book, we display it immediately. Otherwise, + we display the QMessageBox shown below to indicate that their search + failed. + + \image addressbook-tutorial-part5-notfound.png +*/ + +/*! + \page tutorials-addressbook-part6.html + + \example tutorials/addressbook/part6 + \title Part 6 - Loading and Saving + + This part covers the Qt file handling features we use to write + loading and saving routines for the address book. + + \image addressbook-tutorial-part6-screenshot.png + + Although browsing and searching the contact list are useful + features, our address book is not complete until we can save + existing contacts and load them again at a later time. + + Qt provides a number of classes for \l{Input/Output and Networking} + {input and output}, but we have chosen to use two which are simple to use + in combination: QFile and QDataStream. + + A QFile object represents a file on disk that can be read from and written + to. QFile is a subclass of the more general QIODevice class which + represents many different kinds of devices. + + A QDataStream object is used to serialize binary data so that it can be + stored in a QIODevice and retrieved again later. Reading from a QIODevice + and writing to it is as simple as opening the stream - with the respective + device as a parameter - and reading from or writing to it. + + + \section1 Defining the AddressBook Class + + We declare two public slots, \c saveToFile() and \c loadFromFile(), as well + as two QPushButton objects, \c loadButton and \c saveButton. + + \snippet tutorials/addressbook/part6/addressbook.h save and load functions declaration + \dots + \snippet tutorials/addressbook/part6/addressbook.h save and load buttons declaration + + \section1 Implementing the AddressBook Class + + In our constructor, we instantiate \c loadButton and \c saveButton. + Ideally, it would be more user-friendly to set the push buttons' labels + to "Load contacts from a file" and "Save contacts to a file". However, due + to the size of our other push buttons, we set the labels to \gui{Load...} + and \gui{Save...}. Fortunately, Qt provides a simple way to set tooltips with + \l{QWidget::setToolTip()}{setToolTip()} and we use it in the following way + for our push buttons: + + \snippet tutorials/addressbook/part6/addressbook.cpp tooltip 1 + \dots + \snippet tutorials/addressbook/part6/addressbook.cpp tooltip 2 + + Although it is not shown here, just like the other features we implemented, + we add the push buttons to the layout panel on the right, \c buttonLayout1, + and we connect the push buttons' \l{QPushButton::clicked()}{clicked()} + signals to their respective slots. + + For the saving feature, we first obtain \c fileName using + QFileDialog::getSaveFileName(). This is a convenience function provided + by QFileDialog, which pops up a modal file dialog and allows the user to + enter a file name or select any existing \c{.abk} file. The \c{.abk} file + is our Address Book extension that we create when we save contacts. + + \snippet tutorials/addressbook/part6/addressbook.cpp saveToFile() function part1 + + The file dialog that pops up is displayed in the screenshot below: + + \image addressbook-tutorial-part6-save.png + + If \c fileName is not empty, we create a QFile object, \c file, with + \c fileName. QFile works with QDataStream as QFile is a QIODevice. + + Next, we attempt to open the file in \l{QIODevice::}{WriteOnly} mode. + If this is unsuccessful, we display a QMessageBox to inform the user. + + \snippet tutorials/addressbook/part6/addressbook.cpp saveToFile() function part2 + + Otherwise, we instantiate a QDataStream object, \c out, to write the open + file. QDataStream requires that the same version of the stream is used + for reading and writing. We ensure that this is the case by setting the + version used to the \l{QDataStream::Qt_4_5}{version introduced with Qt 4.5} + before serializing the data to \c file. + + \snippet tutorials/addressbook/part6/addressbook.cpp saveToFile() function part3 + + For the loading feature, we also obtain \c fileName using + QFileDialog::getOpenFileName(). This function, the counterpart to + QFileDialog::getSaveFileName(), also pops up the modal file dialog and + allows the user to enter a file name or select any existing \c{.abk} file + to load it into the address book. + + \snippet tutorials/addressbook/part6/addressbook.cpp loadFromFile() function part1 + + On Windows, for example, this function pops up a native file dialog, as + shown in the following screenshot. + + \image addressbook-tutorial-part6-load.png + + If \c fileName is not empty, again, we use a QFile object, \c file, and + attempt to open it in \l{QIODevice::}{ReadOnly} mode. Similar to our + implementation of \c saveToFile(), if this attempt is unsuccessful, we + display a QMessageBox to inform the user. + + \snippet tutorials/addressbook/part6/addressbook.cpp loadFromFile() function part2 + + Otherwise, we instantiate a QDataStream object, \c in, set its version as + above and read the serialized data into the \c contacts data structure. + The \c contacts object is emptied before data is read into it to simplify + the file reading process. A more advanced method would be to read the + contacts into a temporary QMap object, and copy over non-duplicate contacts + into \c contacts. + + \snippet tutorials/addressbook/part6/addressbook.cpp loadFromFile() function part3 + + To display the contacts that have been read from the file, we must first + validate the data obtained to ensure that the file we read from actually + contains address book contacts. If it does, we display the first contact; + otherwise, we display a QMessageBox to inform the user about the problem. + Lastly, we update the interface to enable and disable the push buttons + accordingly. +*/ + +/*! + \page tutorials-addressbook-part7.html + + \example tutorials/addressbook/part7 + \title Part 7 - Additional Features + + This part covers some additional features that make the address + book more convenient for the frequent user. + + \image addressbook-tutorial-part7-screenshot.png + + Although our address book is useful in isolation, it would be + better if we could exchange contact data with other applications. + The vCard format is a popular file format that can be used for + this purpose. Here we extend our address book client to allow + contacts to be exported to vCard \c{.vcf} files. + + \section1 Defining the AddressBook Class + + We add a QPushButton object, \c exportButton, and a corresponding public + slot, \c exportAsVCard() to our \c AddressBook class in the + \c addressbook.h file. + + \snippet tutorials/addressbook/part7/addressbook.h exportAsVCard() declaration + \dots + \snippet tutorials/addressbook/part7/addressbook.h exportButton declaration + + \section1 Implementing the AddressBook Class + + Within the \c AddressBook constructor, we connect \c{exportButton}'s + \l{QPushButton::clicked()}{clicked()} signal to \c exportAsVCard(). + We also add this button to our \c buttonLayout1, the layout responsible + for our panel of buttons on the right. + + In our \c exportAsVCard() function, we start by extracting the contact's + name into \c name. We declare \c firstName, \c lastName and \c nameList. + Next, we look for the index of the first white space in \c name. If there + is a white space, we split the contact's name into \c firstName and + \c lastName. Then, we replace the space with an underscore ("_"). + Alternately, if there is no white space, we assume that the contact only + has a first name. + + \snippet tutorials/addressbook/part7/addressbook.cpp export function part1 + + As with the \c saveToFile() function, we open a file dialog to let the user + choose a location for the file. Using the file name chosen, we create an + instance of QFile to write to. + + We attempt to open the file in \l{QIODevice::}{WriteOnly} mode. If this + process fails, we display a QMessageBox to inform the user about the + problem and return. Otherwise, we pass the file as a parameter to a + QTextStream object, \c out. Like QDataStream, the QTextStream class + provides functionality to read and write plain text to files. As a result, + the \c{.vcf} file generated can be opened for editing in a text editor. + + \snippet tutorials/addressbook/part7/addressbook.cpp export function part2 + + We then write out a vCard file with the \c{BEGIN:VCARD} tag, followed by + the \c{VERSION:2.1} tag. The contact's name is written with the \c{N:} + tag. For the \c{FN:} tag, which fills in the "File as" property of a vCard, + we have to check whether the contact has a last name or not. If the contact + does, we use the details in \c nameList to fill it. Otherwise, we write + \c firstName only. + + \snippet tutorials/addressbook/part7/addressbook.cpp export function part3 + + We proceed to write the contact's address. The semicolons in the address + are escaped with "\\", the newlines are replaced with semicolons, and the + commas are replaced with spaces. Lastly, we write the \c{ADR;HOME:;} + tag, followed by \c address and then the \c{END:VCARD} tag. + + \snippet tutorials/addressbook/part7/addressbook.cpp export function part4 + + In the end, a QMessageBox is displayed to inform the user that the vCard + has been successfully exported. + + \e{vCard is a trademark of the \l{http://www.imc.org} + {Internet Mail Consortium}}. +*/ diff --git a/doc/src/tutorials/modelview.qdoc b/doc/src/tutorials/modelview.qdoc new file mode 100644 index 0000000000..efd0ff2efb --- /dev/null +++ b/doc/src/tutorials/modelview.qdoc @@ -0,0 +1,901 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page modelview.html + \ingroup tutorials + \startpage {index.html}{Qt Reference Documentation} + + \title Model/View Tutorial + \brief An introduction to ModelView programming + + Every UI developer should know about ModelView programming and the goal of + this tutorial is to provide you with an easily understandable introduction + to this topic. + + Table, list and tree widgets are components frequently used in GUIs. There + are 2 different ways how these widgets can access their data. The + traditional way involves widgets which include internal containers for + storing data. This approach is very intuitive, however, in many non-trivial + applications, it leads to data synchronization issues. + The second approach is model/view programming, in + which widgets do not maintain internal data containers. They access external + data through a standardized interface and therefore avoid data duplication. + This may seem complicated at first, but once you take a closer look, it is + not only easy to grasp, but the many benefits of model/view programming also + become clearer. + + \image treeview.png + + In the process, we will learn about some basic technologies provided by Qt, + such as: + + \list + \o The difference between standard and model/view widgets + \o Adapters betweeen forms and models + \o Developing a simple model/view application + \o Predefined models + \o Intermediate topics such as: + \list + \o Tree views + \o Selection + \o Delegates + \o Debugging with model test + \endlist + \endlist + + You will also learn whether your new application can be written easier with + model/view programming or if classic widgets will work just as well. + + This tutorial includes example code for you to edit and integrate into your + project. The tutorial's source code is located in Qt's + \c examples/tutorials/modelview directory. + + For more detailed information you may also want to look at the + \l{model-view-programming.html}{reference documentation} + + If you are completely new to Qt, please read \l{How to Learn Qt} if you + have not already done so. + + + \section1 1. Introduction + + Model/View is a technology used to separate data from views in widgets that + handle data sets. Standard widgets are not designed for separating data + from views and this is why Qt 4 has two different types of widgets. Both + types of widgets look the same, but they interact with data differently. + + \table + \row + \o Standard widgets use data that is part of the widget. + \o \image standardwidget.png + \row + \o View classes operate on external data (the model) + \o \image modelview.png + \endtable + + \section2 1.1 Standard Widgets + + Let's have a closer look at a standard table widget. A table widget is a 2D + array of the data elements that the user can change. The table widget can be + integrated into a program flow by reading and writing the data elements that + the table widget provides. + + This method is very intuitive and useful in many applications, but displaying + and editing a database table with a standard table widget can be problematic. + Two copies of the data have to be coordinated: one outside the + widget; one inside the widget. The developer is responsible for + synchronizing both versions. Besides this, the tight coupling of presentation and data + makes it harder to write unit tests. + + \section2 1.2 Model/View to the Rescue + + Model/view stepped up to provide a solution that uses a more versatile + architecture. Model/view eliminates the data consistency problems that may + occur with standard widgets. Model/view also makes it easier to use more + than one view of the same data because one model can be passed on to many + views. The most important difference is that model/view widgets do not store + data behind the table cells. In fact, they operate directly from your data. + Since view classes do not know your data's structure, you need to provide a + wrapper to make your data conform to the QAbstractItemModel interface. A + view uses this interface to read from and write to your data. Any instance + of a class that implements QAbstractItemModel is said to be a model. Once + the view receives a pointer to a model, it will read and display its content + and be its editor. + + \section2 1.3 Overview of the Model/View Widgets + + Here is an overview of the model/view widgets and their corresponding + standard widgets. + + \table + \header + \o Widget + \o Standard Widget\br + (an item based convenience class) + \o Model/View View Class\br + (for use with external data) + \row + \o \inlineimage listview.png + \o \l QListWidget + \o \l QListView + \row + \o \inlineimage tableview.png + \o \l QTableWidget + \o \l QTableView + \row + \o \inlineimage treeview.png + \o \l QTreeWidget + \o \l QTreeView + \row + \o \inlineimage columnview.png + \o + \o \l QColumnView shows a tree as a hierarchy of lists + \row + \o \inlineimage modelview-combobox.png + \o {2, 1} \l QComboBox can work as both a view class and also + as a traditional widget + \endtable + + \section2 1.4 Using Adapters between Forms and Models + + Having adapters between forms and models can come in handy. + + We can edit data stored in tables directly from within the table itself, but + it's much more comfortable to edit data in text fields. There is no direct + model/view counterpart that separates data and views for widgets that + operate on one value (QLineEdit, QCheckBox ...) instead of a dataset, so we + need an adapter in order to connect the form to the source of data. + + \l QDataWidgetMapper is a great solution because it maps form widgets to a + table row and makes it very easy to build forms for database tables. + + \image widgetmapper.png + + Another example of an adapter is \l QCompleter. Qt has \l QCompleter for + providing auto-completions in Qt widgets such as \l QComboBox and, as shown + below, \l QLineEdit. \l QCompleter uses a model as its data source. + + \image qcompleter.png + + + \section1 2. A Simple Model/View Application + If you want to develop a model/view application, where should you start? + We recommend starting with a simple example and extending it step-by-step. + This makes understanding the architecture a lot easier. Trying to understand + the model/view architecture in detail before invoking the IDE has proven + to be less convenient for many developers. It is substantially easier to + start with a simple model/view application that has demo data. Give it a + try! Simply replace the data in the examples below with your own. + + Below are 7 very simple and independent applications that show different + sides of model/view programming. The source code can be found inside the + \c{examples/tutorials/modelview} directory. + + \section2 2.1 A Read Only Table + + We start with an application that uses a QTableView to show data. We will + add editing capabilities later. + + (file source: examples/tutorials/modelview/1_readonly/main.cpp) + \snippet examples/tutorials/modelview/1_readonly/main.cpp Quoting ModelView Tutorial + + We have the usual \l {modelview-part2-main-cpp.html}{main()} function: + + Here is the interesting part: We create an instance of MyModel and use + \l{QTableView::setModel()}{tableView.setModel(&myModel);} to pass a + pointer of it to to \l{QTableView}{tableView}. \l{QTableView}{tableView} + will invoke the methods of the pointer it has received to find out two + things: + + \list + \o How many rows and columns should be displayed. + \o What content should be printed into each cell. + \endlist + + The model needs some code to respond to this. + + We have a table data set, so let's start with QAbstractTableModel since it + is easier to use than the more general QAbstractItemModel. + + (file source: examples/tutorials/modelview/1_readonly/mymodel.h) + \snippet examples/tutorials/modelview/1_readonly/mymodel.h Quoting ModelView Tutorial + + QAbstractTableModel requires the implementation of three abstract methods. + + (file source: examples/tutorials/modelview/1_readonly/mymodel.cpp) + \snippet examples/tutorials/modelview/1_readonly/mymodel.cpp Quoting ModelView Tutorial + + The number of rows and columns is provided by + \l{QAbstractItemModel::rowCount()}{MyModel::rowCount()} and + \l{QAbstractItemModel::columnCount()}{MyModel::columnCount()}. When the view + has to know what the cell's text is, it calls the method + \l{QAbstractItemModel::data()}{MyModel::data()}. Row and column information + is specified with parameter \c index and the role is set to + \l{Qt::ItemDataRole}{Qt::DisplayRole}. Other roles are covered in the next + section. In our example, the data that should be displayed is generated. In + a real application, \c MyModel would have a member called \c MyData, which + serves as the target for all reading and writing operations. + + This small example demonstrates the passive nature of a model. The model + does not know when it will be used or which data is needed. It simply + provides data each time the view requests it. + + What happens when the model's data needs to be changed? How does the view + realize that data has changed and needs to be read again? The model has to + emit a signal that indicates what range of cells has changed. This will be + demonstrated in section 2.3. + + \section2 2.2 Extending the Read Only Example with Roles + + In addition to controlling what text the view displays, the model also + controls the text's appearance. When we slightly change the model, we get + the following result: \image readonlytable_role.png + + In fact, nothing except for the \l{QAbstractItemModel::}{data()} method + needs to be changed to set fonts, background colour, alignment and a + checkbox. + Below is the \l{QAbstractItemModel::data()}{data()} method that produces the + result shown above. The difference is that this time we use parameter int + role to return different pieces of information depending on its value. + + (file source: examples/tutorials/modelview/2_formatting/mymodel.cpp) + \snippet examples/tutorials/modelview/2_formatting/mymodel.cpp Quoting ModelView Tutorial + + Each formatting property will be requested from the model with a separate + call to the \l{QAbstractItemModel::data()}{data()} method. The \c role + parameter is used to let the model know which property is being requested: + + \table + \header + \o \l{Qt::ItemDataRole}{enum Qt::ItemDataRole} + \o Meaning + \o Type + \row + \o \l{Qt::ItemDataRole}{}Qt::DisplayRole + \o text + \o QString + \row + \o \l{Qt::ItemDataRole}{Qt::FontRole} + \o font + \o QFont + \row + \o \l{Qt::ItemDataRole}{BackgroundRole} + \o brush for the background of the cell + \o QBrush + \row + \o \l{Qt::ItemDataRole}{Qt::TextAlignmentRole} + \o text alignment + \o \l{Qt::AlignmentFlag}{enum Qt::AlignmentFlag} + \row + \o {1, 3} \l{Qt::ItemDataRole}{Qt::CheckStateRole} + \o {1, 3} suppresses checkboxes with \l{QVariant}{QVariant()}, + + sets checkboxes with \l{Qt::CheckState}{Qt::Checked} + + or \l{Qt::CheckState}{Qt::Unchecked} + \o {1, 3} \l{Qt::ItemDataRole}{enum Qt::ItemDataRole} + \endtable + + Refer to the Qt namespace documentation to learn more about the + \l{Qt::ItemDataRole}{Qt::ItemDataRole} enum's capabilities. + + Now we need to determine how using a separated model impacts the + application's performance, so let's trace how often the view calls the + \l{QAbstractItemModel::}{data()} method. In order to track how often the + view calls the model, we have put a debug statement in the + \l{QAbstractItemModel::}{data()} method, which logs onto the error output + stream. In our small example, \l{QAbstractItemModel::}{data()} will be + called 42 times. + Each time you hover the cursor over the field, + \l{QAbstractItemModel::}{data()} will be called again \mdash 7 times for + each cell. That's why it is important to make sure that your data is + available when \l{QAbstractItemModel::}{data()} is invoked and expensive + lookup operations are cached. + + \section2 2.3 A Clock inside a Table Cell + + \image clock.png + + We still have a read only table, but this time the content changes every + second because we are showing the current time. + + (file source: examples/tutorials/modelview/3_changingmodel/mymodel.cpp) + \snippet examples/tutorials/modelview/3_changingmodel/mymodel.cpp quoting mymodel_QVariant + + Something is missing to make the clock tick. We need to tell the view every + second that the time has changed and that it needs to be read again. We do + this with a timer. In the constructor, we set its interval to 1 second and + connect its timeout signal. + + (file source: examples/tutorials/modelview/3_changingmodel/mymodel.cpp) + \snippet examples/tutorials/modelview/3_changingmodel/mymodel.cpp quoting mymodel_a + + Here is the corresponding slot: + + (file source: examples/tutorials/modelview/3_changingmodel/mymodel.cpp) + \snippet examples/tutorials/modelview/3_changingmodel/mymodel.cpp quoting mymodel_b + + We ask the view to read the data in the top left cell again by emitting the + \l{QAbstractItemModel::}{dataChanged()} signal. Note that we did not + explicitly connect the \l{QAbstractItemModel::}{dataChanged()} signal to the + view. This happened automatically when we called \l{QTableView::}{setModel()}. + + \section2 2.4 Setting up Headers for Columns and Rows + + Headers can be hidden via a view method: \c{tableView->verticalHeader()->hide();} + \image modelview-header.png + + The header content, however, is set via the model, so we reimplement the + \l{QAbstractItemModel::headerData()}{headerData()} method: + + (file source: examples/tutorials/modelview/4_headers/mymodel.cpp) + \snippet examples/tutorials/modelview/4_headers/mymodel.cpp quoting mymodel_c + + Note that method \l{QAbstractItemModel::headerData()}{headerData()} also has + a parameter role which has the same meaning as in + \l{QAbstractItemModel::data()}{MyModel::data()}. + + \section2 2.5 The Minimal Editing Example + + In this example, we are going to build an application that automatically + populates a window title with content by repeating values entered into table + cells. To be able to access the window title easily we put the QTableView in + a QMainWindow. + + The model decides whether editing capabilities are available. We only have + to modify the model in order for the available editing capabilities to be + enabled. This is done by reimplementing the following virtual methods: + \l{QAbstractItemModel::}{setData()} and \l{QAbstractItemModel::}{flags()}. + + (file source: examples/tutorials/modelview/5_edit/mymodel.h) + \snippet examples/tutorials/modelview/5_edit/mymodel.h Quoting ModelView Tutorial + + We use \c the two-dimensional array QString \c m_gridData to store our data. + This makes \c m_gridData the core of \c MyModel. The rest of \c MyModel acts + like a wrapper and adapts \c m_gridData to the QAbstractItemModel + interface. We have also introduced the \c editCompleted() signal, which + makes it possible to transfer the modified text to the window title. + + (file source: examples/tutorials/modelview/5_edit/mymodel.cpp) + \snippet examples/tutorials/modelview/5_edit/mymodel.cpp quoting mymodel_e + + \l{QAbstractItemModel::setData()}{setData()} will be called each time the + user edits a cell. The \c index parameter tells us which field has been + edited and \c value provides the result of the editing process. The role + will always be set to \l Qt::EditRole because our cells only contain text. + If a checkbox were present and user permissions are set to allow the + checkbox to be selected, calls would also be made with the role set to + \l Qt::CheckStateRole. + + (file source: examples/tutorials/modelview/5_edit/mymodel.cpp) + \snippet examples/tutorials/modelview/5_edit/mymodel.cpp quoting mymodel_f + + Various properties of a cell can be adjusted with + \l{QAbstractItemModel::flags()}{flags()}. + + Returning \l{Qt::ItemFlag}{Qt::ItemIsSelectable | Qt::ItemIsEditable | Qt::ItemIsEnabled} + is enough to show an editor that a cell can be selected. + + If editing one cell modifies more data than the data in that particular + cell, the model must emit a \l{QAbstractItemModel::}{dataChanged()} signal + in order for the data that has been changed to be read. + + + \section1 3. Intermediate Topics + + \section2 3.1 TreeView + + You can convert the example above into an application with a tree view. + Simply replace QTableView with QTreeView, which results in a read/write + tree. No changes have to be made to the model. The tree won't have any + hierarchies because there aren't any hierarchies in the model itself. + + \image dummy_tree.png + + QListView, QTableView and QTreeView all use a model abstraction, which is a + merged list, table and tree. This makes it possible to use several different + types of view classes from the same model. + + \image list_table_tree.png + + This is how our example model looks so far: + + \image example_model.png + + We want to present a real tree. We have wrapped our data in the examples + above in order to make a model. This time we use QStandardItemModel, which + is a container for hierarchical data that also implements + QAbstractItemModel. To show a tree, QStandardItemModel must be populated + with \l{QStandardItem}s, which are able to hold all the standard properties + of items like text, fonts, checkboxes or brushes. + + \image tree_2_with_algorithm.png + + (file source: examples/tutorials/modelview/6_treeview/mainwindow.cpp) + \snippet examples/tutorials/modelview/6_treeview/mainwindow.cpp Quoting ModelView Tutorial + + We simply instantiate a QStandardItemModel and add a couple of + \l{QStandardItem}{QStandardItems} to the constructor. We can then make a + hierarchical data structure because a QStandardItem can hold other + \l{QStandardItem}{QStandardItems}. Nodes are collapsed and expanded within + the view. + + \section2 3.2 Working with Selections + + We want to access a selected item's content in order to output it into the + window title together with the hierarchy level. + + \image selection2.png + + So let's create a couple of items: + + (file source: examples/tutorials/modelview/7_selections/mainwindow.cpp) + \snippet examples/tutorials/modelview/7_selections/mainwindow.cpp quoting modelview_a + + Views manage selections within a separate selection model, which can be + retrieved with the \l{QAbstractItemView::}{selectionModel()} method. We + retrieve the selection Model in order to connect a slot to its + \l{QAbstractItemView::}{selectionChanged()} signal. + + (file source: examples/tutorials/modelview/7_selections/mainwindow.cpp) + \snippet examples/tutorials/modelview/7_selections/mainwindow.cpp quoting modelview_b + + We get the model index that corresponds to the selection by calling + \l{QItemSelectionModel::currentIndex()}{treeView->selectionModel()->currentIndex()} + and we get the the field's string by using the model index. Then we just + calculate the item's \c hierarchyLevel. Top level items do not have parents + and the \l{QAbstractItemModel::}{parent()} method will return a default + constructed \l{QModelIndex}{QModelIndex()}. This is why we use the + \l{QAbstractItemModel::}{parent()} method to iterate to the top level while + counting the steps performed during iteration. + + The selection model (as shown above) can be retrieved, but it can also be + set with \l{QAbstractItemView}{QAbstractItemView::setSelectionModel}. This + is how it's possible to have 3 view classes with synchronised selections + because only one instance of a selection model is used. To share a selection + model between 3 views use \l{QAbstractItemView::}{selectionModel()} and + assign the result to the second and third view class with + \l{QAbstractItemView::}{setSelectionModel()}. + + \section2 3.3 Predefined Models + + The typical way to use model/view is to wrap specific data to make it usable + with view classes. Qt, however, also provides predefined models for common + underlying data structures. If one of the available data structures is + suitable for your application, a predefined model can be a good choice. + + \table + \row + \o QStringListModel + \o Stores a list of strings + \row + \o QStandardItemModel + \o Stores arbitrary hierarchical items + \row + \o QFileSystemModel\br + QDirModel + \o Encapsulate the local file system + \row + \o QSqlQueryModel + \o Encapsulate an SQL result set + \row + \o QSqlTableModel + \o Encapsulates an SQL table + \row + \o QSqlRelationalTableModel + \o Encapsulates an SQL table with foreign keys + \row + \o QSortFilterProxyModel + \o Sorts and/or filters another model + + \endtable + + \section2 3.4 Delegates + + In all examples so far, data is presented as text or a checkbox in a cell + and is edited as text or a checkbox. The component that provides these + presentation and editing services is called a \e delegate. We are only just + beginning to work with the delegate because the view uses a default + delegate. But imagine that we want to have a different editor (e.g., a + slider or a drop down list) Or imagine that we want to present data as + graphics. + Let's take a look at an example called \l{Star Delegate Example}{Star + Delegate}, in which stars are used to show a rating: + + \image stardelegate.png + + The view has a \l{QAbstractItemView::}{setItemDelegate()} method that + replaces the default delegate and installs a custom delegate. + A new delegate can be written by creating a class that inherits from + QStyledItemDelegate. In order to write a delegate that displays stars and + has no input capabilities, we only need to override 2 methods. + + \code + class StarDelegate : public QStyledItemDelegate + { + Q_OBJECT + public: + StarDelegate(QWidget *parent = 0); + void paint(QPainter *painter, const QStyleOptionViewItem &option, + const QModelIndex &index) const; + QSize sizeHint(const QStyleOptionViewItem &option, + const QModelIndex &index) const; + }; + \endcode + + \l{QStyledItemDelegate::}{paint()} draws stars depending on the content of + the underlying data. The data can be looked up by calling + \l{QModelIndex::data()}{index.data()}. The delegate's + \l{QAbstractItemDelegate::}{sizeHint()} method is used to obtain each + star's dimensions, so the the cell will provide enough height and width to + accommodate the stars. + + Writing custom delegates is the right choice if you want to show your data + with a custom graphical representation inside the grid of the view class. If + you want to leave the grid, you would not use a custom delegate but a custom + view class. + + Other references to delegates in Qt Documentation: + + \list + \o \l{Spin Box Delegate Example} + \o \l{QAbstractItemDelegate}{QAbstractItemDelegate Class Reference} + \o \l{QSqlRelationalDelegate}{QSqlRelationalDelegate Class Reference} + \o \l{QStyledItemDelegate}{QStyledItemDelegate Class Reference} + \o \l{QItemDelegate}{QItemDelegate Class Reference} + \endlist + + + \section2 3.5 Debugging with ModelTest + + The passive nature of models provides new challenges for programmers. + Inconsistencies in the model can cause the application to crash. Since the + model is hit by numerous calls from the view, it is hard to find out which + call has crashed the application and which operation has introduced the + problem. + + Qt Labs provides software called + \l{http://labs.qt.nokia.com/page/Projects/Itemview/Modeltest}{ModelTest}, + which checks models while your programming is running. Every time the model + is changed, ModelTest scans the model and reports errors with an assert. + This is especially important for tree models, since their hierarchical + nature leaves many possibilities for subtle inconsistencies. + + Unlike view classes, ModelTest uses out of range indexes to test the model. + This means your application may crash with ModelTest even if it runs + perfectly without it. So you also need to handle all of the indexes that are + out of range when using ModelTest. + + + \section1 4. Good Sources of Additional Information + + \section2 4.1 Books + + Model/View programming is covered quite extensively in the documentation of + Qt but also in several good books. + + \list 1 + \o \bold{C++ GUI Programming with Qt 4} / Jasmin Blanchette, Mark Summerfield, + \e{Prentice Hall, 2nd edition}, ISBN 0-13-235416-0. Also available in + German: \bold{C++ GUI Programmierung mit Qt 4: Die offizielle Einführung}, + \e{Addison-Wesley}, ISBN 3-827327-29-6 + \o \bold{The Book of Qt4, The Art of Building Qt Applications} / Daniel Molkentin, + \e{Open Source Press}, ISBN 1-59327-147-6. + Translated from \bold{Qt 4, Einführung in die Applikationsentwicklung}, + \e{Open Source Press}, ISBN 3-937514-12-0. + \o \bold{Foundations of Qt Development} / Johan Thelin, \e{Apress}, ISBN 1-59059-831-8. + \o \bold{Advanced Qt Programming} / Mark Summerfield, \e{Prentice Hall}, ISBN 0-321-63590-6. + This book covers Model/View programming on more than 150 pages. + \endlist + + More information about these books is available on the + \l{Books about Qt Programming}{Qt Web site}. + + The following list provides an overview of example programs contained in the first three + books listed above. Some of them make very good templates for developing similar + applications. + + \table + \header + \o Example name + \o View class used + \o Model used + \o Aspects covered + \o + \row + \o Team Leaders + \o QListview + \o QStringListModel + \o + \o Book 1, Chapter 10, Figure 10.6 + \row + \o Directory Viewer + \o QTreeView + \o QDirModel + \o + \o Book 1, Chapter 10, Figure 10.7 + \row + \o Color Names + \o QListView + \o QSortFilterProxyModel + applied to QStringListModel + \o + \o Book 1, Chapter 10, Figure 10.8 + \row + \o Currencies + \o QTableView + \o custom model based on + QAbstractTableModel + \o Read only + \o Book 1, Chapter 10, Figure 10.10 + \row + \o Cities + \o QTableView + \o Custom model based on + QAbstractTableModel + \o Read / write + \o Book 1, Chapter 10, Figure 10.12 + \row + \o Boolean Parser + \o QTreeView + \o Custom model based on + QAbstractItemModel + \o Read only + \o Book 1, Chapter 10, Figure 10.14 + \row + \o Track Editor + \o {2, 1} QTableWidget + \o Custom delegate providing a custom editor + \o Book 1, Chapter 10, Figure 10.15 + + \row + \o Four directory views + \o QListView + QTableView + QTreeView + \o QDirModel + \o Demonstrates the use of multiple views + \o Book2, Chapter 8.2 + \row + \o Address Book + \o QListView + QTableView + QTreeView + \o Custom model based on + QAbstractTableModel + \o Read / write + \o Book2, Chapter 8.4 + \row + \o Address Book with sorting + \o + \o QProxyModel + \o Introducing sort and filter capabilities + \o Book2, Chapter 8.5 + \row + \o Address Book + with checkboxes + \o + \o + \o Introducing checkboxes in model/view + \o Book2, Chapter 8.6 + \row + \o Address Book with transposed grid + \o + \o Custom proxy Model based on QAbstractProxyModel + \o Introducing a custom model + \o Book2, Chapter 8.7 + \row + \o Address Book with drag and drop + \o + \o + \o Introducing drag and drop support + \o Book2, Chapter 8.8 + \row + \o Address Book with custom editor + \o + \o + \o Introducing custom delegates + \o Book2, Chapter 8.9 + \row + \o Views + \o QListView + QTableView + QTreeView + \o QStandardItemModel + \o Read only + \o Book 3, Chapter 5, figure 5-3 + \row + \o Bardelegate + \o QTableView + \o + \o Custom delegate for presentation based on QAbstractItemDelegate + \o Book 3, Chapter 5, figure 5-5 + \row + \o Editdelegate + \o QTableView + \o + \o Custom delegate for editing based on QAbstractItemDelegate + \o Book 3, Chapter 5, figure 5-6 + \row + \o Singleitemview + \o Custom view based on QAbstractItemView + \o + \o Custom view + \o Book 3, + Chapter 5, + figure 5-7 + \row + \o listmodel + \o QTableView + \o Custom Model based on QAbstractTableModel + \o Read only + \o Book 3, Chapter 5, Figure 5-8 + \row + \o treemodel + \o QTreeView + \o Custom Model based on QAbstractItemModel + \o Read only + \o Book 3, Chapter 5, Figure 5-10 + \row + \o edit integers + \o QListView + \o Custom Model based on QAbstractListModel + \o Read / write + \o Book 3, Chapter 5, Listing 5-37, Figure 5-11 + \row + \o sorting + \o QTableView + \o QSortFilterProxyModel applied to QStringListModel + \o Demonstrates sorting + \o Book 3, Chapter 5, Figure 5-12 + \endtable + + + \section2 4.2 Qt Documentation + + Qt 4.7 comes with 17 examples and 2 Demonstrations for model/view. + The examples can be found on the \l{Item Views Examples} page. + + \table + \header + \o Example name + \o View class used + \o Model used + \o Aspects covered + \row + \o Address Book + \o QTableView + \o QAbstractTableModel + QSortFilterProxyModel + \o Usage of QSortFilterProxyModel to generate different + subsets from one data pool + \row + \o Basic Sort/Filter Model + \o QTreeView + \o QStandardItemModel + QSortFilterProxyModel + \o + \row + \o Chart + \o Custom view + \o QStandardItemModel + \o Designing custom views that cooperate with selection models + \row + \o Color Editor Factory + \o {2, 1} QTableWidget + \o Enhancing the standard delegate with a new custom editor to choose colours + \row + \o Combo Widget Mapper + \o QDataWidgetMapper to map QLineEdit, QTextEdit and QComboBox + \o QStandardItemModel + \o Shows how a QComboBox can serve as a view class + \row + \o Custom Sort/Filter Model + \o QTreeView + \o QStandardItemModel + QSortFilterProxyModel + \o Subclass QSortFilterProxyModel for advanced sorting and filtering + \row + \o Dir View + \o QTreeView + \o QDirModel + \o Very small example to demonstrate how to assign a model to a view + \row + \o Editable Tree Model + \o QTreeView + \o Custom tree model + \o Comprehensive example for working with trees, demonstrates + editing cells and tree structure with an underlying custom + model + \row + \o Fetch More + \o QListView + \o Custom list model + \o Dynamically changing model + \row + \o Frozen Column + \o QTableView + \o QStandardItemModel + \o + \row + \o Pixelator + \o QTableView + \o Custom table model + \o Implementation of a custom delegate + \row + \o Puzzle + \o QListView + \o Custom list model + \o Model/view with drag and drop + \row + \o Simple DOM Model + \o QTreeView + \o Custom tree model + \o Read only example for a custom tree model + \row + \o Simple Tree Model + \o QTreeView + \o Custom tree model + \o Read only example for a custom tree model + \row + \o Simple Widget Mapper + \o QDataWidgetMapper to map QLineEdit, QTextEdit and QSpinBox + \o QStandardItemModel + \o Basic QDataWidgetMapper usage + \row + \o Spin Box Delegate + \o QTableView + \o QStandardItemModel + \o Custom delegate that uses a spin box as a cell editor + \row + \o Star Delegate + \o {2, 1} QTableWidget + \o Comprehensive custom delegate example. + \endtable + + \l{Qt Demonstrations}{Demonstrations} are similar to examples except that no + walkthrough is provided for the code. Demonstrations are typically more + feature rich than examples. + + \list + \o The \bold Interview demonstration shows the same model and + selection being shared between three different views. + \o The \bold Spreadsheet demonstration illustrates the use of a + table view as a spreadsheet, using custom delegates to render + each item according to the type of data it contains. + \endlist + + A \l{Model/View Programming}{reference document} for model/view technology + is also available. +*/ + +/*! + \page modelview-part2-main-cpp.html + \title main.cpp + \quotefile tutorials/modelview/1_readonly/main.cpp +*/ diff --git a/doc/src/tutorials/threads.qdoc b/doc/src/tutorials/threads.qdoc new file mode 100644 index 0000000000..2d6a540bf3 --- /dev/null +++ b/doc/src/tutorials/threads.qdoc @@ -0,0 +1,572 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page thread-basics.html + \ingroup tutorials + \startpage {index.html}{Qt Reference Documentation} + + \title Threading Basics + \brief An introduction to threads + + \section1 What Are Threads? + + Threads are about doing things in parallel, just like processes. So how do + threads differ from processes? While you are making calculations on a + spreadsheet, there may also be a media player running on the same desktop + playing your favorite song. Here is an example of two processes working in + parallel: one running the spreadsheet program; one running a media player. + Multitasking is a well known term for this. A closer look at the media + player reveals that there are again things going on in parallel within one + single process. While the media player is sending music to the audio driver, + the user interface with all its bells and whistles is being constantly + updated. This is what threads are for \mdash concurrency within one single + process. + + So how is concurrency implemented? Parallel work on single core CPUs is an + illusion which is somewhat similar to the illusion of moving images in + cinema. + For processes, the illusion is produced by interrupting the processor's + work on one process after a very short time. Then the processor moves on to + the next process. In order to switch between processes, the current program + counter is saved and the next processor's program counter is loaded. This + is not sufficient because the same needs to be done with registers and + certain architecture and OS specific data. + + Just as one CPU can power two or more processes, it is also possible to let + the CPU run on two different code segments of one single process. When a + process starts, it always executes one code segment and therefore the + process is said to have one thread. However, the program may decide to + start a second thread. Then, two different code sequences are processed + simultaneously inside one process. Concurrency is achieved on single core + CPUs by repeatedly saving program counters and registers then loading the + next thread's program counters and registers. No cooperation from the + program is required to cycle between the active threads. A thread may be in + any state when the switch to the next thread occurs. + + The current trend in CPU design is to have several cores. A typical + single-threaded application can make use of only one core. However, a + program with multiple threads can be assigned to multiple cores, making + things happen in a truly concurrent way. As a result, distributing work + to more than one thread can make a program run much faster on multicore + CPUs because additional cores can be used. + + \section2 GUI Thread and Worker Thread + + As mentioned, each program has one thread when it is started. This thread + is called the "main thread" (also known as the "GUI thread" in Qt + applications). The Qt GUI must run in this thread. All widgets and several + related classes, for example QPixmap, don't work in secondary threads. + A secondary thread is commonly referred to as a "worker thread" because it + is used to offload processing work from the main thread. + + \section2 Simultaneous Access to Data + + Each thread has its own stack, which means each thread has its own call + history and local variables. Unlike processes, threads share the same + address space. The following diagram shows how the building blocks of + threads are located in memory. Program counter and registers of inactive + threads are typically kept in kernel space. There is a shared copy of the + code and a separate stack for each thread. + + \image threadvisual-example.png "Thread visualization" + + If two threads have a pointer to the same object, it is possible that both + threads will access that object at the same time and this can potentially + destroy the object's integrity. It's easy to imagine the many things that + can go wrong when two methods of the same object are executed + simultaneously. + + Sometimes it is necessary to access one object from different threads; + for example, when objects living in different threads need to communicate. + Since threads use the same address space, it is easier and faster for + threads to exchange data than it is for processes. Data does not have to be + serialized and copied. Passing pointers is possible, but there must be a + strict coordination of what thread touches which object. Simultaneous + execution of operations on one object must be prevented. There are several + ways of achieving this and some of them are described below. + + So what can be done safely? All objects created in a thread can be used + safely within that thread provided that other threads don't have references + to them and objects don't have implicit coupling with other threads. Such + implicit coupling may happen when data is shared between instances as with + static members, singletons or global data. Familiarize yourself with the + concept of \l{Reentrancy and Thread-Safety}{thread safe and reentrant} + classes and functions. + + \section1 Using Threads + + There are basically two use cases for threads: + + \list + \o Make processing faster by making use of multicore processors. + \o Keep the GUI thread or other time critical threads responsive by + offloading long lasting processing or blocking calls to other threads. + \endlist + + \section2 When to Use Alternatives to Threads + + Developers need to be very careful with threads. It is easy to start other + threads, but very hard to ensure that all shared data remains consistent. + Problems are often hard to find because they may only show up once in a + while or only on specific hardware configurations. Before creating threads + to solve certain problems, possible alternatives should be considered. + + \table + \header + \o Alternative + \o Comment + \row + \o QEventLoop::processEvents() + \o Calling QEventLoop::processEvents() repeatedly during a + time-consuming calculation prevents GUI blocking. However, this + solution doesn't scale well because the call to processEvents() may + occur too often, or not often enough, depending on hardware. + \row + \o QTimer + \o Background processing can sometimes be done conveniently using a + timer to schedule execution of a slot at some point in the future. + A timer with an interval of 0 will time out as soon as there are no + more events to process. + \row + \o QSocketNotifier QNetworkAccessManager QIODevice::readyRead() + \o This is an alternative to having one or multiple threads, each with + a blocking read on a slow network connection. As long as the + calculation in response to a chunk of network data can be executed + quickly, this reactive design is better than synchronous waiting in + threads. Reactive design is less error prone and energy efficient + than threading. In many cases there are also performance benefits. + \endtable + + In general, it is recommended to only use safe and tested paths and to + avoid introducing ad-hoc threading concepts. QtConcurrent provides an easy + interface for distributing work to all of the processor's cores. The + threading code is completely hidden in the QtConcurrent framework, so you + don't have to take care of the details. However, QtConcurrent can't be used + when communication with the running thread is needed, and it shouldn't be + used to handle blocking operations. + + \section2 Which Qt Thread Technology Should You Use? + + Sometimes you want to do more than just running a method in the context of + another thread. You may want to have an object which lives in another + thread that provides a service to the GUI thread. Maybe you want another + thread to stay alive forever to poll hardware ports and send a signal to + the GUI thread when something noteworthy has happened. Qt provides + different solutions for developing threaded applications. The right + solution depends on the purpose of the new thread as well as on the + thread's lifetime. + + \table + \header + \o Lifetime of thread + \o Development task + \o Solution + \row + \o One call + \o Run one method within another thread and quit the thread when the + method is finished. + \o Qt provides different solutions: + \list + \o Write a function and run it with QtConcurrent::run() + \o Derive a class from QRunnable and run it in the global thread + pool with QThreadPool::globalInstance()->start() + \o Derive a class from QThread, reimplement the QThread::run() + method and use QThread::start() to run it. + \endlist + + \row + \o One call + \o Operations are to be performed on all items of a container. + Processing should be performed using all available cores. A common + example is to produce thumbnails from a list of images. + \o QtConcurrent provides the \l{QtConcurrent::}{map()} function for + applying operations on every container element, + \l{QtConcurrent::}{filter()} for selecting container elements, and + the option of specifying a reduce function for combining the + remaining elements. + \row + \o One call + \o A long running operation has to be put in another thread. During the + course of processing, status information should be sent to the GUI + thread. + \o Use QThread, reimplement run and emit signals as needed. Connect the + signals to the GUI thread's slots using queued signal/slot + connections. + + \row + \o Permanent + \o Have an object living in another thread and let it perform different + tasks upon request. + This means communication to and from the worker thread is required. + \o Derive a class from QObject and implement the necessary slots and + signals, move the object to a thread with a running event loop and + communicate with the object over queued signal/slot connections. + \row + \o Permanent + \o Have an object living in another thread, let the object perform + repeated tasks such as polling a port and enable communication with + the GUI thread. + \o Same as above but also use a timer in the worker thread to implement + polling. However, the best solution for polling is to avoid it + completely. Sometimes using QSocketNotifier is an alternative. + \endtable + + + \section1 Qt Thread Basics + + QThread is a very convenient cross platform abstraction of native platform + threads. Starting a thread is very simple. Let us look at a short piece of + code that generates another thread which says hello in that thread and then + exits. + + \snippet examples/tutorials/threads/hellothread/hellothread.h 1 + + We derive a class from QThread and reimplement the \l{QThread::}{run()} + method. + + \snippet examples/tutorials/threads/hellothread/hellothread.cpp 1 + + The run method contains the code that will be run in a separate thread. In + this example, a message containing the thread ID will be printed. + QThread::start() will call the method in another thread. + + \snippet examples/tutorials/threads/hellothread/main.cpp 1 + + To start the thread, our thread object needs to be instantiated. The + \l{QThread::}{start()} method creates a new thread and calls the + reimplemented \l{QThread::}{run()} method in this new thread. Right after + \l{QThread::}{start()} is called, two program counters walk through the + program code. The main function starts with only the GUI thread running and + it should terminate with only the GUI thread running. Exiting the program + when another thread is still busy is a programming error, and therefore, + wait is called which blocks the calling thread until the + \l{QThread::}{run()} method has completed. + + This is the result of running the code: + + \badcode + hello from GUI thread 3079423696 + hello from worker thread 3076111216 + \endcode + + + \section2 QObject and Threads + + A QObject is said to have a \e{thread affinity} or, in other words, that it + lives in a certain thread. This means that, at creation time, QObject saves + a pointer to the current thread. This information becomes relevant when an + event is posted with \l{QCoreApplication::}{postEvent()}. The event will be + put in the corresponding thread's event loop. If the thread where the + QObject lives doesn't have an event loop, the event will never be delivered. + + To start an event loop, \l{QThread::}{exec()} must be called inside + \l{QThread::}{run()}. Thread affinity can be changed using + \l{QObject::}{moveToThread()}. + + As mentioned above, developers must always be careful when calling objects' + methods from other threads. Thread affinity does not change this situation. + Qt documentation marks several methods as thread-safe. + \l{QCoreApplication::}{postEvent()} is a noteworthy example. A thread-safe + method may be called from different threads simultaneously. + + In cases where there is usually no concurrent access to methods, calling + non-thread-safe methods of objects in other threads may work thousands + of times before a concurrent access occurs, causing unexpected behavior. + Writing test code does not entirely ensure thread correctness, but it is + still important. + On Linux, Valgrind and Helgrind can help detect threading errors. + + The anatomy of QThread is quite interesting: + + \list + \o QThread does not live in the new thread where \l{QThread::}{run()} is + executed. It lives in the old thread. + \o Most QThread methods are the thread's control interface and are meant to + be called from the old thread. Do not move this interface to the newly + created thread using \l{QObject::}{moveToThread()}; i.e., calling + \l{QObject::moveToThread()}{moveToThread(this)} is regarded as bad + practice. + \o \l{QThread::}{exec()} and the static methods + \l{QThread::}{usleep()}, \l{QThread::}{msleep()}, + \l{QThread::}{sleep()} are meant to be called from the newly created + thread. + \o Additional members defined in the QThread subclass are + accessible by both threads. The developer is responsible for + coordinating access. A typical strategy is to set the members before + \l{QThread::}{start()} is called. Once the worker thread is running, + the main thread should not touch the additional members anymore. After + the worker has terminated, the main thread can access the additional + members again. This is a convenient strategy for passing parameters to a + thread before it is started as well as for collecting the result once it + has terminated. + \endlist + + A QObject's parent must always be in the same thread. This has a surprising + consequence for objects generated within the \l{QThread::}{run()} method: + + \code + void HelloThread::run() + { + QObject *object1 = new QObject(this); //error, parent must be in the same thread + QObject object2; // OK + QSharedPointer <QObject> object3(new QObject); // OK + } + \endcode + + \section2 Using a Mutex to Protect the Integrity of Data + + A mutex is an object that has \l{QMutex::}{lock()} and \l{QMutex::}{unlock()} + methods and remembers if it is already locked. A mutex is designed to be + called from multiple threads. \l{QMutex::}{lock()} returns immediately if + the mutex is not locked. The next call from another thread will find the + mutex in a locked state and then \l{QMutex::}{lock()} will block the thread + until the other thread calls \l{QMutex::}{unlock()}. This functionality can + make sure that a code section will be executed by only one thread at a time. + + The following line sketches how a mutex can be used to make a method + thread-safe: + + \code + void Worker::work() + { + this->mutex.lock(); // first thread can pass, other threads will be blocked here + doWork(); + this->mutex.unlock(); + } + \endcode + + What happens if one thread does not unlock a mutex? The result can be a + frozen application. In the example above, an exception might be thrown and + \c{mutex.unlock()} will never be reached. To prevent problems like this, + QMutexLocker should be used. + + \code + void Worker::work() + { + QMutexLocker locker(&mutex); // Locks the mutex and unlocks when locker exits the scope + doWork(); + } + \endcode + + This looks easy, but mutexes introduce a new class of problems: deadlocks. + A deadlock happens when a thread waits for a mutex to become unlocked, but + the mutex remains locked because the owning thread is waiting for the first + thread to unlock it. The result is a frozen application. Mutexes can be + used to make a method thread safe. Most Qt methods aren't thread safe + because there is always a performance penalty when using mutexes. + + It isn't always possible to lock and unlock a mutex in a method. Sometimes + the need to lock spans several calls. For example, modifying a container + with an iterator requires a sequence of several calls which should not be + interrupted by other threads. In such a scenario, locking can be achieved + with a mutex that is kept outside of the object to be manipulated. With an + external mutex, the duration of locking can be adjusted to the needs of the + operation. One disadvantage is that external mutexes aid locking, but do + not enforce it because users of the object may forget to use it. + + \section2 Using the Event Loop to Prevent Data Corruption + + The event loops of Qt are a very valuable tool for inter-thread + communication. Every thread may have its own event loop. A safe way of + calling a slot in another thread is by placing that call in another + thread's event loop. This ensures that the target object finishes the + method that is currently running before another method is started. + + So how is it possible to put a method invocation in an event loop? Qt has + two ways of doing this. One way is via queued signal-slot connections; the + other way is to post an event with QCoreApplication::postEvent(). A queued + signal-slot connection is a signal slot connection that is executed + asynchronously. The internal implementation is based on posted events. The + arguments of the signal are put into the event loop and the signal method + returns immediately. + + The connected slot will be executed at a time which depends on what else is + in the event loop. + + Communication via the event loop eliminates the deadlock problem we face + when using mutexes. This is why we recommend using the event loop rather + than locking an object using a mutex. + + \section2 Dealing with Asynchronous Execution + + One way to obtain a worker thread's result is by waiting for the thread + to terminate. In many cases, however, a blocking wait isn't acceptable. The + alternative to a blocking wait are asynchronous result deliveries with + either posted events or queued signals and slots. This generates a certain + overhead because an operation's result does not appear on the next source + line, but in a slot located somewhere else in the source file. Qt + developers are used to working with this kind of asynchronous behavior + because it is much similar to the kind of event-driven programming used in + GUI applications. + + \section1 Examples + + This tutorial comes with examples for Qt's three basic ways of working with + threads. Two more examples show how to communicate with a running thread + and how a QObject can be placed in another thread, providing service to the + main thread. + + \list + \o Using QThread as shown \l{Qt thread basics}{above} + \o \l{Example 1: Using the Thread Pool}{Using the global QThreadPool} + \o \l{Example 2: Using QtConcurrent}{Using QtConcurrent} + \o \l{Example 3: Clock}{Communication with the GUI thread} + \o \l{Example 4: A Permanent Thread}{A permanent QObject in another thread + provides service to the main thread} + \endlist + + The following examples can all be compiled and run independently. The source can + be found in the examples directory: examples/tutorials/threads/ + + \section2 Example 1: Using the Thread Pool + + Creating and destroying threads frequently can be expensive. To avoid the + cost of thread creation, a thread pool can be used. A thread pool is a + place where threads can be parked and fetched. We can write the same + "hello thread" program as \l{Qt Thread Basics}{above} using the global + thread pool. We derive a class from QRunnable. The code we want to run in + another thread needs to be placed in the reimplemented QRunnable::run() + method. + + \snippet examples/tutorials/threads/hellothreadpool/hellothreadpool.cpp 1 + + We instantiate Work in main(), locate the global thread pool and use the + QThreadPool::start() method. Now the thread pool runs our worker in another + thread. Using the thread pool has a performance advantage because threads + are not destroyed after they have finished running. They are kept in a pool + and wait to be used again later. + + \section2 Example 2: Using QtConcurrent + + \snippet examples/tutorials/threads/helloconcurrent/helloconcurrent.cpp 1 + + We write a global function hello() to implement the work. QtConcurrent::run() + is used to run the function in another thread. The result is a QFuture. + QFuture provides a method called \l{QFuture::}{waitForFinished()}, which + blocks until the calculation is completed. The real power of QtConcurrent + becomes visible when data can be made available in a container. QtConcurrent + provides several functions that are able to process itemized data on all + available cores simultaneously. The use of QtConcurrent is very similar to + applying an STL algorithm to an STL container. + \l{examples-threadandconcurrent.html}{QtConcurrent Map} is a very short and + clear example about how a container of images can be scaled on all available + cores. The image scaling example uses the blocking variants of the functions + used. For every blocking function there is also a non-blocking, asynchronous + counterpart. Getting results asynchronously is implemented with QFuture and + QFutureWatcher. + + \section2 Example 3: Clock + + \image thread_clock.png "clock" + + We want to produce a clock application. The application has a GUI and a + worker thread. The worker thread checks every 10 milliseconds what time it + is. If the formatted time has changed, the result will be sent to the GUI + thread where it is displayed. + + Of course, this is an overly complicated way of designing a clock and, + actually, a separate thread is unnecessary. We would be better off placing + the timer in the main thread because the calculation made in the timer slot + is very short-lived. This example is purely for instructional use and shows + how to communicate from a worker thread to a GUI thread. Note that + communication in this direction is easy. We only need to add a signal + to QThread and make a queued signal/slot connection to the main thread. + Communication from the GUI to the worker thread is shown in the next + example. + + \snippet examples/tutorials/threads/clock/main.cpp 1 + + We've connected the \c clockThread with the label. The connection must be a + queued signal-slot connection because we want to put the call in the event + loop. + + \snippet examples/tutorials/threads/clock/clockthread.h 1 + + We have derived a class from QThread and declared the \c sendTime() signal. + + \snippet examples/tutorials/threads/clock/clockthread.cpp 1 + + The trickiest part of this example is that the timer is connected to its + slot via a direct connection. A default connection would produce a queued + signal-slot connection because the connected objects live in different + threads; remember that QThread does not live in the thread it creates. + + Still it is safe to access ClockThread::timerHit() from the worker thread + because ClockThread::timerHit() is private and only touches local variables + and a private member that isn't touched by public methods. + QDateTime::currentDateTime() isn't marked as thread-safe in Qt + documentation, however we can get away with using it in this small + example because we know that the QDateTime::currentDateTime() static + method isn't used in any other threads. + + \section2 Example 4: A Permanent Thread + + This example shows how it is possible to have a QObject in a worker thread + that accepts requests from the GUI thread, does polling using a timer and + continuously reports results back to the GUI thread. The actual work + including the polling must be implemented in a class derived from QObject. + We have called this class \c WorkerObject in the code shown below. The + thread-specific code is hidden in a class called \c Thread, derived from + QThread. + \c Thread has two additional public members. The \c launchWorker() member + takes the worker object and moves it to another thread with a started event + loop. + The call blocks for a very short moment until the thread creation operation + is completed, allowing the worker object to be used again on the next line. + The \c Thread class's code is short but somewhat involved, so we only show + how to use the class. + + \snippet examples/tutorials/threads/movedobject/main.cpp 1 + + QMetaObject::invokeMethod() calls a slot via the event loop. The worker + object's methods should not be called directly after the object has been + moved to another thread. We let the worker thread do some work and polling, + and use a timer to shut the application down after 3 seconds. Shutting the + worker down needs some care. We call \c{Thread::stop()} to exit the event + loop. We wait for the thread to terminate and, after this has occurred, we + delete the worker. + + \section1 Digging Deeper + + Threading is a very complicated subject. Qt offers more classes for + threading than we have presented in this tutorial. The following materials + can help you go into the subject in more depth: + + \list + \o Good video tutorials about threads with Qt can be found in the material + from the \l{Training Day at Qt Developer Days 2009}. + \o The \l{Thread Support in Qt} document is a good starting point into + the reference documentation. + \o Qt comes with several additional examples for + \l{Threading and Concurrent Programming Examples}{QThread and QtConcurrent}. + \o Several good books describe how to work with Qt threads. The most + extensive coverage can be found in \e{Advanced Qt Programming} by Mark + Summerfield, Prentice Hall - roughly 70 of 500 pages cover QThread and + QtConcurrent. + \endlist +*/ diff --git a/doc/src/tutorials/widgets-tutorial.qdoc b/doc/src/tutorials/widgets-tutorial.qdoc new file mode 100644 index 0000000000..4877339348 --- /dev/null +++ b/doc/src/tutorials/widgets-tutorial.qdoc @@ -0,0 +1,249 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page widgets-tutorial.html + \ingroup tutorials + \title Widgets Tutorial + \brief This tutorial covers basic usage of widgets and layouts, showing how + they are used to build GUI applications. + + \section1 Introduction + + Widgets are the basic building blocks for graphical user interface + (GUI) applications built with Qt. Each GUI component (e.g. + buttons, labels, text editor) is a \l{QWidget}{widget} that is + placed somewhere within a user interface window, or is displayed + as an independent window. Each type of widge is provided by a + subclass of QWidget, which is itself a subclass of QObject. + + QWidget is not an abstract class. It can be used as a container + for other widgets, and it can be subclassed with minimal effort to + create new, custom widgets. QWidget is often used to create a + window inside which other \l{QWidget}s are placed. + + As with \l{QObject}s, \l{QWidget}s can be created with parent + objects to indicate ownership, ensuring that objects are deleted + when they are no longer used. With widgets, these parent-child + relationships have an additional meaning: Each child widget is + displayed within the screen area occupied by its parent widget. + This means that when you delete a window widget, all the child + widgets it contains are also deleted. + + \section1 Writing a main Function + + Many of the GUI examples provided with Qt follow the pattern of + having a \c{main.cpp} file, which contains the standard code to + initialize the application, plus any number of other source/header + files that contain the application logic and custom GUI components. + + A typical \c main() function in \c{main.cpp} looks like this: + + \snippet doc/src/snippets/widgets-tutorial/template.cpp main.cpp body + + First, a QApplication object is constructed, which can be + configured with arguments passed in from the command line. After + the widgets have been created and shown, QApplication::exec() is + called to start Qt's event loop. Control passes to Qt until this + function returns. Finally, \c{main()} returns the value returned + by QApplication::exec(). + + \section1 Simple widget examples + + Each of theses simple widget examples is written entirely within + the \c main() function. + + \list + \o \l {tutorials/widgets/toplevel} {Creating a window} + + \o \l {tutorials/widgets/childwidget} {Creating child widgets} + + \o \l {tutorials/widgets/windowlayout} {Using layouts} + + \o \l {tutorials/widgets/nestedlayouts} {Nested layouts} + \endlist + + \section1 Real world widget examples + + In these \l{Widget examples} {more advanced examples}, the code + that creates the widgets and layouts is stored in other files. For + example, the GUI for a main window may be created in the + constructor of a QMainWindow subclass. + + \section1 Building The Examples + + If you installed a binary package to get Qt, or if you compiled Qt + yourself, the examples described in this tutorial should already + be built and ready to run. If you wish to modify and recompile + them, follow these steps: + + \list 1 + + \o From a command prompt, enter the directory containing the + example you have modified. + + \o Type \c qmake and press \key{Return}. If this doesn't work, + make sure that the executable is on your path, or enter its + full location. + + \o On Linux/Unix and Mac OS X, type \c make and press + \key{Return}; on Windows with Visual Studio, type \c nmake and + press \key{Return}. + + \endlist + + An executable file is created in the current directory. On + Windows, this file may be located in a \c debug or \c release + subdirectory. You can run this executable to see the example code + at work. +*/ + +/*! + \example tutorials/widgets/toplevel + \title Widgets Tutorial - Creating a Window + + If a widget is created without a parent, it is treated as a window, or + \e{top-level widget}, when it is shown. Since it has no parent object to + ensure that it is deleted when no longer needed, it is up to the + developer to keep track of the top-level widgets in an application. + + In the following example, we use QWidget to create and show a window with + a default size: + + \div {class="qt-code"} + \table + \row + \o \snippet tutorials/widgets/toplevel/main.cpp main program + \o \inlineimage widgets-tutorial-toplevel.png + \endtable + \enddiv + + To create a real GUI, we need to place widgets inside the window. To do + this, we pass a QWidget instance to a widget's constructor, as we will + demonstrate in the next part of this tutorial. + +*/ + +/*! + \example tutorials/widgets/childwidget + \title Widgets Tutorial - Child Widgets + + We can add a child widget to the window created in the previous example by + passing \c window as the parent to its constructor. In this case, we add a + button to the window and place it in a specific location: + + \div {class="qt-code"} + \table + \row + \o \snippet tutorials/widgets/childwidget/main.cpp main program + \o \inlineimage widgets-tutorial-childwidget.png + \endtable + \enddiv + + The button is now a child of the window and will be deleted when the + window is destroyed. Note that hiding or closing the window does not + automatically destroy it. It will be destroyed when the example exits. +*/ + +/*! + \example tutorials/widgets/windowlayout + \title Widgets Tutorial - Using Layouts + + Usually, child widgets are arranged inside a window using layout objects + rather than by specifying positions and sizes explicitly. Here, we + construct a label and line edit widget that we would like to arrange + side-by-side. + + \div {class="qt-code"} + \table + \row + \o \snippet tutorials/widgets/windowlayout/main.cpp main program + \o \inlineimage widgets-tutorial-windowlayout.png + \endtable + \enddiv + + The \c layout object we construct manages the positions and sizes of + widgets supplied to it with the \l{QHBoxLayout::}{addWidget()} function. + The layout itself is supplied to the window itself in the call to + \l{QWidget::}{setLayout()}. Layouts are only visible through the effects + they have on the widgets (and other layouts) they are responsible for + managing. + + In the example above, the ownership of each widget is not immediately + clear. Since we construct the widgets and the layout without parent + objects, we would expect to see an empty window and two separate windows + containing a label and a line edit. However, when we tell the layout to + manage the label and line edit and set the layout on the window, both the + widgets and the layout itself are ''reparented'' to become children of + the window. +*/ + +/*! + \example tutorials/widgets/nestedlayouts + \title Widgets Tutorial - Nested Layouts + + Just as widgets can contain other widgets, layouts can be used to provide + different levels of grouping for widgets. Here, we want to display a + label alongside a line edit at the top of a window, above a table view + showing the results of a query. + + We achieve this by creating two layouts: \c{queryLayout} is a QHBoxLayout + that contains QLabel and QLineEdit widgets placed side-by-side; + \c{mainLayout} is a QVBoxLayout that contains \c{queryLayout} and a + QTableView arranged vertically. + + \div {class="qt-code"} + \table + \row + \o \snippet tutorials/widgets/nestedlayouts/main.cpp first part + \snippet tutorials/widgets/nestedlayouts/main.cpp last part + \o \inlineimage widgets-tutorial-nestedlayouts.png + \endtable + \enddiv + + Note that we call the \c{mainLayout}'s \l{QBoxLayout::}{addLayout()} + function to insert the \c{queryLayout} above the \c{resultView} table. + + We have omitted the code that sets up the model containing the data shown + by the QTableView widget, \c resultView. For completeness, we show this below. + + As well as QHBoxLayout and QVBoxLayout, Qt also provides QGridLayout + and QFormLayout classes to help with more complex user interfaces. + These can be seen if you run \l{Qt Designer}. + + \section1 Setting up the Model + + In the code above, we did not show where the table's data came from + because we wanted to concentrate on the use of layouts. Here, we see + that the model holds a number of items corresponding to rows, each of + which is set up to contain data for two columns. + + \snippet tutorials/widgets/nestedlayouts/main.cpp set up the model + + The use of models and views is covered in the + \l{Item Views Examples} and in the \l{Model/View Programming} overview. +*/ diff --git a/doc/src/widgets-and-layouts/focus.qdoc b/doc/src/widgets-and-layouts/focus.qdoc new file mode 100644 index 0000000000..446b374901 --- /dev/null +++ b/doc/src/widgets-and-layouts/focus.qdoc @@ -0,0 +1,186 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page focus.html + \title Keyboard Focus + \brief Keyboard focus management and handling. + \ingroup frameworks-technologies + + \keyword keyboard focus + + Qt's widgets handle keyboard focus in the ways that have become + customary in GUIs. + + The basic issue is that the user's key strokes can be directed at any + of several windows on the screen, and any of several widgets inside + the intended window. When the user presses a key, they expect it to go + to the right place, and the software must try to meet this + expectation. The system must determine which application the key stroke + is directed at, which window within that application, and which widget + within that window. + + \section1 Focus Motion + + The customs which have evolved for directing keyboard focus to a + particular widget are these: + + \list 1 + + \o The user presses \key Tab (or \key Shift+Tab). + \o The user clicks a widget. + \o The user presses a keyboard shortcut. + \o The user uses the mouse wheel. + \o The user moves the focus to a window, and the application must + determine which widget within the window should get the focus. + \endlist + + Each of these motion mechanisms is different, and different types of + widgets receive focus in only some of them. We'll cover each of them + in turn. + + \section2 Tab or Shift+Tab + + Pressing \key Tab is by far the most common way to move focus + using the keyboard. (Sometimes in data-entry applications Enter + does the same as \key{Tab}; this can easily be achieved in Qt by + implementing an \l{The Event System}{event filter}.) + + Pressing \key Tab, in all window systems in common use today, + moves the keyboard focus to the next widget in a circular + per-window list. \key Tab moves focus along the circular list in + one direction, \key Shift+Tab in the other. The order in which + \key Tab presses move from widget to widget is called the tab order. + + You can customize the tab order using QWidget::setTabOrder(). (If + you don't, \key Tab generally moves focus in the order of widget + construction.) \l{Qt Designer} provides a means of visually + changing the tab order. + + Since pressing \key Tab is so common, most widgets that can have focus + should support tab focus. The major exception is widgets that are + rarely used, and where there is some keyboard accelerator or error + handler that moves the focus. + + For example, in a data entry dialog, there might be a field that + is only necessary in one per cent of all cases. In such a dialog, + \key Tab could skip this field, and the dialog could use one of + these mechanisms: + + \list 1 + + \o If the program can determine whether the field is needed, it can + move focus there when the user finishes entry and presses \gui OK, or when + the user presses Enter after finishing the other fields. Alternately, + include the field in the tab order but disable it. Enable it if it + becomes appropriate in view of what the user has set in the other + fields. + + \o The label for the field can include a keyboard shortcut that moves + focus to this field. + + \endlist + + Another exception to \key Tab support is text-entry widgets that + must support the insertion of tabs; almost all text editors fall + into this class. Qt treats \key Ctrl+Tab as \key Tab and \key + Ctrl+Shift+Tab as \key Shift+Tab, and such widgets can + reimplement QWidget::event() and handle Tab before calling + QWidget::event() to get normal processing of all other keys. + However, since some systems use \key Ctrl+Tab for other purposes, + and many users aren't aware of \key Ctrl+Tab anyway, this isn't a + complete solution. + + \section2 The User Clicks a Widget + + This is perhaps even more common than pressing \key Tab on + computers with a mouse or other pointing device. + + Clicking to move the focus is slightly more powerful than \key + Tab. While it moves the focus \e to a widget, for editor widgets + it also moves the text cursor (the widget's internal focus) to + the spot where the mouse is clicked. + + Since it is so common and people are used to it, it's a good idea to + support it for most widgets. However, there is also an important + reason to avoid it: you may not want to remove focus from the widget + where it was. + + For example, in a word processor, when the user clicks the 'B' (bold) + tool button, what should happen to the keyboard focus? Should it + remain where it was, almost certainly in the editing widget, or should + it move to the 'B' button? + + We advise supporting click-to-focus for widgets that support text + entry, and to avoid it for most widgets where a mouse click has a + different effect. (For buttons, we also recommend adding a keyboard + shortcut: QAbstractButton and its subclasses make this very easy.) + + In Qt, only the QWidget::setFocusPolicy() function affects + click-to-focus. + + \section2 The User Presses a Keyboard Shortcut + + It's not unusual for keyboard shortcuts to move the focus. This + can happen implicitly by opening modal dialogs, but also + explicitly using focus accelerators such as those provided by + QLabel::setBuddy(), QGroupBox, and QTabBar. + + We advise supporting shortcut focus for all widgets that the user + may want to jump to. For example, a tab dialog can have keyboard + shortcuts for each of its pages, so the user can press e.g. \key + Alt+P to step to the \underline{P}rinting page. It is easy to + overdo this: there are only a few keys, and it's also important + to provide keyboard shortcuts for commands. \key Alt+P is also + used for Paste, Play, Print, and Print Here in the \l{Standard + Accelerator Keys} list, for example. + + \section2 The User Rotates the Mouse Wheel + + On Microsoft Windows, mouse wheel usage is always handled by the + widget that has keyboard focus. On Mac OS X and X11, it's handled by + the widget that gets other mouse events. + + The way Qt handles this platform difference is by letting widgets move + the keyboard focus when the wheel is used. With the right focus policy + on each widget, applications can work idiomatically correctly on + Windows, Mac OS X, and X11. + + \section2 The User Moves the Focus to This Window + + In this situation the application must determine which widget within + the window should receive the focus. + + This can be simple: If the focus has been in this window before, + then the last widget to have focus should regain it. Qt does this + automatically. + + If focus has never been in this window before and you know where + focus should start out, call QWidget::setFocus() on the widget + which should receive focus before you call QWidget::show() it. If + you don't, Qt will pick a suitable widget. +*/ diff --git a/doc/src/widgets-and-layouts/gallery-cde.qdoc b/doc/src/widgets-and-layouts/gallery-cde.qdoc new file mode 100644 index 0000000000..ac8dd8c696 --- /dev/null +++ b/doc/src/widgets-and-layouts/gallery-cde.qdoc @@ -0,0 +1,133 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page gallery-cde.html + + \title CDE Style Widget Gallery + \ingroup gallery + + This page shows some of the widgets available in Qt + when configured to use the "cde" style. + +\section2 Buttons + +\table 100% +\row +\o \image cde-checkbox.png + \caption The QCheckBox widget provides a checkbox with a text label. +\o \image cde-radiobutton.png + \caption The QRadioButton widget provides a radio button with a text or pixmap label. +\o \image cde-pushbutton.png + \image cde-toolbutton.png + \caption The QPushButton widget provides a command button. +\endtable + +\section2 Containers + +\table 100% +\row +\o \image cde-groupbox.png + The The QGroupBox widget provides a group box frame with a title. +\o \image cde-tabwidget.png + The QTabWidget class provides a stack of tabbed widgets. +\o \image cde-frame.png + The QFrame widget provides a simple decorated container for other widgets. +\o \image cde-toolbox.png + The QToolBox class provides a column of tabbed widget items. +\endtable + +\section2 Item Views + +\table 100% +\row +\o \image cde-listview.png + The QListView class provides a default model/view implementation of a list/icon view. The QListWidget class provides a classic item-based list/icon view. +\o \image cde-treeview.png + The QTreeView class provides a default model/view implementation of a tree view. The QTreeWidget class provides a classic item-based tree view. +\o \image cde-tableview.png + The QTableView class provides a default model/view implementation of a table view. The QTableWidget class provides a classic item-based table view.\o +\o +\endtable + +\section2 Display Widgets + +\table 100% +\row +\o \image cde-progressbar.png + The QProgressBar widget provides a horizontal progress bar. +\o \image cde-label.png + The QLabel widget provides a text or image display. +\o \image cde-lcdnumber.png + The QLCDNumber widget displays a number with LCD-like digits. +\endtable + +\section2 Input Widgets + +\table 100% +\row +\o \image cde-lineedit.png + The QLineEdit widget is a one-line text editor. +\o \image cde-dateedit.png + The QDateEdit class provides a widget for editing dates. +\o \image cde-timeedit.png + The QTimeEdit class provides a widget for editing times. +\o \image cde-datetimeedit.png + The QDateTimeEdit class provides a widget for editing dates and times. +\endtable + +\table 100% +\row +\o \image cde-slider.png + The QSlider widget provides a vertical or horizontal slider. +\o \image cde-combobox.png + The QComboBox widget is a combined button and pop-up list. +\o \image cde-spinbox.png + The QSpinBox class provides a spin box widget. +\endtable + +\table 100% +\row +\o \image cde-fontcombobox.png + The QFontComboBox widget is a specialized combobox that enables fonts to be selected from a pop-up list containing previews of available fonts. +\o \image cde-doublespinbox.png + The QDoubleSpinBox class provides a spin box widget that allows double precision floating point numbers to be entered. +\o \image cde-horizontalscrollbar.png + The QScrollBar widget provides a vertical or horizontal scroll bar. Here, we show a scroll bar with horizontal orientation. +\endtable + +\table 100% +\row +\o \image cde-dial.png + The QDial class provides a rounded range control (like a speedometer or potentiometer). +\o \image cde-textedit.png + The QTextEdit class provides a widget that is used to edit and display both plain and rich text. +\o \image cde-calendarwidget.png + The QCalendarWidget class provides a monthly calendar widget that can be used to select dates. +\endtable + +*/ diff --git a/doc/src/widgets-and-layouts/gallery-cleanlooks.qdoc b/doc/src/widgets-and-layouts/gallery-cleanlooks.qdoc new file mode 100644 index 0000000000..2300a54613 --- /dev/null +++ b/doc/src/widgets-and-layouts/gallery-cleanlooks.qdoc @@ -0,0 +1,138 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page gallery-cleanlooks.html + + \title Cleanlooks Style Widget Gallery + \ingroup gallery + + This page shows some of the widgets available in Qt + when configured to use the "cleanlooks" style. + +\section2 Buttons + +\table 100% +\row +\o \image cleanlooks-pushbutton.png + \caption The QPushButton widget provides a command button. +\o \image cleanlooks-toolbutton.png + \caption The QToolButton class provides a quick-access button to commands + or options, usually used inside a QToolBar. +\endtable + +\table 100% +\row +\o \image cleanlooks-checkbox.png + \caption The QCheckBox widget provides a checkbox with a text label. +\o \image cleanlooks-radiobutton.png + \caption The QRadioButton widget provides a radio button with a text or pixmap label. +\endtable + +\section2 Containers + +\table 100% +\row +\o \image cleanlooks-groupbox.png + The The QGroupBox widget provides a group box frame with a title. +\o \image cleanlooks-tabwidget.png + The QTabWidget class provides a stack of tabbed widgets. +\o \image cleanlooks-frame.png + The QFrame widget provides a simple decorated container for other widgets. +\o \image cleanlooks-toolbox.png + The QToolBox class provides a column of tabbed widget items. +\endtable + +\section2 Item Views + +\table 100% +\row +\o \image cleanlooks-listview.png + The QListView class provides a default model/view implementation of a list/icon view. The QListWidget class provides a classic item-based list/icon view. +\o \image cleanlooks-treeview.png + The QTreeView class provides a default model/view implementation of a tree view. The QTreeWidget class provides a classic item-based tree view. +\o \image cleanlooks-tableview.png + The QTableView class provides a default model/view implementation of a table view. The QTableWidget class provides a classic item-based table view.\o +\o +\endtable + +\section2 Display Widgets + +\table 100% +\row +\o \image cleanlooks-progressbar.png + The QProgressBar widget provides a horizontal progress bar. +\o \image cleanlooks-label.png + The QLabel widget provides a text or image display. +\o \image cleanlooks-lcdnumber.png + The QLCDNumber widget displays a number with LCD-like digits. +\endtable + +\section2 Input Widgets + +\table 100% +\row +\o \image cleanlooks-lineedit.png + The QLineEdit widget is a one-line text editor. +\o \image cleanlooks-dateedit.png + The QDateEdit class provides a widget for editing dates. +\o \image cleanlooks-timeedit.png + The QTimeEdit class provides a widget for editing times. +\o \image cleanlooks-datetimeedit.png + The QDateTimeEdit class provides a widget for editing dates and times. +\endtable + +\table 100% +\row +\o \image cleanlooks-slider.png + The QSlider widget provides a vertical or horizontal slider. +\o \image cleanlooks-combobox.png + The QComboBox widget is a combined button and pop-up list. +\o \image cleanlooks-spinbox.png + The QSpinBox class provides a spin box widget. +\endtable + +\table 100% +\row +\o \image cleanlooks-fontcombobox.png + The QFontComboBox widget is a specialized combobox that enables fonts to be selected from a pop-up list containing previews of available fonts. +\o \image cleanlooks-doublespinbox.png + The QDoubleSpinBox class provides a spin box widget that allows double precision floating point numbers to be entered. +\o \image cleanlooks-horizontalscrollbar.png + The QScrollBar widget provides a vertical or horizontal scroll bar. Here, we show a scroll bar with horizontal orientation. +\endtable + +\table 100% +\row +\o \image cleanlooks-dial.png + The QDial class provides a rounded range control (like a speedometer or potentiometer). +\o \image cleanlooks-textedit.png + The QTextEdit class provides a widget that is used to edit and display both plain and rich text. +\o \image cleanlooks-calendarwidget.png + The QCalendarWidget class provides a monthly calendar widget that can be used to select dates. +\endtable +*/ diff --git a/doc/src/widgets-and-layouts/gallery-gtk.qdoc b/doc/src/widgets-and-layouts/gallery-gtk.qdoc new file mode 100644 index 0000000000..5446af30d1 --- /dev/null +++ b/doc/src/widgets-and-layouts/gallery-gtk.qdoc @@ -0,0 +1,141 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page gallery-gtk.html + + \title GTK Style Widget Gallery + \ingroup gallery + + This page shows some of the widgets available in Qt + when configured to use the "gtk" style. + + Take a look at the \l{Qt Widget Gallery} to see how Qt + applications appear in other styles. + +\section2 Buttons + +\table 100% +\row +\o \image gtk-pushbutton.png + \caption The QPushButton widget provides a command button. +\o \image gtk-toolbutton.png + \caption The QToolButton class provides a quick-access button to commands + or options, usually used inside a QToolBar. +\endtable + +\table 100% +\row +\o \image gtk-checkbox.png + \caption The QCheckBox widget provides a checkbox with a text label. +\o \image gtk-radiobutton.png + \caption The QRadioButton widget provides a radio button with a text or pixmap label. +\endtable + +\section2 Containers + +\table 100% +\row +\o \image gtk-groupbox.png + The The QGroupBox widget provides a group box frame with a title. +\o \image gtk-tabwidget.png + The QTabWidget class provides a stack of tabbed widgets. +\o \image gtk-frame.png + The QFrame widget provides a simple decorated container for other widgets. +\o \image gtk-toolbox.png + The QToolBox class provides a column of tabbed widget items. +\endtable + +\section2 Item Views + +\table 100% +\row +\o \image gtk-listview.png + The QListView class provides a default model/view implementation of a list/icon view. The QListWidget class provides a classic item-based list/icon view. +\o \image gtk-treeview.png + The QTreeView class provides a default model/view implementation of a tree view. The QTreeWidget class provides a classic item-based tree view. +\o \image gtk-tableview.png + The QTableView class provides a default model/view implementation of a table view. The QTableWidget class provides a classic item-based table view.\o +\o +\endtable + +\section2 Display Widgets + +\table 100% +\row +\o \image gtk-progressbar.png + The QProgressBar widget provides a horizontal progress bar. +\o \image gtk-label.png + The QLabel widget provides a text or image display. +\o \image gtk-lcdnumber.png + The QLCDNumber widget displays a number with LCD-like digits. +\endtable + +\section2 Input Widgets + +\table 100% +\row +\o \image gtk-lineedit.png + The QLineEdit widget is a one-line text editor. +\o \image gtk-dateedit.png + The QDateEdit class provides a widget for editing dates. +\o \image gtk-timeedit.png + The QTimeEdit class provides a widget for editing times. +\o \image gtk-datetimeedit.png + The QDateTimeEdit class provides a widget for editing dates and times. +\endtable + +\table 100% +\row +\o \image gtk-slider.png + The QSlider widget provides a vertical or horizontal slider. +\o \image gtk-combobox.png + The QComboBox widget is a combined button and pop-up list. +\o \image gtk-spinbox.png + The QSpinBox class provides a spin box widget. +\endtable + +\table 100% +\row +\o \image gtk-fontcombobox.png + The QFontComboBox widget is a specialized combobox that enables fonts to be selected from a pop-up list containing previews of available fonts. +\o \image gtk-doublespinbox.png + The QDoubleSpinBox class provides a spin box widget that allows double precision floating point numbers to be entered. +\o \image gtk-horizontalscrollbar.png + The QScrollBar widget provides a vertical or horizontal scroll bar. Here, we show a scroll bar with horizontal orientation. +\endtable + +\table 100% +\row +\o \image gtk-dial.png + The QDial class provides a rounded range control (like a speedometer or potentiometer). +\o \image gtk-textedit.png + The QTextEdit class provides a widget that is used to edit and display both plain and rich text. +\o \image gtk-calendarwidget.png + The QCalendarWidget class provides a monthly calendar widget that can be used to select dates. +\endtable +*/ diff --git a/doc/src/widgets-and-layouts/gallery-macintosh.qdoc b/doc/src/widgets-and-layouts/gallery-macintosh.qdoc new file mode 100644 index 0000000000..9049e11d03 --- /dev/null +++ b/doc/src/widgets-and-layouts/gallery-macintosh.qdoc @@ -0,0 +1,138 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page gallery-macintosh.html + + \title Macintosh Style Widget Gallery + \ingroup gallery + + This page shows some of the widgets available in Qt + when configured to use the "macintosh" style. + +\section2 Buttons + +\table 100% +\row +\o \image macintosh-pushbutton.png + \caption The QPushButton widget provides a command button. +\o \image macintosh-toolbutton.png + \caption The QToolButton class provides a quick-access button to commands + or options, usually used inside a QToolBar. +\endtable + +\table 100% +\row +\o \image macintosh-checkbox.png + \caption The QCheckBox widget provides a checkbox with a text label. +\o \image macintosh-radiobutton.png + \caption The QRadioButton widget provides a radio button with a text or pixmap label. +\endtable + +\section2 Containers + +\table 100% +\row +\o \image macintosh-groupbox.png + The The QGroupBox widget provides a group box frame with a title. +\o \image macintosh-tabwidget.png + The QTabWidget class provides a stack of tabbed widgets. +\o \image macintosh-frame.png + The QFrame widget provides a simple decorated container for other widgets. +\o \image macintosh-toolbox.png + The QToolBox class provides a column of tabbed widget items. +\endtable + +\section2 Item Views + +\table 100% +\row +\o \image macintosh-listview.png + The QListView class provides a default model/view implementation of a list/icon view. The QListWidget class provides a classic item-based list/icon view. +\o \image macintosh-treeview.png + The QTreeView class provides a default model/view implementation of a tree view. The QTreeWidget class provides a classic item-based tree view. +\o \image macintosh-tableview.png + The QTableView class provides a default model/view implementation of a table view. The QTableWidget class provides a classic item-based table view.\o +\o +\endtable + +\section2 Display Widgets + +\table 100% +\row +\o \image macintosh-progressbar.png + The QProgressBar widget provides a horizontal progress bar. +\o \image macintosh-label.png + The QLabel widget provides a text or image display. +\o \image macintosh-lcdnumber.png + The QLCDNumber widget displays a number with LCD-like digits. +\endtable + +\section2 Input Widgets + +\table 100% +\row +\o \image macintosh-lineedit.png + The QLineEdit widget is a one-line text editor. +\o \image macintosh-dateedit.png + The QDateEdit class provides a widget for editing dates. +\o \image macintosh-timeedit.png + The QTimeEdit class provides a widget for editing times. +\o \image macintosh-datetimeedit.png + The QDateTimeEdit class provides a widget for editing dates and times. +\endtable + +\table 100% +\row +\o \image macintosh-slider.png + The QSlider widget provides a vertical or horizontal slider. +\o \image macintosh-combobox.png + The QComboBox widget is a combined button and pop-up list. +\o \image macintosh-spinbox.png + The QSpinBox class provides a spin box widget. +\endtable + +\table 100% +\row +\o \image macintosh-fontcombobox.png + The QFontComboBox widget is a specialized combobox that enables fonts to be selected from a pop-up list containing previews of available fonts. +\o \image macintosh-doublespinbox.png + The QDoubleSpinBox class provides a spin box widget that allows double precision floating point numbers to be entered. +\o \image macintosh-horizontalscrollbar.png + The QScrollBar widget provides a vertical or horizontal scroll bar. Here, we show a scroll bar with horizontal orientation. +\endtable + +\table 100% +\row +\o \image macintosh-dial.png + The QDial class provides a rounded range control (like a speedometer or potentiometer). +\o \image macintosh-textedit.png + The QTextEdit class provides a widget that is used to edit and display both plain and rich text. +\o \image macintosh-calendarwidget.png + The QCalendarWidget class provides a monthly calendar widget that can be used to select dates. +\endtable +*/ diff --git a/doc/src/widgets-and-layouts/gallery-motif.qdoc b/doc/src/widgets-and-layouts/gallery-motif.qdoc new file mode 100644 index 0000000000..c65b49aee6 --- /dev/null +++ b/doc/src/widgets-and-layouts/gallery-motif.qdoc @@ -0,0 +1,138 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page gallery-motif.html + + \title Motif Style Widget Gallery + \ingroup gallery + + This page shows some of the widgets available in Qt + when configured to use the "motif" style. + +\section2 Buttons + +\table 100% +\row +\o \image motif-pushbutton.png + \caption The QPushButton widget provides a command button. +\o \image motif-toolbutton.png + \caption The QToolButton class provides a quick-access button to commands + or options, usually used inside a QToolBar. +\endtable + +\table 100% +\row +\o \image motif-checkbox.png + \caption The QCheckBox widget provides a checkbox with a text label. +\o \image motif-radiobutton.png + \caption The QRadioButton widget provides a radio button with a text or pixmap label. +\endtable + +\section2 Containers + +\table 100% +\row +\o \image motif-groupbox.png + The The QGroupBox widget provides a group box frame with a title. +\o \image motif-tabwidget.png + The QTabWidget class provides a stack of tabbed widgets. +\o \image motif-frame.png + The QFrame widget provides a simple decorated container for other widgets. +\o \image motif-toolbox.png + The QToolBox class provides a column of tabbed widget items. +\endtable + +\section2 Item Views + +\table 100% +\row +\o \image motif-listview.png + The QListView class provides a default model/view implementation of a list/icon view. The QListWidget class provides a classic item-based list/icon view. +\o \image motif-treeview.png + The QTreeView class provides a default model/view implementation of a tree view. The QTreeWidget class provides a classic item-based tree view. +\o \image motif-tableview.png + The QTableView class provides a default model/view implementation of a table view. The QTableWidget class provides a classic item-based table view.\o +\o +\endtable + +\section2 Display Widgets + +\table 100% +\row +\o \image motif-progressbar.png + The QProgressBar widget provides a horizontal progress bar. +\o \image motif-label.png + The QLabel widget provides a text or image display. +\o \image motif-lcdnumber.png + The QLCDNumber widget displays a number with LCD-like digits. +\endtable + +\section2 Input Widgets + +\table 100% +\row +\o \image motif-lineedit.png + The QLineEdit widget is a one-line text editor. +\o \image motif-dateedit.png + The QDateEdit class provides a widget for editing dates. +\o \image motif-timeedit.png + The QTimeEdit class provides a widget for editing times. +\o \image motif-datetimeedit.png + The QDateTimeEdit class provides a widget for editing dates and times. +\endtable + +\table 100% +\row +\o \image motif-slider.png + The QSlider widget provides a vertical or horizontal slider. +\o \image motif-combobox.png + The QComboBox widget is a combined button and pop-up list. +\o \image motif-spinbox.png + The QSpinBox class provides a spin box widget. +\endtable + +\table 100% +\row +\o \image motif-fontcombobox.png + The QFontComboBox widget is a specialized combobox that enables fonts to be selected from a pop-up list containing previews of available fonts. +\o \image motif-doublespinbox.png + The QDoubleSpinBox class provides a spin box widget that allows double precision floating point numbers to be entered. +\o \image motif-horizontalscrollbar.png + The QScrollBar widget provides a vertical or horizontal scroll bar. Here, we show a scroll bar with horizontal orientation. +\endtable + +\table 100% +\row +\o \image motif-dial.png + The QDial class provides a rounded range control (like a speedometer or potentiometer). +\o \image motif-textedit.png + The QTextEdit class provides a widget that is used to edit and display both plain and rich text. +\o \image motif-calendarwidget.png + The QCalendarWidget class provides a monthly calendar widget that can be used to select dates. +\endtable +*/ diff --git a/doc/src/widgets-and-layouts/gallery-plastique.qdoc b/doc/src/widgets-and-layouts/gallery-plastique.qdoc new file mode 100644 index 0000000000..f49627f8c6 --- /dev/null +++ b/doc/src/widgets-and-layouts/gallery-plastique.qdoc @@ -0,0 +1,138 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page gallery-plastique.html + + \title Plastique Style Widget Gallery + \ingroup gallery + + This page shows some of the widgets available in Qt + when configured to use the "plastique" style. + +\section2 Buttons + +\table 100% +\row +\o \image plastique-pushbutton.png + \caption The QPushButton widget provides a command button. +\o \image plastique-toolbutton.png + \caption The QToolButton class provides a quick-access button to commands + or options, usually used inside a QToolBar. +\endtable + +\table 100% +\row +\o \image plastique-checkbox.png + \caption The QCheckBox widget provides a checkbox with a text label. +\o \image plastique-radiobutton.png + \caption The QRadioButton widget provides a radio button with a text or pixmap label. +\endtable + +\section2 Containers + +\table 100% +\row +\o \image plastique-groupbox.png + The The QGroupBox widget provides a group box frame with a title. +\o \image plastique-tabwidget.png + The QTabWidget class provides a stack of tabbed widgets. +\o \image plastique-frame.png + The QFrame widget provides a simple decorated container for other widgets. +\o \image plastique-toolbox.png + The QToolBox class provides a column of tabbed widget items. +\endtable + +\section2 Item Views + +\table 100% +\row +\o \image plastique-listview.png + The QListView class provides a default model/view implementation of a list/icon view. The QListWidget class provides a classic item-based list/icon view. +\o \image plastique-treeview.png + The QTreeView class provides a default model/view implementation of a tree view. The QTreeWidget class provides a classic item-based tree view. +\o \image plastique-tableview.png + The QTableView class provides a default model/view implementation of a table view. The QTableWidget class provides a classic item-based table view.\o +\o +\endtable + +\section2 Display Widgets + +\table 100% +\row +\o \image plastique-progressbar.png + The QProgressBar widget provides a horizontal progress bar. +\o \image plastique-label.png + The QLabel widget provides a text or image display. +\o \image plastique-lcdnumber.png + The QLCDNumber widget displays a number with LCD-like digits. +\endtable + +\section2 Input Widgets + +\table 100% +\row +\o \image plastique-lineedit.png + The QLineEdit widget is a one-line text editor. +\o \image plastique-dateedit.png + The QDateEdit class provides a widget for editing dates. +\o \image plastique-timeedit.png + The QTimeEdit class provides a widget for editing times. +\o \image plastique-datetimeedit.png + The QDateTimeEdit class provides a widget for editing dates and times. +\endtable + +\table 100% +\row +\o \image plastique-slider.png + The QSlider widget provides a vertical or horizontal slider. +\o \image plastique-combobox.png + The QComboBox widget is a combined button and pop-up list. +\o \image plastique-spinbox.png + The QSpinBox class provides a spin box widget. +\endtable + +\table 100% +\row +\o \image plastique-fontcombobox.png + The QFontComboBox widget is a specialized combobox that enables fonts to be selected from a pop-up list containing previews of available fonts. +\o \image plastique-doublespinbox.png + The QDoubleSpinBox class provides a spin box widget that allows double precision floating point numbers to be entered. +\o \image plastique-horizontalscrollbar.png + The QScrollBar widget provides a vertical or horizontal scroll bar. Here, we show a scroll bar with horizontal orientation. +\endtable + +\table 100% +\row +\o \image plastique-dial.png + The QDial class provides a rounded range control (like a speedometer or potentiometer). +\o \image plastique-textedit.png + The QTextEdit class provides a widget that is used to edit and display both plain and rich text. +\o \image plastique-calendarwidget.png + The QCalendarWidget class provides a monthly calendar widget that can be used to select dates. +\endtable +*/ diff --git a/doc/src/widgets-and-layouts/gallery-windows.qdoc b/doc/src/widgets-and-layouts/gallery-windows.qdoc new file mode 100644 index 0000000000..59a30bd654 --- /dev/null +++ b/doc/src/widgets-and-layouts/gallery-windows.qdoc @@ -0,0 +1,138 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page gallery-windows.html + + \title Windows Style Widget Gallery + \ingroup gallery + + This page shows some of the widgets available in Qt + when configured to use the "windows" style. + +\section2 Buttons + +\table 100% +\row +\o \image windows-pushbutton.png + \caption The QPushButton widget provides a command button. +\o \image windows-toolbutton.png + \caption The QToolButton class provides a quick-access button to commands + or options, usually used inside a QToolBar. +\endtable + +\table 100% +\row +\o \image windows-checkbox.png + \caption The QCheckBox widget provides a checkbox with a text label. +\o \image windows-radiobutton.png + \caption The QRadioButton widget provides a radio button with a text or pixmap label. +\endtable + +\section2 Containers + +\table 100% +\row +\o \image windows-groupbox.png + The The QGroupBox widget provides a group box frame with a title. +\o \image windows-tabwidget.png + The QTabWidget class provides a stack of tabbed widgets. +\o \image windows-frame.png + The QFrame widget provides a simple decorated container for other widgets. +\o \image windows-toolbox.png + The QToolBox class provides a column of tabbed widget items. +\endtable + +\section2 Item Views + +\table 100% +\row +\o \image windows-listview.png + The QListView class provides a default model/view implementation of a list/icon view. The QListWidget class provides a classic item-based list/icon view. +\o \image windows-treeview.png + The QTreeView class provides a default model/view implementation of a tree view. The QTreeWidget class provides a classic item-based tree view. +\o \image windows-tableview.png + The QTableView class provides a default model/view implementation of a table view. The QTableWidget class provides a classic item-based table view.\o +\o +\endtable + +\section2 Display Widgets + +\table 100% +\row +\o \image windows-progressbar.png + The QProgressBar widget provides a horizontal progress bar. +\o \image windows-label.png + The QLabel widget provides a text or image display. +\o \image windows-lcdnumber.png + The QLCDNumber widget displays a number with LCD-like digits. +\endtable + +\section2 Input Widgets + +\table 100% +\row +\o \image windows-lineedit.png + The QLineEdit widget is a one-line text editor. +\o \image windows-dateedit.png + The QDateEdit class provides a widget for editing dates. +\o \image windows-timeedit.png + The QTimeEdit class provides a widget for editing times. +\o \image windows-datetimeedit.png + The QDateTimeEdit class provides a widget for editing dates and times. +\endtable + +\table 100% +\row +\o \image windows-slider.png + The QSlider widget provides a vertical or horizontal slider. +\o \image windows-combobox.png + The QComboBox widget is a combined button and pop-up list. +\o \image windows-spinbox.png + The QSpinBox class provides a spin box widget. +\endtable + +\table 100% +\row +\o \image windows-fontcombobox.png + The QFontComboBox widget is a specialized combobox that enables fonts to be selected from a pop-up list containing previews of available fonts. +\o \image windows-doublespinbox.png + The QDoubleSpinBox class provides a spin box widget that allows double precision floating point numbers to be entered. +\o \image windows-horizontalscrollbar.png + The QScrollBar widget provides a vertical or horizontal scroll bar. Here, we show a scroll bar with horizontal orientation. +\endtable + +\table 100% +\row +\o \image windows-dial.png + The QDial class provides a rounded range control (like a speedometer or potentiometer). +\o \image windows-textedit.png + The QTextEdit class provides a widget that is used to edit and display both plain and rich text. +\o \image windows-calendarwidget.png + The QCalendarWidget class provides a monthly calendar widget that can be used to select dates. +\endtable +*/ diff --git a/doc/src/widgets-and-layouts/gallery-windowsvista.qdoc b/doc/src/widgets-and-layouts/gallery-windowsvista.qdoc new file mode 100644 index 0000000000..5ca4a52b78 --- /dev/null +++ b/doc/src/widgets-and-layouts/gallery-windowsvista.qdoc @@ -0,0 +1,138 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page gallery-windowsvista.html + + \title Windows Vista Style Widget Gallery + \ingroup gallery + + This page shows some of the widgets available in Qt + when configured to use the "windowsvista" style. + +\section2 Buttons + +\table 100% +\row +\o \image windowsvista-pushbutton.png + \caption The QPushButton widget provides a command button. +\o \image windowsvista-toolbutton.png + \caption The QToolButton class provides a quick-access button to commands + or options, usually used inside a QToolBar. +\endtable + +\table 100% +\row +\o \image windowsvista-checkbox.png + \caption The QCheckBox widget provides a checkbox with a text label. +\o \image windowsvista-radiobutton.png + \caption The QRadioButton widget provides a radio button with a text or pixmap label. +\endtable + +\section2 Containers + +\table 100% +\row +\o \image windowsvista-groupbox.png + The The QGroupBox widget provides a group box frame with a title. +\o \image windowsvista-tabwidget.png + The QTabWidget class provides a stack of tabbed widgets. +\o \image windowsvista-frame.png + The QFrame widget provides a simple decorated container for other widgets. +\o \image windowsvista-toolbox.png + The QToolBox class provides a column of tabbed widget items. +\endtable + +\section2 Item Views + +\table 100% +\row +\o \image windowsvista-listview.png + The QListView class provides a default model/view implementation of a list/icon view. The QListWidget class provides a classic item-based list/icon view. +\o \image windowsvista-treeview.png + The QTreeView class provides a default model/view implementation of a tree view. The QTreeWidget class provides a classic item-based tree view. +\o \image windowsvista-tableview.png + The QTableView class provides a default model/view implementation of a table view. The QTableWidget class provides a classic item-based table view.\o +\o +\endtable + +\section2 Display Widgets + +\table 100% +\row +\o \image windowsvista-progressbar.png + The QProgressBar widget provides a horizontal progress bar. +\o \image windowsvista-label.png + The QLabel widget provides a text or image display. +\o \image windowsvista-lcdnumber.png + The QLCDNumber widget displays a number with LCD-like digits. +\endtable + +\section2 Input Widgets + +\table 100% +\row +\o \image windowsvista-lineedit.png + The QLineEdit widget is a one-line text editor. +\o \image windowsvista-dateedit.png + The QDateEdit class provides a widget for editing dates. +\o \image windowsvista-timeedit.png + The QTimeEdit class provides a widget for editing times. +\o \image windowsvista-datetimeedit.png + The QDateTimeEdit class provides a widget for editing dates and times. +\endtable + +\table 100% +\row +\o \image windowsvista-slider.png + The QSlider widget provides a vertical or horizontal slider. +\o \image windowsvista-combobox.png + The QComboBox widget is a combined button and pop-up list. +\o \image windowsvista-spinbox.png + The QSpinBox class provides a spin box widget. +\endtable + +\table 100% +\row +\o \image windowsvista-fontcombobox.png + The QFontComboBox widget is a specialized combobox that enables fonts to be selected from a pop-up list containing previews of available fonts. +\o \image windowsvista-doublespinbox.png + The QDoubleSpinBox class provides a spin box widget that allows double precision floating point numbers to be entered. +\o \image windowsvista-horizontalscrollbar.png + The QScrollBar widget provides a vertical or horizontal scroll bar. Here, we show a scroll bar with horizontal orientation. +\endtable + +\table 100% +\row +\o \image windowsvista-dial.png + The QDial class provides a rounded range control (like a speedometer or potentiometer). +\o \image windowsvista-textedit.png + The QTextEdit class provides a widget that is used to edit and display both plain and rich text. +\o \image windowsvista-calendarwidget.png + The QCalendarWidget class provides a monthly calendar widget that can be used to select dates. +\endtable +*/ diff --git a/doc/src/widgets-and-layouts/gallery-windowsxp.qdoc b/doc/src/widgets-and-layouts/gallery-windowsxp.qdoc new file mode 100644 index 0000000000..11d615911a --- /dev/null +++ b/doc/src/widgets-and-layouts/gallery-windowsxp.qdoc @@ -0,0 +1,138 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page gallery-windowsxp.html + + \title Windows XP Style Widget Gallery + \ingroup gallery + + This page shows some of the widgets available in Qt + when configured to use the "windowsxp" style. + +\section2 Buttons + +\table 100% +\row +\o \image windowsxp-pushbutton.png + \caption The QPushButton widget provides a command button. +\o \image windowsxp-toolbutton.png + \caption The QToolButton class provides a quick-access button to commands + or options, usually used inside a QToolBar. +\endtable + +\table 100% +\row +\o \image windowsxp-checkbox.png + \caption The QCheckBox widget provides a checkbox with a text label. +\o \image windowsxp-radiobutton.png + \caption The QRadioButton widget provides a radio button with a text or pixmap label. +\endtable + +\section2 Containers + +\table 100% +\row +\o \image windowsxp-groupbox.png + The The QGroupBox widget provides a group box frame with a title. +\o \image windowsxp-tabwidget.png + The QTabWidget class provides a stack of tabbed widgets. +\o \image windowsxp-frame.png + The QFrame widget provides a simple decorated container for other widgets. +\o \image windowsxp-toolbox.png + The QToolBox class provides a column of tabbed widget items. +\endtable + +\section2 Item Views + +\table 100% +\row +\o \image windowsxp-listview.png + The QListView class provides a default model/view implementation of a list/icon view. The QListWidget class provides a classic item-based list/icon view. +\o \image windowsxp-treeview.png + The QTreeView class provides a default model/view implementation of a tree view. The QTreeWidget class provides a classic item-based tree view. +\o \image windowsxp-tableview.png + The QTableView class provides a default model/view implementation of a table view. The QTableWidget class provides a classic item-based table view.\o +\o +\endtable + +\section2 Display Widgets + +\table 100% +\row +\o \image windowsxp-progressbar.png + The QProgressBar widget provides a horizontal progress bar. +\o \image windowsxp-label.png + The QLabel widget provides a text or image display. +\o \image windowsxp-lcdnumber.png + The QLCDNumber widget displays a number with LCD-like digits. +\endtable + +\section2 Input Widgets + +\table 100% +\row +\o \image windowsxp-lineedit.png + The QLineEdit widget is a one-line text editor. +\o \image windowsxp-dateedit.png + The QDateEdit class provides a widget for editing dates. +\o \image windowsxp-timeedit.png + The QTimeEdit class provides a widget for editing times. +\o \image windowsxp-datetimeedit.png + The QDateTimeEdit class provides a widget for editing dates and times. +\endtable + +\table 100% +\row +\o \image windowsxp-slider.png + The QSlider widget provides a vertical or horizontal slider. +\o \image windowsxp-combobox.png + The QComboBox widget is a combined button and pop-up list. +\o \image windowsxp-spinbox.png + The QSpinBox class provides a spin box widget. +\endtable + +\table 100% +\row +\o \image windowsxp-fontcombobox.png + The QFontComboBox widget is a specialized combobox that enables fonts to be selected from a pop-up list containing previews of available fonts. +\o \image windowsxp-doublespinbox.png + The QDoubleSpinBox class provides a spin box widget that allows double precision floating point numbers to be entered. +\o \image windowsxp-horizontalscrollbar.png + The QScrollBar widget provides a vertical or horizontal scroll bar. Here, we show a scroll bar with horizontal orientation. +\endtable + +\table 100% +\row +\o \image windowsxp-dial.png + The QDial class provides a rounded range control (like a speedometer or potentiometer). +\o \image windowsxp-textedit.png + The QTextEdit class provides a widget that is used to edit and display both plain and rich text. +\o \image windowsxp-calendarwidget.png + The QCalendarWidget class provides a monthly calendar widget that can be used to select dates. +\endtable +*/ diff --git a/doc/src/widgets-and-layouts/gallery.qdoc b/doc/src/widgets-and-layouts/gallery.qdoc new file mode 100644 index 0000000000..ec33226735 --- /dev/null +++ b/doc/src/widgets-and-layouts/gallery.qdoc @@ -0,0 +1,84 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \group gallery + \title Qt Widget Gallery + \brief Qt widgets shown in different styles on various platforms. + + Qt's support for widget styles and themes enables your application to fit in + with the native desktop enviroment. Below, you can find links to the various + widget styles that are supplied with Qt 4. + + \table + \row + \o \image plastique-tabwidget.png Plastique Style Widget Gallery + \caption \l{Plastique Style Widget Gallery} + + The Plastique style is provided by QPlastiqueStyle. + \o \image windowsxp-tabwidget.png Windows XP Style Widget Gallery + \caption \l{Windows XP Style Widget Gallery} + + The Windows XP style is provided by QWindowsXPStyle. + \o \image windows-tabwidget.png Windows Style Widget Gallery + \caption \l{Windows Style Widget Gallery} + + The Windows style is provided by QWindowsStyle. + \endtable + + \table + \row + \o \image macintosh-tabwidget.png Macintosh Style Widget Gallery + \caption \l{Macintosh Style Widget Gallery} + + The Macintosh style is provided by QMacStyle. + \o \image cleanlooks-tabwidget.png Cleanlooks Style Widget Gallery + \caption \l{Cleanlooks Style Widget Gallery} + + The Cleanlooks style is provided by QCleanlooksStyle. + \o \image windowsvista-tabwidget.png Windows Vista Style Widget Gallery + \caption \l{Windows Vista Style Widget Gallery} + + The Windows Vista style is provided by QWindowsVistaStyle. + \endtable + + \table + \row + \o \image gtk-tabwidget.png GTK Style Widget Gallery + \caption \l{GTK Style Widget Gallery} + + The GTK style is provided by QGtkStyle. + \o \image motif-tabwidget.png Motif Style Widget Gallery + \caption \l{Motif Style Widget Gallery} + + The Motif style is provided by QMotifStyle. + \o \image cde-tabwidget.png CDE Style Widget Gallery + \caption \l{CDE Style Widget Gallery} + + The Common Desktop Environment style is provided by QCDEStyle. + \endtable +*/ diff --git a/doc/src/widgets-and-layouts/layout.qdoc b/doc/src/widgets-and-layouts/layout.qdoc new file mode 100644 index 0000000000..1d8214bf15 --- /dev/null +++ b/doc/src/widgets-and-layouts/layout.qdoc @@ -0,0 +1,396 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \group geomanagement + \title Layout Classes +*/ + +/*! + \page layout.html + \title Layout Management + \ingroup qt-basic-concepts + \ingroup qt-gui-concepts + \brief A tour of the standard layout managers and an introduction to custom + layouts. + + \previouspage Widgets and Layouts + \contentspage Widgets and Layouts + \nextpage {Styles and Style Aware Widgets}{Styles} + + \ingroup frameworks-technologies + + The Qt layout system provides a simple and powerful way of automatically + arranging child widgets within a widget to ensure that they make good use + of the available space. + + \tableofcontents + + \section1 Introduction + + Qt includes a set of layout management classes that are used to describe + how widgets are laid out in an application's user interface. These layouts + automatically position and resize widgets when the amount of space + available for them changes, ensuring that they are consistently arranged + and that the user interface as a whole remains usable. + + All QWidget subclasses can use layouts to manage their children. The + QWidget::setLayout() function applies a layout to a widget. When a layout + is set on a widget in this way, it takes charge of the following tasks: + + \list + \o Positioning of child widgets. + \o Sensible default sizes for windows. + \o Sensible minimum sizes for windows. + \o Resize handling. + \o Automatic updates when contents change: + \list + \o Font size, text or other contents of child widgets. + \o Hiding or showing a child widget. + \o Removal of child widgets. + \endlist + \endlist + + \section1 Qt's Layout Classes + + Qt's layout classes were designed for hand-written C++ code, allowing + measurements to be specified in pixels for simplicity, so they are easy to + understand and use. The code generated for forms created using \QD also + uses the layout classes. \QD is useful to use when experimenting with the + design of a form since it avoids the compile, link and run cycle usually + involved in user interface development. + + \annotatedlist geomanagement + + \section1 Horizontal, Vertical, Grid, and Form Layouts + + The easiest way to give your widgets a good layout is to use the built-in + layout managers: QHBoxLayout, QVBoxLayout, QGridLayout, and QFormLayout. + These classes inherit from QLayout, which in turn derives from QObject (not + QWidget). They take care of geometry management for a set of widgets. To + create more complex layouts, you can nest layout managers inside each other. + + \list + \o A QHBoxLayout lays out widgets in a horizontal row, from left to + right (or right to left for right-to-left languages). + \image qhboxlayout-with-5-children.png + + \o A QVBoxLayout lays out widgets in a vertical column, from top to + bottom. + \image qvboxlayout-with-5-children.png + + \o A QGridLayout lays out widgets in a two-dimensional grid. Widgets + can occupy multiple cells. + \image qgridlayout-with-5-children.png + + \o A QFormLayout lays out widgets in a 2-column descriptive label- + field style. + \image qformlayout-with-6-children.png + \endlist + + + \section2 Laying Out Widgets in Code + + The following code creates a QHBoxLayout that manages the geometry of five + \l{QPushButton}{QPushButtons}, as shown on the first screenshot above: + + \snippet doc/src/snippets/layouts/layouts.cpp 0 + \snippet doc/src/snippets/layouts/layouts.cpp 1 + \snippet doc/src/snippets/layouts/layouts.cpp 2 + \codeline + \snippet doc/src/snippets/layouts/layouts.cpp 3 + \snippet doc/src/snippets/layouts/layouts.cpp 4 + \snippet doc/src/snippets/layouts/layouts.cpp 5 + + The code for QVBoxLayout is identical, except the line where the layout is + created. The code for QGridLayout is a bit different, because we need to + specify the row and column position of the child widget: + + \snippet doc/src/snippets/layouts/layouts.cpp 12 + \snippet doc/src/snippets/layouts/layouts.cpp 13 + \snippet doc/src/snippets/layouts/layouts.cpp 14 + \codeline + \snippet doc/src/snippets/layouts/layouts.cpp 15 + \snippet doc/src/snippets/layouts/layouts.cpp 16 + \snippet doc/src/snippets/layouts/layouts.cpp 17 + + The third QPushButton spans 2 columns. This is possible by specifying 2 as + the fifth argument to QGridLayout::addWidget(). + + QFormLayout will add two widgets on a row, commonly a QLabel and a QLineEdit + to create forms. Adding a QLabel and a QLineEdit on the same row will set + the QLineEdit as the QLabel's buddy. The following code will use the + QFormLayout to place three \l{QPushButton}{QPushButtons} and a corresponding + QLineEdit on a row. + + \snippet doc/src/snippets/layouts/layouts.cpp 18 + \snippet doc/src/snippets/layouts/layouts.cpp 19 + \snippet doc/src/snippets/layouts/layouts.cpp 20 + \codeline + \snippet doc/src/snippets/layouts/layouts.cpp 21 + \snippet doc/src/snippets/layouts/layouts.cpp 22 + \snippet doc/src/snippets/layouts/layouts.cpp 23 + + + \section2 Tips for Using Layouts + + When you use a layout, you do not need to pass a parent when constructing + the child widgets. The layout will automatically reparent the widgets + (using QWidget::setParent()) so that they are children of the widget on + which the layout is installed. + + \note Widgets in a layout are children of the widget on which the layout + is installed, \e not of the layout itself. Widgets can only have other + widgets as parent, not layouts. + + You can nest layouts using \c addLayout() on a layout; the inner layout + then becomes a child of the layout it is inserted into. + + + \section1 Adding Widgets to a Layout + + When you add widgets to a layout, the layout process works as follows: + + \list 1 + \o All the widgets will initially be allocated an amount of space in + accordance with their QWidget::sizePolicy() and + QWidget::sizeHint(). + + \o If any of the widgets have stretch factors set, with a value + greater than zero, then they are allocated space in proportion to + their stretch factor (explained below). + + \o If any of the widgets have stretch factors set to zero they will + only get more space if no other widgets want the space. Of these, + space is allocated to widgets with an + \l{QSizePolicy::Expanding}{Expanding} size policy first. + + \o Any widgets that are allocated less space than their minimum size + (or minimum size hint if no minimum size is specified) are + allocated this minimum size they require. (Widgets don't have to + have a minimum size or minimum size hint in which case the strech + factor is their determining factor.) + + \o Any widgets that are allocated more space than their maximum size + are allocated the maximum size space they require. (Widgets do not + have to have a maximum size in which case the strech factor is + their determining factor.) + \endlist + + + \section2 Stretch Factors + \keyword stretch factor + + Widgets are normally created without any stretch factor set. When they are + laid out in a layout the widgets are given a share of space in accordance + with their QWidget::sizePolicy() or their minimum size hint whichever is + the greater. Stretch factors are used to change how much space widgets are + given in proportion to one another. + + If we have three widgets laid out using a QHBoxLayout with no stretch + factors set we will get a layout like this: + + \img layout1.png Three widgets in a row + + If we apply stretch factors to each widget, they will be laid out in + proportion (but never less than their minimum size hint), e.g. + + \img layout2.png Three widgets with different stretch factors in a row + + + \section1 Custom Widgets in Layouts + + When you make your own widget class, you should also communicate its layout + properties. If the widget has a one of Qt's layouts, this is already taken + care of. If the widget does not have any child widgets, or uses manual + layout, you can change the behavior of the widget using any or all of the + following mechanisms: + + \list + \o Reimplement QWidget::sizeHint() to return the preferred size of the + widget. + \o Reimplement QWidget::minimumSizeHint() to return the smallest size + the widget can have. + \o Call QWidget::setSizePolicy() to specify the space requirements of + the widget. + \endlist + + Call QWidget::updateGeometry() whenever the size hint, minimum size hint or + size policy changes. This will cause a layout recalculation. Multiple + consecutive calls to QWidget::updateGeometry() will only cause one layout + recalculation. + + If the preferred height of your widget depends on its actual width (e.g., + a label with automatic word-breaking), set the + \l{QSizePolicy::hasHeightForWidth()}{height-for-width} flag in the + widget's \l{QWidget::sizePolicy}{size policy} and reimplement + QWidget::heightForWidth(). + + Even if you implement QWidget::heightForWidth(), it is still a good idea to + provide a reasonable sizeHint(). + + For further guidance when implementing these functions, see the + \e{Qt Quarterly} article + \l{http://doc.qt.nokia.com/qq/qq04-height-for-width.html} + {Trading Height for Width}. + + + \section1 Layout Issues + + The use of rich text in a label widget can introduce some problems to the + layout of its parent widget. Problems occur due to the way rich text is + handled by Qt's layout managers when the label is word wrapped. + + In certain cases the parent layout is put into QLayout::FreeResize mode, + meaning that it will not adapt the layout of its contents to fit inside + small sized windows, or even prevent the user from making the window too + small to be usable. This can be overcome by subclassing the problematic + widgets, and implementing suitable \l{QWidget::}{sizeHint()} and + \l{QWidget::}{minimumSizeHint()} functions. + + In some cases, it is relevant when a layout is added to a widget. When + you set the widget of a QDockWidget or a QScrollArea (with + QDockWidget::setWidget() and QScrollArea::setWidget()), the layout must + already have been set on the widget. If not, the widget will not be + visible. + + + \section1 Manual Layout + + If you are making a one-of-a-kind special layout, you can also make a + custom widget as described above. Reimplement QWidget::resizeEvent() to + calculate the required distribution of sizes and call + \l{QWidget::}{setGeometry()} on each child. + + The widget will get an event of type QEvent::LayoutRequest when the + layout needs to be recalculated. Reimplement QWidget::event() to handle + QEvent::LayoutRequest events. + + + \section1 How to Write A Custom Layout Manager + + An alternative to manual layout is to write your own layout manager by + subclassing QLayout. The \l{layouts/borderlayout}{Border Layout} and + \l{layouts/flowlayout}{Flow Layout} examples show how to do this. + + Here we present an example in detail. The \c CardLayout class is inspired + by the Java layout manager of the same name. It lays out the items (widgets + or nested layouts) on top of each other, each item offset by + QLayout::spacing(). + + To write your own layout class, you must define the following: + \list + \o A data structure to store the items handled by the layout. Each + item is a \link QLayoutItem QLayoutItem\endlink. We will use a + QList in this example. + \o \l{QLayout::}{addItem()}, how to add items to the layout. + \o \l{QLayout::}{setGeometry()}, how to perform the layout. + \o \l{QLayout::}{sizeHint()}, the preferred size of the layout. + \o \l{QLayout::}{itemAt()}, how to iterate over the layout. + \o \l{QLayout::}{takeAt()}, how to remove items from the layout. + \endlist + + In most cases, you will also implement \l{QLayout::}{minimumSize()}. + + + \section2 The Header File (\c card.h) + + \snippet doc/src/snippets/code/doc_src_layout.cpp 0 + + + \section2 The Implementation File (\c card.cpp) + + \snippet doc/src/snippets/code/doc_src_layout.cpp 1 + + First we define \c{count()} to fetch the number of items in the list. + + \snippet doc/src/snippets/code/doc_src_layout.cpp 2 + + Then we define two functions that iterate over the layout: \c{itemAt()} + and \c{takeAt()}. These functions are used internally by the layout system + to handle deletion of widgets. They are also available for application + programmers. + + \c{itemAt()} returns the item at the given index. \c{takeAt()} removes the + item at the given index, and returns it. In this case we use the list index + as the layout index. In other cases where we have a more complex data + structure, we may have to spend more effort defining a linear order for the + items. + + \snippet doc/src/snippets/code/doc_src_layout.cpp 3 + + \c{addItem()} implements the default placement strategy for layout items. + This function must be implemented. It is used by QLayout::add(), by the + QLayout constructor that takes a layout as parent. If your layout has + advanced placement options that require parameters, you must provide extra + access functions such as the row and column spanning overloads of + QGridLayout::addItem(), QGridLayout::addWidget(), and + QGridLayout::addLayout(). + + \snippet doc/src/snippets/code/doc_src_layout.cpp 4 + + The layout takes over responsibility of the items added. Since QLayoutItem + does not inherit QObject, we must delete the items manually. In the + destructor, we remove each item from the list using \c{takeAt()}, and + then delete it. + + \snippet doc/src/snippets/code/doc_src_layout.cpp 5 + + The \c{setGeometry()} function actually performs the layout. The rectangle + supplied as an argument does not include \c{margin()}. If relevant, use + \c{spacing()} as the distance between items. + + \snippet doc/src/snippets/code/doc_src_layout.cpp 6 + + \c{sizeHint()} and \c{minimumSize()} are normally very similar in + implementation. The sizes returned by both functions should include + \c{spacing()}, but not \c{margin()}. + + \snippet doc/src/snippets/code/doc_src_layout.cpp 7 + + + \section2 Further Notes + + \list + \o This custom layout does not handle height for width. + \o We ignore QLayoutItem::isEmpty(); this means that the layout will + treat hidden widgets as visible. + \o For complex layouts, speed can be greatly increased by caching + calculated values. In that case, implement + QLayoutItem::invalidate() to mark the cached data is dirty. + \o Calling QLayoutItem::sizeHint(), etc. may be expensive. So, you + should store the value in a local variable if you need it again + later within in the same function. + \o You should not call QLayoutItem::setGeometry() twice on the same + item in the same function. This call can be very expensive if the + item has several child widgets, because the layout manager must do + a complete layout every time. Instead, calculate the geometry and + then set it. (This does not only apply to layouts, you should do + the same if you implement your own resizeEvent(), for example.) + \endlist +*/ + diff --git a/doc/src/widgets-and-layouts/styles.qdoc b/doc/src/widgets-and-layouts/styles.qdoc new file mode 100644 index 0000000000..9e9dd64610 --- /dev/null +++ b/doc/src/widgets-and-layouts/styles.qdoc @@ -0,0 +1,2102 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \group appearance + \title Widget Appearance and Style + \brief Classes used for customizing UI appearance and style. +*/ + +/*! + \page style-reference.html + \title Styles and Style Aware Widgets + \ingroup qt-gui-concepts + \brief Styles and the styling of widgets. + + Styles (classes that inherit QStyle) draw on behalf of widgets + and encapsulate the look and feel of a GUI. The QStyle class is + an abstract base class that encapsulates the look and feel of a + GUI. Qt's built-in widgets use it to perform nearly all of their + drawing, ensuring that they look exactly like the equivalent + native widgets. + + Several styles are built into Qt (e.g., windows style and motif style). + Other styles are only available on specific platforms (such as + the windows XP style). Custom styles are made available as plugins + or by creating an instance of the style class in an application and + setting it with QApplication::setStyle(). + + To implement a new style, you inherit one of Qt's existing styles + - the one most resembling the style you want to create - and + reimplement a few virtual functions. This process is somewhat + involved, and we therefore provide this overview. We give a + step-by-step walkthrough of how to style individual Qt widgets. + We will examine the QStyle virtual functions, member variables, + and enumerations. + + The part of this document that does not concern the styling of + individual widgets is meant to be read sequentially because later + sections tend to depend on earlier ones. The description of the + widgets can be used for reference while implementing a style. + However, you may need to consult the Qt source code in some cases. + The sequence in the styling process should become clear after + reading this document, which will aid you in locating relevant code. + + To develop style aware widgets (i.e., widgets that conform to + the style in which they are drawn), you need to draw them using the + current style. This document shows how widgets draw themselves + and which possibilities the style gives them. + + \section1 Classes for Widget Styling + + These classes are used to customize an application's appearance and + style. + + \annotatedlist appearance + + \section1 The QStyle implementation + + The API of QStyle contains functions that draw the widgets, static + helper functions to do common and difficult tasks (e.g., + calculating the position of slider handles) and functions to do + the various calculations necessary while drawing (e.g., for the + widgets to calculate their size hints). The style also help some + widgets with the layout of their contents. In addition, it creates + a QPalette that contains \l{QBrush}es to draw with. + + QStyle draws graphical elements; an element is a widget or a + widget part like a push button bevel, a window frame, or a scroll + bar. Most draw functions now 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 + + When a widget asks a style to draw an element, it provides the style + with a QStyleOption, which is a class that contains the information + necessary for drawing. Thanks to QStyleOption, it is possible to make + QStyle draw widgets without linking in any code for the widget. This + makes it possible to use \l{QStyle}'s draw functions on any paint + device, i.e., you can draw a combobox on any widget, not just on a + QComboBox. + + 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. + + We will in the course of this section look at the style elements, + the style options, and the functions of QStyle. Finally, we describe + how the palette is used. + + Items in item views is drawn by \l{Delegate Classes}{delegates} in + Qt. The item view headers are still drawn by the style. Qt's + default delegate, QStyledItemDelegate, draws its items partially + through the current style; it draws the check box indicators and + calculate bounding rectangles for the elements of which the item + consists. In this document, we only describe how to implement a + QStyle subclass. If you wish to add support for other datatypes + than those supported by the QStyledItemDelegate, you need to + implement a custom delegate. Note that delegates must be set + programmatically for each individual widget (i.e., default + delegates cannot be provided as plugins). + + \section2 The Style Elements + + A style element is a graphical part of a GUI. A widget consists + of a hierarchy (or tree) of style elements. For instance, when a + style receives a request to draw a push button (from QPushButton, + for example), it draws a label (text and icon), a button bevel, + and a focus frame. The button bevel, in turn, consists of a frame + around the bevel and two other elements, which we will look at + later. Below is a conceptual illustration of the push button + element tree. We will see the actual tree for QPushButton when we + go through the individual widgets. + + \image javastyle/conceptualpushbuttontree.png + + Widgets are not necessarily drawn by asking the style to draw + only one element. Widgets can make several calls to the style to + draw different elements. An example is QTabWidget, which draws its + tabs and frame individually. + + There are three element types: primitive elements, control + elements, and complex control elements. The elements are defined + by the \l{QStyle::}{ComplexControl}, \l{QStyle::}{ControlElement}, + and \l{QStyle::}{PrimitiveElement} enums. The values of + each element enum has a prefix to identify their type: \c{CC_} for + complex elements, \c{CE_} for control elements, and \c{PE_} for + primitive elements. We will in the following three sections see what + defines the different elements and see examples of widgets that use + them. + + The QStyle class description contains a list of these elements and + their roles in styling widgets. We will see how they are used when + we style individual widgets. + + \section3 Primitive Elements + + Primitive elements are GUI elements that are common and often used + by several widgets. Examples of these are frames, button bevels, + and arrows for spin boxes, scroll bars, and combo boxes. + Primitive elements cannot exist on their own: they are always part + of a larger construct. They take no part in the interaction with + the user, but are passive decorations in the GUI. + + \section3 Control Elements + + A control element performs an action or displays information + to the user. Examples of control elements are push buttons, check + boxes, and header sections in tables and tree views. Control + elements are not necessarily complete widgets such as push + buttons, but can also be widget parts such as tab bar tabs and + scroll bar sliders. They differ from primitive elements in that + they are not passive, but fill a function in the interaction with + the user. Controls that consist of several elements often use the + style to calculate the bounding rectangles of the elements. The + available sub elements are defined by the \l{QStyle::}{SubElement} + enum. This enum is only used for calculating bounding rectangles, + and sub elements are as such not graphical elements to be drawn + like primitive, control, and complex elements. + + \section3 Complex Control Elements + + Complex control elements contain sub controls. Complex controls + behave differently depending on where the user handles them with + the mouse and which keyboard keys are pressed. This is dependent + on which sub control (if any) that the mouse is over or received a + mouse press. Examples of complex controls are scroll bars and + combo boxes. With a scroll bar, you can use the mouse to move the + slider and press the line up and line down buttons. The available + sub controls are defined by the \l{QStyle}{SubControl} enum. + + In addition to drawing, the style needs to provide the widgets + with information on which sub control (if any) a mouse press was + made on. For instance, a QScrollBar needs to know if the user + pressed the slider, the slider groove, or one of the buttons. + + Note that sub controls are not the same as the control elements + described in the previous section. You cannot use the style to + draw a sub control; the style will only calculate the bounding + rectangle in which the sub control should be drawn. It is common, + though, that complex elements use control and primitive elements + to draw their sub controls, which is an approach that is + frequently used by the built-in styles in Qt and also the Java + style. For instance, the Java style uses PE_IndicatorCheckBox to + draw the check box in group boxes (which is a sub control of + CC_GroupBox). Some sub controls have an equivalent control element, + e.g., the scroll bar slider (SC_SCrollBarSlider and + CE_ScrollBarSlider). + + \section3 Other QStyle Tasks + + The style elements and widgets, as mentioned, use the style to + calculate bounding rectangles of sub elements and sub controls, + and pixel metrics, which is a style dependent size in screen + pixels, for measures when drawing. The available rectangles and + pixel metrics are represented by three enums in QStyle: + \l{QStyle::}{SubElement}, \l{QStyle::}{SubControl}, and + \l{QStyle::}{PixelMetric}. Values of the enums can easily by + identified as they start with SE_, SC_ and PM_. + + The style also contain a set of style hints, which is + represented as values in the \l{QStyle::}{StyleHint} enum. All + widgets do not have the same functionality and look in the + different styles. For instance, when the menu items in a menu do not + fit in a single column on the screen, some styles support + scrolling while others draw more than one column to fit all items. + + A style usually has a set of standard images (such as a warning, a + question, and an error image) for message boxes, file dialogs, + etc. QStyle provides the \l{QStyle::}{StandardPixmap} enum. Its + values represent the standard images. Qt's widgets use these, so + when you implement a custom style you should supply the images + used by the style that is being implemented. + + The style calculates the spacing between widgets in layouts. There + are two ways the style can handle these calculations. You can set + the PM_LayoutHorizontalSpacing and PM_LayoutVerticalSpacing, which + is the way the java style does it (through QCommonStyle). + Alternatively, you can implement QStyle::layoutSpacing() and + QStyle::layoutSpacingImplementation() if you need more control over + this part of the layout. In these functions you can calculate the + spacing based on control types (QSizePolicy::ControlType) for + different size policies (QSizePolicy::Policy) and also the style + option for the widget in question. + + \section2 Style Options + + The sub-classes of QStyleOption contain all information necessary + to style the individual elements. Style options are instantiated - + usually on the stack - and filled out by the caller of the QStyle + function. Depending on what is drawn the style will expect + different a different style option class. For example, the + QStyle::PE_FrameFocusRect element expects a QStyleOptionFocusRect + argument, and it's possible to create custom subclasses that a + custom style can use. The style options keep public variables + for performance reasons. + + The widgets can be in a number of different states, which are + defined by the \l{QStyle::}{State} enum. Some of the state flags have + different meanings depending on the widget, but others are common + for all widgets like State_Disabled. It is QStyleOption that sets + the common states with QStyleOption::initFrom(); the rest of the + states are set by the individual widgets. + + Most notably, the style options contain the palette and bounding + rectangles of the widgets to be drawn. Most widgets have + specialized style options. QPushButton and QCheckBox, for + instance, use QStyleOptionButton as style option, which contain + the text, icon, and the size of their icon. The exact contents of + all options are described when we go through individual widgets. + + When reimplementing QStyle functions that take a + QStyleOption parameter, you often need to cast the + QStyleOption to a subclass (e.g., QStyleOptionFocusRect). For + safety, you can use qstyleoption_cast() to ensure that the + pointer type is correct. If the object isn't of the right type, + qstyleoption_cast() returns 0. For example: + + \snippet doc/src/snippets/code/doc_src_qt4-styles.cpp 0 + + The following code snippet illustrates how to use QStyle to + draw the focus rectangle from a custom widget's paintEvent(): + + \snippet doc/src/snippets/code/doc_src_qt4-styles.cpp 1 + + The next example shows how to derive from an existing style to + customize the look of a graphical element: + + \snippet doc/src/snippets/customstyle/customstyle.h 0 + \codeline + \snippet doc/src/snippets/customstyle/customstyle.cpp 2 + \snippet doc/src/snippets/customstyle/customstyle.cpp 3 + \snippet doc/src/snippets/customstyle/customstyle.cpp 4 + + \section2 QStyle Functions + + The QStyle class defines three functions for drawing the primitive, + control, and complex elements: + \l{QStyle::}{drawPrimitive()}, + \l{QStyle::}{drawControl()}, and + \l{QStyle::}{drawComplexControl()}. The functions takes the + following parameters: + + \list + \o the enum value of the element to draw + \o a QStyleOption which contains the information needed to + draw the element. + \o a QPainter with which to draw the element. + \o a pointer to a QWidget, typically the widget + that the element is painted on. + \endlist + + Not all widgets send a pointer to themselves. If the style + option sent to the function does not contain the information you + need, you should check the widget implementation to see if it + sends a pointer to itself. + + The QStyle class also provides helper functions that are used + when drawing the elements. The \l{QStyle::}{drawItemText()} + function draws text within a specified rectangle and taking a + QPalette as a parameter. The \l{QStyle::}{drawItemPixmap()} + function helps to align a pixmap within a specified bounding + rectangle. + + Other QStyle functions do various calculations for the + functions that draw. The widgets also use these functions for + calculating size hints and also for bounding rectangle + calculations if they draw several style elements themselves. + As with the functions that draw elements the helper functions + typically takes the same arguments. + + \list + \o The \l{QStyle::}{subElementRect()} function takes a + \l{QStyle::}{SubElement} enum value, and calculates a bounding + rectangle for a sub element. The style uses this function to + know where to draw the different parts of an element. This is + mainly done for reuse. If you create a new style, you can use + the same location of sub elements as the super class. + + \o The \l{QStyle::}{subControlRect()} function is used to + calculate bounding rectangles for sub controls in complex + controls. When you implement a new style, you reimplement \c + subControlRect() and calculate the rectangles that are different + from the super class. + + \o The \l{QStyle::}{pixelMetric()} function returns a pixel + metric, which is a style dependent size given in screen + pixels. It takes a value of the \l{QStyle::}{PixelMetric} enum + and returns the correct measure. Note that pixel metrics do + not necessarily have to be static measures, but can be + calculated with, for example, the style option. + + \o The \l{QStyle::}{hitTestComplexControl()} function returns the + sub control that the mouse pointer is over in a complex control. + Usually, this is simply a matter of using + \l{QStyle::}{subControlRect()} to get the bounding rectangles of + the sub controls, and see which rectangle contains the position of + the cursor. + \endlist + + QStyle also have the functions \l{QStyle::}{polish()} and + \l{QStyle::}{unpolish()}. All widgets are sent to the \c polish() + function before being shown and to \c unpolish() when they + are hidden. You can use these functions to set attributes on the + widgets or do other work that is required by your style. For + instance, if you need to know when the mouse is hovering over the + widget, you need to set the \l{Qt::}{WA_Hover} widget attribute. + The State_MouseOver state flag will then be set in the widget's + style options. + + QStyle has a few static helper functions that do some common and + difficult tasks. They can calculate the position of a slider + handle from the value of the slider and transform rectangles + and draw text considering reverse layouts; see the QStyle + class documentation for more details. + + The usual approach when one reimplements QStyle virtual + functions is to do work on elements that are different from the + super class; for all other elements, you can simply use the super + class implementation. + + \section2 The Palette + + Each style provides a color - that is, QBrush - palette that + should be used for drawing the widgets. There is one set of colors + for the different widget states (QPalette::ColorGroup): active + (widgets in the window that has keyboard focus), inactive (widgets + used for other windows), and disabled (widgets that are set + disabled). The states can be found by querying the State_Active + and State_Enabled state flags. Each set contains color certain + roles given by the QPalette::ColorRole enum. The roles describe in + which situations the colors should be used (e.g., for painting + widget backgrounds, text, or buttons). + + How the color roles are used is up to the style. For instance, if + the style uses gradients, one can use a palette color and make it + darker or lighter with QColor::darker() and QColor::lighter() to + create the gradient. In general, if you need a brush that is not + provided by the palette, you should try to derive it from one. + + QPalette, which provides the palette, stores colors for + different widget states and color roles. The palette for a style + is returned by \l{QStyle::}{standardPalette()}. The standard + palette is not installed automatically when a new style is set + on the application (QApplication::setStyle()) or widget + (QWidget::setStyle()), so you must set the palette yourself + with (QApplication::setPalette()) or (QWidget::setPalette()). + + It is not recommended to hard code colors as applications and + individual widgets can set their own palette and also use the + styles palette for drawing. Note that none of Qt's widgets set + their own palette. The java style does hard code some colors, but + its author looks past this in silence. Of course, it is not + intended that the style should look good with any palette. + + \section2 Implementation Issues + + When you implement styles, there are several issues to + consider. We will give some hints and advice on implementation + here. + + When implementing styles, it is necessary to look through the + code of the widgets and code of the base class and its ancestors. + This is because the widgets use the style differently, because the + implementation in the different styles virtual functions can + affect the state of the drawing (e.g., by altering the QPainter + state without restoring it and drawing some elements without using + the appropriate pixel metrics and sub elements). + + It is recommended that the styles do not alter the proposed size + of widgets with the QStyle::sizeFromContents() function but let + the QCommonStyle implementation handle it. If changes need to be + made, you should try to keep them small; application development + may be difficult if the layout of widgets looks considerably + different in the various styles. + + We recommend using the QPainter directly for drawing, i.e., not + use pixmaps or images. This makes it easier for the style conform + to the palette (although you can set your own color table on a + QImage with \l{QImage::}{setColorTable()}). + + It is, naturally, possible to draw elements without using the + style to draw the sub elements as intended by Qt. This is + discouraged as custom widgets may depend on these sub elements to + be implemented correctly. The widget walkthrough shows how Qt + uses the sub elements. + + \section1 Java Style + + We have implemented a style that resembles the Java default look + and feel (previously known as Metal). We have done this as it is + relatively simple to implement and we wanted to build a style for + this overview document. To keep it simple and not to extensive, we + have simplified the style somewhat, but Qt is perfectly able to + make an exact copy of the style. However, there are no concrete + plans to implement the style as a part of Qt. + + In this section we will have a look at some implementation + issues. Finally, we will see a complete example on the styling of + a Java widget. We will continue to use the java style + throughout the document for examples and widget images. The + implementation itself is somewhat involved, and it is not + intended that you should read through it. + + \section2 Design and Implementation + + The first step in designing the style was to select the base + class. We chose to subclass QWindowsStyle. This class implements + most of the functionality we need other than performing the actual + drawing. Also, windows and java share layout of sub controls for + several of the complex controls (which reduces the amount of code + required considerably). + + The style is implemented in one class. We have done this + because we find it convenient to keep all code in one file. Also, + it is an advantage with regards to optimization as we instantiate + less objects. We also keep the number of functions at a minimum by + using switches to identify which element to draw in the functions. + This results in large functions, but since we divide the code for + each element in the switches, the code should still be easy to + read. + + \section2 Limitations and Differences from Java + + We have not fully implemented every element in the Java style. + This way, we have reduced the amount and complexity of the code. + In general, the style was intended as a practical example for + this style overview document, and not to be a part of Qt + itself. + + Not all widgets have every state implemented. This goes for + states that are common, e.g., State_Disabled. Each state is, + however, implemented for at least one widget. + + We have only implemented ticks below the slider. Flat push + buttons are also left out. We do not handle the case where the + title bars and dock window titles grows to small for their + contents, but simply draw sub controls over each other. + + We have not tried to emulate the Java fonts. Java and Qt use very + different font engines, so we don't consider it worth the effort + as we only use the style as an example for this overview. + + We have hardcoded the colors (we don't use the QPalette) for + the linear gradients, which are used, for example, for button + bevels, tool bars, and check boxes. This is because the Java + palette cannot produce these colors. Java does not change these + colors based on widget color group or role anyway (they are not + dependent on the palette), so it does not present a problem in any + case. + + It is Qt's widgets that are styled. Some widgets do not exist + at all in Java, e.g., QToolBox. Others contain elements that the + Java widgets don't. The tree widget is an example of the latter in + which Java's JTree does not have a header. + + The style does not handle reverse layouts. We assume that the + layout direction is left to right. QWindowsStyle handles reverse + widgets; if we implemented reverse layouts, widgets that we change + the position of sub elements, or handle text alignment in labels + our selves would need to be updated. + + \section2 Styling Java Check Boxes + + As an example, we will examine the styling of check boxes in the + java style. We describe the complete process and print all code in + both the java style and Qt classes involved. In the rest of this + document, we will not examine the source code of the individual + widgets. Hopefully, this will give you an idea on how to search + through the code if you need to check specific implementation + details; most widgets follow the same structure as the check + boxes. We have edited the QCommonStyle code somewhat to remove + code that is not directly relevant for check box styling. + + We start with a look at how QCheckBox builds it style option, + which is QStyleOptionButton for checkboxes: + + \snippet doc/src/snippets/code/doc_src_styles.cpp 0 + + First we let QStyleOption set up the option with the information + that is common for all widgets with \c initFrom(). We will look at + this shortly. + + The down boolean is true when the user press the box down; this is + true whether the box is checked or not of the checkbox. The + State_NoChange state is set when we have a tristate checkbox and + it is partially checked. It has State_On if the box is checked and + State_Off if it is unchecked. State_MouseOver is set if the mouse + hovers over the checkbox and the widget has attribute Qt::WA_Hover + set - you set this in QStyle::polish(). In addition, the style + option also contains the text, icon, and icon size of the button. + + \l{QStyleOption::}{initFrom()} sets up the style option with the + attributes that are common for all widgets. We print its + implementation here: + + \snippet doc/src/snippets/code/doc_src_styles.cpp 1 + + The State_Enabled is set when the widget is enabled. When the + widget has focus the State_HasFocus flag is set. Equally, the + State_Active flag is set when the widget is a child of the active + window. The State_MouseOver will only be set if the widget has + the WA_HoverEnabled windows flag set. Notice that keypad + navigation must be enabled in Qt for the State_HasEditFocus to + be included; it is not included by default. + + In addition to setting state flags the QStyleOption contains + other information about the widget: \c direction is the layout + direction of the layout, \c rect is the bounding rectangle of the + widget (the area in which to draw), \c palette is the QPalette + that should be used for drawing the widget, and \c fontMetrics is + the metrics of the font that is used by the widget. + + We give an image of a checkbox and the style option to match + it. + + \image javastyle/checkboxexample.png A java style checkbox + + The above checkbox will have the following state flags in its + style option: + + \table 90% + \header + \o State flag + \o Set + \row + \o State_Sunken + \o Yes + \row + \o State_NoChange + \o No + \row + \o State_On + \o Yes + \row + \o State_Off + \o No + \row + \o State_MouseOver + \o Yes + \row + \o State_Enabled + \o Yes + \row + \o State_HasFocus + \o Yes + \row + \o State_KeyboardFocusChange + \o No + \row + \o State_Active + \o Yes + \endtable + + The QCheckBox paints itself in QWidget::paintEvent() with + style option \c opt and QStylePainter \c p. The QStylePainter + class is a convenience class to draw style elements. Most + notably, it wraps the methods in QStyle used for painting. The + QCheckBox draws itself as follows: + + \snippet doc/src/snippets/code/doc_src_styles.cpp 2 + + QCommonStyle handles the CE_CheckBox element. The QCheckBox + has two sub elements: SE_CheckBoxIndicator (the checked indicator) + and SE_CheckBoxContents (the contents, which is used for the + checkbox label). QCommonStyle also implements these sub element + bounding rectangles. We have a look at the QCommonStyle code: + + \snippet doc/src/snippets/code/doc_src_styles.cpp 3 + + As can be seen from the code extract, the common style gets + the bounding rectangles of the two sub elements of + CE_CheckBox, and then draws them. If the checkbox has focus, + the focus frame is also drawn. + + The java style draws CE_CheckBoxIndicator, while QCommonStyle + handles CE_CheckboxLabel. We will examine each implementation and + start with CE_CheckBoxLabel: + + \snippet doc/src/snippets/code/doc_src_styles.cpp 4 + + \l{QStyle::}{visualAlignment()} adjusts the alignment of text + according to the layout direction. We then draw an icon if it + exists, and adjust the space left for the text. + \l{QStyle::}{drawItemText()} draws the text taking alignment, + layout direction, and the mnemonic into account. It also uses the + palette to draw the text in the right color. + + The drawing of labels often get somewhat involved. Luckily, it + can usually be handled by the base class. The java style + implements its own push button label since Java-contrary to + windows-center button contents also when the button has an icon. + You can examine that implementation if you need an example of + reimplementing label drawing. + + We take a look at the java implementation + of CE_CheckBoxIndicator in \c drawControl(): + + \snippet doc/src/snippets/javastyle.cpp 0 + + We first save the state of the painter. This is not always + necessary but in this case the QWindowsStyle needs the painter in + the same state as it was when PE_IndicatorCheckBox was called (We + could also set the state with function calls, of course). We then + use \c drawButtonBackground() to draw the background of the check + box indicator. This is a helper function that draws the background + and also the frame of push buttons and check boxes. We take a look + at that function below. We then check if the mouse is hovering + over the checkbox. If it is, we draw the frame java checkboxes + have when the box is not pressed down and the mouse is over it. + You may note that java does not handle tristate boxes, so we have + not implemented it. + + Here we use a png image for our indicator. We could also check + here if the widget is disabled. We would then have to use + another image with the indicator in the disabled color. + + \snippet doc/src/snippets/javastyle.cpp 1 + + We have seen how check boxes are styled in the java style from the + widget gets a paint request to the style is finished painting. To + learn in detail how each widget is painted, you need to go through + the code step-by-step as we have done here. However, it is + usually enough to know which style elements the widgets draw. The + widget builds a style option and calls on the style one or more + times to draw the style elements of which it consists. Usually, + it is also sufficient to know the states a widget can be in and the + other contents of the style option, i.e., what we list in the next + section. + + \section1 Widget Walkthrough + + In this section, we will examine how most of Qt's widgets are + styled. Hopefully, this will save you some time and effort while + developing your own styles and widgets. You will not find + information here that is not attainable elsewhere (i.e., by + examining the source code or the class descriptions for the style + related classes). + + We mostly use java style widgets as examples. The java style does not + draw every element in the element trees. This is because they are + not visible for that widget in the java style. We still make sure + that all elements are implemented in a way that conforms with the + java style as custom widgets might need them (this does not + exclude leaving implementations to QWindowsStyle though). + + The following is given for each widget: + + \list + \o A table with the members (variables, etc.) of its style option. + \o A table over the state flags (QStyle::StateFlag) that + can be set on the widget and when the states are set. + \o Its element tree (see section \l{The Style Elements}). + \o An image of the widget in which the elements are outlined. + \omit This is not written yet - probably never will be + either + \o List of style hints that should be checked for the + widget. + \o List of standard pixmaps that could be used by the + elements. + \endomit + \endlist + + The element tree contains the primitive, control, and complex + style elements. By doing a top-down traversal of the element tree, + you get the sequence in which the elements should be drawn. In the + nodes, we have written the sub element rectangles, sub control + elements, and pixel metrics that should be considered when drawing + the element of the node. + + Our approach on styling center on the drawing of the widgets. The + calculations of sub elements rectangles, sub controls, and pixel + metrics used \bold during drawing is only listed as contents in + the element trees. Note that there are rectangles and pixel + metrics that are only used by widgets. This leaves these + calculations untreated in the walkthrough. For instance, the + \l{QStyle::}{subControlRect()} and + \l{QStyle::}{sizeFromContents()} functions often call + \l{QStyle::}{subElementRect()} to calculate their bounding + rectangles. We could draw trees for this as well. However, how + these calculations are done is completely up to the individual + styles, and they do not have to follow a specific structure (Qt + does not impose a specific structure). You should still make sure + that you use the appropriate pixel metrics, though. To limit the + size of the document, we have therefore chosen not to include + trees or describe the calculations made by the Java (or any other) + style. + + You may be confused about how the different pixel metrics, sub + element rectangles, and sub control rectangles should be used when + examining the trees. If you are in doubt after reading the QStyle + enum descriptions, we suggest that you examine the QCommonStyle + and QWindowsStyle implementations. + + Some of the bounding rectangles that we outline in the widget + images are equal. Reasons for this are that some elements draw + backgrounds while others draw frames and labels. If in doubt, + check the description of each element in QStyle. Also, some + elements are there to layout, i.e., decide where to draw, other + elements. + + \section2 Common Widget Properties + + Some states and variables are common for all widgets. These are + set with QStyleOption::initFrom(). Not all elements use this function; + it is the widgets that create the style options, and for some + elements the information from \l{QStyleOption::}{initFrom()} is not + necessary. + + A table with the common states follows: + + \table 90% + \header + \o State + \o State Set When + \row + \o State_Enabled + \o Set if the widget is not disabled (see + QWidget::setEnabled()) + \row + \o State_Focus + \o Set if the widget has focus (see + QWidget::hasFocus()) + \row + \o State_KeyobordFocusChange + \o Set when the user changes focus with the keyboard + (see Qt::WA_KeyboardFocusChange) + \row + \o State_MouseOver + \o Set if the mouse cursor is over the widget + \row + \o State_Active + \o Set if the widget is a child of the active window. + \row + \o State_HasEditFocus + \o Set if the widget has the edit focus + \endtable + + The other common members for widgets are: + + \table 90% + \header + \o Member + \o Content + \row + \o rect + \o The bounding rectangle of the element to draw. This + is set to the widget bounding rectangle + (QWidget::rect()). + \row + \o direction + \o The layout direction; a value of the + Qt::LayoutDirection enum. + \row + \o palette + \o The QPalette to use when drawing the element. This + is set to the widgets palette (QWidget::palette()). + \row + \o fontMetrics + \o The QFontMetrics to use when drawing text on the + widget. + \endtable + + The complex style options (classes that inherit + QStyleOptionComplex) used for complex style elements share two + variables: \l{QStyleOptionComplex::}{subControls} and + \l{QStyleOptionComplex::}{activeSubControls}. Both variables are + an OR'ed combination of QStyle::SubControl enum values. They + indicate which sub controls the complex control consists of and + which of these controls are currently active. + + As mentioned, the style calculates the size of the widgets + contents, which the widgets calculate their size hints from. In + addition, complex controls also use the style to test which + sub-controls the mouse is over. + + \section2 Widget Reference + + Without further delay, we present the widget walkthrough; each + widget has its own sub-section. + + \section3 Push Buttons + + The style structure for push buttons is shown below. By doing a + top-down traversal of the tree, you get the sequence in which the + elements should be drawn. + + \image javastyle/pushbutton.png The style structure for push buttons + + The layout of the buttons, with regard element bounds, varies from + style to style. This makes it difficult to show conceptual images + of this. Also, elements may - even be intended to - have the same + bounds; the PE_PushButtonBevel, for instance, is used in + QCommonStyle to draw the elements that contains it: + PE_FrameDefaultButton, PE_FrameButtonBevel, and + PE_PanelButtonCommand, all of which have the same bounds in common + and windows style. PE_PushButtonBevel is also responsible for + drawing the menu indicator (QCommonStyle draws + PE_IndicatorArrowDown). + + An image of a push button in the java style that show the bounding + rectangles of the elements is given below. Colors are used to + separate the bounding rectangles in the image; they do not fill + any other purpose. This is also true for similar images for the + other widgets. + + \image javastyle/button.png + + The java style, as well as all other styles implemented in Qt, + does not use PE_FrameButtonBevel. It is usual that a button + with a PE_DefaultFrame adjusts the PE_PanelButtonCommand's + rectangle by PM_ButtonDefaultIndicator. The CE_PushButtonLabel + is found by adjusting the rect by PM_DefaultFrameWidth. + + We will now examine the style option for push + buttons - QStyleOptionButton. A table for the states that + QPushButton can set on the style option follows: + + \table 90% + \header + \o State + \o State Set When + \row + \o State_Sunken + \o Button is down or menu is pressed shown + \row + \o State_On + \o Button is checked + \row + \o State_Raised + \o Button is not flat and not pressed down + \endtable + + Other members of QStyleOptionButton is: + + \table 90% + \header + \o Member + \o Content + \row + \o features + \o Flags of the QStyleOptionButton::ButtonFeatures enum, + which describes various button properties (see enum) + \row + \o icon + \o The buttons QIcon (if any) + \row + \o iconSize + \o The QSize of the icon + \row + \o text + \o a QString with the buttons text + \endtable + + \section3 Check and Radio Buttons + + The structures for radio and check buttons are identical. + We show the structure using QCheckBox element and pixel + metric names: + + \image javastyle/checkbox.png + + QStyleOptionButton is used as the style option for both check + and radio buttons. We first give a table of the states that + can be set in the option: + + \table 90% + \header + \o State + \o State Set When + \row + \o State_sunken + \o The box is pressed down + \row + \o State_NoChange + \o The box is partially checked (for tristate + checkboxes.) + \row + \o State_On + \o The box is checked + \row + \o State_Off + \o The box is unchecked + \endtable + + See \l{Push Buttons} for a table over other members in the + QStyleOptionButtonClass. + + \section3 Tabs + + In Qt, QTabBar uses the style to draw its tabs. Tabs exist either + in a QTabWidget, which contains a QTabBar, or as a separate bar. + If the bar is not part of a tab widget, it draws its own base. + + QTabBar lays out the tabs, so the style does not have control over + tab placement. However, while laying out its tabs, the bar asks + the style for PM_TabBarTabHSpace and PM_TabBarTabVSpace, which is + extra width and height over the minimum size of the tab bar tab + label (icon and text). The style can also further influence the + tab size before it is laid out, as the tab bar asks for + CT_TabBarTab. The bounding rectangle of the bar is decided by the + tab widget when it is part of the widget (still considering + CT_TabBarTab). + + The tab bar is responsible for drawing the buttons that appear on + the tab bar when all tabs do not fit. Their placement is not + controlled by the style, but the buttons are \l{QToolButton}s + and are therefore drawn by the style. + + Here is the style structure for QTabWidget and QTabBar: + + \image javastyle/tab.png + + The dotted lines indicate that the QTabWidget contains a tab bar, + but does not draw it itself, that QTabBar only draws its base line + when not part of a tab widget, and that the tab bar keeps two tool + buttons that scroll the bar when all tabs do not fit; see \l{Tool + Buttons} for their element tree. Also note that since the buttons + are children of the tab bar, they are drawn after the bar. The + tabs bounding rectangles overlap the base by PM_TabBarBaseOverlap. + + Here is a tab widget in the java style: + + \image javastyle/tabwidget.png + + In the java style (and also windows), the tab bar shape and label + have the same bounding rectangle as CE_TabBarTab. Notice that the + tabs overlap with the tab widget frame. The base of the tab bar + (if drawn) is the area where the tabs and frame overlap. + + The style option for tabs (QStyleOptionTab) contains the necessary + information for drawing tabs. The option contains the position of + the tab in the tab bar, the position of the selected tab, the + shape of the tab, the text, and icon. After Qt 4.1 the option + should be cast to a QStyleOptionTabV2, which also contains the + icons size. + + As the java style tabs don't overlap, we also present an image of + a tab widget in the windows style. Note that if you want the tabs + to overlap horizontally, you do that when drawing the tabs in + CE_TabBarTabShape; the tabs bounding rectangles will not be + altered by the tab bar. The tabs are drawn from left to right in a + north tab bar shape, top to bottom in an east tab bar shape, etc. + The selected tab is drawn last, so that it is easy to draw it over + the other tabs (if it is to be bigger). + + \image javastyle/windowstabimage.png + + A table of the states a tab bar can set on its tabs follows: + + \table 90% + \header + \o State + \o State Set When + \row + \o State_Sunken + \o The tab is pressed on with the mouse. + \row + \o State_Selected + \o If it is the current tab. + \row + \o State_HasFocus + \o The tab bar has focus and the tab is selected + \endtable + + Note that individual tabs may be disabled even if the tab bar + is not. The tab will be active if the tab bar is active. + + Here follows a table of QStyleOptionTabV2's members: + + \table 90% + \header + \o Member + \o Content + \row + \o cornerWidgets + \o Is flags of the CornerWidget enum, which indicate + if and which corner widgets the tab bar has. + \row + \o icon + \o The QIcon of the tab + \row + \o iconSize + \o The QSize of the icon + \row + \o position + \o A TabPosition enum value that indicates the tabs + position on the bar relative to the other tabs. + \row + \o row + \o holds which row the tab is in + \row + \o selectedPosition + \o A value of the SelectedPosition enum that indicates + whether the selected tab is adjacent to or is the + tab. + \row + \o shape + \o A value of the QTabBar::Shape enum indication + whether the tab has rounded or triangular corners + and the orientation of the tab. + \row + \o text + \o The tab text + \endtable + + The frame for tab widgets use QStyleOptionTabWidgetFrame as + style option. We list its members here. It does not have + states set besides the common flags. + + \table 90% + \header + \o Member + \o content + \row + \o leftCornerWidgetSize + \o The QSize of the left corner widget (if any). + \row + \o rightCornerWidgetSize + \o The QSize of the right corner widget (if any). + \row + \o lineWidth + \o holds the line with for drawing the panel. + \row + \o midLineWith + \o this value is currently always 0. + \row + \o shape + \o The shape of the tabs on the tab bar. + \row + \o tabBarSize + \o The QSize of the tab bar. + \endtable + + \section3 Scroll Bars + + Here is the style structure for scrollBars: + + \image javastyle/scrollbar.png + + QScrollBar simply creates its style option and then draws + CC_ScrollBar. Some styles draw the background of add page and sub + page with PE_PanelButtonBevel and also use indicator arrows to + draw the arrows in the nest and previous line indicators; we have + not included these in the tree as their use is up to the + individual style. The style's PM_MaximumDragDistance is the + maximum distance in pixels the mouse can move from the bounds + of the scroll bar and still move the handle. + + Here is an image of a scrollbar in the java style: + + \image javastyle/scrollbarimage.png + + You may notice that the scrollbar is slightly different from + Java's as it has two line up indicators. We have done this to show + how that you can have two separate bounding rectangles for a + single sub control. The scroll bar is an example of a widget that + is entirely implemented by the java style - neither QWindowsStyle + nor QCommonStyle are involved in the drawing. + + We have a look at the different states a scroll bar can set on + the style option: + + \table 90% + \header + \o State + \o State Set When + \row + \o State_Horizontal + \o The scroll bar is horizontal + \endtable + + The style option of QScrollBar is QStyleOptionSlider. Its + members are listed in the following table. The option is used + by all \l{QAbstractSlider}s; we only describe the members + relevant for scroll bars here. + + \table 90% + \header + \o Member + \o Content + \row + \o maximum + \o the maximum value of the scroll bar + \row + \o minimum + \o the minimum value of the scroll bar + \row + \o notchTarget + \o the number of pixels between notches + \row + \o orientation + \o a value of the Qt::Orientation enum that specifies + whether the scroll bar is vertical or horizontal + \row + \o pageStep + \o the number to increase or decrease the sliders + value (relative to the size of the slider and its value + range) on page steps. + \row + \o singleStep + \o the number to increase or decrease the sliders + value on single (or line) steps + \row + \o sliderValue + \o The value of the slider + \row + \o sliderPosition + \o the position of the slider handle. This is the same + as \c sliderValue if the scroll bar is + QAbstractSlider::tracking. If not, the scroll + bar does not update its value before the mouse + releases the handle. + \row + \o upsideDown + \o holds the direction in which the scroll bar + increases its value. This is used instead of + QStyleOption::direction for all abstract sliders. + \endtable + + \section3 Sliders + + When calculating the sliders size hint, PM_SliderTickness and + PM_SliderLength is queried from the style. As with scroll bars, + the QSlider only lets the user move the handle if the mouse is + within PM_MaximumDragDistance from the slider bounds. When it + draws itself it creates the style option and calls \c + drawComplexControl() with CC_Slider: + + \image javastyle/slider.png + + We also show a picture of a slider in the java style. We show + the bounding rectangles of the sub elements as all drawing is done + in CC_Slider. + + \image javastyle/sliderimage.png + + QSlider uses QStyleOptionSlider as all \l{QAbstractSlider}s do. We + present a table with the members that affect QSlider: + + \table 90% + \header + \o Member + \o Content + \row + \o maximum + \o the maximum value of the slider + \row + \o minimum + \o the minimum value of the slider + \row + \o notchTarget + \o this is the number of pixels between each notch + \row + \o orientation + \o a Qt::Orientation enum value that gives whether the + slider is vertical or horizontal. + \row + \o pageStep + \o a number in slider value to increase or decrease + for page steps + \row + \o singleStep + \o the number to increase or decrease the sliders + value on single (or line) steps. + \row + \o sliderValue + \o the value of the slider. + \row + \o sliderPosition + \o the position of the slider given as a slider value. + This will be equal to the \c sliderValue if the + slider is \l{QAbstractSlider::}{tracking}; if + not, the sliders value will not change until the handle is + released with the mouse. + \row + \o upsideDown + \o this member is used instead of QStyleOption::direction + for all abstract sliders. + \endtable + + You should note that the slider does not use direction for + reverse layouts; it uses \c upsideDown. + + \section3 Spin Boxes + + When QSpinBox paints itself it creates a QStyleOptionSpinBox and + asks the style to draw CC_SpinBox. The edit field is a line + edit that is a child of the spin box. The dimensions of the + field is calculated by the style with SC_SpinBoxEditField. + + Here follows the style tree for spin boxes. It is not + required that a style uses the button panel primitive to paint + the indicator backgrounds. You can see an image below the tree + showing the sub elements in QSpinBox in the java style. + + \image javastyle/spinbox.png + + \image javastyle/spinboximage.png + + The QStyleOptionSpinBox, which is the style option for spin + boxes. It can set the following states on the spin box.: + + \table 90% + \header + \o State + \o State Set When + \row + \o State_Sunken + \o Is set if one of the sub controls CC_SpinUp or + CC_SpinDown is pressed on with the mouse. + \endtable + + The rest of the members in the spin boxes style options are: + + \table 90% + \header + \o Property + \o Function + \row + \o frame + \o boolean that is true if the spin box is to draw a + frame. + \row + \o buttonSymbols + \o Value of the ButtonSymbols enum that decides the + symbol on the up/down buttons. + \row + \o stepEnabled + \o A value of the StepEnabled indication which of the + spin box buttons are pressed down. + \endtable + + \section3 Title Bar + + The title bar complex control, CC_TitleBar, is used to draw + the title bars of internal windows in QMdiArea. It typically + consists of a window title and close, minimize, system menu, and + maximize buttons. Some styles also provide buttons for shading + the window, and a button for context sensitive help. + + The bar is drawn in CC_TitleBar without using any sub elements. + How the individual styles draw their buttons is individual, but + there are standard pixmaps for the buttons that the style should + provide. + + \image javastyle/titlebar.png + + In an image over a title bar in the java style, we show the + bounding rectangles of the sub elements supported by the java style + (all of which are drawn with standard pixmaps). It is usual to + draw the button backgrounds using PE_PanelButtonTool, but it's no + rule. + + \image javastyle/titlebarimage.png + + The style option for title bars is QStyleOptionTitleBar. It's + members are: + + \table 90% + \header + \o Member + \o Content + \row + \o icon + \o The title bars icon + \row + \o text + \o the text for the title bar's label + \row + \o windowFlags + \o flags of the Qt::WindowFlag enum. The window flags + used by QMdiArea for window management. + \row + \o titleBarState + \o this is the QWidget::windowState() of the window + that contains the title bar. + \endtable + + \section3 Combo Box + + A QComboBox uses the style to draw the button and label of + non-editable boxes with CC_ComboBox and CE_ComboBoxLabel. + + The list that pops up when the user clicks on the combo box is + drawn by a \l{Delegate Classes}{delegate}, which we do not cover + in this overview. You can, however, use the style to control the + list's size and position with the sub element + SC_ComboBoxListBoxPopup. The style also decides where the edit + field for editable boxes should be with SC_ComboBoxEditField; the + field itself is a QLineEdit that is a child of the combo box. + + \image javastyle/combobox.png + + We show an image over a java style combo box in which we have + outlined its sub elements and sub element rectangles: + + \image javastyle/comboboximage.png + + Java combo boxes do not use the focus rect; it changes its + background color when it has focus. The SC_ComboBoxEdit field is + used both by QComboBox to calculate the size of the edit field and + the style for calculating the size of the combo box label. + + The style option for combo boxes is QStyleOptionComboBox. It + can set the following states: + + \table 90% + \header + \o State + \o Set When + \row + \o State_Selected + \o The box is not editable and has focus + \row + \o State_Sunken + \o SC_ComboBoxArrow is active + \row + \o State_on + \o The container (list) of the box is visible + \endtable + + The style options other members are: + + \table + \header + \o Member + \o Content + \row + \o currentIcon + \o the icon of the current (selected) item of the + combo box. + \row + \o currentText + \o the text of the current item in the box. + \row + \o editable + \o holds whether the combo box is editable or not + \row + \o frame + \o holds whether the combo box has a frame or not + \row + \o iconSize + \o the size of the current items icon. + \row + \o popupRect + \o the bounding rectangle of the combo box's popup + list. + \endtable + + \section3 Group Boxes + + When calculating the size hint, QGroupBox fetches three pixel + metrics from the style: PM_IndicatorWidth, + PM_CheckBoxLabelSpacing, and PM_IndicatorHeight. QGroupBox has + the following style element tree: + + \image javastyle/groupbox.png + + Qt does not impose restrictions on how the check box is drawn; the + java style draws it with CE_IndicatorCheckBox. See \l{Check and + Radio Buttons} for the complete tree. + + We also give an image of the widget with the sub controls and + sub control rectangles drawn: + + \image javastyle/groupboximage.png + + The style option for group boxes are QStyleOptionGroupBox. The + following states can be set on it: + + \table 90% + \header + \o State + \o Set When + \row + \o State_On + \o The check box is checked + \row + \o State_Sunken + \o The checkbox is pressed down + \row + \o State_Off + \o The check box is unchecked (or there is no check box) + \endtable + + The remaining members of QStyleOptionGroupBox are: + + \table + \header + \o Member + \o Content + \row + \o features + \o flags of the QStyleOptionFrameV2::FrameFeatures + enum describing the frame of the group box. + \row + \o lineWidth + \o the line width with which to draw the panel. This + is always 1. + \row + \o text + \o the text of the group box. + \row + \o textAlignment + \o the alignment of the group box title + \row + \o textColor + \o the QColor of the text + \endtable + + \section3 Splitters + + As the structure of splitters are simple and do not contain any + sub elements, we do not include image of splitters. CE_Splitter + does not use any other elements or metrics. + + For its style option, Splitters uses the base class QStyleOption. + It can set the following state flags on it: + + \table 90% + \header + \o State + \o Set When + \row + \o State_Horizontal + \o Set if it is a horizontal splitter + \endtable + + QSplitter does not use \l{QStyleOption::}{initFrom()} to set up its + option; it sets the State_MouseOver and State_Disabled flags + itself. + + \section3 Progress Bar + + The CE_ProgressBar element is used by QProgressBar, and it is the + only element used by this widget. We start with looking at the + style structure: + + \image javastyle/progressbar.png + + Here is a progress bar in the windows style (the java style + bounding rectangles are equal): + + \image javastyle/progressbarimage.png + + The style option for QProgressBar is QStyleOptionProgressBarV2. + The bar does not set any state flags, but the other members of the + option are: + + \table 90% + \header + \o Member + \o Content + \row + \o minimum + \o The minimum value of the bar + \row + \o maximum + \o The maximum value of the bar + \row + \o progress + \o The current value of the bar + \row + \o textAlignment + \o How the text is aligned in the label + \row + \o textVisible + \o Whether the label is drawn + \row + \o text + \o The label text + \row + \o orientation + \o Progress bars can be vertical or horizontal + \row + \o invertedAppearance + \o The progress is inverted (i.e., right to left in a + horizontal bar) + \row + \o bottomToTop + \o Boolean that if true, turns the label of vertical + progress bars 90 degrees. + \endtable + + \section3 Tool Buttons + + Tool buttons exist either independently or as part of tool bars. + They are drawn equally either way. The QToolButton draws only one + style element: CC_ToolButton. + + As you must be used to by now (at least if you have read this + document sequentially), we have a tree of the widget's style + structure: + + \image javastyle/toolbutton.png + + Note that PE_FrameButtonTool and PE_IndicatorArrowDown are + included in the tree as the java style draws them, but they can + safely be omitted if you prefer it. The structure may also be + different. QWindowsStyle, for instance, draws both + PE_IndicatorButtonDropDown and PE_IndicatorArrowDown in + CE_ToolButton. + + We also have an image of a tool button where we have outlined + the sub element bounding rectangles and sub controls. + + \image javastyle/toolbuttonimage.png + + Here is the states table for tool buttons: + + \table 90% + \header + \o State + \o Set When + \row + \o State_AutoRise + \o the tool button has the autoRise property set + \row + \o State_raised + \o the button is not sunken (i.e., by being checked or + pressed on with the mouse). + \row + \o State_Sunken + \o the button is down + \row + \o State_On + \o the button is checkable and checked. + \endtable + + QStyleOptionToolButton also contains the following members: + + \table + \header + \o Member + \o Content + \row + \o arrowType + \o a Qt::ArrowType enum value, which contains the + direction of the buttons arrow (if an arrow is to + be used in place of an icon) + \row + \o features + \o flags of the QStyleOptionToolButton::ButtonFeature + enum describing if the button has an arrow, a menu, + and/or has a popup-delay. + \row + \o font + \o the QFont of the buttons label + \row + \o icon + \o the QIcon of the tool button + \row + \o iconSize + \o the icon size of the button's icon + \row + \o pos + \o the position of the button, as given by + QWidget::pos() + \row + \o text + \o the text of the button + \row + \o toolButtonStyle + \o a Qt::ToolButtonStyle enum value which decides + whether the button shows the icon, the text, or both. + \endtable + + \section3 Toolbars + + Toolbars are part of the \l{QMainWindow}{main window framework} + and cooperates with the QMainWindow to which it belongs while it + builds its style option. A main window has 4 areas that toolbars + can be placed in. They are positioned next to the four sides of + the window (i.e., north, south, west, and east). Within each area + there can be more than one line of toolbars; a line consists of + toolbars with equal orientation (vertical or horizontal) placed + next to each other. + + \l{QToolbar}{QToolbar}s in Qt consists of three elements + CE_ToolBar, PE_IndicatorToolBarHandle, and + PE_IndicatorToolBarSeparator. It is QMainWindowLayout that + calculates the bounding rectangles (i.e., position and size of the + toolbars and their contents. The main window also uses the \c + sizeHint() of the items in the toolbars when calculating the size + of the bars. + + Here is the element tree for QToolBar: + + \image javastyle/toolbar.png + + The dotted lines indicate that the QToolBar keeps an instance of + QToolBarLayout and that QToolBarSeparators are kept by + QToolBarLayout. When the toolbar is floating (i.e., has its own + window) the PE_FrameMenu element is drawn, else QToolbar draws + CE_ToolBar. + + Here is an image of a toolbar in the java style: + + \image javastyle/toolbarimage.png + + QToolBarSaparator uses QStyleOption for their style option. It + sets the State_horizontal flag if the toolbar they live in is + horizontal. Other than that, they use \l{QStyleOption::}{initFrom()}. + + The style option for QToolBar is QStyleOptionToolBar. The only + state flag set (besides the common flags) is State_Horizontal + if the bar is horizontal (i.e., in the north or south toolbar area). + The member variables of the style option are: + + \table 90% + \header + \o Member + \o Content + \row + \o features + \o Holds whether the bar is movable in a value of the + ToolBarFeature, which is either Movable or None. + \row + \o lineWidth + \o The width of the tool bar frame. + \row + \o midLineWidth + \o This variable is currently not used and is always + 0. + \row + \o positionOfLine + \o The position of the toolbar line within the toolbar + area to which it belongs. + \row + \o positionWithinLine + \o The position of the toolbar within the toolbar line. + \row + \o toolBarArea + \o The toolbar area in which the toolbar lives. + \endtable + + \section3 Menus + + Menus in Qt are implemented in QMenu. The QMenu keeps a list of + action, which it draws as menu items. When QMenu receives paint + events ,it calculates the size of each menu item and draws them + individually with CE_MenuItem. (Menu items do not have a separate + element for their label (contents), so all drawing is done in + CE_MenuItem. The menu also draws the frame of the menu with + PE_FrameMenu. It also draws CE_MenuScroller if the style supports + scrolling. CE_MenuTearOff is drawn if the menu is to large for its + bounding rectangle. + + In the style structure tree, we also include QMenu as it also does + styling related work. The bounding rectangles of menu items are + calculated for the menus size hint and when the menu is displayed + or resized. + + \image javastyle/menu.png + + The CE_MenuScroller and CE_MenuTearOff elements are handled by + QCommonStyle and are not shown unless the menu is to large to fit + on the screen. PE_FrameMenu is only drawn for pop-up menus. + + QMenu calculates rectangles based on its actions and calls + CE_MenuItem and CE_MenuScroller if the style supports that. + + It is also usual to use PE_IndicatorCheckBox (instead of using + PE_IndicatorMenuCheckMark) and PE_IndicatorRadioButton for drawing + checkable menu items; we have not included them in the style tree + as this is optional and varies from style to style. + + \image javastyle/menuimage.png + + The style option for menu items is QStyleOptionMenuItem. The + following tables describe its state flags and other members. + + \table 90% + \header + \o State + \o Set When + \row + \o State_Selected + \o The mouse is over the action and the action is not + a separator. + \row + \o State_Sunken + \o The mouse is pressed down on the menu item. + \row + \o State_DownArrow + \o Set if the menu item is a menu scroller and it scrolls + the menu downwards. + \endtable + + \table 90% + \header + \o Member + \o Content + \row + \o checkType + \o A value of the \l{QStyleOptionMenuItem::}{CheckType} enum, + which is either NotCheckable, Exclusive, or + NonExclusive. + \row + \o checked + \o Boolean that is true if the menu item is checked. + \row + \o font + \o The QFont to use for the menu item's text. + \row + \o icon + \o the QIcon of the menu item. + \row + \o maxIconWidth + \o The maximum width allowed for the icon + \row + \o menuHasChecableItem + \o Boolean which is true if at least one item in the + menu is checkable. + \row + \o menuItemType + \o The type of the menu item. This a value of the + \l{QStyleOptionMenuItem::}{MenuItemType}. + \row + \o menuRect + \o The bounding rectangle for the QMenu that the menu + item lives in. + \row + \o tabWidth + \o This is the distance between the text of the menu + item and the shortcut. + \row + \o text + \o The text of the menu item. + \endtable + + The setup of the style option for CE_MenuTearOff and + CE_MenuScroller also uses QStyleOptionMenuItem; they only set the + \c menuRect variable in addition to the common settings with + QStyleOption's \l{QStyleOption::}{initFrom()}. + + \section3 Menu Bar + + QMenuBar uses the style to draw each menu bar item and the empty + area of the menu bar. The pull-down menus themselves are + \l{QMenu}s (see \l{Menus}). The style element tree for the menu + bar follows: + + \image javastyle/menubar.png + + The panel and empty area is drawn after the menu items. The + QPainter that the QMenuBar sends to the style has the bounding + rectangles of the items clipped out (i.e., clip region), so you + don't need to worry about drawing over the items. The pixel + metrics in QMenuBar is used when the bounding rectangles of the + menu bar items are calculated. + + \image javastyle/menubarimage.png + + QStyleOptionMenuItem is used for menu bar items. The members that + are used by QMenuBar is described in the following table: + + \table + \header + \o Member + \o Content + \row + \o menuRect + \o the bounding rectangle of the entire menu bar to + which the item belongs. + \row + \o text + \o the text of the item + \row + \o icon + \o the icon of the menu item (it is not common that + styles draw this icon) + \endtable + + QStyleOptionMenuItem is also used for drawing CE_EmptyMenuBarArea. + + QStyleOptionFrame is used for drawing the panel frame The + \l{QStyleOptionFrame::}{lineWidth} is set to PM_MenuBarPanelWidth. + The \l{QStyleOptionFrame::}{midLineWidth} is currently always set + to 0. + + \section3 Item View Headers + + It is the style that draws the headers of Qt's item views. The + item views keeps the dimensions on individual sections. Also + note that the delegates may use the style to paint decorations + and frames around items. QItemDelegate, for instance, draws + PE_FrameFocusRect and PE_IndicatorViewItemCheck. + + \image javastyle/header.png + + Here is a QTableWidget showing the bounding rects of a Java + header: + + \image javastyle/headerimage.png + + The QHeaderView uses CT_HeaderSection, PM_HeaderMargin and + PM_HeaderGripMargin for size and hit test calculations. The + PM_HeaderMarkSize is currently not used by Qt. QTableView draws + the button in the top-left corner (i.e., the area where the + vertical and horizontal headers intersect) as a CE_Header. + + The style option for header views is QStyleOptionHeader. The view + paints one header section at a time, so the data is for the + section being drawn. Its contents are: + + \table 90% + \header + \o Member + \o Content + \row + \o icon + \o the icon of the header (for section that is being + drawn). + \row + \o iconAlignment + \o the alignment (Qt::Alignment) of the icon in the header. + \row + \o orientation + \o a Qt::Orientation value deciding whether the header + is the horizontal header above the view or the + vertical header on the left. + \row + \o position + \o a QStyleOptionHeader::SectionPosition value + giving the header section's position relative to + the other sections. + \row + \o section + \o holds the section that is being drawn. + \row + \o selectedPosition + \o a QStyleOptionHeader::SelectedPosition value giving + the selected section's position relative to the + section that is being painted. + \row + \o sortIndicator + \o a QStyleOptionHeader::SortIndicator value that + describes the direction in which the section's sort + indicator should be drawn. + \row + \o text + \o the text of the currently drawn section. + \row + \o textAlignment + \o the Qt::Alignment of the text within the + headersection. + \endtable + + \section3 Tree Branch Indicators + + The branch indicators in a tree view is drawn by the style with + PE_IndicatorBranch. We think of indicators here as the indicators + that describe the relationship of the nodes in the tree. The + generic QStyleOption is sent to the style for drawing this + elements. The various branch types are described by states. Since + there are no specific style option, we simply present the states + table: + + \table 90% + \header + \o State + \o Set When + \row + \o State_Sibling + \o the node in the tree has a sibling (i.e., there is + another node in the same column). + \row + \o State_Item + \o this branch indicator has an item. + \row + \o State_Children + \o the branch has children (i.e., a new sub-tree can + be opened at the branch). + \row + \o State_Open + \o the branch indicator has an opened sub-tree. + \endtable + + The tree view (and tree widget) use the style to draw the branches + (or nodes if you will) of the tree. + + QStyleOption is used as the style for PE_IndicatorBranch has state + flags set depending on what type of branch it is. + + Since there is no tree structure for branch indicators, we only + present an image of a tree in the java style. Each state is marked + in the image with a rectangle in a specific color (i.e., these + rectangles are not bounding rectangles). All combinations of + states you must be aware of are represented in the image. + + \image javastyle/branchindicatorimage.png + + \section3 Tool Boxes + + PM_SmallIconSize for sizeHints. + + QToolBox is a container that keeps a collection of widgets. It has + one tab for each widget and display one of them at a time. The + tool box lays the components it displays (the tool box buttons + and selected widget) in a QVBoxLayout. The style tree for tool + boxes looks like this: + + \image javastyle/toolbox.png + + We show an image of a tool box in the Plastique style: + + \image javastyle/toolboximage.png + + All elements have the same bounding rectangles in the + Plastique as well as the other Qt built-in styles. + + The style option for tool boxes is QStyleOptionToolBox. It + contains the text and icon of the tool box contents. The only + state set by QToolBox is State_Sunken, which is set when the user + presses a tab down with the mouse. The rest of the + QStyleOptionToolBox members are: + + \table 90% + \header + \o Member + \o Content + \row + \o icon + \o the icon on the toolbox tab + \row + \o text + \o the text on the toolbox tab + \endtable + + \section3 Size Grip + + The size grip calculates its size hint with CT_SizeGrip. The pixel + metric PM_SizeGripSize is currently unused by Qt. The element tree + for and an image in the Plastique style of QSizeGrip follows: + + \image javastyle/sizegrip.png + + \image javastyle/sizegripimage.png + + We show the size grip in a \l{QMainWindow}'s bottom right + corner. + + The size grip style option, QStyleOptionSizeGrip, have one + member except the common members from QStyleOption: + + \table 90% + \header + \o Member + \o Content + \row + \o corner + \o a Qt::Corner value that describe which corner in a + window (or equivalent) the grip is located. + \endtable + + \section3 Rubber Band + + The \l{QRubberBand}'s style tree consists of two nodes. + + \image javastyle/rubberband.png + + We present an image of a Java style window being moved in a + QMdiArea with a rubber band: + + \image javastyle/rubberbandimage.png + + The style option for rubber bands is QStyleOptionRubberBand. + Its members are: + + \table + \header + \o Member + \o Content + \row + \o opaque + \o boolean that is true if the rubber band must be + drawn in an opaque style (i.e., color) + \row + \o shape + \o a QRubberBand::Shape enum value that holds the + shape of the band (which is either a rectangle or a + line) + \endtable + + \section3 Dock Widgets + + When the dock widget lays out its contents it asks the style for + these pixel metrics: PM_DockWidgetSeparatorExtent, + PM_DockWidgetTitleBarButtonMargin, PM_DockWidgetFrameWidth, and + PM_DockWidgetTitleMargin. It also calculates the bounding + rectangles of the float and close buttons with + SE_DockWidgetCloseButton and SE_DockWidgetFloatButton. + + \image javastyle/dockwidget.png + + The dotted lines indicate that the sender keeps instances of the + recipient of the arrow (i.e., it is not a style element to draw). + The dock widget only draws PE_frameDockWidget when it is detached + from its main window (i.e., it is a top level window). If it is + docked it draws the indicator dock widget resize handle. We show a + dock widget in both docked and floating state in the plastique + style: + + \image javastyle/dockwidgetimage.png + + The style option is QStyleOptionDockWidget: + + \table 90% + \header + \o Member + \o Content + \row + \o closeable + \o boolean that holds whether the dock window can be + closed + \row + \o floatable + \o boolean that holds whether the dock window can + float (i.e., detach from the main window in which + it lives) + \row + \o movable + \o boolean that holds whether the window is movable + (i.e., can move to other dock widget areas) + \row + \o title + \o the title text of the dock window + \endtable + + For the buttons, QStyleOptionButton is used (see \l{Tool Buttons} + for content description). The dock widget resize handle has a + plain QStyleOption. +*/ diff --git a/doc/src/widgets-and-layouts/stylesheet.qdoc b/doc/src/widgets-and-layouts/stylesheet.qdoc new file mode 100644 index 0000000000..8cfa2b4c73 --- /dev/null +++ b/doc/src/widgets-and-layouts/stylesheet.qdoc @@ -0,0 +1,3963 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page stylesheet.html + \title Qt Style Sheets + \brief How to use style sheets to customize the appearance of widgets. + + \ingroup frameworks-technologies + \ingroup qt-basic-concepts + \ingroup qt-gui-concepts + + \previouspage {Styles and Style Aware Widgets}{Styles} + \contentspage Widgets and Layouts + \nextpage The Style Sheet Syntax + + \keyword style sheet + \keyword stylesheet + + Qt Style Sheets are a powerful mechanism that allows you to + customize the appearance of widgets, in addition to what is + already possible by subclassing QStyle. The concepts, + terminology, and syntax of Qt Style Sheets are heavily inspired + by HTML \l{http://www.w3.org/Style/CSS/}{Cascading Style Sheets + (CSS)} but adapted to the world of widgets. + + Topics: + + \list + \i \l{Overview} + \i \l{The Style Sheet Syntax} + \i \l{Qt Designer Integration} + \i \l{Customizing Qt Widgets Using Style Sheets} + \i \l{Qt Style Sheets Reference} + \i \l{Qt Style Sheets Examples} + \endlist + + \target overview + \section1 Overview + + Styles sheets are textual specifications that can be set on the + whole application using QApplication::setStyleSheet() or on a + specific widget (and its children) using + QWidget::setStyleSheet(). If several style sheets are set at + different levels, Qt derives the effective style sheet from all + of those that are set. This is called cascading. + + For example, the following style sheet specifies that all + \l{QLineEdit}s should use yellow as their background color, and + all \l{QCheckBox}es should use red as the text color: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 0 + + For this kind of customization, style sheets are much more + powerful than QPalette. For example, it might be tempting to set + the QPalette::Button role to red for a QPushButton to obtain a + red push button. However, this wasn't guaranteed to work for all + styles, because style authors are restricted by the different + platforms' guidelines and (on Windows XP and Mac OS X) by the + native theme engine. + + Style sheets let you perform all kinds of customizations that are + difficult or impossible to perform using QPalette alone. If you + want yellow backgrounds for mandatory fields, red text for + potentially destructive push buttons, or fancy check boxes, style + sheets are the answer. + + Style sheets are applied on top of the current \l{QStyle}{widget + style}, meaning that your applications will look as native as + possible, but any style sheet constraints will be taken into + consideration. Unlike palette fiddling, style sheets offer + guarantees: If you set the background color of a QPushButton to be + red, you can be assured that the button will have a red background + in all styles, on all platforms. In addition, \l{Qt Designer} + provides style sheet integration, making it easy to view the effects + of a style sheet in different \l{QStyle}{widget styles}. + + In addition, style sheets can be used to provide a distinctive + look and feel for your application, without having to subclass + QStyle. For example, you can specify arbitrary images for radio + buttons and check boxes to make them stand out. Using this + technique, you can also achieve minor customizations that would + normally require subclassing several style classes, such as + specifying a \l{QStyle::styleHint()}{style hint}. The + \l{widgets/stylesheet}{Style Sheet} example depicted below defines + two distinctive style sheets that you can try out and modify at + will. + + \table + \row \o \inlineimage stylesheet-coffee-xp.png + \o \inlineimage stylesheet-pagefold.png + \row \o Coffee theme running on Windows XP + \o Pagefold theme running on Windows XP + \endtable + + \table + \row \o \inlineimage stylesheet-coffee-cleanlooks.png + \o \inlineimage stylesheet-pagefold-mac.png + \row \o Coffee theme running on Ubuntu Linux + \o Pagefold theme running on Mac OS X + \endtable + + When a style sheet is active, the QStyle returned by QWidget::style() + is a wrapper "style sheet" style, \e not the platform-specific style. The + wrapper style ensures that any active style sheet is respected and + otherwise forwards the drawing operations to the underlying, + platform-specific style (e.g., QWindowsXPStyle on Windows XP). + + Since Qt 4.5, Qt style sheets fully supports Mac OS X. + + \warning Qt style sheets are currently not supported for custom QStyle + subclasses. We plan to address this in some future release. +*/ + +/*! + \page stylesheet-syntax.html + \contentspage {Qt Style Sheet}{Contents} + \previouspage Qt Style Sheet + \nextpage Qt Designer Integration + \title The Style Sheet Syntax + + Qt Style Sheet terminology and syntactic rules are almost + identical to those of HTML CSS. If you already know CSS, you can + probably skim quickly through this section. + + \tableofcontents + + \section1 Style Rules + + Style sheets consist of a sequence of style rules. A \e{style + rule} is made up of a selector and a declaration. The + \e{selector} specifies which widgets are affected by the rule; + the \e{declaration} specifies which properties should be set on + the widget. For example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 1 + + In the above style rule, \c QPushButton is the selector and \c{{ + color: red }} is the declaration. The rule specifies that + QPushButton and its subclasses (e.g., \c MyPushButton) should use + red as their foreground color. + + Qt Style Sheet is generally case insensitive (i.e., \c color, + \c Color, \c COLOR, and \c cOloR refer to the same property). + The only exceptions are class names, + \l{QObject::setObjectName()}{object names}, and Qt property + names, which are case sensitive. + + Several selectors can be specified for the same declaration, + using commas (\c{,}) to separate the selectors. For example, + the rule + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 2 + + is equivalent to this sequence of three rules: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 3 + + The declaration part of a style rule is a list of + \tt{\e{property}: \e{value}} pairs, enclosed in braces (\c{{}}) + and separated with semicolons. For example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 4 + + See the \l{List of Properties} section below for the list of + properties provided by Qt widgets. + + \section1 Selector Types + + All the examples so far used the simplest type of selector, the + Type Selector. Qt Style Sheets support all the + \l{http://www.w3.org/TR/REC-CSS2/selector.html#q1}{selectors + defined in CSS2}. The table below summarizes the most useful + types of selectors. + + \table 100% + \header + \o Selector + \o Example + \o Explanation + + \row + \o Universal Selector + \o \c * + \o Matches all widgets. + + \row + \o Type Selector + \o \c QPushButton + \o Matches instances of QPushButton and of its subclasses. + + \row + \o Property Selector + \o \c{QPushButton[flat="false"]} + \o Matches instances of QPushButton that are not + \l{QPushButton::}{flat}. You may use this selector to test + for any Qt \l{Qt's Property System}{property} that supports + QVariant::toString() (see the \l{QVariant::}{toString()} + function documentation for details). In addition, the + special \c class property is supported, for the name of the + class. + + This selector may also be used to test dynamic properties. + For more information on customization using dynamic properties, + refer to \l{Customizing Using Dynamic Properties}. + + Instead of \c =, you can also use \c ~= to test whether a + Qt property of type QStringList contains a given QString. + + \warning If the value of the Qt property changes after the + style sheet has been set, it might be necessary to force a + style sheet recomputation. One way to achieve this is to + unset the style sheet and set it again. + + \row + \o Class Selector + \o \c .QPushButton + \o Matches instances of QPushButton, but not of its subclasses. + + This is equivalent to \c{*[class~="QPushButton"]}. + + \row + \o ID \target ID Selector + Selector + \o \c{QPushButton#okButton} + \o Matches all QPushButton instances whose + \l{QObject::objectName}{object name} is \c okButton. + + \row + \o Descendant Selector + \o \c{QDialog QPushButton} + \o Matches all instances of QPushButton that are descendants + (children, grandchildren, etc.) of a QDialog. + + \row + \o Child Selector + \o \c{QDialog > QPushButton} + \o Matches all instances of QPushButton that are direct + children of a QDialog. + \endtable + + \section1 Sub-Controls + + For styling complex widgets, it is necessary to access subcontrols of the + widget, such as the drop-down button of a QComboBox or the up and down + arrows of a QSpinBox. Selectors may contain \e{subcontrols} that make it + possible to restrict the application of a rule to specific widget + subcontrols. For example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 5 + + The above rule styles the drop-down button of all \l{QComboBox}es. + Although the double-colon (\c{::}) syntax is reminiscent of CSS3 + Pseudo-Elements, Qt Sub-Controls differ conceptually from these and have + different cascading semantics. + + Sub-controls are always positioned with respect to another element - a + reference element. This reference element could be the widget or another + Sub-control. For example, the \l{Qt Style Sheets Reference#drop-down-sub} + {::drop-down} of a QComboBox is placed, by default, in the top right corner + of the Padding rectangle of the QComboBox. The + \l{Qt Style Sheets Reference#drop-down-sub}{::drop-down} is placed, + by default, in the Center of the Contents rectangle of the + \l{Qt Style Sheets Reference#drop-down-sub}{::drop-down} Sub-control. See + the \l{List of Stylable Widgets} below for the Sub-controls to use to + style a widget and their default positions. + + The origin rectangle to be used can be changed using the + \l{Qt Style Sheets Reference#subcontrol-origin-prop}{subcontrol-origin} + property. For example, if we want to place the drop-down in the margin + rectangle of the QComboBox instead of the default Padding rectangle, we + can specify: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 6 + + The alignment of the drop-down within the Margin rectangle is changed + using \l{Qt Style Sheets Reference#subcontrol-position-prop} + {subcontrol-position} property. + + The \l{Qt Style Sheets Reference#width-prop}{width} and + \l{Qt Style Sheets Reference#height-prop}{height} properties can be used + to control the size of the Sub-control. Note that setting a + \l{Qt Style Sheets Reference#image-prop}{image} implicitly sets the size + of a Sub-control. + + The relative positioning scheme + (\l{Qt Style Sheets Reference#position-prop}{position} : relative), + allows the position of the Sub-Control to be offset from its initial + position. For example, when the QComboBox's drop-down button is + pressed, we might like the arrow inside to be offset to give a + "pressed" effect. To achieve this, we can specify: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 7 + + The absolute positioning scheme + (\l{Qt Style Sheets Reference#position-prop}{position} : absolute), + allows the position and size of the Sub-control to be changed with + respect to the reference element. + + Once positioned, they are treated the same as widgets and can be styled + using the \l{box model}. + + See the \l{List of Sub-Controls} below for a list of supported + sub-controls, and \l{Customizing the QPushButton's Menu Indicator + Sub-Control} for a realistic example. + + \note With complex widgets such as QComboBox and QScrollBar, if one + property or sub-control is customized, \bold{all} the other properties or + sub-controls must be customized as well. + + \section1 Pseudo-States + + Selectors may contain \e{pseudo-states} that denote that restrict + the application of the rule based on the widget's state. + Pseudo-states appear at the end of the selector, with a colon + (\c{:}) in between. For example, the following rule applies when + the mouse hovers over a QPushButton: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 8 + + Pseudo-states can be negated using the exclamation operator. For + example, the following rule applies when the mouse does not hover + over a QRadioButton: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 9 + + Pseudo-states can be chained, in which case a logical AND is + implied. For example, the following rule applies to when the + mouse hovers over a checked QCheckBox: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 10 + + Negated Pseudo-states may appear in Pseudo-state chains. For example, + the following rule applies when the mouse hovers over a QPushButton + that is not pressed: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 11 + + If needed, logical OR can be expressed using the comma operator: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 12 + + Pseudo-states can appear in combination with subcontrols. For + example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 13 + + See the \l{List of Pseudo-States} section below for the list of + pseudo-states provided by Qt widgets. + + \section1 Conflict Resolution + + Conflicts arise when several style rules specify the same + properties with different values. Consider the following style + sheet: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 14 + + Both rules match QPushButton instances called \c okButton and + there is a conflict for the \c color property. To resolve this + conflict, we must take into account the \e specificity of the + selectors. In the above example, \c{QPushButton#okButton} is + considered more specific than \c QPushButton, because it + (usually) refers to a single object, not to all instances of a + class. + + Similarly, selectors with pseudo-states are more specific than + ones that do not specify pseudo-states. Thus, the following style + sheet specifies that a \l{QPushButton} should have white text + when the mouse is hovering over it, otherwise red text: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 15 + + Here's a tricky one: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 16 + + Here, both selectors have the same specificity, so if the mouse + hovers over the button while it is enabled, the second rule takes + precedence. If we want the text to be white in that case, we can + reorder the rules like this: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 17 + + Alternatively, we can make the first rule more specific: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 18 + + A similar issue arises in conjunction with Type Selectors. + Consider the following example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 19 + + Both rules apply to QPushButton instances (since QPushButton + inherits QAbstractButton) and there is a conflict for the + \l{Qt Style Sheets Reference#color-prop}{color} property. Because QPushButton + inherits QAbstractButton, it might be tempting to assume that + \c QPushButton is more specific than \c QAbstractButton. However, + for style sheet computations, all Type Selectors have the same + specificity, and the rule that appears last takes precedence. In + other words, \l{Qt Style Sheets Reference#color-prop}{color} is set to \c gray + for all \l{QAbstractButton}s, including \l{QPushButton}s. If we really + want \l{QPushButton}s to have red text, we can always reorder the + rules. + + For determining the specificity of a rule, Qt Style Sheets follow + the + \l{http://www.w3.org/TR/REC-CSS2/cascade.html#specificity}{CSS2 + Specification}: + + \quotation + \e{A selector's specificity is calculated as follows:} + + \list + \o \e{count the number of ID attributes in the selector (= a)} + \o \e{count the number of other attributes and pseudo-classes in the selector (= b)} + \o \e{count the number of element names in the selector (= c)} + \o \e{ignore pseudo-elements [i.e., \l{subcontrols}].} + \endlist + + \e{Concatenating the three numbers a-b-c (in a number system with a + large base) gives the specificity.} + + \e{Some examples:} + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 20 + \endquotation + + \section1 Cascading + + Style sheets can be set on the QApplication, on parent widgets, + and on child widgets. An arbitrary widget's effective style sheet + is obtained by merging the style sheets set on the widget's + ancestors (parent, grandparent, etc.), as well as any style sheet + set on the QApplication. + + When conflicts arise, the widget's own style sheet is always + preferred to any inherited style sheet, irrespective of the + specificity of the conflicting rules. Likewise, the parent + widget's style sheet is preferred to the grandparent's, etc. + + One consequence of this is that setting a style rule on a widget + automatically gives it precedence over other rules specified in + the ancestor widgets' style sheets or the QApplication style + sheet. Consider the following example. First, we set a style + sheet on the QApplication: + + \snippet doc/src/snippets/code/doc_src_stylesheet.cpp 21 + + Then we set a style sheet on a QPushButton object: + + \snippet doc/src/snippets/code/doc_src_stylesheet.cpp 22 + + The style sheet on the QPushButton forces the QPushButton (and + any child widget) to have blue text, in spite of the more + specific rule set provided by the application-wide style sheet. + + The result would have been the same if we had written + + \snippet doc/src/snippets/code/doc_src_stylesheet.cpp 23 + + except that if the QPushButton had children (which is unlikely), + the style sheet would have no impact on them. + + Style sheet cascading is a complex topic. Refer to the + \l{http://www.w3.org/TR/CSS2/cascade.html#cascade}{CSS2 + Specification} for the gory details. Be aware that Qt currently + doesn't implement \c{!important}. + + \section1 Inheritance + + In classic CSS, when font and color of an item is not explicitly set, + it gets automatically inherited from the parent. When using Qt Style Sheets, + a widget does \bold{not} automatically inherit its font and color setting + from its parent widget. + + For example, consider a QPushButton inside a QGroupBox: + + \snippet doc/src/snippets/code/doc_src_stylesheet.cpp 24 + + The QPushButton does not have an explicit color set. Hence, instead + of inheriting color of its parent QGroupBox, it has the system color. + If we want to set the color on a QGroupBox and its children, + we can write: + + \snippet doc/src/snippets/code/doc_src_stylesheet.cpp 25 + + In contrast, setting a font and propagate using QWidget::setFont() and + QWidget::setPalette() propagates to child widgets. + + \section1 Widgets inside C++ namespaces + + The Type Selector can be used to style widgets of a particular type. For + example, + + \snippet doc/src/snippets/code/doc_src_stylesheet.cpp 26 + + Qt Style Sheet uses QObject::className() of the widget to determine + when to apply the Type Selector. When custom widgets are inside namespaces, + the QObject::className() returns <namespace>::<classname>. This conflicts + with the syntax for \l{Sub-Controls}. To overcome this problem, + when using the Type Selector for widgets inside namespaces, we must + replace the "::" with "--". For example, + + \snippet doc/src/snippets/code/doc_src_stylesheet.cpp 27 + + \section1 Setting QObject properties + + From 4.3 and above, any designable Q_PROPERTY + can be set using the qproperty-<property name> syntax. + + For example, + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 28 + + If the property references an enum declared with Q_ENUMS, you should + reference its constants by name, i.e., not their numeric value. + +*/ + +/*! + \page stylesheet-designer.html + \contentspage {Qt Style Sheet}{Contents} + \previouspage The Style Sheet Syntax + \nextpage Customizing Qt Widgets Using Style Sheets + \title Qt Designer Integration + + \l{Qt Designer}{Qt Designer} is an excellent tool + to preview style sheets. You can right-click on any widget in Designer + and select \gui{Change styleSheet...} to set the style sheet. + + \image designer-stylesheet-options.png + + In Qt 4.2 and later, \l{Qt Designer}{Qt Designer} also includes a + style sheet syntax highlighter and validator. The validator indicates + if the syntax is valid or invalid, at the bottom left of the \gui{Edit + Style Sheet} dialog. + + \image designer-validator-highlighter.png + + When you click \gui{OK} or \gui{Apply}, \QD will automatically display + the widget with its new stylesheet. + + \image designer-stylesheet-usage.png + */ + +/*! + \page stylesheet-customizing.html + \contentspage {Qt Style Sheet}{Contents} + \previouspage Qt Designer Integration + \nextpage Qt Style Sheets Reference + \title Customizing Qt Widgets Using Style Sheets + + When using style sheets, every widget is treated as a box with four + concentric rectangles: the margin rectangle, the border rectangle, the + padding rectangle, and the content rectangle. The box model describes + this in further detail. + + \tableofcontents + + \target box model + \section1 The Box Model + + The four concentric rectangles appear conceptually as below: + + \image stylesheet-boxmodel.png + + \list + \o The margin falls outside the border. + \o The border is drawn between the margin and the padding. + \o The padding falls inside the border, between the border and + the actual contents. + \o The content is what is left from the original widget or + subcontrol once we have removed the margin, the border, and + the padding. + \endlist + + The \l{Qt Style Sheets Reference#margin-prop}{margin}, + \l{Qt Style Sheets Reference#border-width-prop} + {border-width}, and + \l{Qt Style Sheets Reference#padding-prop}{padding} + properties all default to zero. In that case, all four rectangles + (\c margin, \c border, \c padding, and \c content) coincide exactly. + + You can specify a background for the widget using the + \l{Qt Style Sheets Reference#background-image-prop}{background-image} + property. By default, the background-image is drawn only for the area + inside the border. This can be changed using the + \l{Qt Style Sheets Reference#background-clip-prop}{background-clip} + property. You can use + \l{Qt Style Sheets Reference#background-repeat-prop}{background-repeat} + and + \l{Qt Style Sheets Reference#background-origin-prop}{background-origin} + to control the repetition and origin of the background image. + + A background-image does not scale with the size of the widget. To provide + a "skin" or background that scales along with the widget size, one must + use + \l{Qt Style Sheets Reference#border-image-prop}{border-image}. Since the + border-image property provides an alternate background, it is not required + to specify a background-image when border-image is specified. In the case, + when both of them are specified, the border-image draws over the + background-image. + + In addition, the \l{Qt Style Sheets Reference#image-prop}{image} property + may be used to draw an image over the border-image. The image specified does + not tile or stretch and when its size does not match the size of the widget, + its alignment is specified using the + \l{Qt Style Sheets Reference#image-position-prop}{image-position} + property. Unlike background-image and border-image, one may specify a + SVG in the image property, in which case the image is scaled automatically + according to the widget size. + + The steps to render a rule are as follows: + \list + \o Set clip for entire rendering operation (border-radius) + \o Draw the background (background-image) + \o Draw the border (border-image, border) + \o Draw overlay image (image) + \endlist + + \target sub controls + \section1 Sub-controls + + A widget is considered as a hierarchy (tree) of subcontrols drawn on top + of each other. For example, the QComboBox draws the drop-down sub-control + followed by the down-arrow sub-control. A QComboBox is thus rendered as + follows: + \list + \o Render the QComboBox { } rule + \o Render the QComboBox::drop-down { } rule + \o Render the QComboBox::down-arrow { } rule + \endlist + + Sub-controls share a parent-child relationship. In the case of QComboBox, + the parent of down-arrow is the drop-down and the parent of drop-down is + the widget itself. Sub-controls are positioned within their parent using + the \l{Qt Style Sheets Reference#subcontrol-position-prop} + {subcontrol-position} and + \l{Qt Style Sheets Reference#subcontrol-origin-prop}{subcontrol-origin} + properties. + + Once positioned, sub-controls can be styled using the \l{box model}. + + \note With complex widgets such as QComboBox and QScrollBar, if one + property or sub-control is customized, \bold{all} the other properties or + sub-controls must be customized as well. + +*/ + +/*! + \page stylesheet-reference.html + \contentspage {Qt Style Sheet}{Contents} + \previouspage Customizing Qt Widgets Using Style Sheets + \nextpage Qt Style Sheets Examples + \title Qt Style Sheets Reference + + Qt Style Sheets support various properties, pseudo-states, and + subcontrols that make it possible to customize the look of + widgets. + + \tableofcontents + + \section1 List of Stylable Widgets + + The following table lists the Qt widgets that can be customized + using style sheets: + + \table 100% + \header + \o Widget + \o How to Style + + \row + \o QAbstractScrollArea \target qabstractscrollarea-widget + \o Supports the \l{box model}. + + All derivatives of QAbstractScrollArea, including QTextEdit, + and QAbstractItemView (all item view classes), support + scrollable backgrounds using + \l{Qt Style Sheets Reference#background-attachment-prop} + {background-attachment}. Setting the background-attachment to + \c{fixed} provides a background-image that does not scroll with the + viewport. Setting the background-attachment to \c{scroll}, scrolls + the background-image when the scroll bars move. + + See \l{Qt Style Sheets Examples#Customizing QAbstractScrollArea} + {Customizing QAbstractScrollArea} for an example. + + \row + \o QCheckBox \target qcheckbox-widget + \o Supports the \l{box model}. The check indicator can be + styled using the \l{#indicator-sub}{::indicator} + subcontrol. By default, the indicator is placed in the Top + Left corner of the Contents rectangle of the widget. + + The \l{#spacing-prop}{spacing} property + specifies the spacing between the check indicator and + the text. + + See \l{Qt Style Sheets Examples#Customizing QCheckBox} + {Customizing QCheckBox} for an example. + + \row + \o QColumnView \target qcolumnview-widget + \o The grip can be styled be using the \l{image-prop}{image} property. + The arrow indicators can by styled using the + \l{left-arrow-sub}{::left-arrow} subcontrol and the + \l{right-arrow-sub}{::right-arrow} subcontrol. + + \row + \o QComboBox \target qcombobox-widget + \o The frame around the combobox can be styled using the + \l{box model}. The drop-down button can be styled using + the \l{#drop-down-sub}{::drop-down} subcontrol. By default, the + drop-down button is placed in the top right corner of the padding + rectangle of the widget. The arrow mark inside the drop-down button + can be styled using the \l{#down-arrow-sub}{::down-arrow} + subcontrol. By default, the arrow is placed in the center of the + contents rectangle of the drop-down subcontrol. + + See \l{Qt Style Sheets Examples#Customizing QComboBox}{Customizing QComboBox} + for an example. + + \row + \o QDateEdit \target qdateedit-widget + \o See \l{#qspinbox-widget}{QSpinBox}. + + \row + \o QDateTimeEdit \target qdatetimeedit-widget + \o See \l{#qspinbox-widget}{QSpinBox}. + + \row + \o QDialog \target qdialog-widget + \o Supports only the \l{Qt Style Sheets Reference#background-prop}{background}, + \l{#background-clip-prop}{background-clip} and + \l{#background-origin-prop}{background-origin} properties. + + \warning Make sure you define the Q_OBJECT macro for your custom + widget. + + \row + \o QDialogButtonBox \target qdialogbuttonbox-widget + \o The layout of buttons can be altered using the + \l{#button-layout-prop}{button-layout} property. + + \row + \o QDockWidget \target qdockwidget-widget + \o Supports styling of the title bar and the title bar buttons when docked. + + The dock widget border can be styled using the \l{#border-prop}{border} + property. The \l{#title-sub}{::title} subcontrol can be used to customize + the title bar. The close and float buttons are positioned with respect + to the \l{title-sub}{::title} subcontrol using the + \l{#close-button-sub}{::close-button} and + \l{#float-button-sub}{::float-button} respectively. + + When the title bar is vertical, the \l{#vertical-ps}{:vertical} pseudo + class is set. In addition, depending on QDockWidget::DockWidgetFeature, + the \l{#closable-ps}{:closable}, \l{#floatable-ps}{:floatable} and + \l{#movable-ps}{:movable} pseudo states are set. + + \note Use QMainWindow::separator to style the resize handle. + + \warning The style sheet has no effect when the QDockWidget is undocked + as Qt uses native top level windows when undocked. + + See \l{Qt Style Sheets Examples#Customizing QDockWidget} + {Customizing QDockWidget} for an example. + + \row + \o QDoubleSpinBox \target qdoublespinbox-widget + \o See \l{#qspinbox-widget}{QSpinBox}. + + \row + \o QFrame \target qframe-widget + \o Supports the \l{box model}. + + Since 4.3, setting a stylesheet on a QLabel automatically + sets the QFrame::frameStyle property to QFrame::StyledPanel. + + See \l{Qt Style Sheets Examples#Customizing QFrame}{Customizing QFrame} + for an example. + + \row + \o QGroupBox \target qgroupbox-widget + \o Supports the \l{box model}. The title can be styled using the + \l{#title-sub}{::title} subcontrol. By default, the title is placed + depending on QGroupBox::textAlignment. + + In the case of a checkable QGroupBox, the title includes the + check indicator. The indicator is styled using the + the \l{#indicator-sub}{::indicator} subcontrol. The + \l{#spacing-prop}{spacing} property can be used to control + the spacing between the text and indicator. + + See \l{Qt Style Sheets Examples#Customizing QGroupBox}{Customizing QGroupBox} + for an example. + + \row + \o QHeaderView \target qheaderview-widget + \o Supports the \l{box model}. The sections of the header view are + styled using the \l{#section-sub}{::section} sub control. The + \c{section} Sub-control supports the \l{#middle-ps}{:middle}, + \l{#first-ps}{:first}, \l{#last-ps}{:last}, + \l{#only-one-ps}{:only-one}, \l{#next-selected-ps}{:next-selected}, + \l{#previous-selected-ps}{:previous-selected}, + \l{#selected-ps}{:selected}, + and \l{#checked-ps}{:checked} pseudo states. + + Sort indicator in can be styled using the + \l{#up-arrow-sub}{::up-arrow} and the + \l{#down-arrow-sub}{::down-arrow} Sub-control. + + See \l{Qt Style Sheets Examples#Customizing QHeaderView}{Customizing QHeaderView} + for an example. + + \row + \o QLabel \target qlabel-widget + \o Supports the \l{box model}. Does not support the + \l{#hover-ps}{:hover} pseudo-state. + + Since 4.3, setting a stylesheet on a QLabel automatically + sets the QFrame::frameStyle property to QFrame::StyledPanel. + + See \l{Qt Style Sheets Examples#Customizing QFrame}{Customizing QFrame} for an + example (a QLabel derives from QFrame). + + \row + \o QLineEdit \target qlineedit-widget + \o Support the \l{box model}. + + The color and background of the selected item is styled using + \l{#selection-color-prop}{selection-color} and + \l{#selection-background-color-prop}{selection-background-color} + respectively. + + The password character can be styled using the + \l{#lineedit-password-character-prop}{lineedit-password-character} + property. + + See \l{Qt Style Sheets Examples#Customizing QLineEdit}{Customizing QLineEdit} + for an example. + + \row + \o QListView \target qlistview-widget + \o Supports the \l{box model}. When + \l{QAbstractItemView::alternatingRowColors}{alternating row colors} + is enabled, the alternating colors can be styled using the + \l{#alternate-background-color-prop}{alternate-background-color} + property. + + The color and background of the selected item is styled using + \l{#selection-color-prop}{selection-color} and + \l{#selection-background-color-prop}{selection-background-color} + respectively. + + The selection behavior is controlled by the + \l{#show-decoration-selected-prop}{show-decoration-selected} property. + + Use the \l{#item-sub}{::item} subcontrol for more fine grained + control over the items in the QListView. + + See \l{qabstractscrollarea-widget}{QAbsractScrollArea} to + style scrollable backgrounds. + + See \l{Qt Style Sheets Examples#Customizing QListView} + {Customzing QListView} for an example. + + \row + \o QListWidget \target qlistwidget-widget + \o See \l{#qlistview-widget}{QListView}. + + \row + \o QMainWindow \target qmainwindow-widget + \o Supports styling of the separator + + The separator in a QMainWindow when using QDockWidget is styled + using the \l{#separator-sub}{::separator} subcontrol. + + See \l{Qt Style Sheets Examples#Customizing QMainWindow}{Customizing QMainWindow} + for an example. + + \row + \o QMenu \target qmenu-widget + \o Supports the \l{box model}. + + Individual items are styled using the \l{#item-sub}{::item} + subcontrol. In addition to the usually supported pseudo states, + \c{item} subcontrol supports the + \l{#selected-ps}{:selected}, \l{#default-ps}{:default}, + \l{#exclusive-ps}{:exclusive} and the + \l{#non-exclusive-ps}{non-exclusive} pseudo states. + + The indicator of checkable menu items is styled using the + \l{#indicator-sub}{::indicator} subcontrol. + + The separator is styled using the \l{#separator-sub}{::separator} + subcontrol. + + For items with a sub menu, the arrow marks are styled using the + \l{right-arrow-sub}{right-arrow} and + \l{left-arrow-sub}{left-arrow}. + + The scroller is styled using the \l{#scroller-sub}{::scroller}. + + The tear-off is styled using the \l{#tearoff-sub}{::tearoff}. + + See \l{Qt Style Sheets Examples#Customizing QMenu}{Customizing QMenu} + for an example. + + \row + \o QMenuBar \target qmenubar-widget + \o Supports the \l{box model}. The \l{#spacing-prop}{spacing} + property specifies the spacing between menu items. + Individual items are styled using the \l{#item-sub}{::item} + subcontrol. + + \warning When running on Qt/Mac, the menu bar is usually embedded into the + system-wide menu bar. In this case, the style sheet will have no effect. + + See \l{Qt Style Sheets Examples#Customizing QMenuBar}{Customizing QMenuBar} + for an example. + + \row + \o QMessageBox \target qmessagebox-widget + \o The \l{#messagebox-text-interaction-flags-prop} + {messagebox-text-interaction-flags} property can be used to alter + the interaction with text in the message box. + + \row + \o QProgressBar \target qprogressbar-widget + \o Supports the \l{box model}. The chunks of the progress bar + can be styled using the \l{#chunk-sub}{::chunk} subcontrol. + The chunk is displayed on the Contents rectangle of the widget. + + If the progress bar displays text, use the \l{text-align-prop}{text-align} + property to position the text. + + Indeterminate progress bars have the + \l{#indeterminate-ps}{:indeterminate} pseudo state set. + + See \l{Qt Style Sheets Examples#Customizing QProgressBar}{Customizing QProgressBar} + for an example. + + \row + \o QPushButton \target qpushbutton-widget + \o Supports the \l{box model}. Supports the \l{#default-ps}{:default}, + \l{#flat-ps}{:flat}, \l{#checked-ps}{:checked} pseudo states. + + For QPushButton with a menu, the menu indicator is styled + using the \l{#menu-indicator-sub}{::menu-indicator} + subcontrol. Appearance of checkable push buttons can be + customized using the \l{#open-ps}{:open} and + \l{#closed-ps}{:closed} pseudo-states. + + \warning If you only set a background-color on a QPushButton, the background + may not appear unless you set the border property to some value. This is + because, by default, the QPushButton draws a native border which completely + overlaps the background-color. For example, + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 30 + + See \l{Qt Style Sheets Examples#Customizing QPushButton}{Customizing QPushButton} + for an example. + + \row + \o QRadioButton \target qradiobutton-widget + \o Supports the \l{box model}. The check indicator can be + styled using the \l{#indicator-sub}{::indicator} + subcontrol. By default, the indicator is placed in the Top + Left corner of the Contents rectangle of the widget. + + The \l{#spacing-prop}{spacing} property + specifies the spacing between the check indicator and + the text. + + See \l{Qt Style Sheets Examples#Customizing QRadioButton} + {Customizing QRadioButton} for an example. + + \row + \o QScrollBar \target qscrollbar-widget + \o Supports the \l{box model}. The Contents rectangle of the widget + is considered to be the groove over which the slider moves. The extent + of the QScrollBar (i.e the width or the height depending on the orientation) + is set using the \l{#width-prop}{width} or \l{#height-prop}{height} property + respectively. To determine the orientation, use the + \l{#horizontal-ps}{:horizontal} and the \l{vertical-ps}{:vertical} + pseudo states. + + The slider can be styled using the \l{#handle-sub}{::handle} subcontrol. + Setting the \l{#min-width-prop}{min-width} or \l{#min-height-prop}{min-height} + provides size contraints for the slider depending on the orientation. + + The \l{add-line-sub}{::add-line} subcontrol can be used to style the + button to add a line. By default, the add-line subcontrol is placed in + top right corner of the Border rectangle of the widget. Depending on the + orientation the \l{#right-arrow-sub}{::right-arrow} or + \l{#down-arrow-sub}{::down-arrow}. By default, the arrows are placed in + the center of the Contents rectangle of the add-line subcontrol. + + The \l{sub-line-sub}{::sub-line} subcontrol can be used to style the + button to subtract a line. By default, the sub-line subcontrol is placed in + bottom right corner of the Border rectangle of the widget. Depending on the + orientation the \l{#left-arrow-sub}{::left-arrow} or + \l{#up-arrow-sub}{::up-arrow}. By default, the arrows are placed in + the center of the Contents rectangle of the sub-line subcontrol. + + The \l{sub-page-sub}{::sub-page} subcontrol can be used to style the + region of the slider that subtracts a page. The \l{add-page-sub}{::add-page} + subcontrol can be used to style the region of the slider that adds a page. + + See \l{Qt Style Sheets Examples#Customizing QScrollBar}{Customizing QScrollBar} + for an example. + + \row + \o QSizeGrip \target qsizegrip-widget + \o Supports the \l{#width-prop}{width}, + \l{#height-prop}{height}, and \l{#image-prop}{image} + properties. + + See \l{Qt Style Sheets Examples#Customizing QSizeGrip}{Customizing QSizeGrip} + for an example. + + \row + \o QSlider \target qslider-widget + \o Supports the \l{box model}. For horizontal slides, the + \l{min-width-prop}{min-width} and \l{height-prop}{height} + properties must be provided. For vertical sliders, the + \l{min-height-prop}{min-height} and \l{width-prop}{width} + properties must be provided. + + The groove of the slider is styled + using the \l{#groove-sub}{::groove}. The groove is + positioned by default in the Contents rectangle of the widget. + The thumb of the slider is styled using \l{#handle-sub}{::handle} + subcontrol. The subcontrol moves in the Contents rectangle of + the groove subcontrol. + + See \l{Qt Style Sheets Examples#Customizing QSlider}{Customizing QSlider} + for an example. + + \row + \o QSpinBox \target qspinbox-widget + \o The frame of the spin box can be styled using the \l{box + model}. + + The up button and arrow can be styled using the + \l{#up-button-sub}{::up-button} and + \l{#up-arrow-sub}{::up-arrow} subcontrols. By default, + the up-button is placed in the top right corner in the + Padding rectangle of the widget. Without an explicit size, + it occupies half the height of its reference rectangle. + The up-arrow is placed in the center of the Contents + rectangle of the up-button. + + The down button and arrow can be styled using the + \l{#down-button-sub}{::down-button} and + \l{#down-arrow-sub}{::down-arrow} subcontrols. By default, + the down-button is placed in the bottom right corner in the + Padding rectangle of the widget. Without an explicit size, + it occupies half the height of its reference rectangle. + The bottom-arrow is placed in the center of the Contents + rectangle of the bottom-button. + + See \l{Qt Style Sheets Examples#Customizing QSpinBox}{Customizing QSpinBox} + for an example. + + \row + \o QSplitter \target qsplitter-widget + \o Supports the \l{box model}. The handle of the splitter + is styled using the \l{#handle-sub}{::handle} subcontrol. + + See \l{Qt Style Sheets Examples#Customizing QSplitter}{Customizing QSplitter} + for an example. + + \row + \o QStatusBar \target qstatusbar-widget + \o Supports only the \l{Qt Style Sheets Reference#background-prop} + {background} property. + The frame for individual items can be style using the + \l{#item-sub}{::item} subcontrol. + + See \l{Qt Style Sheets Examples#Customizing QStatusBar}{Customizing QStatusBar} + for an example. + + \row + \o QTabBar \target qtabbar-widget + \o Individual tabs may be styled using the \l{#tab-sub}{::tab} subcontrol. + Close buttons using the \l{#close-button-sub}{::close-button} + The tabs support the + \l{#only-one-ps}{:only-one}, \l{#first-ps}{:first}, + \l{#last-ps}{:last}, \l{#middle-ps}{:middle}, + \l{#previous-selected-ps}{:previous--selected}, + \l{#next-selected-ps}{:next-selected}, + \l{#selected-ps}{:selected} pseudo states. + + The \l{#top-ps}{:top}, \l{#left-ps}{:left}, \l{#right-ps}{:right}, + \l{#bottom-ps}{:bottom} pseudo states depending on the orientation + of the tabs. + + Overlapping tabs for the selected state are created by using + negative margins or using the \c{absolute} position scheme. + + The tear indicator of the QTabBar is styled using the + \l{#tear-sub}{::tear} subcontrol. + + QTabBar used two QToolButtons for its scrollers that can be styled + using the \c{QTabBar QToolButton} selector. To specify the width + of the scroll button use the \l{#scroller-sub}{::scroller} + subcontrol. + + The alignment of the tabs within the QTabBar is styled + using the \l{#Alignment}{alignment} property. \warning + + To change the position of the QTabBar within a QTabWidget, use the + \l{#tab-bar-sub}{tab-bar} subcontrol (and set subcontrol-position). + + See \l{Qt Style Sheets Examples#Customizing QTabWidget and QTabBar}{Customizing QTabBar} + for an example. + + \row + \o QTabWidget \target qtabwidget-widget + \o The frame of the tab widget is styled using the + \l{#pane-sub}{::pane} subcontrol. The left and right + corners are styled using the \l{#left-corner-sub}{::left-corner} + and \l{#right-corner-sub}{::right-corner} respectively. + The position of the tab bar is controlled using the + \l{#tab-bar-sub}{::tab-bar} subcontrol. + + By default, the subcontrols have positions of a QTabWidget in + the QWindowsStyle. To place the QTabBar in the center, set the + subcontrol-position of the tab-bar subcontrol. + + The \l{#top-ps}{:top}, \l{#left-ps}{:left}, \l{#right-ps}{:right}, + \l{#bottom-ps}{:bottom} pseudo states depending on the orientation + of the tabs. + + See \l{Qt Style Sheets Examples#Customizing QTabWidget and QTabBar} + {Customizing QTabWidget} for an example. + + \row + \o QTableView \target qtableview-widget + \o Supports the \l{box model}. When + \l{QAbstractItemView::alternatingRowColors}{alternating row colors} + is enabled, the alternating colors can be styled using the + \l{#alternate-background-color-prop}{alternate-background-color} + property. + + The color and background of the selected item is styled using + \l{#selection-color-prop}{selection-color} and + \l{#selection-background-color-prop}{selection-background-color} + respectively. + + The corner widget in a QTableView is implemented as a QAbstractButton + and can be styled using the "QTableView QTableCornerButton::section" + selector. + + \warning If you only set a background-color on a QTableCornerButton, + the background may not appear unless you set the border property to + some value. This is because, by default, the QTableCornerButton draws a + native border which completely overlaps the background-color. + + The color of the grid can be specified using the + \l{#gridline-color-prop}{gridline-color} property. + + See \l{qabstractscrollarea-widget}{QAbsractScrollArea} to + style scrollable backgrounds. + + See \l{Qt Style Sheets Examples#Customizing QTableView} + {Customzing QTableView} for an example. + + \row + \o QTableWidget \target qtablewidget-widget + \o See \l{#qtableview-widget}{QTableView}. + + \row + \o QTextEdit \target qtextedit-widget + \o Supports the \l{box model}. + + The color and background of selected text is styled using + \l{#selection-color-prop}{selection-color} and + \l{#selection-background-color-prop}{selection-background-color} + respectively. + + See \l{qabstractscrollarea-widget}{QAbsractScrollArea} to + style scrollable backgrounds. + + \row + \o QTimeEdit \target qtimeedit-widget + \o See \l{#qspinbox-widget}{QSpinBox}. + + \row + \o QToolBar \target qtoolbar-widget + \o Supports the \l{box model}. + + The \l{#top-ps}{:top}, \l{#left-ps}{:left}, \l{#right-ps}{:right}, + \l{#bottom-ps}{:bottom} pseudo states depending on the area in + which the tool bar is grouped. + + The \l{#first-ps}{:first}, \l{#last-ps}{:last}, \l{#middle-ps}{:middle}, + \l{#only-one-ps}{:only-one} pseudo states indicator the position + of the tool bar within a line group (See + QStyleOptionToolBar::positionWithinLine). + + The separator of a QToolBar is styled using the + \l{#separator-sub}{::separator} subcontrol. + + The handle (to move the toolbar) is styled using the + \l{#handle-sub}{::handle} subcontrol. + + See \l{Qt Style Sheets Examples#Customizing QToolBar}{Customizing QToolBar} + for an example. + + \row + \o QToolButton \target qtoolbutton-widget + \o Supports the \l{box model}. + + If the QToolButton has a menu, is + \l{#menu-indicator-sub}{::menu-indicator} subcontrol can be used to + style the indicator. By default, the menu-indicator is positioned + at the bottom right of the Padding rectangle of the widget. + + If the QToolButton is in QToolButton::MenuButtonPopup mode, + the \l{#menu-button-sub}{::menu-button} subcontrol is used to draw the + menu button. \l{#menu-arrow-sub}{::menu-arrow} subcontrol is used to + draw the menu arrow inside the menu-button. By default, it is + positioned in the center of the Contents rectangle of the + menu-button subcontrol. + + When the QToolButton displays arrows, the \l{#up-arrow-sub}{::up-arrow}, + \l{#down-arrow-sub}{::down-arrow}, \l{#left-arrow-sub}{::left-arrow} + and \l{#right-arrow-sub}{::right-arrow} subcontrols are used. + + \warning If you only set a background-color on a QToolButton, the background + will not appear unless you set the border property to some value. This is + because, by default, the QToolButton draws a native border which completely + overlaps the background-color. For example, + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 31 + + See \l{Qt Style Sheets Examples#Customizing QToolButton}{Customizing QToolButton} + for an example. + + \row + \o QToolBox \target qtoolbox-widget + \o Supports the \l{box model}. + + The individual tabs can by styled using the + \l{#tab-sub}{::tab} subcontrol. The tabs support the + \l{#only-one-ps}{:only-one}, \l{#first-ps}{:first}, + \l{#last-ps}{:last}, \l{#middle-ps}{:middle}, + \l{#previous-selected-ps}{:previous-selected}, + \l{#next-selected-ps}{:next-selected}, + \l{#selected-ps}{:selected} pseudo states. + + \row + \o QToolTip \target qtooltip-widget + \o Supports the \l{box model}. The \l{#opacity-prop}{opacity} + property controls the opacity of the tooltip. + + See \l{Qt Style Sheets Examples#Customizing QFrame}{Customizing QFrame} + for an example (a QToolTip is a QFrame). + + \row + \o QTreeView \target qtreeview-widget + \o Supports the \l{box model}. When + \l{QAbstractItemView::alternatingRowColors}{alternating row colors} + is enabled, the alternating colors can be styled using the + \l{#alternate-background-color-prop}{alternate-background-color} + property. + + The color and background of the selected item is styled using + \l{#selection-color-prop}{selection-color} and + \l{#selection-background-color-prop}{selection-background-color} + respectively. + + The selection behavior is controlled by the + \l{#show-decoration-selected-prop}{show-decoration-selected} property. + + The branches of the tree view can be styled using the + \l{#branch-sub}{::branch} subcontrol. The + ::branch Sub-control supports the \l{open-ps}{:open}, + \l{closed-ps}{:closed}, \l{has-siblings-ps}{:has-sibling} and + \l{has-children-ps}{:has-children} pseudo states. + + Use the \l{#item-sub}{::item} subcontrol for more fine grained + control over the items in the QTreeView. + + See \l{qabstractscrollarea-widget}{QAbsractScrollArea} to + style scrollable backgrounds. + + See \l{Qt Style Sheets Examples#Customizing QTreeView}{Customizing QTreeView} + for an example to style the branches. + + \row + \o QTreeWidget \target qtreewidget-widget + \o See \l{#qtreeview-widget}{QTreeView}. + + \row + \o QWidget \target qwidget-widget + \o Supports only the \l{Qt Style Sheets Reference#background-prop}{background}, + \l{#background-clip-prop}{background-clip} and + \l{#background-origin-prop}{background-origin} properties. + + If you subclass from QWidget, you need to provide a paintEvent for your + custom QWidget as below: + \snippet doc/src/snippets/code/doc_src_stylesheet.cpp 32 + + The above code is a no-operation if there is no stylesheet set. + + \warning Make sure you define the Q_OBJECT macro for your custom + widget. + + \endtable + + \section1 List of Properties + + The table below lists all the properties supported by Qt Style + Sheets. Which values can be given to an property depend on the + \l{List of Property Types}{property's type}. Unless otherwise + specified, properties below apply to all widgets. Properties + marked with an asterisk * are specific to Qt and have no equivalent + in CSS2 or CSS3. + + \table 100% + \header + \o Property + \o Type + \o Description + + \row + \o \bold{\c alternate-background-color} \target alternate-background-color-prop + \o \l{#Brush}{Brush} \BR + \o The \l{QAbstractItemView::alternatingRowColors} + {alternate background color} used in QAbstractItemView subclasses. + + If this property is not set, the default value is + whatever is set for the palette's + \l{QPalette::}{AlternateBase} role. + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 33 + + See also \l{Qt Style Sheets Reference#background-prop}{background} and + \l{#selection-background-color-prop}{selection-background-color}. + + \row + \o \bold{\c background} \target background-prop + \o \l{#Background}{Background} + \o Shorthand notation for setting the background. Equivalent + to specifying \c background-color, \c background-image, \c + background-repeat, and/or \c background-position. + + This property is supported by QAbstractItemView + subclasses, QAbstractSpinBox subclasses, QCheckBox, + QComboBox, QDialog, QFrame, QGroupBox, QLabel, QLineEdit, + QMenu, QMenuBar, QPushButton, QRadioButton, QSplitter, + QTextEdit, QToolTip, and plain \l{QWidget}s. + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 34 + + + Often, it is required to set a fill pattern similar to the styles + in Qt::BrushStyle. You can use the background-color property for + Qt::SolidPattern, Qt::RadialGradientPattern, Qt::LinearGradientPattern + and Qt::ConicalGradientPattern. The other patterns are easily achieved + by creating a background image that contains the pattern. + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 35 + + See also \l{#background-origin-prop}{background-origin}, + \l{#selection-background-color-prop}{selection-background-color}, + \l{#background-clip-prop}{background-clip}, + \l{#background-attachment-prop}{background-attachment} + and \l{#alternate-background-color-prop}{alternate-background-color}. + + \row + \o \c background-color \target background-color-prop + \o \l{#Brush}{Brush} \BR + \o The background color used for the widget. + + Examples: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 36 + + \row + \o \c background-image \target background-image-prop + \o \l{#Url}{Url} + \o The background image used for the widget. Semi-transparent + parts of the image let the \c background-color shine + through. + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 37 + + \row + \o \c background-repeat \target background-repeat-prop + \o \l{#Repeat}{Repeat} + \o Whether and how the background image is repeated to fill + the \c background-origin rectangle. + + If this property is not specified, the background image + is repeated in both directions (\c repeat). + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 38 + + \row + \o \c background-position + \o \l{#Alignment}{Alignment} + \o The alignment of the background image within the \c + background-origin rectangle. + + If this property is not specified, the alignment is \c + top \c left. + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 39 + + \row + \o \bold{\c background-attachment} \target background-attachment-prop + \o \l{#Attachment}{Attachment} + \o Determines whether the background-image in a QAbstractScrollArea + is scrolled or fixed with respect to the viewport. + By default, the background-image scrolls with the viewport. + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 40 + + See also \l{Qt Style Sheets Reference#background-prop}{background} + + \row + \o \bold{\c background-clip} \target background-clip-prop + \o \l{#Origin}{Origin} + \o The widget's rectangle, in which the \c background is drawn. + + This property specifies the rectangle to which the \c background-color + and \c background-image are clipped. + + This property is supported by QAbstractItemView + subclasses, QAbstractSpinBox subclasses, QCheckBox, + QComboBox, QDialog, QFrame, QGroupBox, QLabel, + QPushButton, QRadioButton, QSplitter, QTextEdit, QToolTip, + and plain \l{QWidget}s. + + If this property is not specified, the default is \c + border. + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 41 + + See also \l{Qt Style Sheets Reference#background-prop}{background}, + \l{#background-origin-prop}{background-origin} and \l{The Box Model}. + + \row + \o \bold{\c background-origin} \target background-origin-prop + \o \l{#Origin}{Origin} + \o The widget's background rectangle, to use in conjunction + with \c background-position and \c background-image. + + This property is supported by QAbstractItemView + subclasses, QAbstractSpinBox subclasses, QCheckBox, + QComboBox, QDialog, QFrame, QGroupBox, QLabel, + QPushButton, QRadioButton, QSplitter, QTextEdit, QToolTip, + and plain \l{QWidget}s. + + If this property is not specified, the default is \c + padding. + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 42 + + See also \l{Qt Style Sheets Reference#background-prop}{background} and + \l{The Box Model}. + + \row + \o \bold{\c border} \target border-prop + \o \l{#Border}{Border} + \o Shorthand notation for setting the widget's border. Equivalent + to specifying \c border-color, \c border-style, and/or + \c border-width. + + This property is supported by QAbstractItemView + subclasses, QAbstractSpinBox subclasses, QCheckBox, + QComboBox, QFrame, QGroupBox, QLabel, QLineEdit, + QMenu, QMenuBar, QPushButton, QRadioButton, QSplitter, + QTextEdit, QToolTip, and plain \l{QWidget}s. + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 43 + + \row + \o \c border-top + \o \l{#Border}{Border} + \o Shorthand notation for setting the widget's top border. + Equivalent to specifying \c border-top-color, \c + border-top-style, and/or \c border-top-width. + + \row + \o \c border-right + \o \l{#Border}{Border} + \o Shorthand notation for setting the widget's right border. + Equivalent to specifying \c border-right-color, \c + border-right-style, and/or \c border-right-width. + + \row + \o \c border-bottom + \o \l{#Border}{Border} + \o Shorthand notation for setting the widget's bottom border. + Equivalent to specifying \c border-bottom-color, \c + border-bottom-style, and/or \c border-bottom-width. + + \row + \o \c border-left + \o \l{#Border}{Border} + \o Shorthand notation for setting the widget's left border. + Equivalent to specifying \c border-left-color, \c + border-left-style, and/or \c border-left-width. + + \row + \o \bold{\c border-color} \target border-attrs + \target border-color-prop + \o \l{#Box Colors}{Box Colors} + \o The color of all the border's edges. Equivalent to + specifying \c border-top-color, \c border-right-color, \c + border-bottom-color, and \c border-left-color. + + This property is supported by QAbstractItemView + subclasses, QAbstractSpinBox subclasses, QCheckBox, + QComboBox, QFrame, QGroupBox, QLabel, QLineEdit, + QMenu, QMenuBar, QPushButton, QRadioButton, QSplitter, + QTextEdit, QToolTip, and plain \l{QWidget}s. + + If this property is not specified, it defaults to + \l{#color-prop}{color} (i.e., the widget's foreground + color). + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 44 + + See also \l{Qt Style Sheets Reference#border-style-prop}{border-style}, + \l{Qt Style Sheets Reference#border-width-prop}{border-width}, + \l{#border-image-prop}{border-image}, and \l{The Box Model}. + + \row + \o \c border-top-color + \o \l{#Brush}{Brush} \BR + \o The color of the border's top edge. + + \row + \o \c border-right-color + \o \l{#Brush}{Brush} \BR + \o The color of the border's right edge. + + \row + \o \c border-bottom-color + \o \l{#Brush}{Brush} \BR + \o The color of the border's bottom edge. + + \row + \o \c border-left-color + \o \l{#Brush}{Brush} \BR + \o The color of the border's left edge. + + \row + \o \bold{\c border-image} \target border-image-prop + \o \l{#Border Image}{Border Image} + \o The image used to fill the border. The image is cut into + nine parts and stretched appropriately if necessary. See + \l{#Border Image}{Border Image} for details. + + This property is supported by QAbstractItemView + subclasses, QAbstractSpinBox subclasses, QCheckBox, + QComboBox, QFrame, QGroupBox, QLabel, QLineEdit, + QMenu, QMenuBar, QPushButton, QRadioButton, QSplitter, + QTextEdit and QToolTip. + + See also \l{#border-color-prop}{border-color}, + \l{Qt Style Sheets Reference#border-style-prop}{border-style}, + \l{Qt Style Sheets Reference#border-width-prop}{border-width}, and + \l{The Box Model}. + + \row + \o \bold{\c border-radius} \target border-radius-prop + \o \l{#Radius}{Radius} + \o The radius of the border's corners. Equivalent to + specifying \c border-top-left-radius, \c + border-top-right-radius, \c border-bottom-right-radius, + and \c border-bottom-left-radius. + + The border-radius clips the element's + \l{Qt Style Sheets Reference#background-prop}{background}. + + This property is supported by QAbstractItemView + subclasses, QAbstractSpinBox subclasses, QCheckBox, + QComboBox, QFrame, QGroupBox, QLabel, QLineEdit, QMenu, + QMenuBar, QPushButton, QRadioButton, QSplitter, QTextEdit, + and QToolTip. + + If this property is not specified, it defaults to 0. + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 45 + + See also \l{Qt Style Sheets Reference#border-width-prop}{border-width} and + \l{The Box Model}. + + \row + \o \c border-top-left-radius + \o \l{#Radius}{Radius} + \o The radius of the border's top-left corner. + + \row + \o \c border-top-right-radius + \o \l{#Radius}{Radius} + \o The radius of the border's top-right corner. + + \row + \o \c border-bottom-right-radius + \o \l{#Radius}{Radius} + \o The radius of the border's bottom-right corner. Setting + this property to a positive value results in a rounded + corner. + + \row + \o \c border-bottom-left-radius + \o \l{#Radius}{Radius} + \o The radius of the border's bottom-left corner. Setting this + property to a positive value results in a rounded corner. + + \row + \o \bold{\c border-style} \target border-style-prop + \o \l {Border Style} + \o The style of all the border's edges. + + This property is supported by QAbstractItemView + subclasses, QAbstractSpinBox subclasses, QCheckBox, + QComboBox, QFrame, QGroupBox, QLabel, QLineEdit, QMenu, + QMenuBar, QPushButton, QRadioButton, QSplitter, QTextEdit, + and QToolTip. + + If this property is not specified, it defaults to \c none. + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 46 + + See also \l{#border-color-prop}{border-color}, + \l{Qt Style Sheets Reference#border-style-prop}{border-style}, + \l{#border-image-prop}{border-image}, and \l{The Box Model}. + + \row + \o \c border-top-style + \o \l{#Border Style}{Border Style} + \o The style of the border's top edge. + + \row + \o \c border-right-style + \o \l{#Border Style}{Border Style} + \o The style of the border's right edge/ + + \row + \o \c border-bottom-style + \o \l{#Border Style}{Border Style} + \o The style of the border's bottom edge. + + \row + \o \c border-left-style + \o \l{#Border Style}{Border Style} + \o The style of the border's left edge. + + \row + \o \bold{\c border-width} \target border-width-prop + \o \l{#Box Lengths}{Box Lengths} + \o The width of the border. Equivalent to setting \c + border-top-width, \c border-right-width, \c + border-bottom-width, and \c border-left-width. + + This property is supported by QAbstractItemView + subclasses, QAbstractSpinBox subclasses, QCheckBox, + QComboBox, QFrame, QGroupBox, QLabel, QLineEdit, QMenu, + QMenuBar, QPushButton, QRadioButton, QSplitter, QTextEdit, + and QToolTip. + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 47 + + See also \l{#border-color-prop}{border-color}, + \l{#border-radius-prop}{border-radius}, + \l{Qt Style Sheets Reference#border-style-prop}{border-style}, + \l{#border-image-prop}{border-image}, and + \l{The Box Model}. + + \row + \o \c border-top-width + \o \l{#Length}{Length} + \o The width of the border's top edge. + + \row + \o \c border-right-width + \o \l{#Length}{Length} + \o The width of the border's right edge. + + \row + \o \c border-bottom-width + \o \l{#Length}{Length} + \o The width of the border's bottom edge. + + \row + \o \c border-left-width + \o \l{#Length}{Length} + \o The width of the border's left edge. + + \row + \o \bold{\c bottom} \target bottom-prop + \o \l{#Length}{Length} + \o If \l{#position-prop}{position} is \c relative (the + default), moves a \l{subcontrol} by a certain offset up; + specifying \tt{bottom: \e{y}} is then equivalent to + specifying \tt{\l{Qt Style Sheets Reference#top-prop}{top}: -\e{y}}. + + If \l{#position-prop}{position} is \c absolute, the \c + bottom property specifies the subcontrol's bottom edge + in relation to the parent's bottom edge (see also + \l{Qt Style Sheets Reference#subcontrol-origin-prop} + {subcontrol-origin}). + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 48 + + See also \l{Qt Style Sheets Reference#left-prop}{left}, \l{#right-prop}{right}, and + \l{Qt Style Sheets Reference#top-prop}{top}. + + \row + \o \bold{\c button-layout} \target button-layout-prop + \o \l{#Number}{Number} + \o The layout of buttons in a QDialogButtonBox or + a QMessageBox. The possible values are 0 + (\l{QDialogButtonBox::}{WinLayout}), 1 + (\l{QDialogButtonBox::}{MacLayout}), 2 + (\l{QDialogButtonBox::}{KdeLayout}), and 3 + (\l{QDialogButtonBox::}{GnomeLayout}). + + If this property is not specified, it defaults to the + value specified by the current style for the + \l{QStyle::}{SH_DialogButtonLayout} style hint. + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 49 + + \row + \o \bold{\c color} \target color-prop + \o \l{#Brush}{Brush} \BR + \o The color used to render text. + + This property is supported by all widgets that respect + the \l QWidget::palette. + + If this property is not set, the default is whatever is + set for in the widget's palette for the + QWidget::foregroundRole (typically black). + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 50 + + See also \l{Qt Style Sheets Reference#background-prop}{background} and + \l{#selection-color-prop}{selection-color}. + + \row + \o \bold{\c dialogbuttonbox-buttons-have-icons} + \o \l{#Boolean}{Boolean} + \o Whether the buttons in a QDialogButtonBox show icons + + If this property is set to 1, the buttons of a QDialogButtonBox + show icons; if it is set to 0, the icons are not shown. + + See the \l{Qt Style Sheets Reference#list of icons}{List of Icons} + section for information on how to set icons. + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 51 + + \note Styles defining this property must be applied before the + QDialogButtonBox is created; this means that you must apply the + style to the parent widget or to the application itself. + + \omit + \row + \o \bold{\c etch-disabled-text}* + \o \l{#Boolean}{Boolean} + \o Whether disabled text is drawn etched. + + If this property is not specified, it defaults to the + value specified by the current style for the + \l{QStyle::}{SH_EtchDisabledText} style hint. + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 52 + \endomit + + \row + \o \bold{\c font} \target font-prop + \o \l{#Font}{Font} + \o Shorthand notation for setting the text's font. Equivalent + to specifying \c font-family, \c font-size, \c font-style, + and/or \c font-weight. + + This property is supported by all widgets that respect + the \l QWidget::font. + + If this property is not set, the default is the + QWidget::font. + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 53 + + \row + \o \c font-family + \o String + \o The font family. + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 54 + + \row + \o \c font-size + \o \l{#Font Size}{Font Size} + \o The font size. In this version of Qt, only pt and px metrics are + supported. + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 55 + + \row + \o \c font-style + \o \l {Font Style} + \o The font style. + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 56 + + \row + \o \c font-weight + \o \l{#Font Weight}{Font Weight} + \o The weight of the font. + + \row + \o \bold{\c gridline-color}* \target gridline-color-prop + \o \l{#Color}{Color} \BR + \o The color of the grid line in a QTableView. + + If this property is not specified, it defaults to the + value specified by the current style for the + \l{QStyle::}{SH_Table_GridLineColor} style hint. + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 57 + + \row + \o \bold{\c height} \target height-prop + \o \l{#Length}{Length} + \o The height of a \l{subcontrol} (or in some case, a widget). + + If this property is not specified, it defaults to a value + that depends on the subcontrol/widget and on the current style. + + \warning Unless otherwise specified, this property has no effect + when set on widgets. If you want a widget with a fixed height, set + the \l{#min-width-prop}{min-height} and + \l{#max-width-prop}{max-height} to the same value. + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 58 + + See also \l{#width-prop}{width}. + + \row + \o \bold{\c icon-size} \target icon-size-prop + \o \l{#Length}{Length} + \o The width and height of the icon in a widget. + + The icon size of the following widgets can be set using this + property. + \list + \i QCheckBox + \i QListView + \i QPushButton + \i QRadioButton + \i QTabBar + \i QToolBar + \i QToolBox + \i QTreeView + \endlist + + \row + \o \bold{\c image}* \target image-prop + \o \l{#Url}{Url}+ + \o The image that is drawn in the contents rectangle of a + \l{subcontrol}. + + The image property accepts a list of \l{#Url}{Url}s or + an \c{svg}. The actual image that is drawn is determined + using the same algorithm as QIcon (i.e) the image is never scaled + up but always scaled down if necessary. If a \c{svg} is specified, + the image is scaled to the size of the contents rectangle. + + Setting the image property on sub controls implicitly sets the + width and height of the sub-control (unless the image in a SVG). + + In Qt 4.3 and later, the alignment of the + image within the rectangle can be specified using + \l{image-position-prop}{image-position}. + + This property is for \l{subcontrol}s only--we don't support it for + other elements. + + \warning The QIcon SVG plugin is needed to render SVG images. + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 59 + + \row + \o \bold{\c image-position} \target image-position-prop + \o \l{#Alignment}{alignment} + \o In Qt 4.3 and later, the alignment of the image image's position can be specified + using relative or absolute position. + + \row + \o \bold{\c left} \target left-prop + \o \l{#Length}{Length} + \o If \l{#position-prop}{position} is \c relative (the + default), moves a \l{subcontrol} by a certain offset to + the right. + + If \l{#position-prop}{position} is \c absolute, the \c + left property specifies the subcontrol's left edge in + relation to the parent's left edge (see also + \l{Qt Style Sheets Reference#subcontrol-origin-prop}{subcontrol-origin}). + + If this property is not specified, it defaults to \c 0. + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 60 + + See also \l{#right-prop}{right}, \l{Qt Style Sheets Reference#top-prop}{top}, and + \l{#bottom-prop}{bottom}. + + \row + \o \bold{\c lineedit-password-character*} \target lineedit-password-character-prop + \o \l{#Number}{Number} + \o The QLineEdit password character as a Unicode number. + + If this property is not specified, it defaults to the + value specified by the current style for the + \l{QStyle::}{SH_LineEdit_PasswordCharacter} style hint. + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 61 + + \row + \o \bold{\c margin} \target margin-prop + \o \l {Box Lengths} + \o The widget's margins. Equivalent to specifying \c + margin-top, \c margin-right, \c margin-bottom, and \c + margin-left. + + This property is supported by QAbstractItemView + subclasses, QAbstractSpinBox subclasses, QCheckBox, + QComboBox, QFrame, QGroupBox, QLabel, QLineEdit, QMenu, + QMenuBar, QPushButton, QRadioButton, QSplitter, QTextEdit, + and QToolTip. + + If this property is not specified, it defaults to \c 0. + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 62 + + See also \l{Qt Style Sheets Reference#padding-prop}{padding}, + \l{#spacing-prop}{spacing}, and \l{The Box Model}. + + \row + \o \c margin-top + \o \l{#Length}{Length} + \o The widget's top margin. + + \row + \o \c margin-right + \o \l{#Length}{Length} + \o The widget's right margin. + + \row + \o \c margin-bottom + \o \l{#Length}{Length} + \o The widget's bottom margin. + + \row + \o \c margin-left + \o \l{#Length}{Length} + \o The widget's left margin. + + \row + \o \bold{\c max-height} \target max-height-prop + \o \l{#Length}{Length} + \o The widget's or a subcontrol's maximum height. + + This property is supported by QAbstractItemView + subclasses, QAbstractSpinBox subclasses, QCheckBox, + QComboBox, QFrame, QGroupBox, QLabel, QLineEdit, QMenu, + QMenuBar, QPushButton, QRadioButton, QSizeGrip, QSpinBox, + QSplitter, QStatusBar, QTextEdit, and QToolTip. + + The value is relative to the contents rect in the \l{The + Box Model}{box model}. + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 63 + + See also \l{#max-width-prop}{max-width}. + + \row + \o \bold{\c max-width} \target max-width-prop + \o \l{#Length}{Length} + \o The widget's or a subcontrol's maximum width. + + This property is supported by QAbstractItemView + subclasses, QAbstractSpinBox subclasses, QCheckBox, + QComboBox, QFrame, QGroupBox, QLabel, QLineEdit, QMenu, + QMenuBar, QPushButton, QRadioButton, QSizeGrip, QSpinBox, + QSplitter, QStatusBar, QTextEdit, and QToolTip. + + The value is relative to the contents rect in the \l{The + Box Model}{box model}. + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 64 + + See also \l{#max-height-prop}{max-height}. + + + \row + \o \bold{\c messagebox-text-interaction-flags*} \target messagebox-text-interaction-flags-prop + \o \l{#Number}{Number} + \o The interaction behavior for text in a message box. + Possible values are based on Qt::TextInteractionFlags. + + If this property is not specified, it defaults to the + value specified by the current style for the + \l{QStyle::}{SH_MessageBox_TextInteractionFlags} style + hint. + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 65 + + \row + \o \bold{\c min-height} \target min-height-prop + \o \l{#Length}{Length} + \o The widget's or a subcontrol's minimum height. + + This property is supported by QAbstractItemView + subclasses, QAbstractSpinBox subclasses, QCheckBox, + QComboBox, QFrame, QGroupBox, QLabel, QLineEdit, QMenu, + QMenuBar, QPushButton, QRadioButton, QSizeGrip, QSpinBox, + QSplitter, QStatusBar, QTextEdit, and QToolTip. + + If this property is not specified, the minimum height is + derived based on the widget's contents and the style. + + The value is relative to the contents rect in the \l{The + Box Model}{box model}. + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 66 + + See also \l{#min-width-prop}{min-width}. + + \row + \o \bold{\c min-width} \target min-width-prop + \o \l{#Length}{Length} + \o The widget's or a subcontrol's minimum width. + + This property is supported by QAbstractItemView + subclasses, QAbstractSpinBox subclasses, QCheckBox, + QComboBox, QFrame, QGroupBox, QLabel, QLineEdit, QMenu, + QMenuBar, QPushButton, QRadioButton, QSizeGrip, QSpinBox, + QSplitter, QStatusBar, QTextEdit, and QToolTip. + + If this property is not specified, the minimum width is + derived based on the widget's contents and the style. + + The value is relative to the contents rect in the \l{The + Box Model}{box model}. + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 67 + + See also \l{#min-height-prop}{min-height}. + + \row + \o \bold{\c opacity*} \target opacity-prop + \o \l{#Number}{Number} + \o The opacity for a widget. Possible values are from 0 + (transparent) to 255 (opaque). For the moment, this is + only supported for \l{QToolTip}{tooltips}. + + If this property is not specified, it defaults to the + value specified by the current style for the + \l{QStyle::}{SH_ToolTipLabel_Opacity} style hint. + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 68 + + \row + \o \bold{\c padding} \target padding-prop + \o \l{#Box Lengths}{Box Lengths} + \o The widget's padding. Equivalent to specifying \c + padding-top, \c padding-right, \c padding-bottom, and \c + padding-left. + + This property is supported by QAbstractItemView + subclasses, QAbstractSpinBox subclasses, QCheckBox, + QComboBox, QFrame, QGroupBox, QLabel, QLineEdit, QMenu, + QMenuBar, QPushButton, QRadioButton, QSplitter, QTextEdit, + and QToolTip. + + If this property is not specified, it defaults to \c 0. + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 69 + + See also \l{#margin-prop}{margin}, + \l{#spacing-prop}{spacing}, and \l{The Box Model}. + + \row + \o \c padding-top + \o \l{#Length}{Length} + \o The widget's top padding. + + \row + \o \c padding-right + \o \l{#Length}{Length} + \o The widget's right padding. + + \row + \o \c padding-bottom + \o \l{#Length}{Length} + \o The widget's bottom padding. + + \row + \o \c padding-left + \o \l{#Length}{Length} + \o The widget's left padding. + + \row + \o \bold{\c paint-alternating-row-colors-for-empty-area} + \target paint-alternating-row-colors-for-empty-area-prop + \o \c bool + \o Whether the QTreeView paints alternating row colors for the empty + area (i.e the area where there are no items) + + \row + \o \bold{\c position} \target position-prop + \o \c relative \BR + | \c absolute + \o Whether offsets specified using \l{Qt Style Sheets Reference#left-prop}{left}, + \l{#right-prop}{right}, \l{Qt Style Sheets Reference#top-prop}{top}, and + \l{#bottom-prop}{bottom} are relative or absolute + coordinates. + + If this property is not specified, it defaults to \c + relative. + + \row + \o \bold{\c right} \target right-prop + \o \l{#Length}{Length} + \o If \l{#position-prop}{position} is \c relative (the + default), moves a \l{subcontrol} by a certain offset to + the left; specifying \tt{right: \e{x}} is then equivalent + to specifying \tt{\l{Qt Style Sheets Reference#left-prop}{left}: -\e{x}}. + + If \l{#position-prop}{position} is \c absolute, the \c + right property specifies the subcontrol's right edge in + relation to the parent's right edge (see also + \l{Qt Style Sheets Reference#subcontrol-origin-prop}{subcontrol-origin}). + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 70 + + See also \l{Qt Style Sheets Reference#left-prop}{left}, \l{Qt Style Sheets Reference#top-prop}{top}, and + \l{#bottom-prop}{bottom}. + + \row + \o \bold{\c selection-background-color*} \target selection-background-color-prop + \o \l{#Brush}{Brush} \BR + \o The background of selected text or items. + + This property is supported by all widgets that respect + the \l QWidget::palette and that show selection text. + + If this property is not set, the default value is + whatever is set for the palette's + \l{QPalette::}{Highlight} role. + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 71 + + See also \l{#selection-color-prop}{selection-color} and + \l{Qt Style Sheets Reference#background-prop}{background}. + + \row + \o \bold{\c selection-color*} \target selection-color-prop + \o \l{#Brush}{Brush} \BR + \o The foreground of selected text or items. + + This property is supported by all widgets that respect + the \l QWidget::palette and that show selection text. + + If this property is not set, the default value is + whatever is set for the palette's + \l{QPalette::}{HighlightedText} role. + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 72 + + See also + \l{#selection-background-color-prop}{selection-background-color} + and \l{#color-prop}{color}. + + \row + \o \bold{\c show-decoration-selected*} \target show-decoration-selected-prop + \o \l{#Boolean}{Boolean} + \o Controls whether selections in a QListView cover the + entire row or just the extent of the text. + + If this property is not specified, it defaults to the + value specified by the current style for the + \l{QStyle::}{SH_ItemView_ShowDecorationSelected} style + hint. + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 73 + + \row + \o \bold{\c spacing*} \target spacing-prop + \o \l{#Length}{Length} + \o Internal spacing in the widget. + + This property is supported by QCheckBox, checkable + \l{QGroupBox}es, QMenuBar, and QRadioButton. + + If this property is not specified, the default value + depends on the widget and on the current style. + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 74 + + See also \l{Qt Style Sheets Reference#padding-prop}{padding} and + \l{#margin-prop}{margin}. + + \row + \o \bold{\c subcontrol-origin*} \target subcontrol-origin-prop + \o \l{#Origin}{Origin} + \o The origin rectangle of the \l subcontrol within the + parent element. + + If this property is not specified, the default is \c + padding. + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 75 + + See also + \l{Qt Style Sheets Reference#subcontrol-position-prop}{subcontrol-position}. + + \row + \o \bold{\c subcontrol-position*} \target subcontrol-position-prop + \o \l{#Alignment}{Alignment} + \o The alignment of the \l subcontrol within the origin + rectangle specified by \l{Qt Style Sheets Reference#subcontrol-origin-prop} + {subcontrol-origin}. + + If this property is not specified, it defaults to a value + that depends on the subcontrol. + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 76 + + See also + \l{Qt Style Sheets Reference#subcontrol-origin-prop}{subcontrol-origin}. + + \row + \o \bold{\c text-align} \target text-align-prop + \o \l{#Alignment}{Alignment} + \o The alignment of text and icon within the contents of the widget. + + If this value is not specified, it defaults to the value + that depends on the native style. + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 77 + + This property is currently supported only by QPushButton + and QProgressBar. + + \row + \o \bold{\c text-decoration} + \o \c none \BR + \c underline \BR + \c overline \BR + \c line-through + \o Additional text effects + + \row + \o \bold{\c top} \target top-prop + \o \l{#Length}{Length} + \o If \l{#position-prop}{position} is \c relative (the + default), moves a \l{subcontrol} by a certain offset + down. + + If \l{#position-prop}{position} is \c absolute, the \c top + property specifies the subcontrol's top edge in relation + to the parent's top edge (see also + \l{Qt Style Sheets Reference#subcontrol-origin-prop}{subcontrol-origin}). + + If this property is not specified, it defaults to \c 0. + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 78 + + See also \l{Qt Style Sheets Reference#left-prop}{left}, \l{#right-prop}{right}, and + \l{#bottom-prop}{bottom}. + + \row + \o \bold{\c width} \target width-prop + \o \l{#Length}{Length} + \o The width of a \l{subcontrol} (or a widget in some cases). + + If this property is not specified, it defaults to a value + that depends on the subcontrol/widget and on the current style. + + \warning Unless otherwise specified, this property has no effect + when set on widgets. If you want a widget with a fixed width, set + the \l{#min-width-prop}{min-width} and + \l{#max-width-prop}{max-width} to the same value. + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 79 + + See also \l{#height-prop}{height}. + + \endtable + + \target list of icons + \section1 List of Icons + + Icons used in Qt can be customized using the following properties. Each of + the properties listed in this section have the type \l{#Icon}{Icon}. + + Note that for icons to appear in buttons in a QDialogButtonBox, you need to + set the dialogbuttonbox-buttons-have-icons property to true. Also, to + customize the size of the icons, use the icon-size property. + + \table 100% + \header + \o Name + \o QStyle::StandardPixmap + + \row + \o backward-icon + \o QStyle::SP_ArrowBack + + \row + \o cd-icon + \o QStyle::SP_DriveCDIcon + + \row + \o computer-icon + \o QStyle::SP_ComputerIcon + + \row + \o desktop-icon + \o QStyle::SP_DesktopIcon + + \row + \o dialog-apply-icon + \o QStyle::SP_DialogApplyButton + + \row + \o dialog-cancel-icon + \o QStyle::SP_DialogCancelButton + + \row + \o dialog-close-icon + \o QStyle::SP_DialogCloseButton + + \row + \o dialog-discard-icon + \o QStyle::SP_DialogDiscardButton + + \row + \o dialog-help-icon + \o QStyle::SP_DialogHelpButton + + \row + \o dialog-no-icon + \o QStyle::SP_DialogNoButton + + \row + \o dialog-ok-icon + \o QStyle::SP_DialogOkButton + + \row + \o dialog-open-icon + \o QStyle::SP_DialogOpenButton + + \row + \o dialog-reset-icon + \o QStyle::SP_DialogResetButton + + \row + \o dialog-save-icon + \o QStyle::SP_DialogSaveButton + + \row + \o dialog-yes-icon + \o QStyle::SP_DialogYesButton + + \row + \o directory-closed-icon + \o QStyle::SP_DirClosedIcon + + \row + \o directory-icon + \o QStyle::SP_DirIcon + + \row + \o directory-link-icon + \o QStyle::SP_DirLinkIcon + + \row + \o directory-open-icon + \o QStyle::SP_DirOpenIcon + + \row + \o dockwidget-close-icon + \o QStyle::SP_DockWidgetCloseButton + + \row + \o downarrow-icon + \o QStyle::SP_ArrowDown + + \row + \o dvd-icon + \o QStyle::SP_DriveDVDIcon + + \row + \o file-icon + \o QStyle::SP_FileIcon + + \row + \o file-link-icon + \o QStyle::SP_FileLinkIcon + + \omit + \row + \o filedialog-backward-icon + \o QStyle::SP_FileDialogBack + \endomit + + \row + \o filedialog-contentsview-icon + \o QStyle::SP_FileDialogContentsView + + \row + \o filedialog-detailedview-icon + \o QStyle::SP_FileDialogDetailedView + + \row + \o filedialog-end-icon + \o QStyle::SP_FileDialogEnd + + \row + \o filedialog-infoview-icon + \o QStyle::SP_FileDialogInfoView + + \row + \o filedialog-listview-icon + \o QStyle::SP_FileDialogListView + + \row + \o filedialog-new-directory-icon + \o QStyle::SP_FileDialogNewFolder + + \row + \o filedialog-parent-directory-icon + \o QStyle::SP_FileDialogToParent + + \row + \o filedialog-start-icon + \o QStyle::SP_FileDialogStart + + \row + \o floppy-icon + \o QStyle::SP_DriveFDIcon + + \row + \o forward-icon + \o QStyle::SP_ArrowForward + + \row + \o harddisk-icon + \o QStyle::SP_DriveHDIcon + + \row + \o home-icon + \o QStyle::SP_DirHomeIcon + + \row + \o leftarrow-icon + \o QStyle::SP_ArrowLeft + + \row + \o messagebox-critical-icon + \o QStyle::SP_MessageBoxCritical + + \row + \o messagebox-information-icon + \o QStyle::SP_MessageBoxInformation + + \row + \o messagebox-question-icon + \o QStyle::SP_MessageBoxQuestion + + \row + \o messagebox-warning-icon + \o QStyle::SP_MessageBoxWarning + + \row + \o network-icon + \o QStyle::SP_DriveNetIcon + + \row + \o rightarrow-icon + \o QStyle::SP_ArrowRight + + \row + \o titlebar-contexthelp-icon + \o QStyle::SP_TitleBarContextHelpButton + + \row + \o titlebar-maximize-icon + \o QStyle::SP_TitleBarMaxButton + + \row + \o titlebar-menu-icon + \o QStyle::SP_TitleBarMenuButton + + \row + \o titlebar-minimize-icon + \o QStyle::SP_TitleBarMinButton + + \row + \o titlebar-normal-icon + \o QStyle::SP_TitleBarNormalButton + + \row + \o titlebar-shade-icon + \o QStyle::SP_TitleBarShadeButton + + \row + \o titlebar-unshade-icon + \o QStyle::SP_TitleBarUnshadeButton + + \row + \o trash-icon + \o QStyle::SP_TrashIcon + + \row + \o uparrow-icon + \o QStyle::SP_ArrowUp + + \endtable + + \section1 List of Property Types + + The following table summarizes the syntax and meaning of the + different property types. + + \table 100% + \header + \o Type + \o Syntax + \o Description + + \row + \o \bold Alignment \target Alignment + \o \{ \c top \BR + | \c bottom \BR + | \c left \BR + | \c right \BR + | \c center \}* + \o Horizontal and/or vertical alignment. + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 80 + + \row + \o \bold Attachment \target Attachment + \o \{ \c scroll \BR + | \c fixed \}* + \o Scroll or fixed attachment. + + \row + \o \bold Background \target Background + \o \{ \l{#Brush}{Brush} \BR + | \l{#Url}{Url} \BR + | \l{#Repeat}{Repeat} \BR + | \l{#Alignment}{Alignment} \}* + \o A sequence of \l{#Brush}{Brush}, \l{#Url}{Url}, + \l{#Repeat}{Repeat}, and \l{#Alignment}{Alignment}. + + \row + \o \bold Boolean \target Boolean + \o 0 | 1 + \o True (\c 1) or false (\c 0). + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 81 + + \row + \o \bold Border \target Border + \o \{ \l{#Border Style}{Border Style} \BR + | \l{#Length}{Length} \BR + | \l{#Brush}{Brush} \}* + \o Shorthand border property. + + \row + \o \bold{Border Image} \target Border Image + \o \c none \BR + | \l{Url} \l{Number}\{4\} \BR (\c stretch | \c repeat){0,2} + \o A border image is an image that is composed of nine parts + (top left, top center, top right, center left, center, + center right, bottom left, bottom center, and bottom + right). When a border of a certain size is required, the + corner parts are used as is, and the top, right, bottom, + and left parts are stretched or repeated to produce a + border with the desired size. + + See the + \l{http://www.w3.org/TR/css3-background/#the-border-image} + {CSS3 Draft Specification} for details. + + \row + \o \bold{Border Style} \target Border Style + \o \c dashed \BR + | \c dot-dash \BR + | \c dot-dot-dash \BR + | \c dotted \BR + | \c double \BR + | \c groove \BR + | \c inset \BR + | \c outset \BR + | \c ridge \BR + | \c solid \BR + | \c none + \o Specifies the pattern used to draw a border. + See the \l{http://www.w3.org/TR/css3-background/#border-style} + {CSS3 Draft Specification} for details. + + \row + \o \bold{Box Colors} \target Box Colors + \o \l{#Brush}{Brush}\{1,4\} + \o One to four occurrences of \l{#Brush}{Brush}, specifying the top, + right, bottom, and left edges of a box, respectively. If + the left color is not specified, it is taken to be the + same as the right color. If the bottom color is not + specified, it is taken to be the same as the top color. If + the right color is not specified, it is taken to be the + same as the top color. + + Example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 82 + + \row + \o \bold{Box Lengths} \target Box Lengths + \o \l{#Length}{Length}\{1,4\} + \o One to four occurrences of \l{#Length}{Length}, specifying the + top, right, bottom, and left edges of a box, + respectively. If the left length is not specified, it is + taken to be the same as the right length. If the bottom + length is not specified, is it taken to be the same as the + top length. If the right length is not specified, it is + taken to be the same as the top length. + + Examples: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 83 + + \row + \o \bold{Brush} \target Brush + \o \l{#Color}{Color} \BR + | \l{Gradient} \BR + | \l{PaletteRole} + \o Specifies a Color or a Gradient or an entry in the Palette. + + \row + \o \bold{Color} \target Color + \o \tt{rgb(\e{r}, \e{g}, \e{b})} \BR + | \tt{rgba(\e{r}, \e{g}, \e{b}, \e{a})} \BR + | \tt{hsv(\e{h}, \e{s}, \e{v})} \BR + | \tt{hsva(\e{h}, \e{s}, \e{v}, \e{a})} \BR + | \tt{#\e{rrggbb}} \BR + | \l{QColor::setNamedColor()}{Color Name} \BR + \o Specifies a color as RGB (red, green, blue) or RGBA + (red, green, blue, alpha) or HSV (hue, saturation, value) or HSVA + (hue, saturation, value, alpha) or a named color. The \c rgb() or \c rgba() + syntax can be used with integer values between 0 and 255, or with + percentages. The value of s, v, and a in \c hsv() or \c hsva() must all + be in the range 0-255; the value of h must be in the range 0-359. + + Examples: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 84 + + \note The RGB colors allowed are the same as those allowed with + CSS 2.1, as listed + \l{http://www.w3.org/TR/CSS21/syndata.html#color-units}{here}. + + \row + \o \bold{Font} \target Font + \o (\l{#Font Style}{Font Style} | \l{#Font Weight}{Font Weight}){0,2} \l{#Font Size}{Font Size} String + \o Shorthand font property. + + \row + \o \bold{Font Size} \target Font Size + \o \l{Length} + \o The size of a font. + + \row + \o \bold{Font Style} \target Font Style + \o \c normal \BR + | \c italic \BR + | \c oblique + \o The style of a font. + + \row + \o \bold{Font Weight} \target Font Weight + \o \c normal \BR + | \c bold \BR + | \c 100 \BR + | \c 200 \BR + ... \BR + | \c 900 + \o The weight of a font. + + \row + \o \bold{Gradient} \target Gradient + \o \c qlineargradient \BR + | \c qradialgradient \BR + | \c qconicalgradient + \o Specifies gradient fills. There are three types of gradient fills: + + \list + \o \e{Linear} gradients interpolate colors between start and + end points. + \o \e{Radial} gradients interpolate colors between a focal + point and end points on a circle surrounding it. + \o \e{Conical} gradients interpolate colors around a center + point. + \endlist + + Gradients are specified in Object Bounding Mode. Imagine the box + in which the gradient is rendered, to have its top left corner at (0, 0) + and its bottom right corner at (1, 1). Gradient parameters are + then specified as percentages from 0 to 1. These values are + extrapolated to actual box coordinates at runtime. It is possible + specify values that lie outside the bounding box (-0.6 or 1.8, for + instance). + + \warning The stops have to appear sorted in ascending order. + + Examples: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 85 + + \row + \o \bold{Icon} \target Icon + \o (\l{#Url}{Url} (\c disabled | \c active | \c normal | \c selected)? + (\c on | \c off)? )* + \o A list of url, QIcon::Mode and QIcon::State. + + Example: + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 86 + + \row + \o \bold{Length} \target Length + \o \l{#Number}{Number} (\c px | \c pt | \c em | \c ex)? + \o A number followed by a measurement unit. The CSS standard recommends + that user agents must + \l{http://www.w3.org/TR/CSS21/syndata.html#illegalvalues}{ignore} + a declaration with an illegal value. In Qt, it is mandatory to + specify measurement units. For compatibility with earlier versions + of Qt, numbers without measurement units are treated as pixels + in most contexts. The supported units are: + + \list + \o \c px: pixels + \o \c pt: the size of one point (i.e., 1/72 of an inch) + \o \c em: the em width of the font (i.e., the width of 'M') + \o \c ex: the ex width of the font (i.e., the height of 'x') + \endlist + + \row + \o \bold{Number} \target Number + \o A decimal integer or a real number + \o Examples: \c 0, \c 18, \c +127, \c -255, \c 12.34, \c -.5, + \c 0009. + + \row + \o \bold{Origin} \target Origin + \o \c margin \BR + | \c border \BR + | \c padding \BR + | \c content + \o Indicates which of four rectangles to use. + + \list + \o \c margin: The margin rectangle. The margin falls outside the border. + \o \c border: The border rectangle. This is where any border is drawn. + \o \c padding: The padding rectangle. Unlike the margins, + padding is located inside the border. + \o \c content: The content rectangle. This specifies where + the actual contents go, excluding any + padding, border, or margin. + \endlist + + See also \l{The Box Model}. + + \row + \o \bold{PaletteRole} \target PaletteRole + \o \c alternate-base \BR + | \c base \BR + | \c bright-text \BR + | \c button \BR + | \c button-text \BR + | \c dark \BR + | \c highlight \BR + | \c highlighted-text \BR + | \c light \BR + | \c link \BR + | \c link-visited \BR + | \c mid \BR + | \c midlight \BR + | \c shadow \BR + | \c text \BR + | \c window \BR + | \c window-text \BR + \o These values correspond the \l{QPalette::ColorRole}{Color roles} + in the widget's QPalette. + + For example, + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 87 + + \row + \o \bold{Radius} \target Radius + \o \l{#Length}{Length}\{1, 2\} + \o One or two occurrences of \l{#Length}{Length}. If only one length is + specified, it is used as the radius of the quarter circle + defining the corner. If two lengths are specified, the + first length is the horizontal radius of a quarter + ellipse, whereas the second length is the vertical radius. + + \row + \o \bold{Repeat} \target Repeat + \o \c repeat-x \BR + | \c repeat-y \BR + | \c repeat \BR + | \c no-repeat + \o A value indicating the nature of repetition. + + \list + \o \c repeat-x: Repeat horizontally. + \o \c repeat-y: Repeat vertically. + \o \c repeat: Repeat horizontally and vertically. + \o \c no-repeat: Don't repeat. + \endlist + + \row + \o \bold{Url} \target Url + \o \tt{url(\e{filename})} + \o \tt{\e{filename}} is the name of a file on the local disk + or stored using \l{the Qt Resource System}. Setting an + image implicitly sets the width and height of the element. + + \endtable + + \section1 List of Pseudo-States + + The following pseudo-states are supported: + + \table 100% + \header + \o Pseudo-State + \o Description + + \row \o \c :active \target active + \o This state is set when the widget resides in an active window. + + \row + \o \c :adjoins-item \target adjoins-item-ps + \o This state is set when the \l{#branch-sub}{::branch} of a QTreeView + is adjacent to an item. + + \row + \o \c :alternate \target alternate-ps + \o This state is set for every alternate row whe painting the row of + a QAbstractItemView when QAbstractItemView::alternatingRowColors() + is set to true. + + \row + \o \c :bottom \target bottom-ps + \o The item is positioned at the bottom. For example, a QTabBar + that has its tabs positioned at the bottom. + + \row + \o \c :checked \target checked-ps + \o The item is checked. For example, the + \l{QAbstractButton::checked}{checked} state of QAbstractButton. + + \row + \o \c :closable \target closable-ps + \o The items can be closed. For example, the QDockWidget has the + QDockWidget::DockWidgetClosable feature turned on. + + \row + \o \c :closed \target closed-ps + \o The item is in the closed state. For example, an non-expanded + item in a QTreeView + + \row + \o \c :default \target default-ps + \o The item is the default. For example, a + \l{QPushButton::default}{default} QPushButton or a default action + in a QMenu. + + \row + \o \c :disabled \target disabled-ps + \o The item is \l{QWidget::enabled}{disabled}. + + \row + \o \c :editable \target editable-ps + \o The QComboBox is editable. + + \row + \o \c :edit-focus \target edit-focus-ps + \o The item has edit focus (See QStyle::State_HasEditFocus). This state + is available only for Qt Extended applications. + + \row + \o \c :enabled \target enabled-ps + \o The item is \l{QWidget::enabled}{enabled}. + + \row + \o \c :exclusive \target exclusive-ps + \o The item is part of an exclusive item group. For example, a menu + item in a exclusive QActionGroup. + + \row + \o \c :first \target first-ps + \o The item is the first (in a list). For example, the first + tab in a QTabBar. + + \row + \o \c :flat \target flat-ps + \o The item is flat. For example, a + \l{QPushButton::flat}{flat} QPushButton. + + \row + \o \c :floatable \target floatable-ps + \o The items can be floated. For example, the QDockWidget has the + QDockWidget::DockWidgetFloatable feature turned on. + + \row + \o \c :focus \target focus-ps + \o The item has \l{QWidget::hasFocus()}{input focus}. + + \row + \o \c :has-children \target has-children-ps + \o The item has children. For example, an item in a + QTreeView that has child items. + + \row + \o \c :has-siblings \target has-siblings-ps + \o The item has siblings. For example, an item in a + QTreeView that siblings. + + \row + \o \c :horizontal \target horizontal-ps + \o The item has horizontal orientation + + \row + \o \c :hover \target hover-ps + \o The mouse is hovering over the item. + + \row + \o \c :indeterminate \target indeterminate-ps + \o The item has indeterminate state. For example, a QCheckBox + or QRadioButton is \l{Qt::PartiallyChecked}{partially checked}. + + \row + \o \c :last \target last-ps + \o The item is the last (in a list). For example, the last + tab in a QTabBar. + + \row + \o \c :left \target left-ps + \o The item is positioned at the left. For example, a QTabBar + that has its tabs positioned at the left. + + \row + \o \c :maximized \target maximized-ps + \o The item is maximized. For example, a maximized QMdiSubWindow. + + \row + \o \c :middle \target middle-ps + \o The item is in the middle (in a list). For example, a tab + that is not in the beginning or the end in a QTabBar. + + \row + \o \c :minimized \target minimized-ps + \o The item is minimized. For example, a minimized QMdiSubWindow. + + \row + \o \c :movable \target movable-ps + \o The item can be moved around. For example, the QDockWidget has the + QDockWidget::DockWidgetMovable feature turned on. + + \row + \o \c :no-frame \target no-frame-ps + \o The item has no frame. For example, a frameless QSpinBox + or QLineEdit. + + \row + \o \c :non-exclusive \target non-exclusive-ps + \o The item is part of a non-exclusive item group. For example, a menu + item in a non-exclusive QActionGroup. + + \row + \o \c :off \target off-ps + \o For items that can be toggled, this applies to items + in the "off" state. + + \row + \o \c :on \target on-ps + \o For items that can be toggled, this applies to widgets + in the "on" state. + + \row + \o \c :only-one \target only-one-ps + \o The item is the only one (in a list). For example, a lone tab + in a QTabBar. + + \row + \o \c :open \target open-ps + \o The item is in the open state. For example, an expanded + item in a QTreeView, or a QComboBox or QPushButton with + an open menu. + + \row + \o \c :next-selected \target next-selected-ps + \o The next item (in a list) is selected. For example, the + selected tab of a QTabBar is next to this item. + + \row + \o \c :pressed \target pressed-ps + \o The item is being pressed using the mouse. + + \row + \o \c :previous-selected \target previous-selected-ps + \o The previous item (in a list) is selected. For example, a + tab in a QTabBar that is next to the selected tab. + + \row + \o \c :read-only \target read-only-ps + \o The item is marked read only or non-editable. For example, + a read only QLineEdit or a non-editable QComboBox. + + \row + \o \c :right \target right-ps + \o The item is positioned at the right. For example, a QTabBar + that has its tabs positioned at the right. + + \row + \o \c :selected \target selected-ps + \o The item is selected. For example, the selected tab in + a QTabBar or the selected item in a QMenu. + + \row + \o \c :top \target top-ps + \o The item is positioned at the top. For example, a QTabBar + that has its tabs positioned at the top. + + \row + \o \c :unchecked \target unchecked-ps + \o The item is + \l{QAbstractButton::checked}{unchecked}. + + \row + \o \c :vertical \target vertical-ps + \o The item has vertical orientation. + + \row + \o \c :window \target window-ps + \o The widget is a window (i.e top level widget) + + \endtable + + \target subcontrols + \section1 List of Sub-Controls + + The following subcontrols are available: + + \table 100% + \header + \o Sub-Control + \o Description + + \row + \o \c ::add-line \target add-line-sub + \o The button to add a line of a QScrollBar. + + \row + \o \c ::add-page \target add-page-sub + \o The region between the handle (slider) and the \l{#add-line-sub}{add-line} + of a QScrollBar. + + \row + \o \c ::branch \target branch-sub + \o The branch indicator of a QTreeView. + + \row + \o \c ::chunk \target chunk-sub + \o The progress chunk of a QProgressBar. + + \row + \o \c ::close-button \target close-button-sub + \o The close button of a QDockWidget or tabs of QTabBar + + \row + \o \c ::corner \target corner-sub + \o The corner between two scrollbars in a QAbstractScrollArea + + \row + \o \c ::down-arrow \target down-arrow-sub + \o The down arrow of a QComboBox, QHeaderView (sort indicator), + QScrollBar or QSpinBox. + + \row + \o \c ::down-button \target down-button-sub + \o The down button of a QScrollBar or a QSpinBox. + + \row + \o \c ::drop-down \target drop-down-sub + \o The drop-down button of a QComboBox. + + \row + \o \c ::float-button \target float-button-sub + \o The float button of a QDockWidget + + \row + \o \c ::groove \target groove-sub + \o The groove of a QSlider. + + \row + \o \c ::indicator \target indicator-sub + \o The indicator of a QAbstractItemView, a QCheckBox, a QRadioButton, + a checkable QMenu item or a checkable QGroupBox. + + \row + \o \c ::handle \target handle-sub + \o The handle (slider) of a QScrollBar, a QSplitter, or a QSlider. + + \row + \o \c ::icon \target icon-sub + \o The icon of a QAbstractItemView or a QMenu. + + \row + \o \c ::item \target item-sub + \o An item of a QAbstractItemView, a QMenuBar, a QMenu, or + a QStatusBar. + + \row + \o \c ::left-arrow \target left-arrow-sub + \o The left arrow of a QScrollBar. + + \row + \o \c ::left-corner \target left-corner-sub + \o The left corner of a QTabWidget. For example, this control can be + used to control position the left corner widget in a QTabWidget. + + \row + \o \c ::menu-arrow \target menu-arrow-sub + \o The arrow of a QToolButton with a menu. + + \row + \o \c ::menu-button \target menu-button-sub + \o The menu button of a QToolButton. + + \row + \o \c ::menu-indicator \target menu-indicator-sub + \o The menu indicator of a QPushButton. + + \row + \o \c ::right-arrow \target right-arrow-sub + \o The right arrow of a QMenu or a QScrollBar. + + \row + \o \c ::pane \target pane-sub + \o The pane (frame) of a QTabWidget. + + \row + \o \c ::right-corner \target right-corner-sub + \o The right corner of a QTabWidget. For example, this control can be + used to control the position the right corner widget in a QTabWidget. + + \row + \o \c ::scroller \target scroller-sub + \o The scroller of a QMenu or QTabBar. + + \row + \o \c ::section \target section-sub + \o The section of a QHeaderView. + + \row + \o \c ::separator \target separator-sub + \o The separator of a QMenu or in a QMainWindow. + + \row + \o \c ::sub-line \target sub-line-sub + \o The button to subtract a line of a QScrollBar. + + \row + \o \c ::sub-page \target sub-page-sub + \o The region between the handle (slider) and the \l{#sub-line-sub}{sub-line} + of a QScrollBar. + + \row + \o \c ::tab \target tab-sub + \o The tab of a QTabBar or QToolBox. + + \row + \o \c ::tab-bar \target tab-bar-sub + \o The tab bar of a QTabWidget. This subcontrol exists only to + control the position of the QTabBar inside the QTabWidget. To + style the tabs using the \l{#tab-sub}{::tab} subcontrol. + + \row + \o \c ::tear \target tear-sub + \o The tear indicator of a QTabBar. + + \row + \o \c ::tearoff \target tearoff-sub + \o The tear-off indicator of a QMenu. + + \row + \o \c ::text \target text-ps + \o The text of a QAbstractItemView. + + \row + \o \c ::title \target title-sub + \o The title of a QGroupBox or a QDockWidget. + + \row + \o \c ::up-arrow \target up-arrow-sub + \o The up arrow of a QHeaderView (sort indicator), QScrollBar + or a QSpinBox. + + \row + \o \c ::up-button \target up-button-sub + \o The up button of a QSpinBox. + + \endtable + + See \l{Customizing the QPushButton's Menu Indicator Sub-Control} + for an example of how to customize a subcontrol. + */ + +/*! + \page stylesheet-examples.html + \contentspage {Qt Style Sheet}{Contents} + \previouspage Qt Style Sheets Reference + \title Qt Style Sheets Examples + + We will now see a few examples to get started with using Qt Style Sheets. + + \tableofcontents + \section1 Style Sheet Usage + + \section2 Customizing the Foreground and Background Colors + + Let's start by setting yellow as the background color of all + \l{QLineEdit}s in an application. This could be achieved like + this: + + \snippet doc/src/snippets/code/doc_src_stylesheet.cpp 88 + + If we want the property to apply only to the \l{QLineEdit}s that are + children (or grandchildren or grand-grandchildren) of a specific dialog, + we would rather do this: + + \snippet doc/src/snippets/code/doc_src_stylesheet.cpp 89 + + If we want the property to apply only to one specific QLineEdit, + we can give it a name using QObject::setObjectName() and use an + ID Selector to refer to it: + + \snippet doc/src/snippets/code/doc_src_stylesheet.cpp 90 + + Alternatively, we can set the + \l{Qt Style Sheets Reference#background-prop}{background-color} property directly on the + QLineEdit, omitting the selector: + + \snippet doc/src/snippets/code/doc_src_stylesheet.cpp 91 + + To ensure a good contrast, we should also specify a suitable + color for the text: + + \snippet doc/src/snippets/code/doc_src_stylesheet.cpp 92 + + It might be a good idea to change the colors used for selected + text as well: + + \snippet doc/src/snippets/code/doc_src_stylesheet.cpp 93 + + + \section2 Customizing Using Dynamic Properties + + There are many situations where we need to present a form that + has mandatory fields. To indicate to the user that the field is + mandatory, one effective (albeit esthetically dubious) solution + is to use yellow as the background color for those fields. It + turns out this is very easy to implement using Qt Style Sheets. + First, we would use the following application-wide style sheet: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 94 + + This means that every widget whose \c mandatoryField Qt property + is set to true would have a yellow background. + + Then, for each mandatory field widget, we would simply create a + \c mandatoryField property on the fly and set it to true. For + example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.cpp 95 + + \section2 Customizing a QPushButton Using the Box Model + + This time, we will show how to create a red QPushButton. This + QPushButton would presumably be connected to a very destructive + piece of code. + + First, we are tempted to use this style sheet: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 96 + + However, the result is a boring, flat button with no borders: + + \image stylesheet-redbutton1.png A flat red button + + What happened is this: + + \list + \o We have made a request that cannot be satisfied using the + native styles alone (e.g., the Windows XP theme engine doesn't + let us specify the background color of a button). + \o Therefore, the button is rendered using style sheets. + \o We haven't specified any values for + \l{Qt Style Sheets Reference#border-width-prop}{border-width} and + \l{Qt Style Sheets Reference#border-style-prop}{border-style}, so by default we obtain + a 0-pixel wide border of style \c none. + \endlist + + Let's improve the situation by specifying a border: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 97 + + \image stylesheet-redbutton2.png A red button with a beige border + + Things look already a lot better. But the button looks a bit + cramped. Let's specify some spacing between the border and the + text using the \l{Qt Style Sheets Reference#padding-prop}{padding}. Additionally, we will + enforce a minimum width, round the corners, and specify a larger + font to make the button look nicer: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 98 + + \image stylesheet-redbutton3.png A red button with a round beige border and big, bold text + + The only issue remaining is that the button doesn't react when we + press it. We can fix this by specifying a slightly different + background color and use a different border style. + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 99 + + \section2 Customizing the QPushButton's Menu Indicator Sub-Control + + Subcontrols give access to the sub-elements of a widget. For + example, a QPushButton associated with a menu (using + QPushButton::setMenu()) has a menu indicator. Let's customize + the menu indicator for the red push button: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 100 + + By default, the menu indicator is located at the bottom-right + corner of the padding rectangle. We can change this by specifying + \l{Qt Style Sheets Reference#subcontrol-position-prop}{subcontrol-position} and + \l{Qt Style Sheets Reference#subcontrol-origin-prop}{subcontrol-origin} to anchor the + indicator differently. We can also use \l{Qt Style Sheets Reference#top-prop}{top} and + \l{Qt Style Sheets Reference#left-prop}{left} to move the indicator by a few pixels. For + example: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 101 + + This positions the \c myindicator.png to the center right of the + QPushButton's \l{Qt Style Sheets Reference#padding-prop}{padding} rectangle (see + \l{Qt Style Sheets Reference#subcontrol-origin-prop}{subcontrol-origin} for more + information). + + \section2 Complex Selector Example + + Since red seems to be our favorite color, let's make the text in + QLineEdit red by setting the following application-wide + stylesheet: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 102 + + However, we would like to give a visual indication that a + QLineEdit is read-only by making it appear gray: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 103 + + At some point, our design team comes with the requirement that + all \l{QLineEdit}s in the registration form (with the + \l{QObject::objectName}{object name} \c registrationDialog) to be + brown: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 104 + + A few UI design meetings later, we decide that all our + \l{QDialog}s should have brown colored \l{QLineEdit}s: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 105 + + Quiz: What happens if we have a read-only QLineEdit in a QDialog? + [Hint: The \l{The Style Sheet Syntax#Conflict Resolution}{Conflict Resolution} section above explains + what happens in cases like this.] + + \section1 Customizing specific widgets + + This section provides examples to customize specific widgets using Style Sheets. + + \section2 Customizing QAbstractScrollArea + + The background of any QAbstractScrollArea (Item views, QTextEdit + and QTextBrowser) can be set using the background properties. For example, + to set a background-image that scrolls with the scroll bar: + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 106 + + If the background-image is to be fixed with the viewport: + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 107 + + \section2 Customizing QCheckBox + + Styling of a QCheckBox is almost indentical to styling a QRadioButton. The + main difference is that a tristate QCheckBox has an indeterminate state. + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 108 + + \section2 Customizing QComboBox + + We will look at an example where the drop down button of a QComboBox + appears "merged" with the combo box frame. + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 109 + + The pop-up of the QComboBox is a QAbstractItemView and is styled using + the descendant selector: + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 110 + + \section2 Customizing QDockWidget + + The title bar and the buttons of a QDockWidget can be customized as + follows: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 111 + + If one desires to move the dock widget buttons to the left, the following + style sheet can be used: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 112 + + \note To customize the separator (resize handle) of a QDockWidget, + use QMainWindow::separator. + + \section2 Customizing QFrame + + A QFrame is styled using the \l{The Box Model}. + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 113 + + \section2 Customizing QGroupBox + + Let us look at an example that moves the QGroupBox's title to + the center. + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 114 + + For a checkable QGroupBox, use the \{#indicator-sub}{::indicator} subcontrol + and style it exactly like a QCheckBox (i.e) + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 115 + + \section2 Customizing QHeaderView + + QHeaderView is customized as follows: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 116 + + \section2 Customizing QLineEdit + + The frame of a QLineEdit is styled using the \l{The Box Model}. To + create a line edit with rounded corners, we can set: + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 117 + + The password character of line edits that have QLineEdit::Password + echo mode can be set using: + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 118 + + The background of a read only QLineEdit can be modified as below: + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 119 + + \section2 Customizing QListView + + The background color of alternating rows can be customized using the following + style sheet: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 120 + + To provide a special background when you hover over items, we can use the + \l{item-sub}{::item} subcontrol. For example, + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 121 + + \section2 Customizing QMainWindow + + The separator of a QMainWindow can be styled as follows: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 122 + + \section2 Customizing QMenu + + Individual items of a QMenu are styled using the 'item' subcontrol as + follows: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 123 + + For a more advanced customization, use a style sheet as follows: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 124 + + \section2 Customizing QMenuBar + + QMenuBar is styled as follows: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 125 + + \section2 Customizing QProgressBar + + The QProgressBar's \l{stylesheet-reference.html#border-prop}{border}, + \l{stylesheet-reference.html#chunk-sub}{chunk}, and + \l{stylesheet-reference.html#text-align-prop}{text-align} can be customized using + style sheets. However, if one property or sub-control is customized, + all the other properties or sub-controls must be customized as well. + + \image progressBar-stylesheet.png + + For example, we change the \l{stylesheet-reference.html#border-prop} + {border} to grey and the \l{stylesheet-reference.html#chunk-sub}{chunk} + to cerulean. + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 126 + + This leaves the \l{stylesheet-reference.html#text-align-prop} + {text-align}, which we customize by positioning the text in the center of + the progress bar. + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 127 + + A \l{stylesheet-reference.html#margin-prop}{margin} can be included to + obtain more visible chunks. + + \image progressBar2-stylesheet.png + + In the screenshot above, we use a + \l{stylesheet-reference.html#margin-prop}{margin} of 0.5 pixels. + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 128 + + \section2 Customizing QPushButton + + A QPushButton is styled as follows: + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 129 + + For a QPushButton with a menu, use the + \l{Qt Style Sheets Reference#menu-indicator-sub}{::menu-indicator} + subcontrol. + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 130 + + Checkable QPushButton have the \l{Qt Style Sheets Reference#checked-ps} + {:checked} pseudo state set. + + \section2 Customizing QRadioButton + + The indicator of a QRadioButton can be changed using: + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 131 + + \section2 Customizing QScrollBar + + The QScrollBar can be styled using its subcontrols like + \l{stylesheet-reference.html#handle-sub}{handle}, + \l{stylesheet-reference.html#add-line-sub}{add-line}, + \l{stylesheet-reference.html#sub-line-sub}{sub-line}, and so on. Note that + if one property or sub-control is customized, all the other properties or + sub-controls must be customized as well. + + \image stylesheet-scrollbar1.png + + The scroll bar above has been styled in aquamarine with a solid grey + border. + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 132 + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 133 + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 134 + + The \l{stylesheet-reference.html#left-arrow-sub}{left-arrow} and + \l{stylesheet-reference.html#right-arrow-sub}{right-arrow} have a solid grey + border with a white background. As an alternative, you could also embed the + image of an arrow. + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 135 + + If you want the scroll buttons of the scroll bar to be placed together + (instead of the edges) like on Mac OS X, you can use the following + stylesheet: + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 136 + + The scroll bar using the above stylesheet looks like this: + \image stylesheet-scrollbar2.png + + + To customize a vertical scroll bar use a style sheet similar to the following: + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 137 + + \section2 Customizing QSizeGrip + + QSizeGrip is usually styled by just setting an image. + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 138 + + \section2 Customizing QSlider + + You can style horizontal slider as below: + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 139 + + If you want to change the color of the slider parts before and after the handle, you can use the add-page + and sub-page subcontrols. For example, for a vertical slider: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 140 + + \section2 Customizing QSpinBox + + QSpinBox can be completely customized as below (the style sheet has commentary inline): + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 141 + + + \section2 Customizing QSplitter + + A QSplitter derives from a QFrame and hence can be styled like a QFrame. + The grip or the handle is customized using the + \l{Qt Style Sheets Reference#handle-sub}{::handle} subcontrol. + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 142 + + \section2 Customizing QStatusBar + + We can provide a background for the status bar and a border for items + inside the status bar as follows: + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 143 + + Note that widgets that have been added to the QStatusBar can be styled + using the descendant declaration (i.e) + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 144 + + \section2 Customizing QTabWidget and QTabBar + + \image tabWidget-stylesheet1.png + + For the screenshot above, we need a stylesheet as follows: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 145 + + Often we require the tabs to overlap to look like below: + \image tabWidget-stylesheet2.png + + For a tab widget that looks like above, we make use of + \l{http://www.communitymx.com/content/article.cfm?cid=B0029} + {negative margins}. The resulting stylesheet looks like this: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 146 + + To move the tab bar to the center (as below), we require the following stylesheet: + \image tabWidget-stylesheet3.png + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 147 + + The tear indicator and the scroll buttons can be further customized as follows: + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 148 + + Since Qt 4.6 the close button can be customized as follow: + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 159 + + \section2 Customizing QTableView + + Suppose we'd like our selected item in QTableView to have bubblegum pink + fade to white as its background. + + \image tableWidget-stylesheet.png + + This is possible with the + \l{stylesheet-reference.html#selection-background-color-prop} + {selection-background-color} property and the syntax required is: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 149 + + The corner widget can be customized using the following style sheet + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 150 + + \section2 Customizing QToolBar + + The background and the handle of a QToolBar is customized as below: + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 151 + + \section2 Customizing QToolBox + + The tabs of the QToolBox are customized using the 'tab' subcontrol. + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 152 + + \section2 Customizing QToolButton + + There are three types of QToolButtons. + \list + \i The QToolButton has no menu. In this case, the QToolButton is styled + exactly like QPushButton. See + \l{#Customizing QPushButton}{Customizing QPushButton} for an + example. + + \i The QToolButton has a menu and has the QToolButton::popupMode set to + QToolButton::DelayedPopup or QToolButton::InstantPopup. In this case, + the QToolButton is styled exactly like a QPushButton with a menu. + See \l{#Customizing QPushButton}{Customizing QPushButton} for an + example of the usage of the menu-indicator pseudo state. + + \i The QToolButton has its QToolButton::popupMode set to + QToolButton::MenuButtonPopup. In this case, we style it as follows: + \endlist + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 153 + + + \section2 Customizing QToolTip + + QToolTip is customized exactly like a QLabel. In addition, for platforms + that support it, the opacity property may be set to adjust the opacity. + + For example, + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 154 + + \section2 Customizing QTreeView + + The background color of alternating rows can be customized using the following + style sheet: + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 155 + + To provide a special background when you hover over items, we can use the + \l{item-sub}{::item} subcontrol. For example, + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 156 + + The branches of a QTreeView are styled using the + \l{Qt Style Sheets Reference#branch-sub}{::branch} subcontrol. The + following stylesheet color codes the various states when drawing + a branch. + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 157 + + Colorful, though it is, a more useful example can be made using the + following images: + + \table + \row + \o \inlineimage stylesheet-vline.png + \o \inlineimage stylesheet-branch-more.png + \o \inlineimage stylesheet-branch-end.png + \o \inlineimage stylesheet-branch-closed.png + \o \inlineimage stylesheet-branch-open.png + \row + \o vline.png + \o branch-more.png + \o branch-end.png + \o branch-closed.png + \o branch-open.png + \endtable + + \snippet doc/src/snippets/code/doc_src_stylesheet.qdoc 158 + + The resulting tree view looks like this: + + \image stylesheet-treeview.png + + \sa {Style Sheet Example}, {Supported HTML Subset}, QStyle + + + \section1 Common mistakes + + This section lists some common mistakes when using stylesheets. + + \section2 QPushButton and images + + When styling a QPushButton, it is often desirable to use an image as the + button graphic. It is common to try the + \l{Qt Style Sheets Reference#background-image-prop}{background-image} + property, + but this has a number of drawbacks: For instance, the background will + often appear hidden behind the button decoration, because it is not + considered a background. In addition, if the button is resized, the + entire background will be stretched or tiled, which does not + always look good. + + It is better to use the + \l{Qt Style Sheets Reference#border-image-prop}{border-image} + property, as it will always display the image, + regardless of the background (you can combine it with a background if it + has alpha values in it), and it has special settings to deal with button + resizing. + + Consider the following snippet: + + \snippet doc/src/snippets/stylesheet/common-mistakes.cpp 1 + + This will produce a button looking like this: + + \image stylesheet-border-image-normal.png + + The numbers after the url gives the top, right, bottom and left number of + pixels, respectively. These numbers correspond to the border and should not + stretch when the size changes. + Whenever you resize the button, the middle part of the image will stretch + in both directions, while the pixels specified in the stylesheet + will not. This makes the borders of the button look more natural, like + this: + + \table + \row + \o \inlineimage stylesheet-border-image-stretched.png + \row + \o With borders + \endtable + + \table + \row + \o \inlineimage stylesheet-border-image-wrong.png + \row + \o Without borders + \endtable + + */ diff --git a/doc/src/widgets-and-layouts/widgets.qdoc b/doc/src/widgets-and-layouts/widgets.qdoc new file mode 100644 index 0000000000..66872b69ed --- /dev/null +++ b/doc/src/widgets-and-layouts/widgets.qdoc @@ -0,0 +1,162 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page widgets-and-layouts.html + \title Widgets and Layouts + \ingroup qt-gui-concepts + \brief The primary elements for designing user interfaces in Qt. + + \section1 Widgets + + Widgets are the primary elements for creating user interfaces in Qt. + \l{The Widget Classes}{Widgets} can display data and status information, + receive user input, and provide a container for other widgets that + should be grouped together. A widget that is not embedded in a + parent widget is called a \l{Window and Dialog Widgets} {window}. + + \image parent-child-widgets.png A parent widget containing various child widgets. + + The QWidget class provides the basic capability to render to the + screen, and to handle user input events. All UI elements that Qt + provides are either subclasses of QWidget, or are used in connection + with a QWidget subclass. Creating custom widgets is done by + subclassing QWidget or a suitable subclass and reimplementing the + virtual event handlers. + + \section1 Layouts + + \l{Layout Management}{Layouts} are an elegant and flexible way to + automatically arrange child widgets within their container. Each + widget reports its size requirements to the layout through the + \l{QWidget::}{sizeHint} and \l{QWidget::}{sizePolicy} properties, + and the layout distributes the available space accordingly. + + \table + \row + \o \image qgridlayout-with-5-children.png + \o \image qformlayout-with-6-children.png + \endtable + + \l{Qt Designer Manual}{\QD} is a powerful tool for interactively creating and + arranging widgets in layouts. + + \section1 Widget Styles + + \l{Styles and Style Aware Widgets}{Styles} draw on behalf of + widgets and encapsulate the look and feel of a GUI. Qt's built-in + widgets use the QStyle class to perform nearly all of their drawing, + ensuring that they look exactly like the equivalent native widgets. + + \table + \row + \o \image windowsxp-tabwidget.png + \o \image plastique-tabwidget.png + \o \image macintosh-tabwidget.png + \endtable + + \l{Qt Style Sheets} are a powerful mechanism that allows you to customize the + appearance of widgets, in addition to what is already possible by subclassing QStyle. + + \section1 The Widget Classes + + The following sections list the widget classes. See the \l{Qt Widget + Gallery} for some examples. + + \section2 Basic Widgets + + These basic widgets (controls), e.g. buttons, comboboxes and + scroll bars, are designed for direct use. + + \table + \row + \o \image windows-label.png + \o \image windowsvista-pushbutton.png + \o \image gtk-progressbar.png + \row + \o \image plastique-combobox.png + \o \image macintosh-radiobutton.png + \o \image cde-lineedit.png + \endtable + + \annotatedlist basicwidgets + + \section2 Advanced Widgets + + Advanced GUI widgets, e.g. tab widgets and progress bars, provide + more complex user interface controls. + + \table + \row + \o \image windowsxp-treeview.png + \o \image gtk-calendarwidget.png + \o \image qundoview.png + \endtable + + \annotatedlist advanced + + \table + \row + \o \image windowsvista-tabwidget.png + \o \image macintosh-groupbox.png + \endtable + + \section2 Organizer Widgets + + Classes like splitters, tab bars, button groups, etc are used for + organizing and grouping GUI primitives into more complex + applications and dialogs. + + \annotatedlist organizers + + \section2 Abstract Widget Classes + + The abstract widget classes are base classes. They are not usable as + standalone classes but provide functionality when they are subclassed. + + \annotatedlist abstractwidgets +*/ + +/*! + \group advanced + \title Advanced Widgets +*/ + +/*! + \group abstractwidgets + \title Abstract Widget Classes +*/ + +/*! + \group basicwidgets + \title Basic Widgets +*/ + +/*! + \group organizers + \title Organizers +*/ diff --git a/doc/src/windows-and-dialogs/dialogs.qdoc b/doc/src/windows-and-dialogs/dialogs.qdoc new file mode 100644 index 0000000000..895b19faaa --- /dev/null +++ b/doc/src/windows-and-dialogs/dialogs.qdoc @@ -0,0 +1,60 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \group standard-dialogs + \ingroup qt-gui-concepts + \title Standard Dialogs + \brief A list of Qt classes for implementing standard dialogs. +*/ + +/*! + \page dialogs.html + \title Dialog Windows + \ingroup qt-gui-concepts + \brief An overview over dialog windows. + + \previouspage Application Main Window + \contentspage Application Windows and Dialogs + \nextpage Desktop Integration + + Dialogs can be \e{modal}, in which case the user is required to provide + necessary information before work in the main window + can continue, or \e{modeless}. Modeless dialogs do not prevent the user from + interacting with any of the other windows in the application. + + Qt provides a set of ready-made dialogs for file, font, color-selection + and more. + + \annotatedlist standard-dialogs + + Custom dialogs can be easily created by composing regular widgets into + a QDialog. These classes are specifically designed for building custom + dialogs: + + \annotatedlist dialog-classes +*/ diff --git a/doc/src/windows-and-dialogs/mainwindow.qdoc b/doc/src/windows-and-dialogs/mainwindow.qdoc new file mode 100644 index 0000000000..e7df50257f --- /dev/null +++ b/doc/src/windows-and-dialogs/mainwindow.qdoc @@ -0,0 +1,261 @@ +/**************************************************************************** +** +** Copyright (C) 2011 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:FDL$ +** 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 Free Documentation License +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of this +** file. +** +** If you have questions regarding the use of this file, please contact +** Nokia at qt-info@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \group mainwindow-classes + \title Main Window and Related Classes +*/ + +/*! + \page application-windows.html + \title Window and Dialog Widgets + \brief Windows and Dialogs in Qt. + \ingroup qt-gui-concepts + + A \l{Widgets Tutorial}{widget} that is not embedded in a parent widget is called a window. + (Usually, windows have a frame and a title bar, although it is also possible to create + windows without such decoration using suitable window flags). In Qt, QMainWindow + and the various subclasses of QDialog are the most common window types. + + In applications, windows provide the screen space upon which the user + interface is built. Windows separate applications visually from each other + and usually provide a window decoration that allows the user to resize and + position the applications according to his preferences. Windows are typically + integrated into the desktop environment and to some degree managed by the + window management system that the desktop environment provides. For instance, + selected windows of an application are represented in the task bar. + + \section1 Primary and Secondary Windows + + Any QWidget that has no parent will become a window, and will on most platforms + be listed in the desktop's task bar. This is usually only wanted for one + window in the application, the \e{primary window}. + + In addition, a QWidget that has a parent can become a window by setting the + \l{Qt::WindowType}{Qt::WA_Window} flag. Depending on the window management system + such \e{secondary windows} are usually stacked on top of their respective parent + window, and not have a task bar entry of their own. + + The QMainWindow and the QDialog classes set the Qt::WA_Window flag in their + constructor, as they are designed to be used as windows and provide facilities + that are not wanted for child widgets. + + \section1 Main Windows and Dialogs + + The \l{Application Main Window} provides the framework for building the + application's main user interface, and are created by subclassing QMainWindow. + QMainWindow has its own layout to which you can add a \l{QMenuBar}{menu bar}, + \l{QToolBar}{tool bars}, \l{QDockWidget}{dockable widgets} and a + \l{QStatusBar}{status bar}. The center area can be occupied by any kind of + QWidget. + + \l{Dialog Windows} are used as secondary windows that present the user with + options and choices. Dialogs are created by subclassing QDialog and using + \l{Widgets and Layouts}{widgets and layouts} to implement the user interface. + In addition, Qt provides a number of ready-made standard dialogs that can be + used for standard tasks like file or font selection. + + Both main windows and dialogs can be created with \QD, Qt's visual design tool. + Using \QD is a lot faster than hand-coding, and makes it easy to test different + design ideas. Creating designs visually and reading the code generated by + \l{uic} is a great way to learn Qt! + + \keyword window geometry + \section1 Window Geometry + + QWidget provides several functions that deal with a widget's + geometry. Some of these functions operate on the pure client area + (i.e. the window excluding the window frame), others include the + window frame. The differentiation is done in a way that covers the + most common usage transparently. + + \list + \o \bold{Including the window frame:} + \l{QWidget::x()}{x()}, + \l{QWidget::y()}{y()}, + \l{QWidget::frameGeometry()}{frameGeometry()}, + \l{QWidget::pos()}{pos()}, and + \l{QWidget::move()}{move()}. + \o \bold{Excluding the window frame:} + \l{QWidget::geometry()}{geometry()}, + \l{QWidget::width()}{width()}, + \l{QWidget::height()}{height()}, + \l{QWidget::rect()}{rect()}, and + \l{QWidget::size()}{size()}. + \endlist + + Note that the distinction only matters for decorated top-level + widgets. For all child widgets, the frame geometry is equal to the + widget's client geometry. + + This diagram shows most of the functions in use: + \img geometry.png Geometry diagram + + \section2 X11 Peculiarities + + On X11, a window does not have a frame until the window manager + decorates it. This happens asynchronously at some point in time + after calling QWidget::show() and the first paint event the + window receives, or it does not happen at all. Bear in mind that + X11 is policy-free (others call it flexible). Thus you cannot + make any safe assumption about the decoration frame your window + will get. Basic rule: There's always one user who uses a window + manager that breaks your assumption, and who will complain to + you. + + Furthermore, a toolkit cannot simply place windows on the screen. All + Qt can do is to send certain hints to the window manager. The window + manager, a separate process, may either obey, ignore or misunderstand + them. Due to the partially unclear Inter-Client Communication + Conventions Manual (ICCCM), window placement is handled quite + differently in existing window managers. + + X11 provides no standard or easy way to get the frame geometry + once the window is decorated. Qt solves this problem with nifty + heuristics and clever code that works on a wide range of window + managers that exist today. Don't be surprised if you find one + where QWidget::frameGeometry() returns wrong results though. + + Nor does X11 provide a way to maximize a window. + QWidget::showMaximized() has to emulate the feature. Its result + depends on the result of QWidget::frameGeometry() and the + capability of the window manager to do proper window placement, + neither of which can be guaranteed. +*/ + +/*! + \page mainwindow.html + \title Application Main Window + \ingroup qt-gui-concepts + \brief Creating the application window. + + \tableofcontents + + \section1 Overview of the Main Window Classes + + These classes provide everything you need for a typical modern main + application window, like the main window itself, menu and tool bars, + a status bar, etc. + + \annotatedlist mainwindow-classes + + \section1 The Main Window Classes + + Qt 4 provides the following classes for managing main windows and + associated user interface components: + + \list + \o QMainWindow remains the central class around which applications + can be built. The interface to this class has been simplified, and + much of the functionality previously included in this class is now + present in the companion QDockWidget and QToolBar classes. + + \o QDockWidget provides a widget that can be used to create + detachable tool palettes or helper windows. Dock widgets keep track + of their own properties, and they can be moved, closed, and floated + as external windows. + + \o QToolBar provides a generic toolbar widget that can hold a + number of different action-related widgets, such as buttons, + drop-down menus, comboboxes, and spin boxes. The emphasis on a + unified action model in Qt 4 means that toolbars cooperate well + with menus and keyboard shortcuts. + \endlist + + \section1 Example Code + + Using QMainWindow is straightforward. Generally, we subclass + QMainWindow and set up menus, toolbars, and dock widgets inside + the QMainWindow constructor. + + To add a menu bar to the main window, we simply create the menus, and + add them to the main window's menu bar. Note that the + QMainWindow::menuBar() function will automatically create the menu bar + the first time it is called. You can also call + QMainWindow::setMenuBar() to use a custom menu bar in the main window. + + \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.cpp 0 + \dots + \snippet examples/mainwindows/menus/mainwindow.cpp 5 + \dots + + Once actions have been created, we can add them to the main window + components. To begin with, we add them to the pop-up menus: + + \snippet examples/mainwindows/menus/mainwindow.cpp 10 + \dots + \snippet examples/mainwindows/menus/mainwindow.cpp 11 + \dots + + The QToolBar and QMenu classes use Qt's action system to provide a + consistent API. In the above code, some existing actions were added to + the file menu with the QMenu::addAction() function. QToolBar also + provides this function, making it easy to reuse actions in different + parts of the main window. This avoids unnecessary duplication of work. + + We create a toolbar as a child of the main window, and add the desired + actions to it: + + \snippet examples/mainwindows/sdi/mainwindow.cpp 0 + \dots + \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.cpp 1 + + In this example, the toolbar is restricted to the top and bottom + toolbar areas of the main window, and is initially placed in the + top tool bar area. We can see that the actions specified by \c + newAct and \c openAct will be displayed both on the toolbar and in + the file menu. + + QDockWidget is used in a similar way to QToolBar. We create a + dock widget as a child of the main window, and add widgets as children + of the dock widget: + + \snippet doc/src/snippets/dockwidgets/mainwindow.cpp 0 + + In this example, the dock widget can only be placed in the left and + right dock areas, and it is initially placed in the left dock area. + + The QMainWindow API allows the programmer to customize which dock + widget areas occupy the four corners of the dock widget area. If + required, the default can be changed with the + QMainWindow::setCorner() function: + + \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.cpp 2 + + The following diagram shows the configuration produced by the above code. + Note that the left and right dock widgets will occupy the top and bottom + corners of the main window in this layout. + + \image mainwindow-docks-example.png + + Once all of the main window components have been set up, the central widget + is created and installed by using code similar to the following: + + \snippet doc/src/snippets/code/doc_src_qt4-mainwindow.cpp 3 + + The central widget can be any subclass of QWidget. +*/ |
