diff options
| author | Gabriel de Dietrich <gabriel.dietrich-de@nokia.com> | 2012-08-17 13:23:19 +0200 |
|---|---|---|
| committer | Qt by Nokia <qt-info@nokia.com> | 2012-08-20 12:20:55 +0200 |
| commit | 806dda08d685bc5f9ed71dfe8b61f21848d48066 (patch) | |
| tree | a63533a1c4a335ae17adc105abb0ae4e62e2f26e /doc | |
| parent | 9f942014e31842b512c3198de035d041c59f54a9 (diff) | |
Moving .qdoc files under examples/widgets/doc
Updated those .qdoc files to refer to the new relative examples
emplacement. Images and snippets to be moved later.
Also grouped all widgets related examples under widgets.
Change-Id: Ib29696e2d8948524537f53e8dda88f9ee26a597f
Reviewed-by: J-P Nurmi <j-p.nurmi@nokia.com>
Diffstat (limited to 'doc')
102 files changed, 0 insertions, 18915 deletions
diff --git a/doc/src/examples/addressbook.qdoc b/doc/src/examples/addressbook.qdoc deleted file mode 100644 index 9b4ede5775..0000000000 --- a/doc/src/examples/addressbook.qdoc +++ /dev/null @@ -1,442 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 \uicontrol File and \uicontrol 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 \b Name and \b 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 \b Name or - \b {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, - \b Name and \b 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 \uicontrol{Edit Entry...} and - \uicontrol{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 \uicontrol{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 \uicontrol OK - and \uicontrol 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 \li \inlineimage addressbook-filemenu.png - \li \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 \uicontrol Open, \uicontrol Close and - \uicontrol Exit actions, as well as the \uicontrol Tools menu with - \uicontrol{Add Entry...}, \uicontrol{Edit Entry...} and \uicontrol{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 \uicontrol File and - \uicontrol Tools menus, connecting the actions to their respective slots. - Both the \uicontrol{Edit Entry...} and \uicontrol{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 - \uicontrol 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 \uicontrol File menu. - - \snippet itemviews/addressbook/mainwindow.cpp 3 - - The \c updateActions() function enables and disables - \uicontrol{Edit Entry...} and \uicontrol{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/affine.qdoc b/doc/src/examples/affine.qdoc deleted file mode 100644 index c69794d511..0000000000 --- a/doc/src/examples/affine.qdoc +++ /dev/null @@ -1,48 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \example painting/affine - \title Affine Transformations - - In this example 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 - \li Dragging the red circle in the centre of each drawing moves it to a new position. - \li Dragging the displaced red circle causes the current drawing to be rotated about the - central circle. Rotation can also be controlled with the \uicontrol Rotate slider. - \li Scaling is controlled with the \uicontrol Scale slider. - \li Each drawing can be sheared with the \uicontrol Shear slider. - \endlist -*/ diff --git a/doc/src/examples/analogclock.qdoc b/doc/src/examples/analogclock.qdoc deleted file mode 100644 index 4385da07b6..0000000000 --- a/doc/src/examples/analogclock.qdoc +++ /dev/null @@ -1,154 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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. - - \image 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 deleted file mode 100644 index 4fe25388cf..0000000000 --- a/doc/src/examples/animatedtiles.qdoc +++ /dev/null @@ -1,36 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 deleted file mode 100644 index 092db7c29e..0000000000 --- a/doc/src/examples/appchooser.qdoc +++ /dev/null @@ -1,38 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 deleted file mode 100644 index 9cfdc08134..0000000000 --- a/doc/src/examples/application.qdoc +++ /dev/null @@ -1,396 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 \uicontrol{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 covers - \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 \uicontrol{Edit|Cut} and \uicontrol{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 \uicontrol{Yes} button is - made the default button (the button that is invoked when the user - presses \uicontrol{Return}) using the QMessageBox::Default flag; the - \uicontrol{Cancel} button is made the escape button (the button that is - invoked when the user presses \uicontrol{Esc}) using the - QMessageBox::Escape flag. - - The \c maybeSave() function returns \c true in all cases, except - when the user clicks \uicontrol{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/basicdrawing.qdoc b/doc/src/examples/basicdrawing.qdoc deleted file mode 100644 index 1c4053f847..0000000000 --- a/doc/src/examples/basicdrawing.qdoc +++ /dev/null @@ -1,454 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 (\uicontrol Shape), and modify the QPainter's pen (\uicontrol - {Pen Width}, \uicontrol {Pen Style}, \uicontrol {Pen Cap}, \uicontrol {Pen Join}), - brush (\uicontrol {Brush Style}) and render hints (\uicontrol - Antialiasing). In addition the user can rotate a shape (\uicontrol - 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 - \li \c RenderArea is a custom widget that renders multiple - copies of the currently active shape. - \li \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 \uicontrol 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 \uicontrol {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 \uicontrol {Pen Style}, \uicontrol - {Pen Cap} and \uicontrol {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 \uicontrol {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 \uicontrol Antialiasing option. - - \snippet examples/painting/basicdrawing/window.cpp 7 - - The \uicontrol 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 \uicontrol 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 \uicontrol Points, \uicontrol Polyline and \uicontrol 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 \uicontrol Path and the \uicontrol 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 \uicontrol Arc, \uicontrol Chord and \uicontrol 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 \uicontrol 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 \uicontrol 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 - \li QPainter::drawLine(), - \li QPainter::drawPoints(), - \li QPainter::drawPolyline(), - \li QPainter::drawPolygon(), - \li QPainter::drawRect(), - \li QPainter::drawRoundedRect(), - \li QPainter::drawEllipse(), - \li QPainter::drawArc(), - \li QPainter::drawChord(), - \li QPainter::drawPie(), - \li QPainter::drawPath(), - \li QPainter::drawText() or - \li 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 \uicontrol 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 deleted file mode 100644 index b7023cf9ca..0000000000 --- a/doc/src/examples/basicgraphicslayouts.qdoc +++ /dev/null @@ -1,164 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 - \li create a new \c LayoutItem, - \li add the item \c linear, and - \li 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 deleted file mode 100644 index 37d9fcb70a..0000000000 --- a/doc/src/examples/basiclayouts.qdoc +++ /dev/null @@ -1,190 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 \uicontrol File menu containing an \uicontrol 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 deleted file mode 100644 index 0ecf4a0629..0000000000 --- a/doc/src/examples/basicsortfiltermodel.qdoc +++ /dev/null @@ -1,37 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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/blurpicker.qdoc b/doc/src/examples/blurpicker.qdoc deleted file mode 100644 index bd57acb061..0000000000 --- a/doc/src/examples/blurpicker.qdoc +++ /dev/null @@ -1,33 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 deleted file mode 100644 index aaff2dda1d..0000000000 --- a/doc/src/examples/borderlayout.qdoc +++ /dev/null @@ -1,36 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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/boxes.qdoc b/doc/src/examples/boxes.qdoc deleted file mode 100644 index aa34a61bc3..0000000000 --- a/doc/src/examples/boxes.qdoc +++ /dev/null @@ -1,49 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \example graphicsview/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 - \li Dragging the mouse while pressing the left mouse button rotates the - box in the center. - \li Dragging the mouse while pressing the right mouse button rotates the - satellite boxes. - \li 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/examples/calculator.qdoc b/doc/src/examples/calculator.qdoc deleted file mode 100644 index 914b8c5299..0000000000 --- a/doc/src/examples/calculator.qdoc +++ /dev/null @@ -1,375 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 - \li \c Calculator is the calculator widget, with all the - calculator functionality. - \li \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 \uicontrol 0 to \uicontrol 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 (\uicontrol{Sqrt}, \uicontrol{x\unicode{178}}, - \uicontrol{1/x}), additive operators (\uicontrol{+}, \uicontrol{-}), and - multiplicative operators (\uicontrol{\unicode{215}}, \uicontrol{\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 (\uicontrol{+}, \uicontrol{-}, \uicontrol{\unicode{215}}, or \uicontrol{\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 - \li \c sumInMemory contains the value stored in the calculator's memory - (using \uicontrol{MS}, \uicontrol{M+}, or \uicontrol{MC}). - \li \c sumSoFar stores the value accumulated so far. When the user - clicks \uicontrol{=}, \c sumSoFar is recomputed and shown on the - display. \uicontrol{Clear All} resets \c sumSoFar to zero. - \li \c factorSoFar stores a temporary value when doing - multiplications and divisions. - \li \c pendingAdditiveOperator stores the last additive operator - clicked by the user. - \li \c pendingMultiplicativeOperator stores the last multiplicative operator - clicked by the user. - \li \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, \uicontrol{1 + 2 \unicode{247} - 3} is interpreted as \uicontrol{1 + (2 \unicode{247} 3)} because \uicontrol{\unicode{247}} has higher - precedence than \uicontrol{+}. - - The table below shows the evolution of the calculator state as - the user enters a mathematical expression. - - \table - \header \li User Input \li Display \li Sum so Far \li Add. Op. \li Factor so Far \li Mult. Op. \li Waiting for Operand? - \row \li \li 0 \li 0 \li \li \li \li \c true - \row \li \uicontrol{1} \li 1 \li 0 \li \li \li \li \c false - \row \li \uicontrol{1 +} \li 1 \li 1 \li \uicontrol{+} \li \li \li \c true - \row \li \uicontrol{1 + 2} \li 2 \li 1 \li \uicontrol{+} \li \li \li \c false - \row \li \uicontrol{1 + 2 \unicode{247}} \li 2 \li 1 \li \uicontrol{+} \li 2 \li \uicontrol{\unicode{247}} \li \c true - \row \li \uicontrol{1 + 2 \unicode{247} 3} \li 3 \li 1 \li \uicontrol{+} \li 2 \li \uicontrol{\unicode{247}} \li \c false - \row \li \uicontrol{1 + 2 \unicode{247} 3 -} \li 1.66667 \li 1.66667 \li \uicontrol{-} \li \li \li \c true - \row \li \uicontrol{1 + 2 \unicode{247} 3 - 4} \li 4 \li 1.66667 \li \uicontrol{-} \li \li \li \c false - \row \li \uicontrol{1 + 2 \unicode{247} 3 - 4 =} \li -2.33333 \li 0 \li \li \li \li \c true - \endtable - - Unary operators, such as \uicontrol 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 \uicontrol{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 \uicontrol Sqrt is applied to a - negative number or \uicontrol{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 \uicontrol{+} or \uicontrol{-} 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 \uicontrol{\unicode{215}} or \uicontrol{\unicode{247}} has been clicked earlier, without clicking - \uicontrol{=} afterward, the current value in the display is the right - operand of the \uicontrol{\unicode{215}} or \uicontrol{\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 \uicontrol{+} or \uicontrol{-} 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 \uicontrol 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 - \li We add 20 to the \l{QSize::height()}{height} component of the size hint. - \li 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 - \uicontrol{Backspace}, \uicontrol{Clear}, and \uicontrol{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 deleted file mode 100644 index aea9805669..0000000000 --- a/doc/src/examples/calendar.qdoc +++ /dev/null @@ -1,223 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 - \li Use of a text editor with a text document - \li Insertion of tables and frames into a document - \li Navigation within a table - \li 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 deleted file mode 100644 index 45423cc2c6..0000000000 --- a/doc/src/examples/calendarwidget.qdoc +++ /dev/null @@ -1,291 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 \li Property - \li Description - \row \li \l{QCalendarWidget::}{selectedDate} - \li The currently selected date. - \row \li \l{QCalendarWidget::}{minimumDate} - \li The earliest date that can be selected. - \row \li \l{QCalendarWidget::}{maximumDate} - \li The latest date that can be selected. - \row \li \l{QCalendarWidget::}{firstDayOfWeek} - \li The day that is displayed as the first day of the week - (usually Sunday or Monday). - \row \li \l{QCalendarWidget::}{gridVisible} - \li Whether the grid should be shown. - \row \li \l{QCalendarWidget::}{selectionMode} - \li Whether the user can select a date or not. - \row \li \l{QCalendarWidget::}{horizontalHeaderFormat} - \li The format of the day names in the horizontal header - (e.g., "M", "Mon", or "Monday"). - \row \li \l{QCalendarWidget::}{verticalHeaderFormat} - \li The format of the vertical header. - \row \li \l{QCalendarWidget::}{navigationBarVisible} - \li 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 \uicontrol 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 \uicontrol{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 \uicontrol {Minimum Date}, \uicontrol {Maximum Date}, - and \uicontrol {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 \uicontrol {Current Date} editor. We also need to react when the user - changes the \uicontrol{Minimum Date} and \uicontrol{Maximum Date} editors. - - Here is the \c createTextFormatsGroup() function: - - \snippet examples/widgets/calendarwidget/window.cpp 16 - - We set up the \uicontrol {Weekday Color} and \uicontrol {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 \uicontrol {Header Text Format} combobox lets the user change the - text format (bold, italic, or plain) used for horizontal and - vertical headers. The \uicontrol {First Friday in blue} and \uicontrol {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 \uicontrol {First Friday in blue} and \uicontrol {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 \uicontrol {Weekday Color} - and \uicontrol {Weekend Color} comboboxes. - - \snippet examples/widgets/calendarwidget/window.cpp 1 - - When the user changes the \uicontrol {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 \uicontrol{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 \uicontrol {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 \uicontrol {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 deleted file mode 100644 index 5fbcae1fad..0000000000 --- a/doc/src/examples/charactermap.qdoc +++ /dev/null @@ -1,274 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 -\li \c CharacterWidget displays the available characters in the current - font and style. -\li \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 deleted file mode 100644 index 947eddf1c9..0000000000 --- a/doc/src/examples/chart.qdoc +++ /dev/null @@ -1,82 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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. - - \b{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 - \li 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. - \li 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/chip.qdoc b/doc/src/examples/chip.qdoc deleted file mode 100644 index 966c16900a..0000000000 --- a/doc/src/examples/chip.qdoc +++ /dev/null @@ -1,38 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \example graphicsview/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/examples/classwizard.qdoc b/doc/src/examples/classwizard.qdoc deleted file mode 100644 index eec9b6ac51..0000000000 --- a/doc/src/examples/classwizard.qdoc +++ /dev/null @@ -1,190 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 - \li \c ClassWizard inherits QWizard and provides a - three-step wizard that generates the skeleton of a C++ class - based on the user's input. - \li \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 - \li The first page is an introduction page, telling the user what - the wizard is going to do. - \li 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. - \li 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). - \li The fourth page allows the user to specify the names of the - output files. - \li The fifth page is a conclusion page. - \endlist - - Although the program is just an example, if you press \uicontrol Finish - (\uicontrol 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 \uicontrol{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 \uicontrol 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 - \uicontrol Next button (\uicontrol 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/codeeditor.qdoc b/doc/src/examples/codeeditor.qdoc deleted file mode 100644 index 695ac5c4ce..0000000000 --- a/doc/src/examples/codeeditor.qdoc +++ /dev/null @@ -1,197 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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. The "Matching Parentheses - with QSyntaxHighlighter" article in Qt Quarterly 31 implements - this. You find it here: \l{http://doc.qt.nokia.com/qq/}. - -*/ diff --git a/doc/src/examples/coloreditorfactory.qdoc b/doc/src/examples/coloreditorfactory.qdoc deleted file mode 100644 index 1806446fb7..0000000000 --- a/doc/src/examples/coloreditorfactory.qdoc +++ /dev/null @@ -1,155 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 - \li 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. - \li If the editor requires other constructors or other - initialization than provided by QItemEditorCreatorBase, you - must reimplement - QItemEditorCreatorBase::createWidget(). - \li 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 deleted file mode 100644 index dae95ddb26..0000000000 --- a/doc/src/examples/combowidgetmapper.qdoc +++ /dev/null @@ -1,167 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \example itemviews/combowidgetmapper - \title Combo Widget Mapper Example - - The Combo 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/composition.qdoc b/doc/src/examples/composition.qdoc deleted file mode 100644 index 6aca01d255..0000000000 --- a/doc/src/examples/composition.qdoc +++ /dev/null @@ -1,44 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \example painting/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 \b{Source} and \b{SourceOver}. - \b{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 \b{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/examples/concentriccircles.qdoc b/doc/src/examples/concentriccircles.qdoc deleted file mode 100644 index 22b0be8fb8..0000000000 --- a/doc/src/examples/concentriccircles.qdoc +++ /dev/null @@ -1,231 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 - \li \c CircleWidget is a custom widget which renders several animated - concentric circles. - \li \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 deleted file mode 100644 index 9acea72a3b..0000000000 --- a/doc/src/examples/configdialog.qdoc +++ /dev/null @@ -1,36 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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/customsortfiltermodel.qdoc b/doc/src/examples/customsortfiltermodel.qdoc deleted file mode 100644 index 61230a7b9a..0000000000 --- a/doc/src/examples/customsortfiltermodel.qdoc +++ /dev/null @@ -1,289 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 - - \li The \c MySortFilterProxyModel class provides a custom proxy - model. - - \li 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 addresses. 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 addresses. 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 addresses we must - first identify the address within the given string: - - \snippet examples/itemviews/customsortfiltermodel/mysortfilterproxymodel.cpp 6 - - We use QRegExp to define a pattern for the addresses 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 address. 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/deform.qdoc b/doc/src/examples/deform.qdoc deleted file mode 100644 index 8195f90ffa..0000000000 --- a/doc/src/examples/deform.qdoc +++ /dev/null @@ -1,51 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \example painting/deform - \title Vector Deformation - - This example 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/examples/diagramscene.qdoc b/doc/src/examples/diagramscene.qdoc deleted file mode 100644 index ac9ca2f294..0000000000 --- a/doc/src/examples/diagramscene.qdoc +++ /dev/null @@ -1,834 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 - \li Create custom graphics items. - \li Handle mouse events and movement of items. - \li Implement a graphics scene that can manage our custom items. - \li Custom painting of items. - \li Create a movable and editable text item. - \endlist - - The example consists of the following classes: - \list - \li \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. - \li \c DiagramItem inherits QGraphicsPolygonItem and - represents a flowchart shape. - \li \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. - \li \c Arrow inherits QGraphicsLineItem and is an arrow - that connect two DiagramItems. - \li \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 deleted file mode 100644 index 39d015efd1..0000000000 --- a/doc/src/examples/digitalclock.qdoc +++ /dev/null @@ -1,74 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 deleted file mode 100644 index a4b799678a..0000000000 --- a/doc/src/examples/dirview.qdoc +++ /dev/null @@ -1,36 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 file and directory information. - - \image dirview-example.png -*/ diff --git a/doc/src/examples/dockwidgets.qdoc b/doc/src/examples/dockwidgets.qdoc deleted file mode 100644 index 8c64c78ae4..0000000000 --- a/doc/src/examples/dockwidgets.qdoc +++ /dev/null @@ -1,163 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 \uicontrol 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/dragdroprobot.qdoc b/doc/src/examples/dragdroprobot.qdoc deleted file mode 100644 index c6563a5286..0000000000 --- a/doc/src/examples/dragdroprobot.qdoc +++ /dev/null @@ -1,365 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \example graphicsview/dragdroprobot - \title Drag and Drop Robot Example - - The Drag and Drop Robot 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 constructor 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/dynamiclayouts.qdoc b/doc/src/examples/dynamiclayouts.qdoc deleted file mode 100644 index 318f719503..0000000000 --- a/doc/src/examples/dynamiclayouts.qdoc +++ /dev/null @@ -1,34 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 deleted file mode 100644 index 7fb7f59531..0000000000 --- a/doc/src/examples/easing.qdoc +++ /dev/null @@ -1,37 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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/editabletreemodel.qdoc b/doc/src/examples/editabletreemodel.qdoc deleted file mode 100644 index 958080ad58..0000000000 --- a/doc/src/examples/editabletreemodel.qdoc +++ /dev/null @@ -1,446 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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()}, - \l{QAbstractItemModel::}{columnCount()}, 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::}{setHeaderData()}, 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 \li \inlineimage itemviews-editabletreemodel-items.png - \li \b{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, \b{A} and - \b{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 \b{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 \li \inlineimage itemviews-editabletreemodel-model.png - \li \b{Accessing data via the model} - - In the case shown in the diagram, the piece of information represented - by \b{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 \b{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 \b{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 \li \b{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 \b{a}, \b{b} and \b{c} in the - previous two diagrams, are stored in items \b{A}, \b{B} and - \b{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. - - \li \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 - \li \inlineimage itemviews-editabletreemodel-indexes.png - \li \b{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 \b{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 \b{B}. The parent model index is - created using the QAbstractItemModel::createIndex() function, passing - the pointer to item \b{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 deleted file mode 100644 index bd25008f60..0000000000 --- a/doc/src/examples/elasticnodes.qdoc +++ /dev/null @@ -1,430 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \example graphicsview/elasticnodes - \title Elastic Nodes Example - - The Elastic Nodes 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 - \li Painting a yellow gradient "ball" in two states: sunken and raised. - \li Managing connections to other nodes. - \li 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 practice, 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 practice 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/elidedlabel.qdoc b/doc/src/examples/elidedlabel.qdoc deleted file mode 100644 index 6833aedc13..0000000000 --- a/doc/src/examples/elidedlabel.qdoc +++ /dev/null @@ -1,162 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \example widgets/elidedlabel - \group all-examples - \title Elided Label Example - - This example creates a widget similar to QLabel, that elides the last - visible line, if the text is too long to fit the widget's geometry. - - \image elidedlabel-example.png Elided Label example on XPressMusic 5800 - - When text of varying length has to be displayed in a uniformly sized - area, for instance within a list or grid view where all list items have the - same size, it can be useful to give the user a visual clue when not all - text is visible. QLabel can elide text that doesn't fit within it, but only - in one line. The \c ElidedLabel widget shown in this example word wraps its - text by its width, and elides the last visible line if some text is left - out. \c TestWidget gives control to the features of \c ElidedWidget and - forms the example application. - - - \section1 ElidedLabel Class Definition - - Like QLabel, \c ElidedLabel inherits from QFrame. Here's the definition of - the \c ElidedLabel class: - - - \snippet examples/widgets/elidedlabel/elidedlabel.h 0 - - The \c isElided property depends the font, text content and geometry of the - widget. Whenever any of these change, the \c elisionChanged() signal might - trigger. We cache the current elision value in \c elided, so that it - doesn't have to be recomputed every time it's asked for. - - - \section1 ElidedLabel Class Implementation - - Except for initializing the member variables, the constructor sets the size - policy to be horizontally expanding, since it's meant to fill the width of - its container and grow vertically. - - \snippet examples/widgets/elidedlabel/elidedlabel.cpp 0 - - Changing the \c content require a repaint of the widget. - - \snippet examples/widgets/elidedlabel/elidedlabel.cpp 1 - - QTextLayout is used in the \c paintEvent() to divide the \c content into - lines, that wrap on word boundaries. Each line, except the last visible - one, is drawn \c lineSpacing pixels below the previous one. The \c draw() - method of QTextLine will draw the line using the coordinate point as the - top left corner. - - \snippet examples/widgets/elidedlabel/elidedlabel.cpp 2 - - Unfortunately, QTextLayout does not elide text, so the last visible line - has to be treated differently. This last line is elided if it is too wide. - The \c drawText() method of QPainter draws the text starting from the base - line, which is \c ascecnt() pixels below the last drawn line. - - Finally, one more line is created to see if everything fit on this line. - - \snippet examples/widgets/elidedlabel/elidedlabel.cpp 3 - - If the text was elided and wasn't before or vice versa, cache it in - \c elided and emit the change. - - \snippet examples/widgets/elidedlabel/elidedlabel.cpp 4 - - - \section1 TestWidget Class Definition - - \c TestWidget is a QWidget and is the main window of the example. It - contains an \c ElidedLabel which can be resized with two QSlider widgets. - - \snippet examples/widgets/elidedlabel/testwidget.h 0 - - \section1 TestWidget Class Implementation - - The constructor initializes the whole widget. Strings of different length - are stored in \c textSamples. The user is able to switch between these. - - \snippet examples/widgets/elidedlabel/testwidget.cpp 0 - - An \c ElidedLabel is created to contain the first of the sample strings. - The frame is made visible to make it easier to see the actual size of the - widget. - - \snippet examples/widgets/elidedlabel/testwidget.cpp 1 - - The buttons and the elision label are created. By connecting the - \c elisionChanged() signal to the \c setVisible() slot of the \c label, - it will act as an indicator to when the text is elided or not. This signal - could, for instance, be used to make a "More" button visible, or similar. - - \snippet examples/widgets/elidedlabel/testwidget.cpp 2 - - The \c widthSlider and \c heightSlider specify the size of the - \c elidedText. Since the y-axis is inverted, the \c heightSlider has to be - inverted to act appropriately. - - \snippet examples/widgets/elidedlabel/testwidget.cpp 3 - - The components are all stored in a QGridLayout, which is made the layout of - the \c TestWidget. - - \snippet examples/widgets/elidedlabel/testwidget.cpp 4 - - On the Maemo platform, windows are stuck in landscape mode by default. With - this attribute set, the window manager is aware that this window can be - rotated. - - \snippet examples/widgets/elidedlabel/testwidget.cpp 5 - - The \c widthSlider and \c heightSlider have the exact same length as the - dimensions of the \c elidedText. The maximum value for both of them is - thus their lengths, and each tick indicates one pixel. - - \snippet examples/widgets/elidedlabel/testwidget.cpp 6 - - The \c switchText() slot simply cycles through all the available sample - texts. - - \snippet examples/widgets/elidedlabel/testwidget.cpp 7 - - These slots set the width and height of the \c elided text, in response to - changes in the sliders. - - \section1 The \c main() Function - - The \c main() function creates an instance of \c TestWidget fullscreen and - enters the message loop. - - \snippet examples/widgets/elidedlabel/main.cpp 0 -*/ - diff --git a/doc/src/examples/embeddeddialogs.qdoc b/doc/src/examples/embeddeddialogs.qdoc deleted file mode 100644 index 24b3abdb37..0000000000 --- a/doc/src/examples/embeddeddialogs.qdoc +++ /dev/null @@ -1,37 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \example graphicsview/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/examples/eventtransitions.qdoc b/doc/src/examples/eventtransitions.qdoc deleted file mode 100644 index eb2e10b051..0000000000 --- a/doc/src/examples/eventtransitions.qdoc +++ /dev/null @@ -1,72 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 deleted file mode 100644 index 9e63b70e3f..0000000000 --- a/doc/src/examples/extension.qdoc +++ /dev/null @@ -1,138 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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: \uicontrol {Match case} and \uicontrol - {Search from start}. The advanced search options include the - possibilities to search for \uicontrol {Whole words}, \uicontrol {Search - backward} and \uicontrol {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 \uicontrol 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 \uicontrol Find button to - start a search and the \uicontrol 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 \uicontrol {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 \uicontrol 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 \uicontrol - 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 \uicontrol More button checkable when we created it, - the connection makes sure that the extension widget is shown - depending on the state of \uicontrol 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 align the QLabel and its buddy, the - QLineEdit, using a QHBoxLayout. Then we vertically align 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 deleted file mode 100644 index ead9695c1c..0000000000 --- a/doc/src/examples/factorial.qdoc +++ /dev/null @@ -1,88 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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: - - \image 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 deleted file mode 100644 index 48f98c03ad..0000000000 --- a/doc/src/examples/fademessage.qdoc +++ /dev/null @@ -1,37 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 deleted file mode 100644 index cd07f3c7ab..0000000000 --- a/doc/src/examples/fetchmore.qdoc +++ /dev/null @@ -1,111 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 \uicontrol - 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 deleted file mode 100644 index 6654070d72..0000000000 --- a/doc/src/examples/findfiles.qdoc +++ /dev/null @@ -1,249 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 appropriate) and containing a specified text. - - The user is provided with a \uicontrol 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 \uicontrol 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 \uicontrol 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/flowlayout.qdoc b/doc/src/examples/flowlayout.qdoc deleted file mode 100644 index eaa0f7baf0..0000000000 --- a/doc/src/examples/flowlayout.qdoc +++ /dev/null @@ -1,145 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 deleted file mode 100644 index 8d7f0e0460..0000000000 --- a/doc/src/examples/fontsampler.qdoc +++ /dev/null @@ -1,35 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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/frozencolumn.qdoc b/doc/src/examples/frozencolumn.qdoc deleted file mode 100644 index 1bb759b6fd..0000000000 --- a/doc/src/examples/frozencolumn.qdoc +++ /dev/null @@ -1,133 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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/gradients.qdoc b/doc/src/examples/gradients.qdoc deleted file mode 100644 index 75f78b56ea..0000000000 --- a/doc/src/examples/gradients.qdoc +++ /dev/null @@ -1,55 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \example painting/gradients - \title Gradients - - In this example we show the various types of gradients that can - be used in Qt. - - \image gradients-demo.png - - There are three types of gradients: - - \list - \li \b{Linear} gradients interpolate colors between start and end points. - \li \b{Radial} gradients interpolate colors between a focal point and the - points on a circle surrounding it. - \li \b{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/examples/groupbox.qdoc b/doc/src/examples/groupbox.qdoc deleted file mode 100644 index f2e4ec995e..0000000000 --- a/doc/src/examples/groupbox.qdoc +++ /dev/null @@ -1,140 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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/icons.qdoc b/doc/src/examples/icons.qdoc deleted file mode 100644 index daabb1651c..0000000000 --- a/doc/src/examples/icons.qdoc +++ /dev/null @@ -1,780 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 \li Mode \li Description - \row - \li QIcon::Normal - \li Display the pixmap when the user is not interacting with the - icon, but the functionality represented by the icon is - available. - \row - \li QIcon::Active - \li 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 - \li QIcon::Disabled - \li Display the pixmap when the functionality represented by - the icon is not available. - \row - \li QIcon::Selected - \li 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 \uicontrol View menu. - - \image icons-view-menu.png Screenshot of the View menu - - The \uicontrol View menu also provide the option to make the application - guess the icon state and mode from an image's file name. The \uicontrol - 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 \uicontrol File menu provide an - \uicontrol Exit option, and the \uicontrol 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 \uicontrol {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 \uicontrol - 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 \li{2,1} Requested Pixmap \li {8,1} Preferred Alternatives (mode/state) - \header \li Mode \li State \li 1 \li 2 \li 3 \li 4 \li 5 \li 6 \li 7 \li 8 - \row \li{1,2} Normal \li Off \li \b N0 \li A0 \li N1 \li A1 \li D0 \li S0 \li D1 \li S1 - \row \li On \li N1 \li \b A1 \li N0 \li A0 \li D1 \li S1 \li D0 \li S0 - \row \li{1,2} Active \li Off \li A0 \li \b N0 \li A1 \li N1 \li D0 \li S0 \li D1 \li S1 - \row \li On \li \b A1 \li N1 \li A0 \li N0 \li D1 \li S1 \li D0 \li S0 - \row \li{1,2} Disabled \li Off \li D0 \li \b {N0'} \li A0' \li D1 \li N1' \li A1' \li S0' \li S1' - \row \li On \li D1 \li N1' \li \b {A1'} \li D0 \li N0' \li A0' \li S1' \li S0' - \row \li{1,2} Selected \li Off \li S0 \li \b {N0''} \li A0'' \li S1 \li N1'' \li A1'' \li D0'' \li D1'' - \row \li On \li S1 \li N1'' \li \b {A1''} \li S0 \li N0'' \li A0'' \li D1'' \li 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 - \li \inlineimage icons_monkey.png Screenshot of the Monkey Files - \li \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 - \li - \li \inlineimage icons_qt_extended_8x8.png Qt Extended icon at 8 x 8 - \li \inlineimage icons_qt_extended_16x16.png Qt Extended icon at 16 x 16 - \li \inlineimage icons_qt_extended_17x17.png Qt Extended icon at 17 x 17 - \row - \li - \li 8 x 8 - \li \b {16 x 16} - \li 17 x 17 - \row - \li \inlineimage icons_qt_extended_32x32.png Qt Extended icon at 32 x 32 - \li \inlineimage icons_qt_extended_33x33.png Qt Extended icon at 33 x 33 - \li \inlineimage icons_qt_extended_48x48.png Qt Extended icon at 48 x 48 - \li \inlineimage icons_qt_extended_64x64.png Qt Extended icon at 64 x 64 - \row - \li \b {32 x 32} - \li 33 x 33 - \li \b {48 x 48} - \li 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 - \li \c MainWindow inherits QMainWindow and is the main application - window. - \li \c IconPreviewArea is a custom widget that displays all - combinations of states and modes for a given icon. - \li \c IconSizeSpinBox is a subclass of QSpinBox that lets the - user enter icon sizes (e.g., "48 x 48"). - \li \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 - \li The \c about() slot simply provides information about the example. - \li The \c changeStyle() slot changes the application's GUI style and - adjust the style dependent size options. - \li The \c changeSize() slot changes the size of the preview area's icon. - \li The \c changeIcon() slot updates the set of pixmaps available to the - icon displayed in the preview area. - \li 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 \uicontrol - {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 \uicontrol File, \uicontrol View and \uicontrol 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 \uicontrol{Add Image} and \uicontrol{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 \uicontrol 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 deleted file mode 100644 index d7700858a0..0000000000 --- a/doc/src/examples/imagecomposition.qdoc +++ /dev/null @@ -1,165 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 - \li \c{sourceButton}'s \l{QPushButton::clicked()}{clicked()} signal is - connected to \c chooseSource(), - \li \c{operatorComboBox}'s \l{QComboBox::activated()}{activated()} - signal is connected to \c recalculateResult(), and - \li \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/imageviewer.qdoc b/doc/src/examples/imageviewer.qdoc deleted file mode 100644 index 554543e252..0000000000 --- a/doc/src/examples/imageviewer.qdoc +++ /dev/null @@ -1,326 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 \uicontrol File menu gives the user the possibility - to: - - \list - \li \uicontrol{Open...} - Open an image file - \li \uicontrol{Print...} - Print an image - \li \uicontrol{Exit} - Exit the application - \endlist - - Once an image is loaded, the \uicontrol View menu allows the users to: - - \list - \li \uicontrol{Zoom In} - Scale the image up by 25% - \li \uicontrol{Zoom Out} - Scale the image down by 25% - \li \uicontrol{Normal Size} - Show the image at its original size - \li \uicontrol{Fit to Window} - Stretch the image to occupy the entire window - \endlist - - In addition the \uicontrol 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 \uicontrol {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 \uicontrol {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 \uicontrol - 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 \uicontrol 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 \uicontrol Print and \uicontrol {Fit to Window} menu entries and update - the rest of the view menu entries. The \uicontrol Open and \uicontrol Exit - entries are enabled by default. - - If the \uicontrol {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 \uicontrol qmake when building the application: - - \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 \uicontrol {Zoom In} - action and a \uicontrol {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 - \li \inlineimage imageviewer-original_size.png - \li \inlineimage imageviewer-zoom_in_1.png - \li \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 \uicontrol {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 \uicontrol {Zoom In}, \uicontrol {Zoom Out} and \uicontrol {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 \uicontrol {Fit to window} option turned on. - Enlarging the window will stretch the image further, as shown in - the third screenshot. - - \table - \row - \li \inlineimage imageviewer-original_size.png - \li \inlineimage imageviewer-fit_to_window_1.png - \li \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 - appropriate slots. We only enable the \c openAct and \c exitAct 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 \uicontrol File, \uicontrol View and \uicontrol 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 - \uicontrol {Zoom In}, \uicontrol {Zoom Out} and \uicontrol {Normal Size} menu - entries depending on whether the \uicontrol {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/interview.qdoc b/doc/src/examples/interview.qdoc deleted file mode 100644 index 35721ccfae..0000000000 --- a/doc/src/examples/interview.qdoc +++ /dev/null @@ -1,37 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \example itemviews/interview - \title Interview - - The Interview example 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/examples/licensewizard.qdoc b/doc/src/examples/licensewizard.qdoc deleted file mode 100644 index f0ad723d50..0000000000 --- a/doc/src/examples/licensewizard.qdoc +++ /dev/null @@ -1,218 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 - \li \c LicenseWizard inherits QWizard and implements a non-linear - five-page wizard that leads the user through the process of - choosing a license agreement. - \li \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 \li Class name \li Enum value \li Page ID - \row \li \c IntroPage \li \c Page_Intro \li 0 - \row \li \c EvaluatePage \li \c Page_Evaluate \li 1 - \row \li \c RegisterPage \li \c Page_Register \li 2 - \row \li \c DetailsPage \li \c Page_Details \li 3 - \row \li \c ConclusionPage \li \c Page_Conclusion \li 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 \uicontrol 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 appropriate for - the current page. If the user clicks \uicontrol 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 \uicontrol{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 - \uicontrol Next button (\uicontrol 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 \uicontrol Print button in the wizard when the \c - ConclusionPage is up. One way to accomplish this is to reimplement - QWidget::setVisible(): - - \list - \li If the page is shown, we set the \l{QWizard::}{CustomButton1} button's - text to \uicontrol{\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. - \li 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 deleted file mode 100644 index aafa70f38c..0000000000 --- a/doc/src/examples/lighting.qdoc +++ /dev/null @@ -1,33 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 deleted file mode 100644 index 70d85cff69..0000000000 --- a/doc/src/examples/lineedits.qdoc +++ /dev/null @@ -1,161 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 \uicontrol{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 \uicontrol{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 \uicontrol{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 - \uicontrol{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 - \uicontrol{Access} group box: - - \snippet examples/widgets/lineedits/window.cpp 13 - - Here, we simply associate the \uicontrol{False} and \uicontrol{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/maemovibration.qdoc b/doc/src/examples/maemovibration.qdoc deleted file mode 100644 index 78bb7f5334..0000000000 --- a/doc/src/examples/maemovibration.qdoc +++ /dev/null @@ -1,164 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \example widgets/maemovibration - \group all-examples - \title Maemo Vibration Example - - The Maemo Vibration example shows how to tell the Maemo Mode Control Entity - (MCE) to vibrate a maemo device. - - The MCE is a system service on Maemo that, among other things, provides an - D-Bus interface to trigger vibrations. The vibrations are specified as - patterns and are defined in a system configuration file. - - The example program reads the configuration file to look for possible - vibration patterns and display a button for each. Pressing a button will - make the device vibrate accordingly, until the application closes, or - another pattern is started. - - \image maemovibration-example.png Screenshot of the Maemo Vibration Example - - The code makes use of two classes: - - \list - \li \c MceVibrator connects to the MCE service and can start a certain - vibrator pattern. It also is responsible to parse the configuration - file. - - \li \c ButtonWidget provides a button for each pattern. Pressing the button - activates the pattern in question. - \endlist - - - \section1 MceVibrator Class Definition - - \snippet examples/widgets/maemovibration/mcevibrator.h 0 - - The \c MceVibrator class inherits from QObject and provides a specialized - and Qt friendly interface to the MCE vibration facilty. The slot \c vibrate() - can be called to make the device vibrate according to a specific pattern - name. We will connect it to a signal of a \c ButtonWidget object later. The - static method \c ParsePatternNames() can be called to find out which patterns - are available to us. - - \list - \li \c mceInterface is our D-Bus handle to the MCE service. We use it to - invoke methods on the MCE request object. - - \li \c lastPatternName contains the pattern that was activated last time. We - have to keep track of this, because the last pattern has to be - deactivated before activating a new pattern. - \endlist - - - \section1 MceVibrator Class Implementation - - To connect to the service, we initialize the D-Bus interface handle. The - system header \c "mce/dbus-names.h" contains definitions of the D-Bus - service name and request object path and interface. These are passed to the - constructor of the handle, and Qt will automatically establish a connection - to it, if it is possible. - - The MCE expects us to first enable the vibrator before we can use it. This - is done with the call to the \c MCE_ENABLE_VIBRATOR D-Bus method. - - \snippet examples/widgets/maemovibration/mcevibrator.cpp 0 - - From now on we can activate vibration patterns. Each time a vibration - pattern is activated, the last pattern has to be deactivated first. In the - vibrate slot we use the MCE interface to call the activation method. - - \snippet examples/widgets/maemovibration/mcevibrator.cpp 1 - - The calls to the private method deactivate simply makes sure to deactivate - the last pattern used, if there was one. - - \snippet examples/widgets/maemovibration/mcevibrator.cpp 2 - - Calling either the activate or deactivate MCE D-Bus method with invalid - pattern names are ignored. - - Finally, the destructor disables the vibrator. When the destructor of the - MCE interface handle is called, the connection is also closed. - - \snippet examples/widgets/maemovibration/mcevibrator.cpp 3 - - The MCE configuration file contains options for many different things. We - are only interested in one line that contains the vibration patterns. It - has the following format: - - - \code - VibratorPatterns=semicolon;separated;list;of;values - \endcode - - The static method \c ParsePatternNames looks for this line and returns a - QStringList containing the values, which are the pattern names we can use. - - \snippet examples/widgets/maemovibration/mcevibrator.cpp 4 - - The helper function \c checkError() saves us some code duplication. None of the - called methods return anything of use to us, so we're only interested in - getting error messages for debugging. - - \snippet examples/widgets/maemovibration/mcevibrator.cpp 5 - - - \section1 ButtonWidget Class Definition - - \snippet examples/widgets/maemovibration/buttonwidget.h 0 - - The \c ButtonWidget class inherits from QWidget and provides the main user - interface for the application. It creates a grid of buttons, one for each - string in the stringlist passed to the constructor. Pressing a button emits - the \c clicked() signal, where the string is the text of the button that - was pressed. - - This class is taken from the QSignalMapper documentation. The only change - is the number of columns in the grid from three to two, to make the button - labels fit. - - - \section1 ButtonWidget Class Implementation - - \snippet examples/widgets/maemovibration/buttonwidget.cpp 0 - - - \section1 \c main() Function - - The main function begins with looking up the patterns available to us. - - \snippet examples/widgets/maemovibration/main.cpp 0 - - Then we create one instance of both classes, and connects the - \c ButtonWidget's clicked signal to the \c MceVibrator's \c vibrate() slot. - This works, since the button texts are the same as the pattern names. - - \snippet examples/widgets/maemovibration/main.cpp 1 -*/ diff --git a/doc/src/examples/mainwindow.qdoc b/doc/src/examples/mainwindow.qdoc deleted file mode 100644 index b4f6aebed1..0000000000 --- a/doc/src/examples/mainwindow.qdoc +++ /dev/null @@ -1,36 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \example mainwindows/mainwindow - \title Main Window - - The Main Window example 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/examples/mdi.qdoc b/doc/src/examples/mdi.qdoc deleted file mode 100644 index e8b1b5c9ef..0000000000 --- a/doc/src/examples/mdi.qdoc +++ /dev/null @@ -1,37 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 deleted file mode 100644 index 575a1f0219..0000000000 --- a/doc/src/examples/menus.qdoc +++ /dev/null @@ -1,218 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 \uicontrol {Left Align} action, a \uicontrol {Right Align} action, a - \uicontrol {Justify} action, and a \uicontrol {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 \uicontrol 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 \uicontrol {Left Align}, \uicontrol {Right Align}, - \uicontrol {Justify}, and a \uicontrol {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 \uicontrol Format menu. First of all, it is added as a submenu - to the \uicontrol 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 - \uicontrol Cut, \uicontrol Copy and \uicontrol 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/moveblocks.qdoc b/doc/src/examples/moveblocks.qdoc deleted file mode 100644 index 38551abd28..0000000000 --- a/doc/src/examples/moveblocks.qdoc +++ /dev/null @@ -1,214 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 - \li \c StateSwitcher inherits QState and can add - \c {StateSwitchTransition}s to other states. - When entered, it will randomly transition to one of these - states. - \li \c StateSwitchTransition is a custom transition that - triggers on \c{StateSwitchEvent}s. - \li \c StateSwitchEvent is a QEvent that triggers \c{StateSwitchTransition}s. - \li \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 deleted file mode 100644 index 7573d796c3..0000000000 --- a/doc/src/examples/movie.qdoc +++ /dev/null @@ -1,39 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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/orderform.qdoc b/doc/src/examples/orderform.qdoc deleted file mode 100644 index c9ef75640f..0000000000 --- a/doc/src/examples/orderform.qdoc +++ /dev/null @@ -1,364 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 \uicontrol OK and \uicontrol 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 - \li {1, 8} frame with \e{referenceFrameFormat} - \row - \li block \li \c{A company} - \row - \li block - \row - \li block \li \c{321 City Street} - \row - \li block - \row - \li block \li \c{Industry Park} - \row - \li block - \row - \li block \li \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 - \li block \li \c{Donald} - \row - \li block \li \c{47338 Park Avenue} - \row - \li block \li \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 - \li block - \row - \li block - \row - \li block \li \c{Date: 25 May 2007} - \row - \li block - \row - \li {1, 4} frame with \e{bodyFrameFormat} - \row - \li block \li \c{I would like to place an order for the following items:} - \row - \li block - \row - \li 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 - \li {1, 11} \c{orderTable} with \e{orderTableFormat} - \row - \li block \li \c{Product} - \row - \li block \li \c{Quantity} - \row - \li block \li \c{T-shirt} - \row - \li block \li \c{4} - \row - \li block \li \c{Badge} - \row - \li block \li \c{3} - \row - \li block \li \c{Reference book} - \row - \li block \li \c{2} - \row - \li block \li \c{Coffee cup} - \row - \li block \li \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 - \li block - \row - \li block\li \c{Please update my...} - \row - \li {1, 5} block - \row - \li {1, 4} \c{offersTable} - \row - \li block \li \c{I want to receive...} - \row - \li block \li \c{I do not want to receive...} - \row - \li block \li \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 - \li block - \row - \li {1, 5} block\li \c{Sincerely,} - \row - \li block - \row - \li block - \row - \li block - \row - \li block \li \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/padnavigator.qdoc b/doc/src/examples/padnavigator.qdoc deleted file mode 100644 index 840c16b0c9..0000000000 --- a/doc/src/examples/padnavigator.qdoc +++ /dev/null @@ -1,583 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 display 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 - \li \c pix: The optional pixmap that is drawn on top of the rectangle. - \li \c fillRect: Corresponds to the \c fill property. - \li \c color: The configurable gradient color fill of the rectangle. - \li \c bounds: The bounds of the rectangle. - \li \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 particularly 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 current 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 controlled by three transformations, and we create one - QGraphicsRotation object for each of these. - - \list - \li \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. - \li \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. - \li \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 between - 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 - \li \c smoothFlipRotation: Animates the main 180 degree rotation of the pad. - \li \c smoothFlipScale: Scales the pad out and then in again while the pad is rotating. - \li \c smoothFlipXRotation: Animates the selection item's X-tilt to 0 and back. - \li \c smoothFlipYRotation: Animates the selection item's Y-tilt to 0 and back. - \li \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 - \li \c splashState: The initial state where the splash item is visible. - \li \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. - \li \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 - \li It disables its scroll bars - this application has no use for scroll bars. - \li It assigns a minimum size. This is necessary to avoid numerical errors - in our fit-in-view \c resizeEvent() implementation. - \li 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. - \li It enables background caching - this makes no performance difference - with OpenGL, but without OpenGL it avoids unnecessary re-scaling of the - background pixmap. - \li It sets render hints that increase rendering quality. - \li 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 deleted file mode 100644 index 1bee28f029..0000000000 --- a/doc/src/examples/painterpaths.qdoc +++ /dev/null @@ -1,418 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 - \li The \c RenderArea class which is a custom widget displaying - a single painter path. - \li 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() function 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 initial 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 which 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/pathstroke.qdoc b/doc/src/examples/pathstroke.qdoc deleted file mode 100644 index 89a0182934..0000000000 --- a/doc/src/examples/pathstroke.qdoc +++ /dev/null @@ -1,47 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \example painting/pathstroke - \title Path Stroking - - In this example 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/examples/pingpong.qdoc b/doc/src/examples/pingpong.qdoc deleted file mode 100644 index 87358684c0..0000000000 --- a/doc/src/examples/pingpong.qdoc +++ /dev/null @@ -1,93 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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: - - \image 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 deleted file mode 100644 index 35031a09d8..0000000000 --- a/doc/src/examples/pixelator.qdoc +++ /dev/null @@ -1,255 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 - \li 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. - \li 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 \uicontrol{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 \uicontrol{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 - \uicontrol{Pixel size} combobox. -*/ diff --git a/doc/src/examples/recentfiles.qdoc b/doc/src/examples/recentfiles.qdoc deleted file mode 100644 index e2e876b088..0000000000 --- a/doc/src/examples/recentfiles.qdoc +++ /dev/null @@ -1,36 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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/rogue.qdoc b/doc/src/examples/rogue.qdoc deleted file mode 100644 index 44e371c667..0000000000 --- a/doc/src/examples/rogue.qdoc +++ /dev/null @@ -1,208 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 - \li \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. - \li \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/screenshot.qdoc b/doc/src/examples/screenshot.qdoc deleted file mode 100644 index 4723d3d43c..0000000000 --- a/doc/src/examples/screenshot.qdoc +++ /dev/null @@ -1,247 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 - \li Delaying the screenshot, giving them time to rearrange - their desktop. - \li 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 - \li The \c newScreenshot() slot prepares a new screenshot. - \li The \c saveScreenshot() slot saves the last screenshot. - \li The \c shootScreen() slot takes the screenshot. - \li The \c updateCheckBox() slot enables or disables the - \uicontrol {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 initial - 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 \uicontrol {Hide This Window} option is checked, if - it is we hide the \c Screenshot widget. Then we disable the \uicontrol - {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 \uicontrol {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 \uicontrol - 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 - - Using the static function QApplication::primaryScreen(), we - obtain the QScreen object for the application's main screen. - - We take the screenshot using the QScreen::grabWindow() - function. The function grabs the contents of the window passed as - an argument, makes a pixmap out of it and returns that pixmap. - The window id can be obtained with QWidget::winId() or QWindow::winId(). - Here, however, we just pass 0 as the window id, indicating that we - want to grab the entire screen. - - We update the screenshot preview label using the private \c - updateScreenshotLabel() function. Then we enable the \uicontrol {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 \uicontrol {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 \uicontrol {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 \uicontrol - {Screenshot Delay} option, and connect the spinbox to the \c - updateCheckBox() slot. Finally, we create a QCheckBox for the \uicontrol - {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 deleted file mode 100644 index 4c4df891b2..0000000000 --- a/doc/src/examples/scribble.qdoc +++ /dev/null @@ -1,417 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 - \uicontrol 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 \uicontrol Options menu allows the users to to choose the - pen color and pen width, as well as clear the screen. In addition - the \uicontrol 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 - \li \c ScribbleArea is a custom widget that displays a QImage and - allows to the user to draw on it. - \li \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 - \li \c modified is \c true if there are unsaved - changes to the image displayed in the scribble area. - \li \c scribbling is \c true while the user is pressing - the left mouse button within the scribble area. - \li \c penWidth and \c penColor hold the currently - set width and color for the pen used in the application. - \li \c image stores the image drawn by the user. - \li \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 - \li 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. - - \li 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.) - - \li 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 \uicontrol 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 \uicontrol{File|Exit} or by clicking the \uicontrol 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 \uicontrol 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 \uicontrol {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 \uicontrol OK and to \c false if the user pressed \uicontrol 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 appropriate - slots. In particular we create the actions found in the \uicontrol - {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 \uicontrol File, - \uicontrol Options and \uicontrol 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 \uicontrol File and \uicontrol 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 \uicontrol Cancel and save the file using another - format. - - The \c maybeSave() function returns \c false if the user clicks - \uicontrol 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 deleted file mode 100644 index b686888797..0000000000 --- a/doc/src/examples/sdi.qdoc +++ /dev/null @@ -1,36 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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/shapedclock.qdoc b/doc/src/examples/shapedclock.qdoc deleted file mode 100644 index b83178b44d..0000000000 --- a/doc/src/examples/shapedclock.qdoc +++ /dev/null @@ -1,131 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 \uicontrol File menu or a close - button, we provide a context menu with an \uicontrol 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/simpledommodel.qdoc b/doc/src/examples/simpledommodel.qdoc deleted file mode 100644 index b49750d5a5..0000000000 --- a/doc/src/examples/simpledommodel.qdoc +++ /dev/null @@ -1,280 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 deleted file mode 100644 index ed584a3307..0000000000 --- a/doc/src/examples/simpletreemodel.qdoc +++ /dev/null @@ -1,333 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 \li \inlineimage treemodel-structure.png - \li \b{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 - \li The \c appendChildItem() is used to add data when the model is first - constructed and is not used during normal use. - \li The \c child() and \c childCount() functions allow the model to obtain - information about any child items. - \li 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. - \li 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 - \li 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. - \li 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 deleted file mode 100644 index 2b24dbcecd..0000000000 --- a/doc/src/examples/simplewidgetmapper.qdoc +++ /dev/null @@ -1,125 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 \uicontrol{Next} and \uicontrol{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 \uicontrol{Previous} - button is disabled. Similarly, the \uicontrol{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 deleted file mode 100644 index b5f18cb4be..0000000000 --- a/doc/src/examples/sipdialog.qdoc +++ /dev/null @@ -1,127 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 \li \inlineimage sipdialog-closed.png - \li \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 - \li \c{button}'s \l{QPushButton::pressed()}{pressed()} signal to - \l{QApplication}'s \l{QApplication::closeAllWindows()} - {closeAllWindows()} slot, - \li \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 deleted file mode 100644 index 383efc6140..0000000000 --- a/doc/src/examples/sliders.qdoc +++ /dev/null @@ -1,255 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 - - \li \c SlidersGroup is a custom widget. It combines a QSlider, a - QScrollBar and a QDial. - - \li \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 \li \li{2,1} QSlider \li{2,1} QScrollBar \li{2,1} QDial - \header \li \li Normal \li Inverted \li Normal \li Inverted \li Normal \li Inverted - \row \li Qt::Horizontal \li Left to right \li Right to left \li Left to right \li Right to left \li Clockwise \li Counterclockwise - \row \li Qt::Vertical \li Bottom to top \li Top to bottom \li Top to bottom \li Bottom to top \li Clockwise \li 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 \uicontrol PageUp to mean "up" on the screen. - - Note that for horizontal and vertical scroll bars, the key - bindings are inverted by default: \uicontrol PageDown increases the - current value, and \uicontrol 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 \uicontrol 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 appropriate - 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 deleted file mode 100644 index b36176b042..0000000000 --- a/doc/src/examples/spinboxdelegate.qdoc +++ /dev/null @@ -1,141 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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. - Furthermore it is also possible to reuse (and avoid deleting) the editor - widget by reimplementing the \a destroyEditor() function. A reused widget - could be a mutable member created in the constructor and deleted in - the destructor. - - \section1 SpinBoxDelegate Class Implementation - - Delegates are often 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 deleted file mode 100644 index 9bdc1e3aff..0000000000 --- a/doc/src/examples/spinboxes.qdoc +++ /dev/null @@ -1,191 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 \uicontrol{Up} and \uicontrol{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 \uicontrol{0%}, but will - display \uicontrol{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 - \uicontrol{Up} and \uicontrol{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/spreadsheet.qdoc b/doc/src/examples/spreadsheet.qdoc deleted file mode 100644 index 7364f022cb..0000000000 --- a/doc/src/examples/spreadsheet.qdoc +++ /dev/null @@ -1,37 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \example itemviews/spreadsheet - \title Spreadsheet - - The Spreadsheet example 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/examples/standarddialogs.qdoc b/doc/src/examples/standarddialogs.qdoc deleted file mode 100644 index b56642b6ec..0000000000 --- a/doc/src/examples/standarddialogs.qdoc +++ /dev/null @@ -1,35 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 deleted file mode 100644 index c9cc1f40cf..0000000000 --- a/doc/src/examples/stardelegate.qdoc +++ /dev/null @@ -1,296 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 - \li \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". - - \li \c StarDelegate inherits QItemDelegate and provides support - for \c StarRating (in addition to the data types already - handled by QItemDelegate). - - \li \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 - \li 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. - - \li 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 deleted file mode 100644 index 52eda087f1..0000000000 --- a/doc/src/examples/states.qdoc +++ /dev/null @@ -1,36 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 deleted file mode 100644 index 518dd1182c..0000000000 --- a/doc/src/examples/stickman.qdoc +++ /dev/null @@ -1,102 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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/styles.qdoc b/doc/src/examples/styles.qdoc deleted file mode 100644 index 0623b34eb4..0000000000 --- a/doc/src/examples/styles.qdoc +++ /dev/null @@ -1,472 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 - \li \c NorwegianWoodStyle inherits from QMotifStyle and implements - the Norwegian Wood style. - \li \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 \li \inlineimage widgets/styles/images/woodbackground.png - - \li \b{woodbackground.png} - - This texture is used as the background of most widgets. - The wood pattern is horizontal. - - \row \li \inlineimage widgets/styles/images/woodbutton.png - - \li \b{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 - \li 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}. - \li 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}. - \li 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 \uicontrol 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 \uicontrol Style combobox to the \c changeStyle() - private slot, the \uicontrol{Use style's standard palette} check box to - the \c changePalette() slot, and the \uicontrol{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 \uicontrol{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 deleted file mode 100644 index af45411f8c..0000000000 --- a/doc/src/examples/stylesheet.qdoc +++ /dev/null @@ -1,36 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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/sub-attaq.qdoc b/doc/src/examples/sub-attaq.qdoc deleted file mode 100644 index ae00eb0926..0000000000 --- a/doc/src/examples/sub-attaq.qdoc +++ /dev/null @@ -1,40 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \example animation/sub-attaq - \title Sub-Attaq - - This example 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/examples/syntaxhighlighter.qdoc b/doc/src/examples/syntaxhighlighter.qdoc deleted file mode 100644 index 597a1a2bf3..0000000000 --- a/doc/src/examples/syntaxhighlighter.qdoc +++ /dev/null @@ -1,252 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 - \li The \c Highlighter class defines and applies the - highlighting rules. - \li 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. - - \section1 Other Code Editor Features - - It is possible to implement parenthesis matching with - QSyntaxHighlighter. The "Matching Parentheses with - QSyntaxHighlighter" article in Qt Quarterly 31 - (\l{http://doc.qt.nokia.com/qq/}) implements this. We also have - the \l{Code Editor Example}, which shows how to implement line - numbers and how to highlight the current line. - -*/ diff --git a/doc/src/examples/tabdialog.qdoc b/doc/src/examples/tabdialog.qdoc deleted file mode 100644 index ff05d9b419..0000000000 --- a/doc/src/examples/tabdialog.qdoc +++ /dev/null @@ -1,134 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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/tablet.qdoc b/doc/src/examples/tablet.qdoc deleted file mode 100644 index 57fa7d5eca..0000000000 --- a/doc/src/examples/tablet.qdoc +++ /dev/null @@ -1,369 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 - \li The \c MainWindow class inherits QMainWindow and creates - the examples menus and connect their slots and signals. - \li 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. - \li The \c TabletApplication class inherits QApplication. This - class handles tablet events that are not sent to \c tabletEvent(). - We will look at this later. - \li 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 whether 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 deleted file mode 100644 index 1b9c3a661d..0000000000 --- a/doc/src/examples/tetrix.qdoc +++ /dev/null @@ -1,431 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 \uicontrol{Left} cursor key moves the current piece one space to the left, the - \uicontrol{Right} cursor key moves it one space to the right, the \uicontrol{Up} cursor - key rotates the piece counter-clockwise by 90 degrees, and the \uicontrol{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 \uicontrol{D} - to immediately move the piece down by one row, or press the \uicontrol{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 - \li The \c TetrixWindow class is used to display the player's score, number of - lives, and information about the next piece to appear. - \li The \c TetrixBoard class contains the game logic, handles keyboard input, and - displays the pieces on the playing area. - \li 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 \uicontrol{Alt} key shortcuts. - - We connect \l{QAbstractButton::}{clicked()} signals from the \uicontrol{Start} - and \uicontrol{Pause} buttons to the board, and from the \uicontrol{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 \uicontrol{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/textedit.qdoc b/doc/src/examples/textedit.qdoc deleted file mode 100644 index 1bb596eb6e..0000000000 --- a/doc/src/examples/textedit.qdoc +++ /dev/null @@ -1,36 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \example richtext/textedit - \title Text Edit - - The Text Edit example 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/examples/tooltips.qdoc b/doc/src/examples/tooltips.qdoc deleted file mode 100644 index cfa1884097..0000000000 --- a/doc/src/examples/tooltips.qdoc +++ /dev/null @@ -1,394 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 - \li \c ShapeItem is a custom widget representing one single shape item. - \li \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 appropriate 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 appropriate 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 height - 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 initial - 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/trafficlight.qdoc b/doc/src/examples/trafficlight.qdoc deleted file mode 100644 index f80225fc84..0000000000 --- a/doc/src/examples/trafficlight.qdoc +++ /dev/null @@ -1,85 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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: - - \image 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: - - \image 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 deleted file mode 100644 index 013ebc2e8c..0000000000 --- a/doc/src/examples/transformations.qdoc +++ /dev/null @@ -1,371 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 - \li The \c RenderArea class controls the rendering of a given shape. - \li The \c Window class is the application's main window. - \li 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() function 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 receives 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 \uicontrol {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 - examples. Among these is the \l {painting/affine}{Affine - Transformations} example that shows Qt's ability to perform - transformations on painting operations. The example also allows the - user to experiment with the various transformation operations. -*/ diff --git a/doc/src/examples/trivialwizard.qdoc b/doc/src/examples/trivialwizard.qdoc deleted file mode 100644 index 5835b63995..0000000000 --- a/doc/src/examples/trivialwizard.qdoc +++ /dev/null @@ -1,82 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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/twowaybutton.qdoc b/doc/src/examples/twowaybutton.qdoc deleted file mode 100644 index b0c0c4910d..0000000000 --- a/doc/src/examples/twowaybutton.qdoc +++ /dev/null @@ -1,68 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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/wiggly.qdoc b/doc/src/examples/wiggly.qdoc deleted file mode 100644 index 677e8b08ca..0000000000 --- a/doc/src/examples/wiggly.qdoc +++ /dev/null @@ -1,167 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 - \li \c WigglyWidget is the custom widget displaying the text - in a wiggly line. - - \li \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 deleted file mode 100644 index 21b983d4e1..0000000000 --- a/doc/src/examples/windowflags.qdoc +++ /dev/null @@ -1,216 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** 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. -** -** Other Usage -** Alternatively, this file may be used in accordance with the terms -** and conditions contained in a signed written agreement between you -** and Nokia. -** -** -** -** -** -** $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 - \li \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. - \li \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 \uicontrol 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 \uicontrol 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 \uicontrol 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. -*/ |